场景捆绑包 ZIP 格式

用于导入导出场景及其引用的场景资源文件。

ZIP 结构

scene_bundle.zip
├─ scene.json           # 场景元数据与定义
└─ assets/
   ├─ scene_asset_xxx/  # 每个场景资源一个子目录
   │  ├─ asset.json     # 资源元数据
   │  └─ files/         # 资源原始文件
   │     ├─ model3.json
   │     ├─ textures/
   │     │  ├─ tex_00.png
   │     │  └─ tex_01.png
   │     └─ motions/
   │        └─ idle.motion3.json
   └─ scene_asset_yyy/
      ├─ asset.json
      └─ files/
         └─ bg.webp

scene.json

字段	类型	必填	说明
version	number	是	固定为 1
id	string	是	场景 UUID（用于导入冲突检测）
name	string	是	场景名称
definition	object	是	场景定义对象，结构与场景编辑器中一致。包含 nodes / animationGroups / rules 等字段。

asset.json

字段	类型	必填	说明
version	number	是	固定为 1
id	string	是	资源 UUID
displayName	string	是	资源显示名
kind	string	是	资源类型：cubism / spine / image / image_variant / video / audio
entryPath	string	是	入口文件在 files/ 下的相对路径，如 model3.json
metadata	object	否	资源元数据（动画列表、表情列表、差分定义、状态/动作预设等）

导入行为

• 导入时按 UUID 检测冲突：若本地已存在同 UUID 的场景或场景资源，弹出确认对话框让用户选择覆盖或导入为副本。
• 导入为副本时会生成新的 UUID，并用 ID 映射表替换 scene.json 中的 assetId 引用。
• definition 中所有 assetId 引用会在导入时自动重新映射。
• 导入后需要手动挂载到人格或群聊才能使用。

最小示例

// scene.json
{
  "version": 1,
  "id": "scene_abc123",
  "name": "咖啡店背景",
  "definition": {
    "version": 1,
    "nodes": [
      {
        "id": "scene_camera",
        "kind": "camera",
        "assetId": "",
        "x": 0,
        "y": 0
      },
      {
        "id": "node_bg",
        "kind": "image",
        "assetId": "scene_asset_bg01",
        "x": 0.5,
        "y": 0.5,
        "scaleX": 1,
        "scaleY": 1,
        "fit": "cover"
      }
    ],
    "animationGroups": [],
    "rules": []
  }
}

// asset.json (assets/scene_asset_bg01/asset.json)
{
  "version": 1,
  "id": "scene_asset_bg01",
  "displayName": "咖啡店背景图",
  "kind": "image",
  "entryPath": "bg.webp",
  "metadata": {}
}

AI 生成约束

• scene.json 中的 definition 对应 SceneDefinition 对象，必须包含 nodes 节点数组。
• 每个节点的 kind 必须是合法值：cubism / spine / image / image_variant / video / audio / slot / camera。
• camera 节点 ID 固定为 scene_camera，且每个场景只能有一个。
• 非 camera / slot 节点必须有 assetId 且不为空。
• 如果 ZIP 中不包含某 assetId 对应的资源，导入时该节点会标记为资源缺失。
• ZIP 内所有路径使用 / 分隔。

常见错误

• definition.nodes 为 [] → 场景有效但渲染结果为空
• 节点引用的 assetId 在 ZIP 中没有对应资源 → 导入成功但节点资源缺失
• asset.json 中 kind 写成了中文如 "图片" → 必须使用英文枚举值
• entryPath 指向的文件在 files/ 下不存在 → 资源导入后入口文件缺失