nnnotes 0.1.4__tar.gz → 0.2.1__tar.gz

nnnotes-0.2.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+nnnotes.toml
+*.local.toml
+.env
+out/
+cache/

{nnnotes-0.1.4 → nnnotes-0.2.1}/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project are listed here. Versions follow [Semantic Versioning](https://semver.org/).
 
+## [0.2.1](https://github.com/MetaSekaiLab/nnnotes/compare/v0.2.0...v0.2.1) - 2026-10-13
+
+### Build
+
+- **deck:** Ournotes-deck v0.0.8 ([53da36f](https://github.com/MetaSekaiLab/nnnotes/commit/53da36f7b73e4ccf9e1158cd571244d87648aa3f))
+
+## [0.2.0](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.4...v0.2.0) - 2026-10-13
+
+### Features
+
+- **music-data:** Reuse cached chart statistics of unchanged model sources ([1bdbd64](https://github.com/MetaSekaiLab/nnnotes/commit/1bdbd640755e4f49e0ab302c74c1ed871aef7f70))
+- **music-data:** Measure chart statistics with nominal lottery and skill probabilities ([303b850](https://github.com/MetaSekaiLab/nnnotes/commit/303b8503621180a016c41c574a41864ac67f7b1f))
+- **fonts:** Read the game font settings from a built-in table in open-font exports ([dfe3c86](https://github.com/MetaSekaiLab/nnnotes/commit/dfe3c86524ef193361eee751983d8d3b60dddecd))
+- **music-data:** Keep native simulation programs and export Snap labels ([096361a](https://github.com/MetaSekaiLab/nnnotes/commit/096361a5f0f585aa5ee332c5d4997958f3064254))
+- **schemas:** Ship the JSON Schemas with the package as nnnotes.schemas ([7b66c09](https://github.com/MetaSekaiLab/nnnotes/commit/7b66c0923ad7c581ba7cf4ff7318f54bc9c80fb1))
+
+### Documentation
+
+- Describe the atoms and the PNG level without measurements ([babe470](https://github.com/MetaSekaiLab/nnnotes/commit/babe4706bb862bb7235b25d6bde1c5e7dec72dc1))
+
+### Build
+
+- **deck:** Ournotes-deck v0.0.3 ([c71e8f5](https://github.com/MetaSekaiLab/nnnotes/commit/c71e8f55b2713b9f394f27867f682cc8aecbaffe))
+- **deck:** Ournotes-deck v0.0.4 ([6139e40](https://github.com/MetaSekaiLab/nnnotes/commit/6139e40c189f653e53180f39a3137a1327085e7d))
+- **deck:** Ournotes-deck v0.0.5 ([7f2c950](https://github.com/MetaSekaiLab/nnnotes/commit/7f2c950d4c6008a91be2cbe32f409dc5cddbff82))
+- **deck:** Ournotes-deck v0.0.6 ([a4b9c4e](https://github.com/MetaSekaiLab/nnnotes/commit/a4b9c4ea7c03ce569155ed389a0a2df744b5b849))
+- Ship nnnotes as a pure Python package with the deck model as the extra deck ([5c1e9c6](https://github.com/MetaSekaiLab/nnnotes/commit/5c1e9c6613234418c5b7ece2b2750708f6633d1c))
+
+### CI
+
+- **release:** Verify wheels and reuse quality checks ([46cf165](https://github.com/MetaSekaiLab/nnnotes/commit/46cf165d28a4d3dfb44e232c7831a47acb3ba184))
+
+### Miscellaneous
+
+- **rust:** Order chartstats imports ([12672e8](https://github.com/MetaSekaiLab/nnnotes/commit/12672e891ca1c06df6d838681325edc9694fe45e))
+
 ## [0.1.4](https://github.com/MetaSekaiLab/nnnotes/compare/v0.1.3...v0.1.4) - 2026-10-06
 
 ### Features

{nnnotes-0.1.4 → nnnotes-0.2.1}/PKG-INFO

@@ -1,32 +1,34 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nnnotes
-Version: 0.1.4
-Classifier: Programming Language :: Python :: 3
+Version: 0.2.1
+Summary: Offline data toolkit for BanG Dream! Our Notes game files: catalogs, bundles, master data, stories, Live2D, audio and live charts
+Project-URL: Homepage, https://github.com/MetaSekaiLab/nnnotes
+Project-URL: Source, https://github.com/MetaSekaiLab/nnnotes
+Project-URL: Issues, https://github.com/MetaSekaiLab/nnnotes/issues
+Author: MetaMiku, emptysekai
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia
-Requires-Dist: unitypy>=1.25
+Requires-Python: >=3.11
+Requires-Dist: brotli>=1.1
+Requires-Dist: grpcio>=1.49.1
 Requires-Dist: numpy>=2.0
 Requires-Dist: pillow>=10.0
 Requires-Dist: pycryptodome>=3.20
-Requires-Dist: grpcio>=1.49.1
-Requires-Dist: brotli>=1.1
-Requires-Dist: fonttools>=4.50 ; extra == 'fonts'
-Requires-Dist: freetype-py>=2.5 ; extra == 'fonts'
-Requires-Dist: scipy>=1.13 ; extra == 'fonts'
-Requires-Dist: pytest>=8 ; extra == 'test'
-Requires-Dist: pyflakes>=3.2 ; extra == 'test'
-Requires-Dist: jsonschema>=4.18 ; extra == 'test'
+Requires-Dist: unitypy>=1.25
+Provides-Extra: deck
+Requires-Dist: ournotes-sim==0.0.8; extra == 'deck'
 Provides-Extra: fonts
+Requires-Dist: fonttools>=4.50; extra == 'fonts'
+Requires-Dist: freetype-py>=2.5; extra == 'fonts'
+Requires-Dist: scipy>=1.13; extra == 'fonts'
 Provides-Extra: test
-License-File: LICENSE
-Summary: Offline data toolkit for BanG Dream! Our Notes game files: catalogs, bundles, master data, stories, Live2D, audio and live charts
-Author: MetaMiku, emptysekai
-License-Expression: MIT
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
-Project-URL: Homepage, https://github.com/MetaSekaiLab/nnnotes
-Project-URL: Issues, https://github.com/MetaSekaiLab/nnnotes/issues
-Project-URL: Source, https://github.com/MetaSekaiLab/nnnotes
+Requires-Dist: jsonschema>=4.18; extra == 'test'
+Requires-Dist: pyflakes>=3.2; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
 
 # nnnotes？！
 
@@ -39,7 +41,7 @@ for configuration and validation limits.
 nnnotes is an offline data toolkit for the game files of BanG Dream! Our Notes: it reads Addressables catalogs,
 downloads and decrypts asset bundles, downloads and decodes master data, and exports stories, Live2D models, spots,
 shaders, CRI audio and live charts as structured JSON and common file formats. The charts, Live2D models and stories `web`
-exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by [mos9527/sssekai](https://github.com/mos9527/sssekai).
+exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by sssekai.
 
 This is an unofficial fan project, not affiliated with the game's developer or operator. The repository contains no
 game assets, keys or server addresses: users supply the game files, the keys needed for decryption and the server
@@ -58,7 +60,8 @@ nnnotes config check             # each setting's origin and whether it is valid
 - Scripts and AI agents get no questions: `nnnotes config init --user --no-input --set SECTION.KEY=VALUE ...` writes
   the file at once, `nnnotes config set SECTION.KEY VALUE` changes one value (VALUE `-` reads it from standard input,
   so a key need not appear on the command line), and `nnnotes config check --json` reports the states for machines.
-- `--fonts game` also needs `pip install 'nnnotes[fonts]'`; the APK, the master data and the external tools are listed
+- `--fonts game` also needs `pip install 'nnnotes[fonts]'`, and the deck statistics of `music-data` need
+  `pip install 'nnnotes[deck]'`; the APK, the master data and the external tools are listed
   under Requirements below.
 
 ## Features
@@ -84,7 +87,7 @@ nnnotes config check             # each setting's origin and whether it is valid
 | `ui` (experimental) | APK set and its embedded catalog | an offline serialized prefab library with dependency roots, AnimatorControllers, stable references and PNG/font resources for the optional ournotes-player UI preview ([format and limits](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)) |
 | `live` | music ID + difficulty | a full chart directory: chart and runtime notes, 3D scene, note and effect assets, BGM and sounds, sound routing |
 | `web` | `--pair music:difficulty` (repeatable) or `--all`; `--live2d model` (repeatable) or `--all-live2d`; `--story episode` (repeatable) or `--all-stories`; `--region region` (repeatable) or `--all-regions` | an ournotes-player static site: shared player + per-chart / per-model / per-episode manifests + content-addressed assets; the Live2D models of the stories are built first as models, listed in `models.json`, and the story manifests reference them; one site can serve several regions, with listing texts in five languages; a story's interface texts are grouped by language, with TextMeshPro font assets generated from open fonts (the game's fonts with `--fonts game`); compressible assets (JSON, shaders, moc3, ...) are stored gzip encoded by default (`--compress br` / `none`) |
-| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (built into nnnotes) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
+| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (installed with `pip install 'nnnotes[deck]'`) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
 
 Export conventions:
 
@@ -218,9 +221,6 @@ settings (TOML / environment / flags)
 Every JSON file is written by one writer (`jsonio`), so encoding, line endings and number formatting are the same
 everywhere.
 
-See [docs/performance.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/performance.md) for where a
-`web` build spends its time and which parts of it run in compiled code.
-
 ## Changelog
 
 [CHANGELOG.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/CHANGELOG.md) lists the changes in every version,
@@ -235,4 +235,3 @@ When a `vX.Y.Z` tag is pushed, the release workflow checks the versions and that
 ## License
 
 MIT, see [LICENSE](https://github.com/MetaSekaiLab/nnnotes/blob/main/LICENSE).
-

{nnnotes-0.1.4 → nnnotes-0.2.1}/README.en.md

@@ -9,7 +9,7 @@ for configuration and validation limits.
 nnnotes is an offline data toolkit for the game files of BanG Dream! Our Notes: it reads Addressables catalogs,
 downloads and decrypts asset bundles, downloads and decodes master data, and exports stories, Live2D models, spots,
 shaders, CRI audio and live charts as structured JSON and common file formats. The charts, Live2D models and stories `web`
-exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by [mos9527/sssekai](https://github.com/mos9527/sssekai).
+exports are the data that [ournotes-player](https://github.com/empty-sekai/ournotes-player) reads. The naming was inspired by sssekai.
 
 This is an unofficial fan project, not affiliated with the game's developer or operator. The repository contains no
 game assets, keys or server addresses: users supply the game files, the keys needed for decryption and the server
@@ -28,7 +28,8 @@ nnnotes config check             # each setting's origin and whether it is valid
 - Scripts and AI agents get no questions: `nnnotes config init --user --no-input --set SECTION.KEY=VALUE ...` writes
   the file at once, `nnnotes config set SECTION.KEY VALUE` changes one value (VALUE `-` reads it from standard input,
   so a key need not appear on the command line), and `nnnotes config check --json` reports the states for machines.
-- `--fonts game` also needs `pip install 'nnnotes[fonts]'`; the APK, the master data and the external tools are listed
+- `--fonts game` also needs `pip install 'nnnotes[fonts]'`, and the deck statistics of `music-data` need
+  `pip install 'nnnotes[deck]'`; the APK, the master data and the external tools are listed
   under Requirements below.
 
 ## Features
@@ -54,7 +55,7 @@ nnnotes config check             # each setting's origin and whether it is valid
 | `ui` (experimental) | APK set and its embedded catalog | an offline serialized prefab library with dependency roots, AnimatorControllers, stable references and PNG/font resources for the optional ournotes-player UI preview ([format and limits](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)) |
 | `live` | music ID + difficulty | a full chart directory: chart and runtime notes, 3D scene, note and effect assets, BGM and sounds, sound routing |
 | `web` | `--pair music:difficulty` (repeatable) or `--all`; `--live2d model` (repeatable) or `--all-live2d`; `--story episode` (repeatable) or `--all-stories`; `--region region` (repeatable) or `--all-regions` | an ournotes-player static site: shared player + per-chart / per-model / per-episode manifests + content-addressed assets; the Live2D models of the stories are built first as models, listed in `models.json`, and the story manifests reference them; one site can serve several regions, with listing texts in five languages; a story's interface texts are grouped by language, with TextMeshPro font assets generated from open fonts (the game's fonts with `--fonts game`); compressible assets (JSON, shaders, moc3, ...) are stored gzip encoded by default (`--compress br` / `none`) |
-| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (built into nnnotes) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
+| `music-data` | master data files (`--master-files` directory or `--apk-master`), or decoded master data with its manifest (`--decoded-master`) | one JSON file with every song and chart: titles and credits in five languages, bands, vocal characters, category, tags, release time, score ranks, BGM length; the Gekisou catalog (member cards, snaps and their Gekisou skills and support skills); per difficulty the level, note counts, BPM, chart times, skill events and fever ranges; and the chart statistics the deck model ournotes-deck (installed with `pip install 'nnnotes[deck]'`) measures on its whole-live simulation (the no-skill score, the weight of every score-up skill kind at every position), plus single-shape Gekisou aptitude (increments and standard errors, not an optimal deck; omit with `--no-gekisou-aptitude`). `--full` adds the deck model's input: every chart's runtime notes and the master data tables about cards, skills, bonuses, scores and events ([format](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/music-data.md)) |
 
 Export conventions:
 
@@ -188,9 +189,6 @@ settings (TOML / environment / flags)
 Every JSON file is written by one writer (`jsonio`), so encoding, line endings and number formatting are the same
 everywhere.
 
-See [docs/performance.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/performance.md) for where a
-`web` build spends its time and which parts of it run in compiled code.
-
 ## Changelog
 
 [CHANGELOG.md](https://github.com/MetaSekaiLab/nnnotes/blob/main/CHANGELOG.md) lists the changes in every version,

nnnotes-0.2.1/README.md

@@ -0,0 +1,156 @@
+# nnnotes？！
+
+[简体中文](README.md) | [English](README.en.md)
+
+nnnotes 是 BanG Dream! Our Notes 游戏文件的离线数据工具包：读取 Addressables catalog、下载并解密资源包、下载与解码 masterdata，再把剧情、Live2D、据点场景、着色器、CRI 音频和谱面导出成结构化的 JSON 与通用格式文件。`web` 导出的谱面、Live2D 模型与剧情站点就是 [ournotes-player](https://github.com/empty-sekai/ournotes-player) 读取的数据。命名灵感来自 sssekai。
+
+本项目为非官方爱好者项目，与游戏的开发和运营方无关。仓库不包含任何游戏资源、密钥或服务器地址：游戏文件、解密所需的密钥和服务器地址都由使用者在配置中自行提供，导出结果只保存在使用者指定的本地目录。
+
+## 安装与初始化
+
+```sh
+pip install nnnotes              # Python 3.11+，推荐 3.13
+nnnotes config init --user       # 在终端里逐项填写设置（密钥不回显），写入用户配置文件，在任何目录下都会读取
+nnnotes config check             # 每项设置的来源和格式是否有效，不显示设置值
+```
+
+- 设置值（密钥、区服的 CDN 与 API 地址、本地数据与工具的路径）都来自使用者自己的游戏客户端，见[配置](#配置)。
+- 在脚本或 AI 代理中不会有交互提问：`nnnotes config init --user --no-input --set 段.键=值 ...` 一次写好，之后用 `nnnotes config set 段.键 值` 修改单项（值写 `-` 时从标准输入读取，密钥不必出现在命令行里），`nnnotes config check --json` 给出机器可读的状态。
+- `--fonts game` 另需 `pip install 'nnnotes[fonts]'`，`music-data` 的组卡统计另需 `pip install 'nnnotes[deck]'`；APK、masterdata 与外部工具见[需要准备](#需要准备)。
+
+## 功能
+
+| 命令 | 输入 | 输出 |
+|---|---|---|
+| `catalog` | 区服 catalog | 列出 Addressables 资源键（可按前缀过滤） |
+| `browse` | 已配置的各区服 catalog | 本地网页浏览 catalog 与资源包（`--host` / `--port`） |
+| `pull` | 资源键 | 下载并解密该键依赖闭包中的全部资源包到本地缓存 |
+| `servers` | 引导 API 根地址 `[bootstrap] api` | 游戏 API 的服务器列表：各区服名称、区域 ID 与 CDN / API 根地址（地址仅在 `--show-hosts` 时输出） |
+| `master version` | 区服 | 该区服当前的 masterdata 版本与资源版本（游戏 API 匿名调用） |
+| `master download` | masterdata 版本号，或 `--latest`（区服当前版本） | 该版本的 `MasterManifest.json` 与全部 `.bin` 文件（SHA-256 校验） |
+| `master decode` | masterdata `.bin` 文件或目录 | 每张表一个 JSON（Rijndael-256 CBC 解密 + gzip 解压） |
+| `adv` | 剧情 ID | `episode.json`：命令表、五语台词、语音 / 音效 / 视频索引 |
+| `story` | 剧情 ID | 剧情目录：episode、音频、舞台场景与着色器、剧情 UI、Frame / 粒子特效 / 后处理 / 静帧 / 对话框 / 聊天资源、视频（WebM）；用到的 Live2D 模型导出到模型目录（`--models`，默认为剧情目录旁的 `live2d/`），已导出的模型供其他剧情复用 |
+| `live2d` | 模型资源键或模型 ID | Live2D（Cubism）运行时目录：moc3、贴图、motion3、物理、表情、预制体参数 |
+| `spot` | 据点 ID | `spot.json` + Spine 角色 + 房间 `room.glb` + 着色器 |
+| `room` | 背景预制体键 | 房间模型（binary glTF） |
+| `shader` | 资源键或 APK 内资源包 | 着色器各平台变体（GLSL ES 等）与索引 |
+| `audio` | CRI cue sheet | 每个 cue 一个音频文件（FLAC / Ogg / WAV）+ cue 元数据 |
+| `crikey` | APK | 读出游戏启动数据中的 CRI HCA 解码密钥（只显示是否找到，可写成 `.hcakey`） |
+| `player` | APK | 渲染相关的全局设置（色彩空间、画质等级、渲染器）JSON |
+| `ui`（实验性） | APK 集合及内嵌 catalog | 离线序列化预制体库，包含依赖根对象、AnimatorController、稳定引用与 PNG／字体资源，供 ournotes-player 可选 UI 预览使用（[格式与边界](https://github.com/MetaSekaiLab/nnnotes/blob/main/docs/ui.md)） |
+| `live` | 曲目 ID + 难度 | 完整谱面目录：谱面与运行时音符、3D 场景、音符与特效资源、BGM 与音效、声音路由 |
+| `web` | `--pair 曲目:难度`（可重复）或 `--all`；`--live2d 模型`（可重复）或 `--all-live2d`；`--story 剧情 ID`（可重复）或 `--all-stories`；`--region 区服`（可重复）或 `--all-regions` | ournotes-player 静态站点：共享播放器 + 每谱 / 每模型 / 每集剧情清单 + 内容寻址资源；剧情用到的 Live2D 模型先按模型构建并列入 `models.json`，剧情清单引用它们；一个站点可服务多个区服，列表文本含五种语言；剧情的界面文字按语言分组，字形由开源字体生成 TextMeshPro 字体资源（`--fonts game` 时用游戏字体）；可压缩的资源（JSON、着色器、moc3 等）默认以 gzip 存储，`--compress br` / `none` 可改 |
+| `music-data` | masterdata 文件（`--master-files` 目录或 `--apk-master`），或带清单的解码 masterdata（`--decoded-master`） | 全部歌曲与谱面的单个 JSON：五语标题与作词作曲编曲、乐队、演唱角色、分类、标签、上线时间、评级线、BGM 时长；激走目录（成员卡、小卡及其激走技能与激走支援技能）；每个难度的等级、音符数、BPM、谱面时间、技能事件与 fever 区间；以及组卡模型 ournotes-deck（`pip install 'nnnotes[deck]'` 安装）在整场模拟上实测的谱面统计（无技能得分、每种加分技能在每个演出位的权重），以及单个激走技能形状的谱面适性（增量与标准误，不选最佳编成；`--no-gekisou-aptitude` 可跳过）。`--full` 另附组卡模型的输入：每张谱面的运行时音符与卡牌、技能、加成、分数、活动相关的 masterdata 表（[格式](docs/music-data.md)） |
+
+导出约定：
+
+- 写文件的命令都用 `-o` 指定输出路径（必填）；`web` 的站点目录是位置参数。
+- JSON 一律 UTF-8、LF 换行；无穷大写作 `1e999`。
+- 在同一套环境下导出是确定的：同样的输入，在 nnnotes、Python 依赖库（UnityPy、Pillow、numpy 等）和外部工具（vgmstream、FFmpeg）版本都相同时，导出文件逐字节相同。版本不同时，相同内容可能写成不同的字节：例如不同版本的 Pillow 写出的 PNG 像素相同，字节可能不同。
+- 数值保留 Unity 序列化值与字段名（`m_LocalPosition`、`_bandIDs` 等），便于与游戏数据对照。
+- 贴图导出为 PNG，着色器保留游戏自带的编译结果，音频由 CRI 格式解码为通用格式。
+
+## 完成度
+
+日服现已支持匿名版本查询、CDN 认证下载、gzip catalog、资源路径与缓存隔离，以及 Android 分包读取。
+配置、命令和日服验证范围见 [日服支持](docs/jp.md)。
+
+以下结果基于台服 1.0.1（zh-Hant）的全部数据：
+
+| 部分 | 状态 |
+|---|---|
+| catalog / 资源包解密 / 依赖闭包 | 可用 |
+| masterdata 解码 | 可用 |
+| 剧情 `adv` | 946 / 946 集可导出 |
+| 剧情 `story`（完整目录） | 946 / 946 集的资源都在 catalog 中且类型均受支持（资源闭包与游戏自带的每集下载清单一致）；946 / 946 集已逐集导出验证：输出中引用的文件、模型与音频均存在，JSON 均可解析，引用的路径均可解析；其中 235 集用到 Frame / Effect / PostEffect / Still / Chat / TalkWindow / 视频资源，两次导出除模型目录路径外逐字节一致 |
+| Live2D 模型 | 239 / 239 个可导出（catalog 中的全部模型，剧情用到其中 185 个） |
+| CRI 音频 | 681 / 681 个 cue sheet 可解码 |
+| 谱面 `live` | 336 / 336 个（曲目, 难度）组合可导出 |
+| 网页站点 `web` | 336 / 336 张谱面，239 / 239 个 Live2D 模型，946 / 946 集剧情（英语、无音频的全量构建两次结果逐字节一致，946 / 946 集通过数据校验）；三个区服、五种语言、含 AAC 音频的全量构建（`--all-regions`，用线上 masterdata：85 首曲目的 340 张谱面）两次结果同样逐字节一致，全部通过数据校验 |
+| 据点 `spot` / `room` | 39 / 39 个据点可导出，引用均可解析；catalog 中 20 / 20 个房间背景可由 `room` 导出。生成的 glb 均通过 Khronos glTF-Validator，0 个错误 |
+| 其他区服（en / kr）与其他语言 | 已核对：各区服同一语言的 catalog 相同、资源包相同，密钥通用；谱面用到的 masterdata 表在三个区服间一致，文本表五种语言齐全；抽查的谱面导出与台服一致。多区服整站已全量构建验证（见上一行） |
+
+## 需要准备
+
+- Python 3.11+，推荐 3.13（`web` 构建读写大量 JSON，3.13 的标准库 JSON 编码更快）；开发时在仓库内 `pip install -e .`
+- 游戏安装包 `base.apk`：APK 内置资源包、CRI 解码密钥、启动设置。`player`、`story`、`live`、`web` 用 nnnotes 自带的类型树读取 APK 启动数据中的 MonoBehaviour，目前支持游戏版本 1.0.1（Unity 6000.3.12f1）；其他版本的 APK 若类型不符，这些命令会报错并给出类名、游戏版本和 Unity 版本
+- 解码后的 masterdata 目录（可用 `master download` + `master decode` 生成）：`adv`、`story`、`spot`、`live` 和 `web` 的谱面需要；`web` 的 Live2D 模型只用它取角色名（可选）
+- 外部工具：[vgmstream](https://vgmstream.org/)（CRI HCA 解码）、[FFmpeg](https://ffmpeg.org/)（转码，含剧情视频的 WebM 封装与 Opus 音频）；`web` 另需 Node.js 20+ 与构建好的 ournotes-player
+
+## 配置
+
+代码中没有任何密钥、服务器地址和默认路径。所有设置按以下顺序读取，后者覆盖前者：
+
+1. 配置文件：`--config <文件>`，否则 `NNNOTES_CONFIG`，否则当前目录的 `nnnotes.toml`，否则用户配置文件（Windows 为 `%APPDATA%\nnnotes\nnnotes.toml`，其他系统为 `~/.config/nnnotes/nnnotes.toml`；`nnnotes config path` 列出查找顺序与实际读取的文件）
+2. 环境变量：`NNNOTES_<节>_<键>`（如 `NNNOTES_BUNDLE_KEY`、`NNNOTES_SERVERS_TW_CDN`）
+3. 命令行参数：`--region`、`--language`、`--catalog`、`--cache`、`--master`、`--apk`、`--ffmpeg`、`--vgmstream`、`--node` 写在命令名之前；`--player` 是 `web` 的参数
+
+`nnnotes config init` 写出配置模板（每项设置为空，模板随包安装，仓库中为 [`src/nnnotes/nnnotes.example.toml`](src/nnnotes/nnnotes.example.toml)），在终端中会逐项询问；`config set` / `config unset` 修改单项并保留文件中的注释。需要的设置包括：资源包解密密钥与 nonce 种子、masterdata 的密钥与 IV、使用的区服 `[catalog] region` 与 catalog 语言 `[catalog] language`、每个区服的 CDN 地址与 API 根地址（`[servers.<区服>]` 的 `cdn`、`api`）、客户端版本 `[client] version`（未设置时读取 APK 的 versionName）、可选的引导 API 根地址 `[bootstrap] api`（`servers` 使用），以及缓存目录、APK、masterdata 目录、ournotes-player 和 vgmstream / FFmpeg / Node.js 的路径（三个工具未设置时在 `PATH` 中查找）。这些值都来自使用者自己的游戏客户端。
+
+缺少或格式错误的设置会让命令以退出码 2 结束，并用一行说明对应的配置键、环境变量和命令行参数，不会输出任何设置值。`nnnotes.toml` 已在 `.gitignore` 中，请勿提交。
+
+完整说明见 [docs/configuration.md](docs/configuration.md)。
+
+## 使用示例
+
+```bash
+nnnotes catalog --prefix Live/MusicScore/ --limit 20
+nnnotes browse --port 8000
+nnnotes pull Live/MusicScore/0001/0001_03
+nnnotes master version
+nnnotes master download --latest -o work/master-bin
+nnnotes master decode work/master-bin -o work/master
+nnnotes --master work/master adv 10462 -o out/adv_10462.json
+nnnotes story 10462 -o out/story_10462
+nnnotes live 100001 --difficulty expert -o out/live_100001
+nnnotes web out/site --all --player <ournotes-player 目录> --workers 5
+nnnotes web out/site --pair 100001:expert --pair 100001:hard --player <ournotes-player 目录>
+nnnotes web out/site --all --region tw --region en --region kr --player <ournotes-player 目录>
+nnnotes web out/site --live2d adv_live2d_rana_003_casual_spring_01 --player <ournotes-player 目录>
+```
+
+`web` 可以增量构建：清单已存在的谱面和模型会跳过（`--force` 重建），不再被引用的资源会被清理。常用参数：
+
+- `--format aac|opus|vorbis|mp3|flac`：BGM 格式，默认 AAC；`--no-audio`：不导出音频
+- `--band` / `--leader-card`：轻量背景与开场时间轴所用乐队；默认取曲目第一位演唱角色的乐队
+- `--workers`：并行处理的曲目进程数（默认为 CPU 数的四分之一，最多 8）与模型进程数（默认最多 4）；`--read-workers`：同时运行的谱面读取集（Node.js 进程）数（默认为 CPU 数的一半，最多 16）；`--tmp`：临时构建目录（默认 `<站点>.tmp`）
+- `--live2d 模型`（模型 ID 或资源键，可重复）/ `--all-live2d`：加入 Live2D 模型（catalog 中全部模型），可与谱面在同一次构建中加入
+- `--region 区服`（可重复）/ `--all-regions`：站点服务的区服（默认 `[catalog] region`）；每个区服的 masterdata 由 `[servers.<区服>] master` 指定。谱面数据相同的区服共用一份清单，列表页用 `?region=&lang=` 切换区服与语言
+- `--player-only`：只重写播放器文件与 `charts.json`、`models.json`；`--reingest-json`：按当前规则重新存储所有谱面与模型的 JSON
+
+各命令的参数与输出目录结构见 [docs/commands.md](docs/commands.md)。
+
+## 架构
+
+```
+配置（TOML / 环境变量 / 参数）
+  └─ 访问层      addressables（catalog 解析、资源包解密、本地浏览）
+                 catalog（依赖闭包、远端与 APK 内资源、本地缓存）
+                 master（masterdata 下载与解码）
+                 gameapi（游戏 API 匿名调用：当前 masterdata 版本、服务器列表）
+       └─ 读取层  unity（UnityPy 读取 typetree 与 TextAsset）
+                  export（预制体 / 组件 / 引用全部解析为 JSON，贴图与着色器随同导出）
+                  shader、textstyle（文字排版与样式）、tmpfont（TextMesh Pro 字体）、player（启动设置）、cri + crikey（CRI 音频）
+            └─ 内容层  剧情：adv、advscene、advmedia（Frame / 特效 / 后处理 / 静帧 / 聊天）、advvideo（USM 视频）、advui、story
+                       Live2D：live2d、motion
+                       据点：spot、room
+                       谱面：score（谱面解析与游戏谱面转换器的复现）、livescene、livenotes、liveui、liveaudio、live
+                       站点：web、webmodel（ournotes-player 数据）
+```
+
+所有 JSON 由同一个写出器生成（`jsonio`），保证编码、换行与数值格式一致。
+
+## 版本记录
+
+每个版本的改动见 [CHANGELOG.md](CHANGELOG.md)，由 [git-cliff](https://git-cliff.org/) 根据提交生成。发版时，改版本号的那个提交同时重新生成它：
+
+```bash
+git cliff --tag vX.Y.Z -o CHANGELOG.md
+```
+
+推送 `vX.Y.Z` 标签后，发布流程会核对版本号，并确认 CHANGELOG.md 里有这个版本。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

nnnotes-0.2.1/docs/assets.md

@@ -0,0 +1,214 @@
+# Asset export
+
+`nnnotes export` writes every object of the selected bundles in a common format: textures and sprites as PNG,
+meshes as binary glTF, text assets and fonts as their stored bytes, prefabs, materials, animations and every other
+class as JSON. It also writes the semantic views of the master data (cards, characters, stamps, …) with the files of
+the objects they name. The work is split into stages ([stages.md](stages.md)); each stage runs one task per subject
+(a bundle, a view, …), and a task's result is stored under a key that covers exactly what its output depends on
+([contracts.md](contracts.md)). A second run over the same data finds every result in the store and only
+rewrites what changed.
+
+```
+nnnotes export -o out/assets
+nnnotes export -o out/cards --select group:membercard --views cards
+nnnotes plan --select key:Image/Jacket/
+nnnotes plan --check && echo "up to date"
+```
+
+## Commands
+
+```
+nnnotes export -o OUT [--layout original[,cas]] [--select group:G|key:PREFIX|bundle:GLOB ...] [--views all|none|a,b]
+               [--store DIR] [--workers N] [--memory GiB] [--fetch-workers N] [--catalog-version L|SHA]
+               [--png-level N] [--flac-level N] [--only-class C,...] [--link auto|clone|hard|copy] [--strict]
+               [--dry-run] [--explain]
+nnnotes plan  [the selection and parameters of export] [-o OUT] [--json] [--since RUN] [--check] [--census]
+              [--emit-tasks DIR] [--why TASK]
+nnnotes run-stage TASK.json|DIR [...] [--store DIR] [--fetch] [--force]
+nnnotes catalogs list [--json] | import FILE [--label L] [--apk-catalog FILE] [--resource-version V] | fetch [--label L]
+                 | diff OLD NEW [--json]
+nnnotes store verify [--quick]
+```
+
+### export
+
+| Flag | Meaning |
+|---|---|
+| `-o OUT` | output directory |
+| `--select SEL` | what to export (repeatable, the union; default everything): `group:G` the bundles of an Addressables group (the stable bundle name up to `_assets_`, else up to its first `_`), `key:PREFIX` the bundles and raw files the catalog keys under `PREFIX` load, `bundle:GLOB` the bundles and raw files whose stable name matches |
+| `--views` | the semantic views to build ([views.md](views.md)): `all`, `none` or names, comma-separated; default `all` when master data is set, else `none` |
+| `--layout` | `original`, `cas` or both (below) |
+| `--store DIR` | the store (`[paths] store`; default `<cache>/store`) |
+| `--workers N` | worker processes (default: the CPUs the process may run on, its affinity mask as `taskset` or a container's cpuset sets it; `0`: every task in this process) |
+| `--memory GiB` | memory budget (default: 80 % of the physical memory where it can be read, else none) |
+| `--fetch-workers N` | parallel downloads of bundles not in the cache (default 8) |
+| `--catalog-version` | an imported catalog version (`catalogs list`) instead of the current catalog |
+| `--png-level N` | zlib level 0-9 of the PNG files (default 6); part of the task keys |
+| `--flac-level N` | FLAC compression level 0-12 of the CRI audio and the movies' audio (default 8; every level decodes to the same samples; 12 writes files 0.2-1.3 % smaller in about five times the encoding time); part of the task keys |
+| `--only-class C,...` | export only objects of these Unity classes; part of the task keys |
+| `--link` | how the layout files are made from the store (below): `auto` (default; `[export] link`), `clone`, `hard` or `copy` |
+| `--strict` | exit 1 when a view has gaps: a required role whose address names no catalog key or no fitting sub-object (empty values and roles that do not apply are not gaps); in `voices`, a voice whose cue sheet has no catalog key or whose decoded sheet lacks its cue, and a story episode without a catalog key |
+| `--dry-run` | print the plan and stop |
+| `--explain` | print every setting of the run first: store, context, selection, pipeline, stages not installed, parameters, workers, memory budget, recycling, layouts |
+
+A run resolves the context (region, language, catalog version) and indexes the catalog, identifies the selected
+bundles (the sha256 of each decrypted bundle, remembered by path, size and modification time; bundles not in the
+cache are fetched), takes the census of each bundle, links the scripts and addresses, exports the bundles, runs the
+stages that need those results (atlas sprites, views), writes the layouts and the reports. The selected raw files
+(CRI audio and movies) not in the cache are fetched while the bundle stages run. The census also covers
+the bundles the selected ones depend on, so script classes and atlas textures in other bundles resolve.
+
+Tasks run in spawned worker processes that stay alive between tasks (no more of them start than a stage has tasks to
+run). The longest tasks (by estimated CPU time) start first; a task starts only while the estimated peak memory of
+the running tasks and its own fits the budget, and a task estimated above the budget runs alone. A worker is
+replaced after 500 tasks or when its resident memory after a task is above 3 GiB, or above 40 % of its part of the
+memory budget (the budget divided by the workers) when that is less, but not below 256 MiB: a worker keeps much of
+its largest task's memory, which the budget does not count (`--explain` prints the threshold). The estimates come
+from each stage's cost model, scaled per stage by the costs measured in earlier runs of the store
+(`<store>/costs/calibration.json`, updated after every export; a task's measured peak counts from its worker's
+memory at its start). None of this changes an output: a run with one worker and a run with many write the same store
+and the same files.
+
+A failed object is reported with its task's result and stays failed until something in its key changes. A task that
+fails as a whole (an exception, an input that cannot be read, a worker that dies) leaves no result and runs again
+next time.
+
+### plan
+
+What `export` with the same flags would do, without running or fetching anything: every task with its status
+(`hit`: its result is stored, `run`, `unknown`: it reads the result of a task that would run first, or of a bundle
+not fetched yet), the reasons it runs (compared with the latest run of the same selection, or `--since RUN`), the
+estimated CPU time and peak memory, and with `-o` the files each layout would write, remove and keep. The text
+gives per stage its counts and its first 20 tasks that are not hits; `--json` has every task.
+
+| Flag | Meaning |
+|---|---|
+| `--json` | the plan document (`nnnotes.plan/1`) |
+| `--check` | exit 1 when anything would run or a layout file would change, else 0 |
+| `--census` | first fetch the bundles without a census and take it, so the plan knows every bundle's classes |
+| `--emit-tasks DIR` | write the tasks that can run now as task descriptions `DIR/<key>.json` |
+| `--why TASK` | one task: its status, reasons, and its key parts beside those of the previous run |
+
+Reasons: `new-input`, `input-changed`, `stage-version`, `atom-changed`, `params-changed`, `context-changed`,
+`previous-failed`, `result-missing`, `forced`; hits are `unchanged` or `cached` (the result is in the store from
+another run); unknown tasks are `pending` on a task, or on `fetch:<file>` for a bundle whose content is not known
+yet. See [contracts.md](contracts.md#plan-nnnotesplan1).
+
+### run-stage
+
+Runs task descriptions (`nnnotes.task/1`, as `plan --emit-tasks` writes them) into a store: each is checked (its key
+is recomputed, its stage must be installed at its version), its inputs are read by content id through their
+locators (the store, the cache, a file, or with `--fetch` the catalog), and its result is stored exactly as `export`
+would store it. Several tasks run one after another in one process; stages that do not read bundles never load
+UnityPy. `--force` runs tasks whose result is stored again (the new result must be identical).
+
+### catalogs
+
+The catalog versions of a store: `import` a catalog file (with the APK's catalog from `[paths] apk` or
+`--apk-catalog`), `fetch` the current catalog of the configured region and language, `list` them, and `diff` two of
+them (labels, version ids or sha256 prefixes): keys added, removed and changed, bundles and raw files by stable name,
+the keys that reach a changed file, and, when a run over each version has stored its address table, the objects by
+stable address (an object keeps its stable address while its object id changes with its bundle's content). A version
+is labelled by `--label`, else by its resource version, else by the first 12 hex digits of its sha256. `fetch`
+records the resource version it downloads (none for `main`); `import` takes `--resource-version`, else the JP
+catalog's source version, else the version in a file name `catalog_<version>_<language>.bin` as `fetch` and the
+cache name them (none for `main`). `export` imports the current catalog when it is not imported yet.
+
+### store verify
+
+Checks that every stored content has the sha256 its name says (`--quick`: sizes only) and that every result names
+its own key, has the key of its parts and names stored contents of the right size. Exit 1 when a problem is found.
+
+## Layouts
+
+A layout places the artifacts of a run as files; it never changes their bytes. With one layout the files are
+written into `OUT`, with several into `OUT/<layout>`. Each layout directory has a `manifest.json`
+(`nnnotes.layout/1`) listing the files it owns; a run writes files atomically, removes the files it owned that are
+no longer wanted, never touches other files, and continues an interrupted write on the next run.
+
+`original` uses the game's names:
+
+- an object with a container path is written at that path, in the catalog's spelling
+  (`Assets/AddressableResources/Image/Jacket/jacket_001.png`), its extension appended unless the path has it
+  (`…/prefab_x.prefab.json`);
+- other objects under the same container path: `stem[<name>].<ext>`, the Addressables sub-object form
+  (`…/member_full[square].png`);
+- objects without a container path: `_bundles/<stable bundle name>/<Class>/<name>~<pathId>.<ext>`;
+- secondary artifacts beside the primary one: `<path>.<role>.<ext>` (`….meta.json`, `….blob.m_Data.moc3`);
+- a container path present in two bundles: `stem@<stable bundle name>.ext` for each;
+- names Windows refuses, reserved device names and trailing dots are escaped as `%XX`; paths that coincide ignoring
+  case get `~<8 hex>` and are listed in the layout report;
+- the outputs of the CRI stages at the catalog names of their content: `Cri/Sound/<sheet>/<stream>.flac` with
+  `cues.json` and `streams.json`, `Cri/Video/<name>/…`; a content several names refer to is placed under each
+  name and listed in the layout report;
+- the views: `views/<view>.json`, each object entry with the `path` of its file in this layout (`views/voices.json`:
+  each stream of a voice).
+
+How the files are made (`--link`, or `[export] link`). Every method writes the same files and the same layout
+manifest; the run manifest and the printed summary name the method and why it was chosen.
+
+| `--link` | the files | extra space | an edit of a file |
+|---|---|---|---|
+| `clone` | clones (reflinks) of the store objects: Linux FICLONE (Btrfs, XFS, bcachefs, …), macOS APFS `clonefile` | none until a file is written (a quota that counts each file's blocks, such as an XFS project quota, counts them in full) | changes that file only |
+| `hard` | hard links to the store objects (same file system) | none | fails, except for the superuser: the store objects are read-only (on Windows a delete fails too) |
+| `copy` | copies | the whole layout again | changes that file only |
+| `auto` (default) | `clone` where the file system makes clones, else `hard` on the same file system, else `copy` | | |
+
+`auto` tries each method once, on a temporary file, before the run starts. An explicit `clone` or `hard` that does
+not work there is a usage error (exit 2) before anything runs; a file that fails with the chosen method is reported
+(summary, layout report, exit 1), left out of the manifest and placed by the next run: no file falls back to
+another method. The store writes its objects read-only; a layout clears the attribute of a file it owns before it
+replaces or removes it where the system needs that (Windows), and the store object stays read-only.
+
+`cas` is `assets/<sha256>.<ext>` per distinct content, plus the manifest. Each layout follows from the other: `cas`
+from the `original` manifest alone, `original` from `cas` and the results. The views are the exception: `original`
+has them with the paths of their objects, `cas` the view documents they are made from.
+
+## Reports
+
+`OUT/_reports/`:
+
+| File | Content |
+|---|---|
+| `run.json` | the run manifest (`nnnotes.run/1`): context, selection, parameters, stage versions, every task with its key and status, the layout manifests, a summary; also stored as `<store>/runs/<id>.json` |
+| `coverage.json` | per class the census total and the count of every item status (`exported`, `contained`, `generic`, `unsupported`, `failed`, and `missing`: objects no task covered; an object two tasks cover, such as a sprite whose image `sprite.crop` makes, counts once); per reason code its count and five examples |
+| `failures.json` | failed tasks and failed objects, with their codes and messages |
+| `sources.json` | files of the selection that could not be read: `source.absent` (a file the catalog names that is not there, or an APK file without `[paths] apk`), `source.error` (the download failed) |
+| `layout-<name>.json` | the paths renamed for collisions, the container paths present in several bundles, the contents placed under several names |
+
+The summary printed at the end names the run, the task and item counts, the layouts' write / remove / keep counts
+and the reports directory.
+
+## Exit codes
+
+| Command | 0 | 1 | 2 | 3 | 4 |
+|---|---|---|---|---|---|
+| `export` | complete (unsupported objects allowed) | a task, an object or a download failed (reports written); with `--strict` also view gaps | usage or settings | aborted: a setting or tool a task needs is missing, or interrupted; results written so far stay valid | |
+| `plan` | | with `--check`: something would run or change | usage or settings | | |
+| `run-stage` | every task ran or hit | a task failed or its result is partial | usage or settings | | a task is incompatible (edited, unknown stage or version); nothing of the batch runs |
+| `store verify` | no problem | problems found | usage or settings | | |
+
+## Running tasks elsewhere
+
+Task descriptions carry everything a task needs; any machine with the same nnnotes version and access to the store
+can run them. A task can only be described once the content of its inputs is known, so the bundles are identified
+first (`plan --census` fetches and hashes them and takes their census). Then plan the tasks that can run now, run
+them in batches on as many workers as you like, and plan again until nothing is left; `export` finally writes the
+layouts and reports (every task is a hit by then).
+
+```sh
+store=/data/nnnotes-store
+nnnotes plan --store "$store" --census > /dev/null
+for round in 1 2 3 4 5 6 7 8; do
+    rm -rf tasks
+    nnnotes plan --store "$store" --emit-tasks tasks > /dev/null
+    ls tasks/*.json > /dev/null 2>&1 || break           # nothing left to run
+    ls tasks/*.json | xargs -n 50 -P 16 nnnotes run-stage --store "$store" --fetch
+done
+nnnotes export --store "$store" -o out/assets
+```
+
+Each round runs the tasks whose inputs are known: the catalog index and the censuses, then the script and address
+tables, then the bundle exports, then the stages that read their results. A task whose result is already stored is
+a hit, so a batch can be run twice; a task that keeps failing is planned again in every round (the loop above stops
+after eight) and reported by `export`.