llll-chart2sus

将 Link! Like! LoveLive! 谱面 JSON 直接转换为 Project SEKAI MusicScoreMakerData JSON。为兼容已有安装，保留项目名称和 python -m llll_chart2sus 入口；convert 不再输出 SUS，也不经过 SUS 中间格式。

功能与边界

• 支持 Single、Flick、Trace，以及由时间点和 UID 链接组成的 Hold。
• 每四分音符 480 ticks，分段积分 BPM 后仅舍入一次；保留 BPM 和拍号变化。
• 将源 0–59 坐标映射至 12 轨；JSON 的 laneStart、laneEnd 为 0–11 的含端点索引。坐标压缩和 tick 舍入不可避免，输出不保证与源连续坐标完全相同。
• Hold 串链严格照原版 ChartResolver.Prepare Pass1 谓词重建：候选须为 Hold、Uid 更大、终点边缘（L2/R2）等于候选起点边缘（L1/R1），且 holds[^1] 与候选 just 在 1e-4（float32 域，即 C# 0.0001f） 内相等；取满足条件的最小 Uid。同一节点可被多条前驱指向（原版允许汇合），不按遍历顺序独占。
• Hold 使用双向连接 ID，不受 SUS 的 36 通道写出限制；中间节点不可见，不额外生成 combo 节点。
• 输出裸 MusicScoreMakerData，包含事件、音符和最大 ticks；不添加 repository 包装或 Newtonsoft $type 元数据。
• 目标契约没有音频偏移字段，非零 Offset 会明确报错，不会静默丢弃或平移谱面。
• 非有限数、非法轨道／BPM／拍号、可达 Hold 断链和循环会报错。相邻航点真实间隔小于一个 tick 时按原版渲染语义折叠（同 tick 只保留最后一个航点），不静默丢链。根节点选择保持源预览语义，不导出无根孤立自环。

快速开始

Python 要求为 3.10 或更新版本。核心转换不需要 Rust 或 .NET；Rust 用于独立解析和 SVG 渲染。

uv venv --python 3.10
uv pip install --python .venv/Scripts/python.exe -e ".[dev]"

.\.venv\Scripts\python.exe -m llll_chart2sus convert `
  --input examples/rhythmgame_chart_203115_04.bytes.json `
  --output tmp/203115_04.pjsk.json

输出必须使用 .json 扩展名，且不得与输入指向同一文件。--strict 参数继续接受；格式与安全检查在所有模式下均启用。历史 SUS 写出函数仅保留供旧内部使用，不提供第二套 CLI 输出模式。

验证并渲染

确保工作区存在支持 JSON 的 pjsekai-scores-rs/ 参考仓库和 Rust toolchain：

.\.venv\Scripts\python.exe -m llll_chart2sus validate `
  --json tmp/203115_04.pjsk.json --svg-out tmp/203115_04.pjsk.svg

先检查 JSON 字段、枚举范围、唯一 ID、双向连接、递增时间和最大 ticks，再调用 Rust 的 --score-format json 解析并渲染 SVG。旧 validate --sus 会返回迁移提示。Rust 解析本身较宽松，不能替代本地语义检查。

.\.venv\Scripts\python.exe -m llll_chart2sus doctor
pwsh ./scripts/doctor.ps1
.\.venv\Scripts\python.exe -m pytest tests -q

doctor 检查 Rust 验证器，不再要求只支持 SUS 的 Python scores。需要完整工具链时可使用 scripts/bootstrap_toolchain.ps1。

目录与参考

• src/llll_chart2sus/：源加载、直接 JSON 映射、校验、写出及 CLI。
• tests/：源加载和新 JSON 链路测试，以及保留内部 SUS 函数的回归测试。
• examples/：源谱面和历史 SUS/SVG 示例；用以上命令生成当前 JSON，历史产物不代表当前默认输出。
• scripts/：本地工具链辅助脚本。
• Sekai-SUS-Parser：目标 MusicScoreMakerData 契约和独立语义对照，核对版本 425f4a2。
• pjsekai-scores-rs：JSON 解析／SVG 渲染，核对版本 986de2e。
• llll-chart：源谱面预览参考。注意其 Hold 链口径（ceil(秒×100) 时间桶 + 目标独占）与原版客户端不一致；串链语义一律以原版 ChartResolver.Prepare Pass1 谓词为准。
• scores、SekaiMusicChart：历史 SUS 参考，不参与新 JSON 必需验证链路。
• LinkLikeToolBox/：本地源数据及格式参考。更新时原远端返回 Repository not found；保留本地版本，不自动改用其他来源。

参考仓库不作为 Python 运行依赖；仅将其更新到远端版本，不在其中修改业务代码。转换不会执行输入中的代码，也不会进行带类型名的对象反序列化。

免责声明

本项目为研究与互操作用途的同人转换工具，与 Link! Like! LoveLive! 或 Project SEKAI 权利方无隶属、认可或赞助关系。游戏资产、谱面、名称及相关知识产权归各权利方所有。使用者应遵守法律、平台条款及版权要求，不得用于未经授权的商业分发。

许可证

项目采用 MIT License，详见 LICENSE。