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

一、项目结构与基本操作

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

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

所有文件选择（打开、保存、导入音频、导出、选封面 / 音效）均调用系统原生文件管理器（Windows / macOS）。首次使用时默认定位到用户「文档」目录；之后会记住上一次选择文件所在的目录，下次打开任意文件选择器时直接定位到该目录。

打开使用旧版难度名（Near / Medium / Distant / Spacey）的旧项目时，编辑器会自动把它们升级为现行难度名（Stable / Drifting / Faint / Relink），并就地改写 song.json。改写只动 song.json 的难度字段：谱面文件不会被改名、新建或删除，song.json 中的文件引用仍指向原来的谱面文件。

项目文件夹的典型结构：

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

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

清空难度：难度标签栏右侧的「Clear chart」按钮会弹出二次确认对话框，避免误操作；若当前项目仅剩一份谱面则直接拒绝（必须至少保留一份）。

二、元数据配置

项目层（所有难度共享）

  • Title / Artist / Charter：歌曲名、艺术家、制谱者
  • Song ID：谱面包的唯一标识，仅允许小写英文字母、数字和下划线（[a-z0-9_]），避免与内置歌曲冲突
  • Cover color：选曲列表中的背景色（RGB）

难度层（各难度独立）

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

三、音频与波形

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

预览区间

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

四、拍号与栅格

BPM 变速

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

  • 时间点（秒）
  • BPM 数值

缩圈速度事件

Approach speed events 是谱面内的缩圈速度变更点，用于控制音符本体 / approach ring 的出现时间与缩圈进度，不影响判定时间、BPM 或音频。

  • 每个事件包含 time（秒）和 speed（倍率）。
  • 0.0 表示暂停缩圈，1.0 表示正常速度，> 1.0 表示加速。
  • 事件是 change point：某个 speed 会持续到下一条事件。若要暂停后恢复默认速度，需要显式新增 speed = 1.0 的事件。
  • 没有 0.0s 事件时，系统等价于隐含 0.0s = 1.0x。
  • 该效果会与玩家 / 预览的 Ring Speed、每音符 ring_time_mult、ring_scale_mult 复合。

拍号对齐（Beat snap）

  • 启用后，放置音符时自动吸附至最近节拍线。
  • 细分粒度按全音符的 1/N 设置，支持 1 至 256；16 对应十六分音符，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 时自动对齐至栅格。
  • 工具切换主快捷键为 X / A / S / D / F / G，分别对应 Select / Tap / Drag / Flick / Hold / Slide；旧版 Alt+X / T / D / F / H / S 仍保留。
  • 新放置的 Hold / Slide 默认持续时长为「当前 BPM 下的一拍」（即 60 / BPM 秒），自动随小节变速调整。Slide 同时附带 +0.1 X 的水平间距作为初始第二节点。

选择操作

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

编辑操作

  • 移动：拖动选中音符，时间与位置同步更新；Slide 的路径点可单独拖动。
  • 删除：Del 键。
  • 复制 / 剪切 / 粘贴：Ctrl+C / Ctrl+X / Ctrl+V。粘贴以当前播放头为时间基准，多选内容保持相对时间关系。
  • 镜像：Shift+H（水平翻转）、Shift+M（垂直翻转）。
  • 时间微调：选中后使用 ← / → 进行小步位移。
  • 音符时间对齐到当前时间：选中单个音符后按 Alt+0，将整体（含 Hold 尾、Slide 路径）整体平移到当前播放位置。
  • Hold 结束时间对齐到当前时间：选中单个 Hold 音符后按 Alt+1。若当前时间早于起点会被拒绝。
  • Slide 路径点时间对齐到当前时间：选中单个 Slide 后按 Alt+0 ~ Alt+9 对应第 0 ~ 9 个路径点；按 Alt+Shift+0 ~ Alt+Shift+9 对应第 10 ~ 19 个。仅该路径点平移，相邻路径点不会跟随移动；尝试越过相邻路径点的时间会被拒绝。
  • Slide 添加新路径点：选中单个 Slide 后按 Alt+P，在最后一个路径点的位置上以 +0.1 X / +半拍时间 偏移新增节点。Inspector 中的「+ Add point」按钮等价。

六、Inspector 面板

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

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

时间字段的合法性校验：

  • Hold 的 End (ms) 不允许早于起始时间；尝试输入更小的值时编辑器会还原数值并在状态栏提示。
  • Slide 路径点的 time 不允许早于上一个路径点的时间；超出时同样会被还原并提示。

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

七、时间轴与播放控制

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

八、预览模式

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

可配置参数：

  • Ring Speed：与游戏设置同义，缩圈基础窗口为 3.0 / speed 秒；例如 5.0x 对应 0.6s
  • Ring start scale：提示圈相对音符的起始大小（默认 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

每个声道支持：

  • 指定自定义音频文件，留空则使用内置音效
  • 独立静音开关
  • 独立音量调节（0–200%，100% 为原始增益，0% 静音）

十、高级功能

撤销与重做

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

从其他难度导入元数据

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

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

编辑器可通过 LiveLink 把当前谱面、音频和封面资源发送到游戏端测试。切换难度、替换音频或封面后会重新广播资源与谱面；游戏端的 LiveLink 局不写入成绩、profile 统计或解锁进度。

十一、导出 .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 + 点击
框选 空白区域拖动
切换工具 Select / Tap / Drag / Flick / Hold / Slide X / A / S / D / F / G（旧版 Alt+X / T / D / F / H / S 仍可用）
音符时间 → 当前时间 Alt+0
Hold 结束时间 → 当前时间 Alt+1
Slide 第 N 路径点 → 当前时间（N = 0 ~ 9） Alt+0 ~ Alt+9
Slide 第 N 路径点 → 当前时间（N = 10 ~ 19） Alt+Shift+0 ~ Alt+Shift+9
Slide 添加新路径点 Alt+P

注意事项

  • Song ID 冲突：与游戏内置歌曲 ID 相同的谱面将无法导入。建议采用带作者前缀的命名方式，例如 <作者名>_<歌曲名>。
  • Song ID 字符集：导入侧只接受 [a-z0-9_]，不要使用空格、连字符、大写字母或非 ASCII 字符。
  • Song ID 变更的影响：分数记录与 Song ID 绑定。修改 ID 相当于新曲，玩家原有记录无法迁移。建议在首次发布前确定 ID，后续更新保持不变。
  • 音频文件位置：可从项目外选择音频；保存 / 导出会复制到项目或包内。若源文件已不存在，则导出失败。
  • 起始空白处理：若音频前有空白，应使用 Audio offset 将谱面零点推至音频实际起点。