noctilink
将 .yzcpkg 谱面包导入 noctilink 的两种方式。
当前产品边界（2026-08-10）：导入/删除菜单、
user://songs/用户曲显示和系统文件关联只在 dev flavor 开放。public flavor 会隐藏这些入口与用户曲，并在导出时剥离文件关联；底层SongLibrary.import_package()仍保留，但不是公开版玩家功能。以下操作均以 dev flavor 为前提。
方法一：应用内导入
- 打开 noctilink dev Godot，进入选曲界面。
- 点击右上角「+ Import song」按钮。
- 在弹出的文件选择器中定位并选择
.yzcpkg文件。 - 导入完成后，曲库自动刷新，选曲光标跳转至新导入的歌曲。
方法二：从其他应用导入
从文件管理器、浏览器等任意应用中接收或下载的 .yzcpkg 文件：
- Android dev：点击文件，在「打开方式」菜单中选择 noctilink dev Godot。
- iOS dev：点击文件后选择分享按钮，在分享菜单中选择 noctilink dev Godot。
导入完成后曲库自动刷新。public flavor 不声明这类外部文件入口；在公开版看不到 noctilink 作为打开/分享目标属于预期行为。
重新导入与更新
对同一首歌曲重复导入新版本的 .yzcpkg（前提是它有一个真实的、非默认的 id）：
- 新包会先解压到临时目录并完成基础校验，再替换旧目录；如果解压或替换失败，原有歌曲目录会保留。
- 替换成功后，旧谱面数据被完全覆盖（这是按
id就地更新同一首歌的预期行为）。 - 游戏记录处理：若某难度的音符数量未变，原最佳分数保留；若音符发生增减，该难度的分数清零，其余难度不受影响。
- 默认
id例外：如果包的id还是编辑器默认的chart，导入时会先判断它是不是某首已导入的默认 chart 系列歌曲（chart、chart_2、chart_3…）的再次导入：- 是同一首（音频文件逐字节相同，或标题与作者都相同且标题非空）→ 就地覆盖更新那一首，不新建条目，沿用上面的最佳成绩处理规则。
- 是不同的歌（音频不同且标题/作者也不同，或包内没有可读音频也没有标题）且
chart已被占用 → 自动顺延为chart_2、chart_3…（目录名与song.json的id一并改写），因此不同协作者都忘记改 ID 时也不会互相覆盖。 - 提示：两个人给同一首曲子做谱、都用默认
chart且标题/作者填得一样时，会被当成同一首而合并。想各自保留请在编辑器里给歌曲填上不同 Title（ID 会自动派生成真实值）或手动设一个Song ID。
包名与路径限制
song.json的id只能使用小写英文字母、数字和下划线（[a-z0-9_]）。id不能与内置歌曲 ID 冲突。- 默认
idchart导入冲突时：识别为同一首（同音频或同标题+作者）则就地覆盖，否则顺延为chart_2、chart_3…（见上节「默认id例外」）。 - 若某次更新新增了与你已导入歌曲
id相同的内置曲，下次启动 / 曲库刷新时，已导入的那首会自动改名（加_imported后缀）并迁移其最佳成绩，内置曲以原id显示——两者都不会丢失。 - 包内文件路径不能包含绝对路径、盘符、反斜杠或
..跳级路径。
常见错误
仅以下一种错误会直接弹出对话框；其它失败情形（包含 song.json 缺失/解析失败、id 字段非 [a-z0-9_]、压缩包路径不安全包含 ../ 或绝对路径、目录替换失败等）会静默地停止导入，错误细节写入运行日志。
| 提示 | 原因 | 处理方式 |
|---|---|---|
Song ID conflicts with a built-in song.<br>Please change the ID in the editor and re-export. |
导入的谱面 ID 与游戏内置歌曲 ID 冲突 | 联系制谱者在编辑器中修改 Song ID 并重新导出 |
如果点击导入后曲库没有刷新也没有任何提示，绝大多数情况是包结构不合法（缺
song.json、id字段无效、含../等不安全路径），让制谱者从编辑器重新导出即可。
关于 .yzcpkg 格式
.yzcpkg 为 ZIP 压缩格式的容器，包含：
song.json：歌曲元数据与各难度引用- 各难度谱面文件（
<难度名>.yzc.json） - 音频文件（
.mp3或.ogg） - 封面图（可选，
.jpg或.png）
详细格式规范参见 chart_format.zh.md。编辑器导出时自动打包，无需手动操作。