modelstage 0.0.0-stage → 0.5.28

package/config/plugins.json

@@ -0,0 +1,13 @@
+{
+  // 展示类型插件开关（JSONC，可写注释）。
+  //   id 的取值：plugins/ 下的目录名，或平铺单 js 的文件名去扩展名（与 /api/plugins 列出的 id 一致）。
+  //
+  // 禁用一个插件的完整效果（缺省 = 全部启用）：
+  //   ① /api/plugins 不再列出它 → 前端插件宿主不注入它的 js → 能力整体消失；
+  //   ② 它声明的 fileKinds（如 bundle 资源包）对应的条目**不再出现在角色库**——
+  //      条目本身是插件能力的一部分，插件没启用就不显示；
+  //   ③ /api/tree 对这类资源根返回空文件列表，并在响应里带 note 说明原因（可探测，不静默）。
+  //
+  // 用途：排查「某能力是否影响了别的东西」时，用配置关掉它做排除法，不需要改文件名或代码。
+  "disabled": []
+}

package/config/resources.example.json

@@ -0,0 +1,40 @@
+// 本地资源根配置示例 —— 复制为 config/resources.json 后再改成你的路径
+// 文件格式：JSONC（标准 JSON + // 注释）；注释由 tool/parse-jsonc.mjs 剥离
+//
+// 必填字段：id（唯一标识，会出现在索引文件名 config/models/<类型>.<id>.json 里）
+//           path（本机的资源目录绝对路径）
+// 可选字段：name（界面显示名，缺省用目录名）
+//           enabled（缺省 true；false = 停用但保留在配置里，随时可再启用）
+//           names（指向 config/names/<names>.json 的角色名表，用于显示角色名）
+//           icons（角色头像目录，可外置：{ "dir": "绝对路径" }）
+//           头像文件名记在名表的 characters[id].icon；名表没记时回退模型目录自带 icon.png
+//
+// 三点需要知道：
+//   · 不声明"这个根是什么类型"：每个根都会被 Spine 与 Live2D 两个扫描器各扫一遍，
+//     目录里有什么内容就进什么清单（config/models/ 下两份索引互不干扰，各自可重建）
+//   · 同级根用同一个 name 会被界面合并成一个游戏节点（同一角色的两种画风自动聚合）
+//   · 界面「选择目录」会重写本文件（只保留文件头部注释），手写内容会被一并覆盖
+//
+// 下面两个根只示范字段写法，值全是占位符：
+//   ① 把所有可选字段都填上（名表 + 外置头像 + 启用）
+//   ② 只写必填字段，并演示停用（enabled:false）
+{
+  "roots": [
+    {
+      "id": "example_spine",
+      "name": "示例游戏 A",
+      "path": "/path/to/your/spine/assets",
+      "names": "example_a",
+      "icons": {
+        "dir": "/path/to/your/char_icons"
+      },
+      "enabled": true
+    },
+    {
+      "id": "example_live2d",
+      "name": "示例游戏 B",
+      "path": "/path/to/your/live2d/assets",
+      "enabled": false
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "modelstage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.28",
+  "description": "Spine / Live2D 模型查看器：三级名册、两套渲染面共享相机与面板、UnityFS 资源包解包",
+  "type": "module",
+  "bin": {
+    "modelstage": "bin/modelstage.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node bin/modelstage.mjs",
+    "test": "node --test test/*.test.mjs",
+    "check:pack": "node tool/check-pack-boundary.mjs",
+    "prepublishOnly": "npm run check:pack && npm run test"
+  },
+  "files": [
+    "bin/",
+    "src/server/",
+    "src/shared/",
+    "src/web/",
+    "plugins/unity-live2d-bundle/",
+    "plugins/unity-spine-bundle/",
+    "tool/parse-jsonc.mjs",
+    "tool/resolve-live2d-runtimes.mjs",
+    "tool/lib/bundle-probe-node.mjs",
+    "tool/lib/paths.mjs",
+    "tool/lib/runtime-guides.mjs",
+    "tool/lib/runtime-package.mjs",
+    "tool/lib/spine-meta.mjs",
+    "tool/lib/spine-motions.mjs",
+    "tool/spine-motion-rules.json",
+    "config/plugins.json",
+    "config/models/",
+    "config/names/",
+    "config/resources.example.json",
+    "config/diag-upload.example.json",
+    "README.md",
+    "LICENSE",
+    "!**/.tmp-*",
+    "!**/*.bak",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EIGHTfs/ModelStage.git"
+  },
+  "homepage": "https://github.com/EIGHTfs/ModelStage#readme",
+  "author": "EIGHTfs",
+  "keywords": [
+    "spine",
+    "live2d",
+    "unityfs",
+    "assetbundle",
+    "viewer",
+    "model-viewer",
+    "cubism",
+    "animation"
+  ],
+  "bugs": {
+    "url": "https://github.com/EIGHTfs/ModelStage/issues"
+  }
+}

package/plugins/unity-live2d-bundle/README.md

@@ -0,0 +1,98 @@
+# unity-live2d-bundle
+
+把 **UnityFS 容器**（Unity AssetBundle）里的 Live2D 资产还原成标准 Live2D 模型文件集，交给核心装进 VirtualFS 渲染。
+
+- 角色：`provides: ["asset-provider"]`
+- 接管条目：`fileKinds: ["bundle"]`（无扩展名的单文件资源包）
+- 产物类型：`produces.kind: "live2d"`
+
+## 目录结构
+
+```
+plugin.json          清单（provides / fileKinds / produces / assets / errorCodes）
+index.js             入口：canHandle + resolve（注册到 window.SpineViewerPlugins）
+lib/unityfs.js       UnityFS 容器解析（头部字段、blocksInfo 两种布局、LZ4 块解压）
+lib/bytes.js         字节读写工具
+lib/serialized.js    SerializedFile 解析
+lib/typetree.js      类型树
+lib/errors.js        错误码与 fail()
+lib/common-strings.js
+profiles/            容器族规则（按容器类型命名，不绑定具体游戏）
+```
+
+## 契约要点（照这些实现，不要自创）
+
+**`canHandle(file)` 必须是纯判定**
+- 只允许读 `file` 的字段（含 `file.bytes`）做容器魔数判定
+- 禁止任何 I/O、禁止修改外部状态、禁止把异常抛给宿主
+- 没有 `file.bytes` 时**返回 `true`**（保守放行）——判 `false` 会让无扩展名的包永远选不中
+- 内部 try/catch 允许，但 catch 后 `return false` 时**必须记一条 debug 日志**（`host.log` 不可用时降级 `console.debug`）
+
+**`resolve(file)` 成功只返回三键**
+```js
+{ prefix, files, entry }
+```
+- `prefix` 格式：`vfs://<providerId>/<rootId>/<相对目录>/`，全局唯一、恒以 `/` 结尾
+- `files`：`relPath → Uint8Array | string`，`relPath` 用 `/` 分隔、允许子目录；`string` 按 UTF-8 读回（model3/motion3/physics3 用 JSON 文本）
+- `entry`：包内**实际存在**的 `*.model3.json` 相对路径
+- 不返回 `report` 之类的附加字段；诊断信息走 `host.log`
+
+**取字节通道**：优先 `file.bytes`；缺失时用 `host.fetchFile(rootId, rel) → Promise<Uint8Array>`
+（注意：直接返回 `Uint8Array`，不是 `{ bytes }`；`host` 不可用则抛 `ULB_ERR_NO_HOST`）
+
+**没有 prepare / revoke 钩子**。渲染前要做的事（重建 model3、解纹理并编码 PNG、把 AnimationClip 转成 motion3）**全部在 `resolve()` 内完成**，`files` 就是最终产物；资源释放由核心按 `prefix` 调 `VirtualFS.revoke()`。
+
+**失败一律抛带 `code` 的 Error**，码表见 `plugin.json` 的 `errorCodes`，核心按 `code` 决定提示文案。
+
+## 容器解析支持范围
+
+UnityFS 的 `blocksInfo` 有两种布局，**必须都支持**（这是踩过的坑）：
+
+```
+(flags & 0x80) == 0    blocksInfo 内联在头部
+                       数据起点 = blocksInfoStart + blocksInfoCompressedSize
+                       （该段按"声明长度"占位，声明长度 > 表内容长度时差额是表尾对齐填充，必须跳过）
+
+(flags & 0x80) != 0    blocksInfo 在文件尾
+                       先存 position → 跳到 Length - compressedSize 读表 → seek 回保存值
+                       回来后就是 header 结束、数据块开始的位置，**不能再加 compressedSize**
+```
+
+> 真实事故：旧实现只写了第一种，对第二种的包也加了 `compressedSize`，把数据起点整体推后
+> （`aijier_3`，Unity 2018.4 / version 6 / LZ4 / `dataflags 0xC2`，推后 101 字节）→ 数据块错位
+> → LZ4 解出垃圾 → 报「LZ4 数据损坏：匹配位置越界」，**报错位置与真实根因相距极远**。
+>
+> 另一个坑：`ArchiveFlags` 里 `0x40` 名义上叫 `BlocksAndDirectoryInfoCombined`，但**实现的判断链里
+> 从不读它**（正常包 `dataflags 0x240` 也带这一位）。拿它当"不支持该布局"的依据会把全部正常包一起拒掉。
+
+**不要相信"解压成功"**：LZ4 块解压通常只校验"输出长度 == expectedSize"，错位数据可能恰好自洽解出。
+必须用结构自洽交叉验证（各段长度相加等于段起点、`bundleSize` 等于实际文件长度、node size 之和等于 block unc 之和等）。
+
+## profile 机制
+
+游戏/容器族的差异走 `profiles/<profile>.json`，**代码里不写死任何游戏名**：
+
+- 资源根配置透传 `profile` 字段 → `resolve` 读到 `ctx.profile` → 自读 `profiles/<profile>.json`
+- 缺 `profile` 或文件不存在 ⇒ 走默认规则，**不报错**
+- profile 按**容器类型/容器族**命名，不要按单一游戏命名（会让"只支持某游戏"的错觉传下去）
+
+## 自检
+
+插件自身的判定/解析/产物形态由仓库统一检查工具覆盖（带契约条款号）：
+
+```bash
+node tool/check-plugin.mjs plugins/unity-live2d-bundle
+```
+
+覆盖：清单与角色合法性、register 形态、`canHandle` 同步布尔、`resolve` 错误码、PL1–PL8 契约条目。
+
+## 边界
+
+- 不读 `src/web/engine`、不假设渲染层细节；产物只按契约三键交付
+- 不做 Blob URL 装载、不安装运行时适配器（那些属于旧宿主通道，已删除）
+- 不设单包体积上限（峰值由核心 `revoke` 控住）
+
+## 只保留一套契约
+
+插件只实现 `canHandle` / `resolve` 两个入口（`probe` / `open` / `produces.legacyEntry` 已移除）。
+宿主按这套契约调用，不再保留任何兼容层。