制谱器使用指南
Theseus Chart Editor 完整操作手册：谱面制作全流程、三种编辑模式、快捷键与常见问题
Theseus Chart Editor（下称"制谱器"）是 Theseus 的官方谱面制作工具：一个 桌面应用（Android 版正在开发中，尚未发布），负责谱写音符、编排事件、实时预览并保存为游戏可加载的谱面文件。
本文覆盖从打开到保存的完整操作流程。想了解谱面 JSON 格式或制作编辑器插件，请看制谱器开发文档。
获取与启动
制谱器随游戏工具包分发，也可单独获取 theseus-chart-editor 可执行文件：
- 桌面版：双击 exe 启动；首次启动若提示 GPU 缓存权限问题，程序已自动禁用磁盘缓存，无需处理。
- Android：正在开发中，尚未发布；发布后安装 apk 即可启动，界面支持触控拖拽分栏。
打开与创建谱面
一个完整谱面在磁盘上是三件套：
| 文件 | 作用 | 是否必需 |
|---|---|---|
| 主谱面 JSON | 元信息、音频引用、BPM、notes 音符数组 | 是 |
同目录 xxx_extra.json | 事件（额外内容）items 数组 | 否，缺省视为无事件 |
| 音频文件 | OGG / MP3 / WAV，位于音频目录 | 预览需要 |
制谱器的入口列表中选择谱面文件夹或 JSON 打开；也可以新建空项目先体验界面。加载时制谱器会同时读取这两个文件，未知字段一律原样保留——包括插件声明的顶层 extensions 段（详见开发文档）。
基础流程走通
第一次做谱建议按以下顺序走一遍：
- 选音频：在元信息面板指定音频文件路径与偏移（offset，毫秒，用于对齐人声前奏）。
- 定时基：在 timingPoints 中设定 BPM 与起始时间；多段变速谱可加多个时间点。时间轴网格、吸附全部由这里驱动。
- 滚动速度：scrollSpeed 控制预览下落速度，随手感调整。
- 移动光标：
Space播放/暂停，←→移动光标；网格与吸附随 timingPoints 自动生成。 - 放置内容：切到音符编辑模式放音符，或在事件模式加表演事件。
- 保存：
Ctrl+S同时写回主谱面 notes 字段与_extra.json事件文件。
事件编辑模式
启动后的默认视图。屏幕自左至右分为三个区域：
- 机架（左）：按目标实体分组列出可创建的事件类型。点选一组后组内子轨道显示在下方；点击某类型即可"选中待创建状态"，再在时间轴空白处左键落点创建。所有事件仅创建你指定的那一种，不会自动附带伴随事件。
- 时间轴（中）：横向布局，X = 时间。事件块可左右拖动改时间，带动画的事件块右端有结束手柄可拉伸时长。鼠标滚轮横向滚动。
- 属性面板（右）：当前选中事件的参数表单。开启"继承"设置后，新建同类事件会自动带入上一个同类事件的参数；切轨也会保留常用值。
常用操作：
- 框选：空白处按下拖出矩形；
Ctrl点击追加选择；Delete删除所选；Ctrl+D原位复制。 - 复制/剪切/粘贴：
Ctrl+C/Ctrl+X/Ctrl+V，粘贴对齐当前光标位置。剪贴板跨谱面可用（甚至关闭重开后仍可粘贴）。 - 时间定位：
Home回到开头；数字键1-5快速把光标送到对应轨道；Ctrl+F打开搜索，可按类型/文本过滤定位事件。 - 切割：选中一个带动画的移动事件后按
F，在光标处切成两半（后半自动接续动画起点）。
竖向事件编辑模式
点击时间轴上方按钮切换到竖向布局：Y 轴 = 时间，判定线（光标）固定在视口中央，上方是未来、下方是过去，适合密集编排时的俯视全局。
- 顶部轨道组列表：列出"假轨道 N""轨道 N""全局"等所有分组，点击切换显隐（多选）。全关时自动保留第一组；可见组平分宽度，窗口太窄会依次隐藏后续组。
- 组内按操作类型再拆子轨道列，事件块只能沿时间上下移动，实体归属不可变。
- 双击空白处：在该列该时刻创建此类型事件（继承设置同样生效）。
- 单击扩展段标记：光标跳转到该时间（只读投射，见下方"扩展段表单"）。
音符编辑模式
通过应用菜单 Edit →「音符编辑模式」勾选切入（Android 平台为工具栏上的同名开关按钮）。此时隐藏次要工作区，专注 note 排布：左侧纵向轨道（轨道数与谱面 lanes 一致）、右侧属性面板、旁边是一条竖直音符时间线。向上 = 未来、向下 = 过去。
放置与删除
按键即放（默认键位，可在设置中改）：
| 键 | 行为 |
|---|---|
Q | 在光标处放置普通音符（NORMAL） |
E | 放置长按音符（HOLD）；对已有 HOLD 再按一次转为 NORMAL |
B | 放置防火墙（BARRIER） |
I | 放置漏洞利用（EXPLOIT） |
P | 放置载荷（PAYLOAD），自动关联同轨最近的前置 EXPLOIT |
W | 删除光标处的音符（±30ms 容差匹配） |
- 新建 HOLD 默认
endTime = time + 500ms。 - 删除 EXPLOIT 时，关联 PAYLOAD 一并自动删除。
- "放置类型"下拉在属性面板 SNAP 区下方，列出内置 + 插件注册的全部类型，
Q会按所选类型放置。 - 无序模式标记：
Shift+S/E/F/G放置充能起止与无序模式起止标记。
选择与修改
- 框选：空白处拖动超过 5px 出现绿色虚线框；
Ctrl+点击加选/减选。 - 整体拖动：按住选中音符拖动，出现半透明预览，松手吸附到当前 SNAP；向下拖减小时间，向上拖增大。
- HOLD 尾端：拖
[==]手柄调整 endTime，最短 100ms。 Ctrl+M镜像选中音符（lane 翻转），Ctrl+Shift+F时间翻转（围绕光标）。- 撤销/重做：
Ctrl+Z/Ctrl+Shift+Z，每次拖动手势合并为一个撤销条目。 - 复制粘贴：
Ctrl+C/Ctrl+X/Ctrl+V，粘贴相对当前光标偏移排列。
光标与吸附
| 键 | 行为 |
|---|---|
↑ / ↓ | 光标按当前步长上移/下移（上移 = 向未来） |
PageUp / PageDown | 大跨度移动（4 拍） |
Ctrl+1/2/4/8 | SNAP 切换为 1/1、1/2、1/4、1/8 拍 |
| 鼠标滚轮 | 视口纵向滚动 |
Alt+滚轮 | 视口横向滚动（多轨并行编排出全景） |
SNAP 数值也可直接在属性面板点按切换。
预览面板
底部或侧边的预览区实时渲染游戏画面效果：真实轨道 + 假轨道 + 假音符 + 文字/文本框 + 插件滤镜全部参与。播放时光标随音乐同步；暂停后用方向键或点击时间轴移动光标，画面立即跳转到对应时刻。
- 预览与游戏的变换中心保持一致（背景、音符和快捷盒共用 centerX / rotCy / scaleCy），所见即所得。
- 若插件滤镜执行异常，该滤镜会被自动停用并在通知里说明一次，不影响其他插件与本体渲染。
多标签页
通过顶栏按钮展开标签菜单可同时打开多个谱面，每个标签页独立持有自己的音符、事件与编辑状态（缩放、进度、模式）。同一音频被复用时，切换标签会把光标恢复到该标签离开时的位置。事件与音符剪贴板在各标签间通用。
扩展段表单
当已安装的编辑器插件声明了 extensions 段 schema 时，右侧属性面板会出现"EXTENSIONS"分区：每个注册过的 key 一张卡片，按 schema 渲染成 number/boolean/select/text 表单，校验错误就地红字提示。
- 声明了 timeField 且数据为数组的段，会同时投射到竖向事件编辑模式的只读轨道，点击标记即可定位。
- 谱面里存在但未注册插件的 key，以只读折叠卡展示原始 JSON——保证数据无损查看。
- 保存时 extensions 原样写入主谱面 JSON，不经过任何归一化。
设置项速览
设置面板（齿轮图标）内可调整：
- 快捷键：全部动作可视化绑定，冲突即时提示；
- 事件继承：新建/切轨是否继承上次参数；
- 皮肤：默认字符皮肤或自定义图片皮肤文件夹（把 png 文件名对齐符号即可自动识别）；
- 增强渲染：HOLD 蓝色/PAYLOAD 橙色以及同 lane 连接入开关；
- 纯键盘模式：忽略鼠标位置，光标只跟键盘（适合盲打流）。
快捷键总表
以下为默认键位（设置面板可自定义）。斜杠表示同一键在不同模式下含义不同。
全局
| 键 | 动作 |
|---|---|
Space | 播放 / 暂停 |
Ctrl+S | 保存（主谱面 notes + _extra.json） |
Ctrl+Z / Ctrl+Shift+Z | 撤销 / 重做（音符与事件栈独立） |
Delete | 删除选中 |
Ctrl+D | 复制（原地重复选中项） |
Ctrl+C / Ctrl+X / Ctrl+V | 复制 / 剪切 / 粘贴 |
← / → | 光标左移 / 右移 |
1-5 | 选择轨道 1-5 |
Ctrl+F | 搜索 |
Home | 返回歌曲开头 |
F | 切割事件块 |
音符编辑模式
| 键 | 动作 |
|---|---|
Q / W / E / B / I / P | 放置 NORMAL / 删除 / HOLD / BARRIER / EXPLOIT / PAYLOAD |
Ctrl+M | 镜像选中音符 |
Ctrl+Shift+F | 时间翻转选中音符 |
↑ / ↓ | 光标上移（未来）/ 下移（过去） |
Ctrl+1/2/4/8 | SNAP 切换 |
PageUp / PageDown | 大跨度光标移动（4 拍） |
Shift+S/E/F/G | 无序模式：充能起点 / 充能终点 / 模式起点 / 模式终点 |
常见问题
音频没声音？ 检查音频文件路径（相对谱面目录或绝对路径均可），以及 audio.offset 是否误设过大导致整曲静默前移。
保存后游戏里看不到事件？ _extra.json 必须与主谱面同名放在同一目录（如 song.json 对应 song_extra.json），命名不一致时游戏不会加载。
我手写的 JSON 被"改坏"了吗？ 制谱器只在保存时写回 notes / disorderMarkers / items 这些它管理的字段；其余顶层字段（含 extensions、备注、私有数据）原样保留。个别看似消失的字段多半是缺少合法 seq 或 trigger 结构导致的规范化补全。
插件音符在预览里显示成字符？ 未命中内置图片且皮肤文件夹中没有 <typeKey>.png 时，回落为字符符号绘制。请检查皮肤文件名或联系插件作者补充资源。
按键不起作用？ 先确认不在输入框聚焦状态；再到设置面板查看该动作的当前绑定（可能已被修改或冲突禁用）。