noctilink 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：该难度的封面图（即谱面格式里的 background 字段，名为 background 实为封面），留空则使用项目默认值
  • Gameplay Background（可选）：游玩时的背景图，与封面相互独立（谱面格式 gameplay_background 字段）。设置后游玩界面显示这张图（模糊 / 变暗处理与封面一致），留空则回退到模糊后的封面；随包导出、LiveLink 实时推送
  • Audio override（可选）：该难度单独指定音频文件，用于剪辑或变奏版本

三、音频与波形

  1. 在元数据面板中选择 MP3 或 OGG 格式的音频文件。
  2. 音频加载后，时间轴下方显示波形图。首次生成会写入缓存，后续加载立即可用。波形时间轴对齐到音频的真实时间（与外部音频编辑器一致），在内置 / 有线输出下与设备延迟无关。
    • ⚠️ 生成波形时请使用内置扬声器或有线输出。 波形靠实时播放抓取，蓝牙（如 AirPods）用的是异步时钟、且易丢帧，会导致波形随时间漂移、出现断裂。生成是一次性的、缓存会保留——先在有线/内置下生成好，之后再切蓝牙听播放不受影响。
  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 至 9999；16 对应十六分音符，4 对应四分音符。
  • 时间轴格子线按细分深度着色。

空间栅格

  • X / Y 两个方向各自独立细分（不要求正方形），例如默认 X = 12 / Y = 8。
  • 启用后，音符位置自动吸附至最近格点。
  • 关闭后支持自由定位。

播放头对齐工具

  • Previous / Next snap：播放头跳转至前一 / 后一栅格线。
  • Snap now：将播放头吸附至当前位置的最近栅格线。
  • 播放头 scrub 快捷键：, / .（及鼠标滚轮）按当前 snap 刻度前后移动播放头；PgUp / PgDn 按小节粗粒度前后跳（对齐时间轴的小节线，依各 BPM 段的拍号 beats_per_measure / beat_unit 计算，不受 snap 设置影响），PgUp 往前、PgDn 往后。← / → 移动的是选中音符 / 节点的时间，不是播放头。

五、音符放置

音符类型

类型 说明
Tap 单次点击
Ex-Tap Tap 的强化变体，不会出现除了 Pure+ 和 Break 之外的判定，视觉上有所强调
Drag 全方向滑动或按压，无需点击
Flick 定向快速滑动（0° 右 / 90° 上 / 180° 左 / 270° 下）
Hold / Ex-Hold 长按音符，包含起止时间
Slide / Ex-Slide 玩家拖动跟随的轨迹音符，由多个路径点组成（finger-driven 模型 — 详见 chart_format.zh.md 的 Slide 章节）

放置操作

放置交互分现代（默认）与经典两套，在设置弹窗顶部「交互方式」切换。无论哪套，音符时间都取当前播放头、位置取鼠标 XY，启用 snap 时自动对齐栅格。

限制放置范围（设置弹窗「交互方式」下方，默认开启）：开启后，音符只能放置 / 拖动到内缩区域 x ∈ [1/8, 7/8]、y ∈ [1/9, 8/9]（即 16×9 栅格左右各留 2 格、上下各留 1 格），超出区域的位置会被夹到边界内。约束作用于音符头、slide 路径点与 hold 尾（Bézier 控制点不受限）。开启时 playfield 上会画出淡淡的允许区域边框。此外，开启时谱面检查会把任何落在区域外的音符（旧谱 / 导入谱里的边缘 note）标为警告（⚠），只提示、不修改谱面。纯编辑器辅助，不改变谱面格式、不影响游玩；关闭后可自由放到边缘，警告也随之消失。（游戏端另有运行时上下留白，详见发布说明；本限制是编辑器作者侧的额外护栏。）

现代模式（默认）

三个工具：Select / Tap / Drag，主快捷键 X / S / D。已处于 Tap 或 Drag 时，按 S 或 D 都会切到另一个。从 Select 进入 Tap/Drag 不会清空选择。Esc 先清空选择（不退出当前工具），再次按 Esc（此时无选择）才回到 Select 工具。

三键固定语义（任意工具下一致；中键 / 右键不需要修饰键）：

鼠标键 作用
左键 放置（Select 工具下＝选择）
中键 选择（单选 / 框选 / Shift·Ctrl 多选，等同 Select 工具的左键）
右键 删除光标下的音符

Tap 工具下，左键手势在松手时按两条轴判定（鼠标是否移动 × 是否用滚轮改了时间）：

移动 改时间 结果
否 否 Tap
否 是 Hold（头在按下点 / 时间，尾＝滚轮停下的时间）
是 否 Flick（方向＝按下→松手，吸附最近 45°）
是 是 Slide（从按下点到松手点，自动选中以便继续加节点）
  • 按住左键时用滚轮调整尾时间（鼠标不必在时间轴上），松手提交；Hold 与 Drag 串都在松手时落定。判定「是否改了时间」看的是松手时播放头相对按下时是否移动，因此滚轮以及 , / . 播放头 scrub 快捷键在手势进行中同样有效（方向键移动的是选中音符的时间，不是播放头，故手势中无效）。
  • Shift 改放 Drag 家族：Shift+单击＝单个 Drag；Shift+拖动+滚轮＝均匀分布的 Drag 串（个数 = 当前时间轴刻度在该时间跨度内的格数）。
  • 选中某 slide 或其节点时，单击即向该 slide 追加节点（无需 Shift，优先于新建音符）。

Drag 工具手势与 Tap 工具相同，但 Shift 反转：原本在 Tap 下需要 Shift 的（Drag、Drag 串）在此不需要 Shift；原本不需要 Shift 的（Tap / Hold / Flick / Slide）在此需要 Shift。中键 / 右键照旧不需要 Shift；「单击给选中 slide 加节点」也照旧不需要 Shift。

手势进行中（包括鼠标未按下时）playfield 会实时绘制松手将生成的内容：按住 Shift 时光标 ghost 即变为 Drag（Drag 工具下相反）；按下后随移动与滚轮在 tap / hold / flick / slide / drag 串间即时切换。松手或取消后清除。

经典模式

七个工具：Select / Tap / Drag / Flick / Hold / Slide / Slidetick，主快捷键 X / A / S / D / F / G / Q。当前激活的工具按钮在左侧调色板中以醒目的强调色 + 左侧色条标示，区别于其它未激活按钮。下面的 Hold 两段式 / Slide 多次点击仅描述经典模式。

  • 选中放置工具后在 playfield 点击即放置；时间取当前播放头、位置取鼠标 XY。
  • 处于任一放置工具下时，playfield 内鼠标位置会实时绘制一个半透明的 ghost note 预览，类型 = 当前工具、位置 = 鼠标所在的 chart 坐标（与点击实际放置严格一致，包括 snap 行为）。ghost 在鼠标离开 playfield、切回 Select 工具、Tab 预览模式、或鼠标停在已有 note 上时自动隐藏。Hold / Slide 的 ghost 仅显示头部圆点（不画尾巴 / 路径）。
  • Hold 两段式放置：在 Hold 工具下，第一下点击 playfield 放置 Hold 头（时间 = 当前播放头，位置 = 鼠标 XY，此时尚未写入谱面，只显示一个 pulsing 头部 + 时间轴上一条延伸到当前播放头的虚线）。随后用户自行 scrub 时间轴到期望的尾时间，第二下点击 playfield 任意位置确认尾时间（X/Y 忽略，只用当前播放头作为 end_time）。两段式中按 Esc 或切换到其它工具会取消未完成的 Hold，不写入谱面、不留 undo。若第二下时当前时间不晚于头时间，会拒绝并保留 pending 状态等用户 scrub 后重试。Hold 不再有”默认时长”——尾时间始终由用户的第二下点击决定。
  • Slide 多次点击放置：第一下点击 playfield 放置仅含 head 的 1 点 slide（无默认尾节点 / 默认时长），编辑器自动切到 Slidetick 工具。后续每次点击在当前播放头时间 + 鼠标位置追加一个路径点，按时间排序入位。详见下方「Slide 工具 + Slidetick 工具」一节。

选择操作

操作 方式
单选 点击音符
加选 / 反选 Shift + 点击
框选 在空白区域拖动
时间区域全选 在时间轴上按住 Shift 拖动，选中拖动区间内当前难度的所有音符
全选当前难度 Ctrl+A
取消选择（+ 回到 Select 工具） Esc

上表的「点击 / 拖动」选择操作：经典模式下用左键（Select 工具）；现代模式下任意工具用中键，Select 工具下左键亦可。现代 Esc 为两段式：先清空选择（留在当前工具），无选择时再按一次才回到 Select。

时间区域全选 仅作用于当前难度。拖动方向不影响结果（左→右与右→左等效）。Hold / Slide 以起始时间判定归属：起始点落在区间内即被选中，尾部超出区间不影响；起始点在区间外则不被选中（即使尾部在区间内）。拖动覆盖了无音符的时间段时会清空当前选择，与空白框选行为一致。新的范围选择会替换之前的选择。

当拖动到时间轴左 / 右边缘 40 px 以内时，视图会自动滚动以便选中视口之外的音符。距离边缘越近滚动越快，到达音频起 / 终点时自动停止；松开鼠标即停止自动滚动。

编辑操作

  • 移动：拖动选中音符，时间与位置同步更新；Slide 的路径点可单独拖动。
  • 删除：Del 键。
  • 复制 / 剪切 / 粘贴：Ctrl+C / Ctrl+X / Ctrl+V。粘贴以当前播放头为时间基准，多选内容保持相对时间关系。
  • 镜像：W（水平翻转）、E（垂直翻转）。
  • 切换 EX 变体：选中后按 V，对所有具备 EX 变体的音符（Tap / Hold / Slide）整体切换 Ex-/普通版本。Drag / Flick 没有 EX 变体，会被静默跳过。
  • 时间微调：选中后使用 ← / → 进行小步位移。
  • 音符时间对齐到当前时间：选中单个音符后按 0 或 `，将整体（含 Hold 尾、Slide 路径）整体平移到当前播放位置。
  • Hold 结束时间对齐到当前时间：选中单个 Hold 音符后按 1。若当前时间早于起点会被拒绝。
  • Slide 路径点时间对齐到当前时间：选中单个 Slide 后按 0 ~ 9 对应第 0 ~ 9 个路径点；按 Shift+0 ~ Shift+9 对应第 10 ~ 19 个；左手用户可用 ` / Shift+` 作为 0 / 10 的别名。仅该路径点平移，相邻路径点不会跟随移动；尝试越过相邻路径点的时间会被拒绝。
  • Slide 添加新路径点：选中单个 Slide 后按 Q，在最后一个路径点的位置上以 +0.1 X / +半拍时间 偏移新增节点。Inspector 中的「+ Add point」按钮等价。
  • Slide 路径点 On-time（准）：Inspector 每一行路径点都有一个「准」复选框（取代了之前的「锚」/ fake 复选框 — fake 字段已从谱面格式移除，中间节点与首末节点的区分按位置决定）。勾上（默认）：该路径点的 time 锚定 autoplay / guide-light 的位置——本体在该时刻位于该点。取消勾选：该点只作为几何锚存在，autoplay 不在该 time 锚定，而是用「前后相邻的 on-time 节点对」之间的总弧长 / 总时长算平均速度匀速通过。常用于：纯粹用来塑形的几何锚（Bezier 控制中段、急转弯），其 time 是为画路径而填的而非节拍，标为非 on-time 可避免本体视觉卡顿。首节点与末节点必须保持 on-time，对应复选框禁用。注意：on_time 只影响 autoplay / 预览节奏，不影响判定 / 得分 / SFX。

Slide 节点级编辑（finger-driven 模型）

Slide 的路径节点可以像 tap 一样被单独编辑：

  • 单独选中节点：Select 工具下，直接点击 slide 轨迹上的任意节点（包括 head、tail、中间节点）——选中的是该节点本身，不是整个 slide。Shift+点击可以多选节点。被选中的节点会显示一个暖色描边圆环。
  • 拖动节点：直接在 playfield 上拖动选中的节点更新 (x, y)。
  • 节点时间对齐到当前播放头：0 或 `。会校验相邻节点的时间顺序，越界拒绝。
  • 节点时间微调：左 / 右方向键，按 snap 步长移动。
  • 删除节点：Del。如果删了之后 slide 路径点不足 2 个，整个 slide 也会被删掉。
  • Inspector 单节点模式：选中单节点时，Inspector 只显示该节点的 (time, x, y)、On-time 复选框、+ 可选的 Bezier 控制（见下方）；slide 整体的字段不再显示。重新选中整个 slide 即可回到 slide-level inspector。注：fake 字段已从谱面格式移除，对应的「Anchor」复选框也不再存在；中间节点与首末节点按位置区分。On-time 复选框含义见上一节。

Slide 工具 + Slidetick 工具：多次点击放置

Slide 工具放置 slide 头之后自动切换到 Slidetick 工具（Q），由 Slidetick 接管后续节点的添加：

  1. 在 Slide 工具（G）下点击 playfield 空白处：放置 slide 的 head（节点 0），自动切到 Slidetick 工具。右侧自动切到 Details 选项卡，面板顶部显示黄色 banner「Click to add nodes · Esc 或按钮结束」+ Finish 按钮。
  2. Slidetick 工具的点击：每次都向当前 slide 添加一个路径点（按节点时间自动排序入位）。在两次点击之间可以 scrub 时间轴调整节点时间。Playfield 上会画一条暖色虚线从已有最近时间的节点连到鼠标位置作为预览。
  3. 退出方式：Esc、Enter、Details banner 的 Finish slide 按钮、或切换到其他工具。新增 slide 时退回 Slide 工具（方便接着开下一条），已有 slide 加节点时退回 Select 工具。如果 slide 不足 2 个节点（仅 head），整个 slide 会被丢弃（不进 undo）。

给已有 slide 添加节点：选中某个 slide（或它的任意路径点），按 Q 切换到 Slidetick 工具——之后的点击向该 slide 添加节点，按 Esc 回到 Select。也可以从工具栏直接点击 Slidetick 按钮（行为相同，需要先有选中的 slide）。

Slide Bezier 曲线段

Slide 路径段可以选择直线或二次 Bezier 曲线。每段的弯曲由该段结束节点的 curve_in 字段决定（详见 chart_format.zh.md 的 Bezier 章节）。

  • 打开 Bezier：选中某个中间节点（不能是 head），用以下任一方式：
    • 在 Inspector 的「Curve in」勾选「Bezier」
    • 按 B 键快速切换 控制点初始化为该段的几何中点（零弯曲）。
  • 拖动控制点：选中的 Bezier 节点会在 playfield 上显示一个冷蓝色的控制点拖柄 + 两条虚线指示器连接 prev → cp → this。直接拖动控制点即可调整曲线形状。
  • 精确输入：Inspector 在 Bezier 模式下额外显示 CP X / CP Y 两行 SpinBox，用于精确数值输入。
  • 关闭 Bezier：再按一次 B，或把「Curve in」复选框取消勾选，该段恢复为直线（保存时序列化器会自动省略 cp_x / cp_y 字段）。

六、Inspector 面板

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

  • Time：触发时间（秒）
  • X / Y：位置坐标（归一化范围 0.0–1.0）
  • End time：结束时间（适用于 Hold 与 Slide）
  • Direction：方向角（适用于 Flick）
  • Approach ring overrides：每音符的提示圈时长与大小倍率，1.0 表示沿用全局设置
  • 准（Slide 路径点 On-time）：该路径点的 time 是否锚定 autoplay / guide-light 节奏；取消勾选则该点变成几何锚（只塑形不锚时）。首节点与末节点必须保持 on-time，复选框禁用。详见 Slide 路径点 On-time 一节。

时间字段的合法性校验：

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

小节表示（Measure / Beat）

每个时间字段（音符 Time、Hold 的 End、单节点 Time、以及 Slide 每一行路径点的 time）的 ms 输入框下方都附带一行小节表示，采用与底部时间轴小节读数一致的约定：[小节]·[拍]·[N] / [D]分音符。小节 / 拍 / N / D 四个值都可编辑。

  • 小节 / 拍：1 起算，并跟随各 BPM 段的拍号（beats_per_measure / beat_unit），与时间轴的小节编号一致。
  • N / D 分音符：D 是「几分音符」的分母（每全音符的分割数，例如 4 = 四分、8 = 八分、16 = 十六分、12 = 三连音）；N 表示「该拍之后第几个 1/D 全音符」。例如 1·2·1 / 12 分 = 第 1 小节第 2 拍之后的第 1 个十二分音（三连音）。以整数计数，三连音 / 非 4/4 / 非二分拍都能精确表示，不会出现除不尽的小数。
  • D 与 snap 解耦、按音符自动取最简：D 不绑定全局 snap 颗粒度，而是把该音符相对拍头的偏移化成最简分数自动给出——分母取能整除该位置的最小整数（最高到 192 分），再按下限规整：本可约到 1 分 / 2 分的位置归到 4 分，可约到 3 分的归到 6 分；4 分及以上原样显示（含五连音 5、七连音 7 等奇数连音）。所以拍正中显示 0/4，拍的 ⅔ 处显示 1/6（而不是没约分的 2/12），五分线上的音符显示 1/5。D 也可手动改写，把同一时间换算到另一个分度上表示（此时不强制约分）。
  • 双向同步：编辑 ms 框会同步更新小节行（并按新位置重新判定 D）；编辑小节 / 拍 / N 会按当前 D 的栅格反算出时间写回 ms 框，并复用同一套撤销 / 校验逻辑（Hold End ≥ 起始、路径点不得早于前一点）。N 加减越界会自动进位到下一拍 / 下一小节。改写 D 只是把同一时间换一种分度表示，不会移动音符。
  • 精度：音符的真实时间是全精度浮点（不是 ms 框那个整数毫秒）；自动判定直接读这个真实时间，编辑小节行写回的也是全精度的精确时刻——和在下方时间轴跳到同一位置再放置 note 完全一致，不会被取整到毫秒。ms 框只是同一时间的「整数毫秒」视图 / 编辑入口。
  • Duration（Hold 时长）：作为「时长」而非「位置」，显示为拍数 / 小节数（如 1.5 beat 或 1 measure + 2 beat），跨 BPM / 拍号变化时按段积分，跨越时以 ≈ 标注、悬停显示精确毫秒。

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

七、时间轴与播放控制

  • 播放 / 暂停：Space 或工具栏按钮。
  • 播放速度：0.25× / 0.5× / 0.75× / 1× / 1.25× / 1.5× 预设。当前实现使用 Godot pitch_scale，速度变化会同时影响音高。
  • 跳转：直接点击时间轴任意位置，或在时间输入框中输入精确毫秒数。
  • 键盘扫描：, / . 按一个吸附细分（关闭吸附时为 10 ms / 0.5 s）前后移动当前时间，长按可连续滚动；与鼠标滚轮在 playfield 上的滚动等价。
  • 缩放：Ctrl + 鼠标滚轮、键盘 Ctrl+. / Ctrl+,，或时间轴控件行右端的 + / − 按钮。三种方式步进一致（×0.8 / ×1.25 倍，范围限制 1 s ~ 120 s）。
  • 水平平移：中键拖动。

八、预览模式

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

可配置参数：

  • Ring Speed：与游戏设置同义，缩圈基础窗口为 3.0 / speed 秒；例如 5.0x 对应 0.6s
  • Ring start scale：提示圈相对音符的起始大小（默认 3×）
  • 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 重做。撤销栈覆盖所有谱面编辑操作（放置、删除、移动、属性修改、批量操作、镜像）。

谱面检查（实时）

编辑器持续对当前难度做轻量「体检」，把问题计数显示在顶部工具栏「垂直镜像」右侧的徽章按钮上（也通过 编辑 → 谱面检查... 入口）。每次新增、删除、移动 note 后自动重算。目前包含两类检查：

叠 note 检测——扫描有重叠风险的 note 对：

  • Error（✕ 红色徽章）：两 note 的「头部」时间相差 ≤ 10ms 且中心距 ≤ 60px（按 1920×1080 参考分辨率换算）。几乎一定是误操作。
  • Warning（⚠ 黄色徽章）：其它情况下的相邻关系——head-on-head 但 60 < d < 80px（紧凑和弦风险）、或 Hold 持续段 / Slide 路径与其它 note 发生 80px 内的接触（玩起来合法但值得知会）。
  • Drag note 完全不参与叠 note 检测（drag 与任何 note 重叠都是合法输入）。

区域外警告——「限制放置范围」开启时，把任何落在允许区域外的音符（旧谱 / 导入谱里的边缘 note）标为 Warning，只提示、不修改谱面（详见上文「限制放置范围」）。

点击工具栏徽章或菜单项弹出列表对话框，按 error→warning、再按时间排序。点击列表中的一行：playhead 跳到该 note 的时间并单选它（叠 note 对的 B 在同一时间段内显示在 playfield 中，便于人工判断）。

从其他难度导入元数据

在 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
    • 音频文件
    • 封面图（如已配置）

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

十二、设置项说明

通过顶部工具栏「垂直镜像」按钮右侧的「设置…」按钮，或菜单栏「编辑 → 设置…」打开设置弹窗。除「Song ID」会写入 song.json 外，其余设置都是编辑器本地偏好（写入 editor_prefs.cfg），不会进入 .yzc.json 谱面或 .yzcpkg 包。

放置模式（设置弹窗顶部）

项 说明
交互方式 切换 现代（默认，手势驱动的 Select / Tap / Drag 三工具）或 经典（按音符类型分的传统七工具）。两种模式的具体操作见「五、音符放置」。切换后左侧工具栏会立即重建。

自 0.20.0 起音符浮现动画恒为开启，相关开关已从设置中移除（旧的 preview.animation_enabled 偏好会被忽略）。

Song 属性

项 说明
Song ID 谱面包的唯一标识，仅允许 a-z / 0-9 / _。留空时保存时会从 Title 自动派生。该值会写入 song.json，发布后不要再改（玩家分数与 Song ID 绑定）。

预览设置（仅影响编辑器内的快照渲染，不写入谱面）

项 说明
方形 Hold / Slide 本体 将 Hold / Slide 的持续段本体由默认的六边形改为方形（圆角矩形），对应游戏内「方形 Hold 音符」开关。仅影响编辑器预览，不写入谱面。
多押提示（仅 Tab 预览时显示） Tab 预览模式下同时刻多 note 的提示：关 / 光晕（边缘发光）/ 线条（连接线）/ 光晕和线条。仅 Tab 预览生效，普通编辑视图不画。
缩圈速度 缩圈基础速度，1.0× ~ 10.0×（步进 0.1）。speed × duration = 3.0，即 5.0× 对应 0.6s 缩圈窗口。和游戏内的「缩圈速度」同名同义。
预判环起始缩放 缩圈相对 note 半径的起始大小，1.0 ~ 10.0（默认 3.0），即起始时缩圈是 note 半径的 3 倍。
音符大小 note 半径预设档位，1 ~ 5（5 个离散档位，和游戏内「音符大小」一一对应）。

编辑模式幽灵（编辑视图中的「未来 / 已过去」note 虚影）

项 说明
显示未来音符幽灵 当前时间之后一段时间内的 note 显示为低 alpha 虚影，便于参考下一个 note 的位置。
幽灵前瞻时间（秒） 上面那段「一段时间」是多久，0.1 ~ 600 秒。
显示已过音符幽灵 当前时间之前一段时间内已过去的 note 也显示为虚影，便于参考刚放过的 note。
已过幽灵时长（秒） 同理，0.1 ~ 600 秒。

自动保存

项 说明
自动保存间隔（秒，0 = 关闭） 自动保存间隔，0 关闭。默认 60。只在项目已经至少手动保存过一次后才会触发（新建未命名项目不会自动保存）。

自动保存采用非破坏性恢复快照：写入独立的恢复 sidecar，不覆盖原工程文件。下次打开同一工程时若检测到更新的恢复快照，会提示是否从快照恢复，避免崩溃 / 异常退出丢失编辑。

界面与字体

项 说明
UI 缩放 × UI 缩放倍率，0.0 ~ 3.0（步进 0.05）。0 表示根据窗口大小自动；非 0 时强制使用该倍率。
语言 界面语言：English / 简体中文 / 繁體中文 / 日本語。切换后立即生效。

时间轴波形

项 说明
时间线波形（首次播放时捕获 — 3 分钟歌曲约 45 秒） 启用时间轴下方的波形显示。首次启用 + 首次播放时实时抓取，之后写入缓存。⚠️ 抓取期间请使用内置扬声器或有线输出，蓝牙会因异步时钟导致波形漂移。

音频音量

项 说明
音乐音量 谱面音频在编辑器播放时的音量，0 ~ 200%（100% 为原始增益，0% 静音）。仅影响编辑器试听，不影响导出包。

打击音（Hit SFX）

四个独立声道，每个声道都可单独开关 + 单独指定自定义音频文件（留空则使用内置音效）：

声道 触发条件
主音（tap / hold 头 / slide 头） Tap / Hold 起点 / Slide 起点
Drag（hold 尾 / slide 节点 / drag） Drag / Hold 终点 / Slide 路径点
EX（ex-tap / ex-hold 头 / ex-slide 头） Ex-Tap / Ex-Hold 起点 / Ex-Slide 起点
Flick（flick 音符） Flick

界面布局

项 说明
重置布局 把所有 sidebar / 时间轴分割条位置恢复到默认值。不影响其他设置。

重置全部

项 说明
重置所有设置 把上述所有编辑器偏好（不含 Song ID）一次性恢复为默认。无二次确认对话框，谨慎使用。

快捷键速查

操作 快捷键
保存 Ctrl+S
撤销 Ctrl+Z
重做 Ctrl+Y
复制 / 剪切 / 粘贴 Ctrl+C / Ctrl+X / Ctrl+V
全选 Ctrl+A
取消选择 + 回到 Select 工具 Esc
删除选中 Del
播放 / 暂停 Space
预览模式切换 Tab
当前时间前后扫描 , / .
时间轴放大 / 缩小 Ctrl+. / Ctrl+,（或时间轴控件行右端的 + / − 按钮）
时间微调 ← / →
水平镜像 W
垂直镜像 E
切换 EX 变体 V
加选 / 反选 Shift + 点击
框选 空白区域拖动
时间区域全选 时间轴上 Shift + 拖动
切换工具 Select / Tap / Drag / Flick / Hold / Slide X / A / S / D / F / G
音符时间 → 当前时间 0 或 `
Hold 结束时间 → 当前时间 1
Slide 第 N 路径点 → 当前时间（N = 0 ~ 9） 0 ~ 9 或 `（对应 0）
Slide 第 N 路径点 → 当前时间（N = 10 ~ 19） Shift+0 ~ Shift+9 或 Shift+`（对应 10）
Slide 添加新路径点 Q

注意事项

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