Dakumi 编辑器使用文档（Edit 界面）
界面布局
编辑界面包含预览区、编辑区、侧边栏，以及上方工具栏：
示意图用来辨认区域；具体按钮和配色以实际软件为准。
| 区域 | 位置 | 功能 |
|---|---|---|
| 游玩区域（Demo） | 左侧大区域 | 实时预览谱面，显示轨道、Note、判定线 |
| 编辑区域（Edit） | 右侧竖条区域 | 分轨道编辑 Note 和 Event |
| 工具栏（EditTool） | 顶部/侧边工具条 | 放置/切换工具、节拍、轨道、速度等控制 |
| 侧边栏（Sidebar） | 最右侧 | 谱面信息、设置、轨道与对象属性 |
一、工具栏（EditTool）
工具栏位于编辑界面顶部，包含以下功能：
保存（Save）
- 快捷键：
Ctrl + S - 保存到当前选中的谱面文件（新建谱面默认名为
chart.json） - 保存失败会提示原因；已生成 JSON 时可选择复制到剪贴板，再粘贴保存为
.json文件 - 每 60 秒自动保存一次（可在设置中关闭）
- 退出时提示是否保存
播放控制（Music Play）
- 快捷键：
Space - 播放/暂停音乐
- 播放时会自动跟随节拍滚动
节拍（Denom）
- 快捷键：
↑/↓调整节拍分度 - 控制节拍线密度（1/4、1/8、1/16 等）
- 数字越大，可吸附的节拍越细
缩放（Scale）
- 控制编辑区域的纵向缩放比例
- 数值越大，每拍占用的像素越多，同一屏显示的拍数越少
轨道（Track）
- 快捷键：
←/→切换轨道 - 选择当前编辑的轨道编号
- 切换后编辑区域会显示对应轨道的 Note 和 Event
围栏（Fence）
- 设置轨道的围栏数量
- 用于辅助定位 Event 的 x 位置
播放速度（Speed）
- 控制音乐播放速度（0.1~）
- 不影响谱面，仅用于预览
Note 假 Note 开关（Note Fake）
- 开启后放置的 Note 会被标记为假 Note
- 假 Note 在游玩中不显示判定，用于练习/装饰
Hold 头部 Note 开关（Note Head）
- 开启后放置的 Hold Note 头部会附带一个 Tap Note
- 用于需要同时按住和点按的谱面
Hold 头部 Wipe 开关（Wipe Head）
- 开启后放置的 Hold Note 头部会附带一个 Slide Note
二、游玩区域（Demo 区域）
轨道显示
- 显示所有轨道的实时位置（由 Event 驱动）
- 轨道编号和名称显示在判定线上方
- 当前选中的轨道会高亮显示
- 围栏线辅助对齐 Event 位置
判定线（Judge Line）
- 位于游玩区域中间
- Note 到达判定线时即为击打时机
- 进度条显示当前播放进度
实时信息
- edit 区顶部信息行显示当前轨道的 x、w、lpos、rpos
- 下方信息面板显示当前节拍、时间和轨道信息
- demo 区显示鼠标位置、围栏位置及 Note / Event 总数
轨道选择
- 在游玩区域鼠标左键点击轨道，可切换到该轨道
- 如果多轨道重叠，会自动切换选择
当前鼠标 x 位置
- 鼠标悬停在游玩区域时，显示当前 x 值和最近的围栏 x 值
三、编辑区域（Edit 区域）
标签页与编辑选项
上方 + 增加标签页，各标签可选择轨道并独立开关 note、x、w、lpos、rpos 栏。未聚焦标签上的按钮也可以点击。多标签页中的框选和粘贴按目标标签轨道放置；切回单标签时，标签页复制表会转换为 demo 区来源的复制表，普通粘贴及包含事件的粘贴规则随之使用 demo 来源规则。
分度、缩放、当前轨道、栅栏、播放速度和放置开关保存在各谱面旁的 <谱面文件>.editToolData，不再共用全局编辑数据；文件不存在时自动创建。移动谱面可一起移动这个文件。
编辑区域分为五个轨道栏目，从左到右依次为：
| 栏目 | 内容 |
|---|---|
| Note（音符） | 显示当前轨道的所有 Note |
| x（x 位置） | 轨道的 x 位置 Event |
| w（宽度） | 轨道的宽度 Event |
| lpos（左位置） | 轨道左边界位置 Event |
| rpos（右位置） | 轨道右边界位置 Event |
Note 编辑
- 放置 Note：快捷键
Q - 放置 Wipe（滑动）：快捷键
W - 放置 Hold（长条）：快捷键
E- 第一次按 E 放置头，第二次按 E 放置尾
- 删除：快捷键
D，删除鼠标附近的 Note/Event - 假 Note：在工具栏打开假 Note 开关后放置
Event 编辑
- 放置 Event：快捷键
E（在 Event 轨道上）- 根据鼠标所在轨道自动选择 Event 类型（x/w/lpos/rpos）
- 第一次按 E 确认头和 from 值，第二次按 E 确认尾和 to 值
- Event 支持两种过渡类型：
- Bezier（贝塞尔曲线）：通过两个内部控制点的四个坐标数定义变化曲线
- Easings（缓动函数）：通过预定义的缓动函数定义变化曲线
事件组编辑
- 在侧边栏打开“事件组”，输入名称并新建，或点击已有事件组的名称。
- 编辑区会切换到该事件组的一条轨道，左侧只预览这一组的事件。此时标签页暂时不可用。
- 在 x、w、lpos、rpos 栏按
E放置事件，按D删除；也可以像普通轨道一样修改事件、框选和撤销。 - 点击侧边栏的“退出事件组编辑”，或切换轨道，即可返回谱面。保存谱面时，组内修改也会一起保存。
- 回到普通谱面后，在事件栏按两次
T可放置事件组引用。引用所在轨道的这段时间内不能再放置其他事件或事件组。
框选（Select）
- 按住
Shift拖拽鼠标进行框选 - 在拖框时按 Shift 确认选择；也可按住 Shift 拖拽后松开确认
- 选中后按
Escape取消选择
快捷操作
- 右键点击 Note/Event：加入/取消选择
- 鼠标滚轮：纵向滚动节拍
- 按住 Ctrl + 滚轮：加速滚动
四、侧边栏（Sidebar）
侧边栏位于编辑区域右侧，显示详细信息和编辑面板。
功能入口
在侧边栏 nil 界面（未选择任何编辑模式时），点击按钮进入：
| 按钮 | 功能 | 快捷键 |
|---|---|---|
| Chart Info（谱面信息） | 编辑曲名、谱师、艺术家、偏移量、BPM 列表 | - |
| Preference（偏好） | 调整 x 偏移、Event 缩放 | - |
| Track（轨道列表） | 查看、切换、筛选和编辑轨道 | - |
| Settings（设置） | 全局设置与改键位 | - |
| 操作历史 | 查看操作、节拍范围并跳转到历史状态 | - |
| 事件组 | 新建事件组，进入单轨编辑，或删除事件组 | - |
| Equalizer（均衡器） | 音频均衡器调节 | - |
| Takana（导出） | 导出为 Takana 谱面格式 | - |
操作历史、均衡器、takana 为外部插件，入口位于设置下方。右上角的返回图标退出当前页面；网站与 GitHub 改为右下角图标，Dakumi 在 GitHub 左边。
Chart Info（谱面信息）
- 编辑曲名、艺术家、谱师名称
- 调整偏移量（Offset，单位 ms）
- 管理 BPM 列表：
- 点击
Add在当前节拍位置添加 BPM 变化点 - 点击
Sub删除 BPM 变化点 - 自动按节拍排序
- 点击
- 点击提示按钮（勾）保存修改
自动测量 BPM 与 offset
在谱面信息中，点击 BPM 表上方的「测量 BPM 与 offset」。程序会在后台分析当前音乐，完成后弹出系统确认框，显示测量结果。选择填入，会同时更新 offset 和第一项 BPM；其它 BPM 变化点保持原样。选择不填入或关闭弹窗，不会修改谱面。
填入会产生一条「测量 BPM 与 offset」操作历史，可以一次撤销或重做。之后仍需按正常方式保存谱面。测量期间切换谱面或音乐，旧结果会自动丢弃。
这里的 offset 沿用 qwwshs/bpm 的测量含义：音乐开头的静音时长，并不是自动识别第一拍。Dakumi 会换算成自己的偏移方向，例如开头有 240 ms 静音，就填入 -240 ms。没有开头静音但第一拍较晚的音乐，仍需手动对齐。
本功能只估计一个整体 BPM，不会生成变速表。节奏变化较大或结果不稳定时会在弹窗中提示，请试听核对。使用 LuaJIT 后台计算，不需要安装原库的命令行界面或额外音频工具；目前支持 2 秒至 30 分钟的音频，非 32/44.1/48 kHz 采样率会先转换到 44.1 kHz。
Preference（偏好设置）
- x_offset（x 偏移）：调整所有轨道的整体 x 偏移
- event_scale（Event 缩放）：调整 Event 数值的缩放比例
- 修改后点击提示按钮保存
Settings（设置）
| 设置项 | 说明 |
|---|---|
| Hit | 开启/关闭打击特效 |
| Hit Sound | 开启/关闭打击音效 |
| Hit Volume | 打击音效音量 |
| Hit Time | 打击特效持续时间 |
| Hit Light Time | 打击光效持续时间 |
| Wavfrom | 开启/关闭波形图显示 |
| 声纹图 | 开启编辑区频率图；可与波形图同时显示 |
| 分析方式 | 鼓点起止、均衡、谐波分线、低音细节 |
| 细节取舍 | 分线优先显示窄而清楚的峰；弱音优先压低强音旁边的杂光 |
| 频率尺样式 | 音名/MIDI、对数频率、均匀间隔 |
| 左端 / 右端频率 | 设定图上由左到右显示的频率范围（Hz） |
| 显示下限 / 显示上限 | 设定变色范围（dB）；下限以下变透明，上限以上最亮 |
| 亮度增益 | 只改变图的颜色，不改变播放音量（dB） |
| 声纹不透明度 / 频率尺 | 调整图像透明度，或控制顶部信息行下方的频率刻度是否可展开 |
| Contact Roller | 鼠标滚动灵敏度 |
| Auto Save | 自动保存开关 |
| Default Trans Type | 默认过渡类型（easings/bezier） |
| Bg Alpha | 背景透明度 |
| Denom Alpha | 节拍线透明度 |
| Music Volume | 音乐音量 |
| Track W Scale | 轨道宽度倍数 |
| Note Height | Note 高度 |
| Judge Line Y | 判定线 Y 位置 |
| Angle | 3D 倾斜角度（预览效果） |
| Window Width/Height | 窗口尺寸 |
| Language | 语言设置 |
- 修改后点击提示按钮保存
设置侧边栏顶部点击“展开改键位”，即可查看各项操作的当前键位。点击要修改的键位，在弹出的小窗口中按下新键位或组合键；松开所有按键后，点击“确认”会立即生效，并保存到 users/key.json。点击“取消”则保留原键位。改键位无需再按设置页底部的保存按钮。
打开声纹图后，点击 x、w、lpos、rpos 信息行最右侧的展开按钮，可在信息行下方展开频率尺；默认收起。在尺上滚动可缩放，按住 Shift 滚动可左右移动显示范围；滚轮在谱面编辑区内仍用于节拍滚动。音名尺显示理论频率位置，不会自动识别歌曲里的音高。
普通人声和大多数旋律先选“谐波分线”；想查看鼓点的起止可选“鼓点起止”；想细看低音可选“低音细节”。长窗口能分清更接近的音高，但短促声音会沿时间方向占据更宽区域；需要对齐鼓点时改用短窗口或同时打开波形图。更多设置建议见声纹图使用说明。
Track（轨道列表）
- 显示所有轨道的编号及当前 x、w 值
- 第一行的切换当前轨道按钮和编辑当前轨道按钮在同一行
- 鼠标在列表上滚动可改变滚动条；展开筛选类型下拉框时，滚轮只操作下拉框
- 点击“轨道筛选”可展开或收起筛选区域；可按 x/w 位置范围、轨道名称或轨道设置项查找。名称及文字设置支持包含匹配，数字按精确值匹配，开关可选“开/关”
- 点击轨道编号切换到该轨道
- 点击
Edit进入轨道属性编辑
Track Edit（轨道编辑）
- Track Name（轨道名称）：为轨道设置名称
- Do Not Hide（不隐藏）：开启后即使 w=0 也显示轨道线
- Parent（父轨道）：设置父轨道编号，子轨道的 x 值会叠加父轨道 x
- 跟随父轨道缩放：开启后子轨道位置和宽度跟随父轨道宽度；关闭时只叠加父轨道位置
- 绘制顺序（zindex）：调整轨道显示顺序
- 边界：无边界、固定坐标或参考其他轨道；固定坐标中的 0 是有效值
- 点击侧边栏右上角返回图标退出；修改需点击页面的确认按钮应用
Event（事件编辑）
选择了一个 Event 后进入该界面：
- from / to：编辑 Event 的起始值和结束值
- 同上/同下：快速复制数值
- Trans Type（过渡类型）：切换 Bezier / Easings
- Bezier 编辑：
- 通过逗号分隔的 4 个数值控制贝塞尔曲线
- 可从预设贝塞尔列表中选取
- 右侧显示实时曲线预览
- Easings 编辑：
- 滑块选择缓动函数索引
- 右侧显示实时曲线预览
- 数值在编辑期间应用到选中的 Event；离开页面时合并为一次历史，确认应用后可撤销
- 事件组引用还可选择组名、水平翻转和时间翻转，见事件组说明
Note（音符编辑）
选择了一个 Note 后进入该界面：
- Fake（假 Note）：设置 Note 是否为假 Note
- Note Head（Hold 头部 Note）：是否在 Hold 头部附带 Tap Note
- Wipe Head（Hold 头部 Wipe）：是否在 Hold 头部附带 Slide Note
Events（批量事件编辑）
选中了多个 Event 后进入该界面：
- 快速调整：上下按钮切换 Bezier/Easings 预设
- 执行（Do）：对选中的 Event 批量执行数值变换
- Perturbation（扰动）：随机偏移量
- From / To：数值变化范围
- Trans Expression（过渡表达式）：
- 支持
bezier 1、easing 5、function x^2等表达式 - 右侧显示实时曲线预览
- 支持
五、快捷键汇总
基础编辑
| 按键 | 功能 |
|---|---|
Q | 放置 Note |
W | 放置 Wipe |
E | 放置 Hold / Event |
T | 放置事件组引用，再按一次完成 |
D | 删除鼠标附近的 Note/Event |
Tab | 打开/关闭预览模式 |
Space | 播放/暂停音乐 |
CapsLock | 打开/关闭 Event 直观编辑 |
导航
| 按键 | 功能 |
|---|---|
← | 轨道减 1 |
→ | 轨道加 1 |
↑ | 节拍分度加 1 |
↓ | 节拍分度减 1 |
| 滚轮 | 纵向滚动 |
Ctrl + 滚轮 | 加速滚动 |
选区操作
| 按键 | 功能 |
|---|---|
Shift + 拖拽 | 框选 |
Escape | 取消选择 |
| 右键点击 | 单选/切换选择 |
剪贴板
| 按键 | 功能 |
|---|---|
Ctrl + C | 复制选中内容 |
Ctrl + X | 剪切选中内容 |
Ctrl + V | 粘贴；demo 来源默认只粘贴 Note |
Ctrl + A + V | 粘贴（包含 Event） |
Ctrl + B | 翻转粘贴（位置按谱面偏好镜像） |
Ctrl + A + B | 翻转粘贴（包含 Event） |
删除选区
| 按键 | 功能 |
|---|---|
Ctrl + D | 删除选中的内容；demo 来源默认只删除 Note |
Ctrl + A + D | 删除选中的 Note 和 Event |
撤销/重做
| 按键 | 功能 |
|---|---|
Ctrl + Z | 撤销 |
Ctrl + Y | 重做 |
Alt 键组合（需选中 Note/Event 后使用）
| 按键 | 功能 |
|---|---|
Alt + Z | 拖头（将 Note/Event 的头部拖到鼠标位置） |
Alt + X | 拖尾（将 Note/Event 的尾部拖到鼠标位置） |
Alt + C | 切割选中的 Event / Hold |
Alt + B | 翻转 Event 数值（镜像翻转 x 位置） |
Alt + T | 快速调整 Event 数值（吸附到最近围栏） |
Alt + U | 上下翻转 Event 的 from/to |
六、Event 直观编辑（CapsLock）
开启 CapsLock 后，选中的 Event 会在游玩区域显示可拖动的控制点：
- 头部圆点：拖动修改 Event 的 from 值和节拍
- 尾部圆点：拖动修改 Event 的 to 值和节拍
- 控制点（Bezier 模式）：拖动调整贝塞尔曲线
在 demo 区按右键弹出当前事件的编辑菜单：
- 切换过渡类型
- 下一个/上一个预设曲线
- 添加/删除控制点
七、预览模式（Tab）
按 Tab 进入全屏预览模式，此时：
- 编辑界面隐藏
- 显示完整的游玩区域
- 可用于检查谱面效果
八、撤销/重做系统
- 音符 / 事件的增删、数值修改、轨道属性、谱面信息、偏好、事件组等谱面修改都记录历史；一次页面编辑或批量操作可合并为一条。
Ctrl + Z撤销，Ctrl + Y重做。- 侧边栏的“操作历史”显示发生了什么和涉及的节拍范围。单对象取起点到终点，多对象取最早起点到最晚终点；拖动还包含修改前后的范围。
- 点击记录可恢复到那一步。撤销后再编辑会保留原分支，在“所有分支”中可查看和跳转。
- 切换谱面会清空历史；历史不保存到文件。事件组编辑时有独立历史，退出后整次组修改记录回主谱面。
- 不涉及对象时间的操作（如改曲名）可能没有节拍范围。全局设置、键位和纯播放位置变化不是谱面撤销操作。
九、提示
- 波形图：在设置中开启后，编辑区域会显示音频波形，辅助对齐
- 声纹图：在设置中开启后，编辑区域会按时间显示不同频率的强弱；左边是低频，右边是高频
- 框选可跨轨道：在游玩区域框选可以选中不同轨道的 Note
- 轨道父子关系：设置父轨道后，子轨道的 x 值会叠加父轨道，用于制作联动轨道
- 围栏辅助：设置围栏数量和 Event 直观编辑配合，可以精确对齐 Event 数值
- 批量编辑：选中多个 Event 后，在 Events 面板可以批量修改数值
输入算式的安全范围
事件起点和终点支持数字、括号及 + - * / % ^ 算式，例如 50 + 10 / 2。可以使用 now.x、now.w、now.lpos、now.rpos 读取当前轨道的位置，以及 r() 或 r(1, 10) 取随机数。
批量缓动仍支持 easing 5、easing linear、bezier 1、bezier 0,0,1,1 和 function x^2。这里的 function 只是算式前缀，不能写 Lua 函数。支持常用数学函数（如 math.sin、math.abs、math.min、math.max）和圆周率 math.pi。
不能调用文件、系统命令或其他 Lua 代码。算式过长、嵌套过深或结果为无穷大等情况会被拒绝；批量操作会先检查全部结果，出错时不会修改事件。旧谱面、语言文件和贝塞尔预设仅接受数据表，不执行其中的代码。