noctilink

将 .yzcpkg 谱面包导入 noctilink 的两种方式。

方法一：应用内导入

1. 打开 noctilink，进入选曲界面。
2. 点击右上角「+ Import song」按钮。
3. 在弹出的文件选择器中定位并选择 .yzcpkg 文件。
4. 导入完成后，曲库自动刷新，选曲光标跳转至新导入的歌曲。

方法二：从其他应用导入

从文件管理器、浏览器等任意应用中接收或下载的 .yzcpkg 文件：

• Android：点击文件，在「打开方式」菜单中选择 noctilink。
• iOS：点击文件后选择分享按钮，在分享菜单中选择 noctilink。

导入完成后曲库自动刷新。

重新导入与更新

对同一首歌曲重复导入新版本的 .yzcpkg（前提是它有一个真实的、非默认的 id）：

• 新包会先解压到临时目录并完成基础校验，再替换旧目录；如果解压或替换失败，原有歌曲目录会保留。
• 替换成功后，旧谱面数据被完全覆盖（这是按 id 就地更新同一首歌的预期行为）。
• 游戏记录处理：若某难度的音符数量未变，原最佳分数保留；若音符发生增减，该难度的分数清零，其余难度不受影响。
• 默认 id 例外：如果包的 id 还是编辑器默认的 chart，导入时绝不覆盖已存在的 chart 歌曲，而是自动顺延为 chart_2、chart_3…（目录名与 song.json 的 id 一并改写）。因此不同协作者都忘记改 ID 时也不会互相覆盖。代价：用默认 chart 重复导入自己更新过的同一首歌，会变成一条新条目而非就地更新——请在编辑器里给歌曲填上 Title（ID 会自动派生成真实值）或手动设一个 Song ID。

包名与路径限制

• song.json 的 id 只能使用小写英文字母、数字和下划线（[a-z0-9_]）。
• id 不能与内置歌曲 ID 冲突。
• 默认 id chart 导入冲突时不会覆盖，而是顺延为 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）

详细格式规范参见 谱面格式规范。编辑器导出时自动打包，无需手动操作。