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

方法一：应用内导入

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

方法二：从其他应用导入

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

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

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

重新导入与更新

对同一首歌曲重复导入新版本的 .yzcpkg：

  • 新包会先解压到临时目录并完成基础校验，再替换旧目录；如果解压或替换失败，原有歌曲目录会保留。
  • 替换成功后，旧谱面数据被完全覆盖。
  • 游戏记录处理：若某难度的音符数量未变，原最佳分数保留；若音符发生增减，该难度的分数清零，其余难度不受影响。

包名与路径限制

  • song.json 的 id 只能使用小写英文字母、数字和下划线（[a-z0-9_]）。
  • id 不能与内置歌曲 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）

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