YozoCone Editor 是独立于游戏主体的桌面端制谱工具，用于创作、编辑并导出 .yzcpkg 谱面包。本指南按工作流顺序组织。详细格式规范见 谱面格式规范。

一、项目结构与基本操作

启动编辑器后，可选择以下操作：

  • 新建项目：指定一个空文件夹作为项目根目录。
  • 打开项目：选择已有的 song.json 或单独的 .yzc.json 谱面文件。
  • 最近打开：顶部菜单保留最近 10 个项目的快捷访问。

项目文件夹的典型结构：

<歌曲名>/
├── song.json              # 元数据与各难度引用
├── Near.yzc.json          # 最易难度
├── Medium.yzc.json
├── Distant.yzc.json       # 默认新建难度
├── Spacey.yzc.json        # 最难
├── music.mp3 / music.ogg  # 音频文件
└── cover.jpg              # 封面图（可选）

自动保存：默认 60 秒间隔，需项目已指定目标文件夹方可生效。关闭编辑器时若存在未保存内容，将弹出确认对话框。

二、元数据配置

项目层（所有难度共享）

  • Title / Artist / Charter：歌曲名、艺术家、制谱者
  • Song ID：谱面包的唯一标识，建议使用小写英文与数字组合，避免与内置歌曲冲突
  • Cover color：选曲列表中的背景色（RGB）

难度层（各难度独立）

  • Difficulty：难度槽位，固定为 Near / Medium / Distant / Spacey 四档
  • Level：难度等级，任意字符串格式，如 7、9+、11
  • Background / Cover：该难度的封面图，留空则使用项目默认值
  • Audio override（可选）：该难度单独指定音频文件，用于剪辑或变奏版本

三、音频与波形

  1. 在元数据面板中选择 MP3 或 OGG 格式的音频文件。
  2. 音频加载后，时间轴下方显示波形图。首次生成会写入缓存，后续加载立即可用。
  3. Audio offset：毫秒级偏移量。若音频起点早于或晚于谱面零点，可通过该值整体对齐。

预览区间

  • Preview start / end：两个时间戳，用于选曲界面的试听片段。留空则使用默认行为。

四、拍号与栅格

BPM 变速

支持任意数量的变速段。在 timing 面板中通过 + 按钮新增变速点，每段包含：

  • 时间点（秒）
  • BPM 数值

拍号对齐（Beat snap）

  • 启用后，放置音符时自动吸附至最近节拍线。
  • 细分粒度可调，支持每拍 1 至 256 细分（用 4 的时候每格为十六分音符）。
  • 时间轴格子线按细分深度着色。

空间栅格

  • 可选的 N×N 网格布局，例如 8×8。
  • 启用后，音符位置自动吸附至最近格点。
  • 关闭后支持自由定位。

播放头对齐工具

  • Previous / Next snap：播放头跳转至前一 / 后一栅格线。
  • Snap now：将播放头吸附至当前位置的最近栅格线。

五、音符放置

音符类型

类型 说明
Tap 单次点击
Ex-Tap Tap 的强化变体，不会出现除了 Pure+ 和 Break 之外的判定，视觉上有所强调
Drag 全方向滑动或按压，无需点击
Flick 定向快速滑动（0° 右 / 90° 上 / 180° 左 / 270° 下）
Hold / Ex-Hold 长按音符，包含起止时间
Slide / Ex-Slide 沿路径移动的 Hold 音符，由多个路径点组成

放置操作

  • 选择工具后，在中央 playfield 画布上点击即可放置音符。音符的时间取当前播放头位置，位置取鼠标 XY 坐标。
  • 启用 snap 时自动对齐至栅格。

选择操作

操作 方式
单选 点击音符
加选 / 反选 Shift + 点击
框选 在空白区域拖动
全选当前难度 Ctrl+A
取消选择 Esc

编辑操作

  • 移动：拖动选中音符，时间与位置同步更新；Slide 的路径点可单独拖动。
  • 删除：Del 键。
  • 复制 / 剪切 / 粘贴：Ctrl+C / Ctrl+X / Ctrl+V。粘贴以当前播放头为时间基准，多选内容保持相对时间关系。
  • 镜像：Shift+H（水平翻转）、Shift+M（垂直翻转）。
  • 时间微调：选中后使用 ← / → 进行小步位移。

六、Inspector 面板

右侧 Inspector 显示当前选中音符的所有属性：

  • Time：触发时间（秒）
  • X / Y：位置坐标（归一化范围 0.0–1.0）
  • End time：结束时间（适用于 Hold 与 Slide）
  • Direction：方向角（适用于 Flick）
  • Approach ring overrides：每音符的提示圈时长与大小倍率，1.0 表示沿用全局设置

多选时，Inspector 支持批量编辑，一次修改应用于全部选中项。

七、时间轴与播放控制

  • 播放 / 暂停：Space 或工具栏按钮。
  • 播放速度：0.25× / 0.5× / 0.75× / 1× / 1.25× / 1.5× 预设，音高保持不变。
  • 跳转：直接点击时间轴任意位置，或在时间输入框中输入精确毫秒数。
  • 缩放：鼠标滚轮。
  • 水平平移：中键拖动。

八、预览模式

按 Tab 切换预览模式。playfield 实时渲染 approach ring 与音符本体，完全模拟游戏内的视觉效果。

可配置参数：

  • Approach ring 时长：提示圈从出现到命中的时间（默认 1.2 秒）
  • Ring 半径倍率：提示圈相对音符的大小（默认 3×）
  • Ring 动画：平滑缩放或瞬间出现
  • Hold 形状：方形或圆形
  • Note 半径：1080p 下的像素大小（默认 80px）
  • Ghost lookahead：未来一定时间内的音符显示为虚影，便于连续放置
  • Post-ghost：已经过的音符显示为虚影，便于参照

九、打击音（Hit SFX）

四个独立声道：

声道 触发条件
Primary Tap / Hold 起点 / Slide 起点
Secondary Drag / Hold 终点 / Slide 路径
EX Ex-Tap / Ex-Hold / Ex-Slide
Flick Flick

每个声道支持：

  • 指定自定义音频文件，留空则使用内置音效
  • 独立静音开关

十、高级功能

撤销与重做

Ctrl+Z 撤销，Ctrl+Y 重做。撤销栈覆盖所有谱面编辑操作（放置、删除、移动、属性修改、批量操作、镜像）。

从其他难度导入元数据

在 Inspector 面板底部的 “Import from other difficulty” 按钮：

  • 选择一个源难度，将其 title / artist / cover / audio / background / offset / BPM 一次性复制至当前难度。
  • 仅复制歌曲级元数据，不涉及音符内容。
  • 操作通过 UndoRedo，可使用 Ctrl+Z 回退。

十一、导出 .yzcpkg

导出前检查

  • 至少一个难度已放置音符。
  • 音频文件存在于项目目录中。

导出步骤

  1. 菜单中选择「Export」。
  2. 指定导出目录与文件名（默认基于 Song ID 自动生成）。
  3. 编辑器生成 .yzcpkg 压缩包，包含：
    • song.json
    • 各难度的 <难度名>.yzc.json
    • 音频文件
    • 封面图（如已配置）

玩家侧的导入流程参见 谱面导入教程。

快捷键速查

操作 快捷键
保存 Ctrl+S
撤销 Ctrl+Z
重做 Ctrl+Y
复制 / 剪切 / 粘贴 Ctrl+C / Ctrl+X / Ctrl+V
全选 Ctrl+A
取消选择 Esc
删除选中 Del
播放 / 暂停 Space
预览模式切换 Tab
时间微调 ← / →
水平镜像 Shift+H
垂直镜像 Shift+M
加选 / 反选 Shift + 点击
框选 空白区域拖动

注意事项

  • Song ID 冲突：与游戏内置歌曲 ID 相同的谱面将无法导入。建议采用带作者前缀的命名方式，例如 <作者名>_<歌曲名>。
  • Song ID 变更的影响：分数记录与 Song ID 绑定。修改 ID 相当于新曲，玩家原有记录无法迁移。建议在首次发布前确定 ID，后续更新保持不变。
  • 音频文件位置：音频文件必须位于项目目录中，否则编辑器无法加载，导出亦会失败。
  • 起始空白处理：若音频前有空白，应使用 Audio offset 将谱面零点推至音频实际起点。