@cavegiant/cave-world-r3f 1.0.0

package/doc/scene-json-structure.md

@@ -0,0 +1,567 @@
+# 空间场景 JSON 结构设计文档
+
+## 概述
+
+本文档描述 `@cavegiant/cave-world-r3f` 所消费的 3D 场景 JSON（`CaveSpace`）数据结构。该设计参考 Unity 的 GameObject + Component 模式，提供了高扩展性的场景描述能力。
+
+完整 TypeScript 定义见 `@cavegiant/cave-world-r3f/types`，该子路径为纯类型、零运行时。
+
+> **关于「宿主注册类型」**：部分 `type`（`infoPoint`、`panoramaVideo`、`digitalHuman2D`、`text`、`light`、`audio`、`npc`）是**官方 schema 类型但没有内置渲染器** —— 它们的视觉与交互高度依赖具体产品。SDK 只保证类型契约；未注册渲染器时这类对象会被静默跳过，注册方式见 [API.md](./API.md#object-renderers)。
+
+## 核心设计理念
+
+1. **GameObject + Component 模式**: 每个 3D 对象都是一个 GameObject，通过添加不同的 Component 来实现各种功能
+2. **高扩展性**: 支持自定义 Component 类型，便于后续功能扩展
+3. **层次化结构**: 支持父子关系，便于场景组织
+4. **类型安全**: 提供完整的 TypeScript 类型定义
+
+## JSON 结构
+
+### 1. 空间场景根结构 (Space)
+
+```json
+{
+  "specVersion": "1.0.0", // JSON结构规范版本
+  "contentVersion": 3, // 数据内容版本（发布时自增）
+  "metadata": {
+    "name": "场景名称",
+    "description": "场景描述",
+    "creatorId": "3123123123123",
+    "publishTime": 1759949369151,
+    "thumbnail": "场景缩略图URL"
+  },
+  "baseLayer": {
+    "visible": true,
+    "transform": {
+      "position": [0, 0, 0],
+      "rotation": [0, 0, 0, 1],
+      "scale": [1, 1, 1]
+    },
+    "scene": {
+      // 基础场景
+      "type": "splat", // "splat" | "model"
+      "url": "基础场景资源URL（默认 LOD，单档场景必填；splatLevels 存在时作为兜底）",
+      "splatCount": 3500000, // 可选，3DGS 点数（仅供作者参考；超出设备能力时控制台会警告）
+      "splatLevels": [
+        // 可选，多 LOD 列表。存在时系统按设备能力（PC ≈ 3M，移动端 ≈ 2M）挑选合适档位。
+        { "url": "low.splat", "splatCount": 800000 },
+        { "url": "medium.splat", "splatCount": 1800000 },
+        { "url": "high.splat", "splatCount": 3000000 }
+      ]
+    },
+    "colliders": [
+      // 场景碰撞体
+      {
+        "id": "123",
+        "type": "box", // "box" | "gltf" | "model"
+        "box": {
+          "position": [0, 0, 0],
+          "rotation": [0, 0, 0, 1],
+          "scale": [1, 1, 1]
+        }
+      },
+      {
+        "id": "456",
+        "type": "gltf",
+        "src": "https://xxxxx.glb"
+      },
+      {
+        "id": "789",
+        "type": "model",
+        "url": "https://xxxxx.obj",
+        "size": 6042883 // 可选，文件大小（字节）
+      }
+    ],
+    "boundaries": [
+      // 基础边界（随transform同步变换）
+      {
+        "id": "123",
+        "type": "box", // "box" | "polygon"
+        "collisionEnabled": true,
+        "box": {
+          "position": [0, 0, 0],
+          "rotation": [0, 0, 0, 1],
+          "scale": [1, 1, 1]
+        }
+      },
+      {
+        "id": "456",
+        "type": "polygon",
+        "collisionEnabled": true,
+        "polygon": {
+          "points": [
+            [10, 0, 10],
+            [30, 0, 10],
+            [30, 0, 30],
+            [10, 0, 30]
+          ],
+          "height": 5
+        }
+      }
+    ],
+    "lighting": {
+      "ambientColor": "#404040",
+      "ambientIntensity": 0.3,
+      "directionalLight": {
+        "color": "#ffffff",
+        "intensity": 1.0,
+        "direction": [1, -1, 0],
+        "castShadow": true
+      }
+    },
+    "skybox": {
+      // 天空盒/背景
+      "type": "cubemap", // "cubemap" | "color"
+      "color": "#87CEEB",
+      "urls": {
+        "px": "right.jpg",
+        "nx": "left.jpg",
+        "py": "top.jpg",
+        "ny": "bottom.jpg",
+        "pz": "front.jpg",
+        "nz": "back.jpg"
+      }
+    },
+    "ambientAudio": {
+      // 背景环境音
+      "url": "环境音URL",
+      "volume": 0.5,
+      "autoplay": true
+    },
+    "connectors": [
+      // 场景连接器——触发场景过渡
+      {
+        "id": "conn-1",
+        "name": "通往大厅",
+        "type": "connector",
+        "transform": {
+          "position": [10, 0, 0],
+          "rotation": [0, 1.57, 0], // Euler 角度
+          "scale": [2, 3, 1]
+        },
+        "connectorInfo": {
+          "to": [
+            {
+              "caveWorldId": "target-space-id",
+              "transitionType": "seamless", // "seamless" | "portal"
+              "transform": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 3, 1] // Matrix4x4 列主序，方向：源 → 目标（seamless 专用）
+            }
+          ]
+        }
+      },
+      {
+        "id": "conn-2",
+        "name": "传送门",
+        "type": "connector",
+        "transform": {
+          "position": [-5, 0, 8],
+          "rotation": [0, 0, 0],
+          "scale": [2, 3, 2]
+        },
+        "connectorInfo": {
+          "to": [
+            {
+              "caveWorldId": "lobby-space-id",
+              "transitionType": "portal",
+              "connectorId": "lobby-conn-1" // 目标场景中的连接器 ID（portal 专用）
+            },
+            {
+              "caveWorldId": "garden-space-id",
+              "transitionType": "portal",
+              "connectorId": "garden-conn-1"
+            }
+          ]
+        }
+      }
+    ],
+    "physics": {
+      "enabled": true,
+      "gravity": [0, -9.81, 0]
+    },
+    "spawnPoint": {
+      "position": [0, 0, 0],
+      "yaw": 0
+    }
+  },
+  "customLayers": [
+    // 自定义图层数组（默认一个）
+    {
+      "name": "default",
+      "visible": true,
+      "objects": []
+    }
+  ]
+}
+```
+
+#### baseLayer.scene 字段说明（3DGS LOD）
+
+| 字段          | 类型                         | 必填 | 说明                                                             |
+| ------------- | ---------------------------- | ---- | ---------------------------------------------------------------- |
+| `type`        | `'splat' \| 'model'`         | 是   | 基础场景资源类型                                                 |
+| `url`         | `string`                     | 是   | 默认资源 URL；当 `splatLevels` 不存在时被直接使用                |
+| `source`      | `{ from, id? }`              | 否   | 资源来源元信息（业务侧使用）                                     |
+| `splatCount`  | `number`                     | 否   | 默认 URL 的 3DGS 点数。仅作为提示：超出设备阈值时会在控制台 warn |
+| `splatLevels` | `Array<{ url, splatCount }>` | 否   | 多档 LOD 列表。存在时系统按设备能力自动选档                      |
+
+**LOD 选择规则**（仅当 `splatLevels` 非空时启用）：
+
+1. 计算当前设备的点数上限 `cap`：
+   - 桌面：3,000,000（≈300 万）
+   - 移动端（通过 `(hover: none) and (pointer: coarse)` 检测）：2,000,000（≈200 万）
+2. 在 `splatCount ≤ cap` 的档位里挑 **点数最多** 的（最佳画质 + 流畅）。
+3. 如果所有档位都超过 `cap`，挑 **点数最少** 的（兜底：降低画质但仍可播放）。
+4. 如果 `splatLevels` 为空数组或所有 entry 无 `url`，退化回 `url` 字段。
+
+设备阈值在 `@cave-world/space` 中以 `DESKTOP_SPLAT_COUNT_CAP` / `MOBILE_SPLAT_COUNT_CAP` 常量导出。
+
+#### baseLayer.spawnPoint 字段说明（出生点）
+
+| 字段       | 类型      | 必填 | 说明                                                                                          |
+| ---------- | --------- | ---- | --------------------------------------------------------------------------------------------- |
+| `position` | `Vector3` | 是   | 出生位置，baseLayer 局部坐标（应用 `baseLayer.transform` 之前，与 collider / connector 一致） |
+| `yaw`      | `number`  | 是   | 人物朝向，绕 Y 轴的弧度。`0` 表示面向 +Z                                                      |
+
+**运行时行为**：
+
+- 仅在玩家**首次进入主场景**且 `space:initialized` 触发后应用一次。
+- 世界位姿由 `G_target × T_target × spawn_local` 计算（与 portal 连接器落点同一套矩阵管线）。
+- seamless / portal 场景切换不会重新应用；缺省时保留 `<SimpleCharacter>` 默认初始位姿。
+
+### 2. 要素结构 (CustomObject)
+
+内置渲染器覆盖 `model`、`splat`、`image`、`video`、`poi`、`portal`、`placeholder`；其余为宿主注册类型（见文首说明）。
+
+```json
+{
+  "id": "unique-element-id",
+  "name": "要素名称",
+  "type": "model", // "splat" | "model" | "text" | "image" | "video" | "npc" | "light" | "audio" | "placeholder" | "poi" | "digitalHuman2D" | "portal" | "infoPoint" | "panoramaVideo"
+  "visible": true,
+  "transform": {
+    "position": [0, 0, 0],
+    "rotation": [0, 0, 0, 1], // quaternion [x, y, z, w]
+    "scale": [1, 1, 1]
+  },
+  "parent": "parent-element-id", // 可选，父要素ID
+  "children": ["child-id-1", "child-id-2"], // 可选，子要素ID数组
+
+  // 根据type不同，包含不同的主要属性
+  "model": {
+    "url": "模型文件URL",
+    "color": "#ffffff", // 可选，整体颜色
+    "opacity": 1.0, // 可选，透明度
+    "castShadow": true,
+    "receiveShadow": true
+  },
+
+  "text": {
+    "content": "显示的文字内容",
+    "fontSize": 16,
+    "color": "#ffffff",
+    "backgroundColor": "#000000", // 可选
+    "maxWidth": 200, // 可选
+    "alignment": "center" // "left" | "center" | "right"
+  },
+
+  "image": {
+    "url": "图片URL",
+    "opacity": 0.5, // 可选
+    "transparent": true, // 可选
+    "billboard": true // 可选，是否始终面向相机
+  },
+
+  "video": {
+    "url": "视频URL",
+    "autoplay": false,
+    "loop": true,
+    "muted": false,
+    "controls": true
+  },
+
+  "light": {
+    "lightType": "directional", // "directional" | "point" | "spot"
+    "color": "#ffffff",
+    "intensity": 1.0,
+    "range": 10.0, // point/spot light
+    "spotAngle": 30.0, // spot light
+    "castShadow": true
+  },
+
+  "audio": {
+    "url": "音频文件URL",
+    "volume": 1.0,
+    "loop": false,
+    "autoplay": false,
+    "spatial": true // 是否3D空间音频
+  },
+
+  // 自定义行为组件
+  "components": {
+    "Window": {
+      "name": "Window",
+      "type": "leftRight",
+      "content": []
+    },
+    "Collider": {
+      "name": "Collider",
+      "shape": "box", // "box" | "sphere" | "mesh"
+      "transform": {
+        "position": [0, 0, 0],
+        "rotation": [0, 0, 0, 1], // quaternion [x, y, z, w]
+        "scale": [1, 1, 1]
+      },
+      "isTrigger": false
+    }
+  }
+}
+```
+
+#### infoPoint 信息点（`type: "infoPoint"`）
+
+结构化信息标注：3D 场景中的可点击标签 + 详情载荷。SDK 仅定义 JSON 契约；**运行时渲染与详情 UI 由宿主门户注册**（`ObjectRegistry.register('infoPoint', Renderer)`），与 `text` / `npc` 等同。
+
+**与 `poi` 的区别**：`poi` 使用 `text` 字段渲染 3D 文本圆点；`infoPoint` 使用 `infoPoint.detail` 结构化载荷，标签样式与弹窗由门户实现。
+
+**与 `Window` 组件的区别**：`Window` 为 proximity + F 键打开 SDK `DetailWindow`；`infoPoint` 为点击 Html 标签触发 `object:click`，详情由门户监听并渲染。
+
+**`label` vs `detail.title`**：`infoPoint.label` 为 3D 标签文案（缺省回退 `name`）；`detail.title` 为详情面板 badge 文案（如 gallery 布局顶部徽章）。
+
+| 字段                                 | 类型              | 必填 | 说明           |
+| ------------------------------------ | ----------------- | ---- | -------------- |
+| `type`                               | `'infoPoint'`     | 是   | 要素类型       |
+| `id`, `name`, `visible`, `transform` | 同 CustomObject   | 是   | 标准要素字段   |
+| `infoPoint`                          | `InfoPointProps`  | 是   | 信息点载荷     |
+| `infoPoint.label`                    | `string`          | 否   | 3D 标签文字    |
+| `infoPoint.detail`                   | `InfoPointDetail` | 是   | 点击后详情数据 |
+| `infoPoint.detail.variant`           | `string`          | 是   | 详情布局类型   |
+
+**gallery variant**（`detail.variant === "gallery"`）：
+
+| 字段      | 类型       | 必填 | 说明                       |
+| --------- | ---------- | ---- | -------------------------- |
+| `images`  | `string[]` | 是   | 图片 URL 列表（至少 1 张） |
+| `title`   | `string`   | 是   | 详情面板 badge 文案        |
+| `content` | `string`   | 是   | 正文（支持 `\n` 换行）     |
+
+**variant 扩展**：新增 variant 时在本文档登记字段 schema；门户通过 `detail.variant` 分发渲染，SDK 不内置 UI。
+
+```json
+{
+  "id": "info-grassland-01",
+  "name": "草原介绍点",
+  "type": "infoPoint",
+  "visible": true,
+  "transform": {
+    "position": [0, 1.8, -3],
+    "rotation": [0, 0, 0, 1],
+    "scale": [1, 1, 1]
+  },
+  "infoPoint": {
+    "label": "草原介绍点",
+    "detail": {
+      "variant": "gallery",
+      "images": ["https://cdn.example.com/a.jpg", "https://cdn.example.com/b.jpg"],
+      "title": "介绍",
+      "content": "正文内容，支持换行。\n\n第二段。"
+    }
+  }
+}
+```
+
+#### panoramaVideo 360° 全景视频（`type: "panoramaVideo"`）
+
+可点击的 360° 全景视频热点：3D 场景中的视频标签 + 全屏沉浸式播放器。SDK 仅定义 JSON 契约；**运行时标签与播放器由宿主门户注册**（`ObjectRegistry.register('panoramaVideo', Renderer)`）。
+
+**与 `video` 的区别**：`video` 在场景内以平面贴图 inline 播放；`panoramaVideo` 为 Html 标签点击后打开全屏 equirectangular 球面播放器。
+
+**与 `infoPoint` 的区别**：`infoPoint` 为信息展示（gallery 等底部弹窗）；`panoramaVideo` 为沉浸式媒体热点，标签样式与全屏播放器独立实现。
+
+| 字段                                 | 类型                 | 必填 | 说明                           |
+| ------------------------------------ | -------------------- | ---- | ------------------------------ |
+| `type`                               | `'panoramaVideo'`    | 是   | 要素类型                       |
+| `id`, `name`, `visible`, `transform` | 同 CustomObject      | 是   | 标准要素字段                   |
+| `panoramaVideo`                      | `PanoramaVideoProps` | 是   | 全景视频载荷                   |
+| `panoramaVideo.label`                | `string`             | 否   | 3D 标签文字（缺省回退 `name`） |
+| `panoramaVideo.url`                  | `string`             | 是   | 等距柱状投影（2:1）视频 URL    |
+| `panoramaVideo.poster`               | `string`             | 否   | 加载前封面图                   |
+| `panoramaVideo.title`                | `string`             | 否   | 播放器内标题 overlay           |
+| `panoramaVideo.description`          | `string`             | 否   | 播放器内说明 overlay           |
+| `panoramaVideo.autoplay`             | `boolean`            | 否   | 打开后自动播放，默认 `true`    |
+| `panoramaVideo.loop`                 | `boolean`            | 否   | 循环播放，默认 `false`         |
+| `panoramaVideo.muted`                | `boolean`            | 否   | 静音，默认 `true`              |
+| `panoramaVideo.initialYaw`           | `number`             | 否   | 初始水平视角（度），默认 `0`   |
+| `panoramaVideo.initialPitch`         | `number`             | 否   | 初始俯仰角（度），默认 `0`     |
+| `panoramaVideo.fov`                  | `number`             | 否   | 视场角（度），默认 `75`        |
+
+```json
+{
+  "id": "panorama-sunset-01",
+  "name": "日落全景",
+  "type": "panoramaVideo",
+  "visible": true,
+  "transform": {
+    "position": [2.5, 1.8, -4.0],
+    "rotation": [0, 0, 0, 1],
+    "scale": [1, 1, 1]
+  },
+  "panoramaVideo": {
+    "label": "观看日落全景",
+    "url": "https://cdn.example.com/panorama/sunset-360.mp4",
+    "poster": "https://cdn.example.com/panorama/sunset-poster.jpg",
+    "title": "草原日落",
+    "description": "拖动屏幕环视，感受鄂尔多斯草原的黄昏。",
+    "autoplay": true,
+    "loop": false,
+    "muted": true,
+    "initialYaw": 90,
+    "initialPitch": 0,
+    "fov": 75
+  }
+}
+```
+
+### 3. 自定义图层结构 (CustomLayer)
+
+```json
+{
+  "name": "图层名称",
+  "visible": true,
+  "objects": [
+    // 要素数组
+  ]
+}
+```
+
+### 4. Component 类型
+
+功能性/特征类组件：
+ComponentName: ComponentAttribute
+
+#### Window - 窗口
+
+```json
+{
+  "placement": "leftRight",
+  "content": []
+}
+```
+
+#### Collider - 碰撞体
+
+```json
+{
+  "shape": "box", // "box" | "sphere" | "mesh"
+  "transform": {
+    "position": [0, 0, 0],
+    "rotation": [0, 0, 0, 1], // quaternion [x, y, z, w]
+    "scale": [1, 1, 1]
+  },
+  "isTrigger": false
+}
+```
+
+#### Rigidbody - 刚体
+
+```json
+{
+  "mass": 1.0,
+  "useGravity": true,
+  "isKinematic": false
+}
+```
+
+### 5. 连接器结构 (ConnectorDef)
+
+连接器定义在 `baseLayer.connectors` 数组中，用于描述场景之间的过渡关系。每个连接器的几何体为一个 box，当用户角色触碰到该 box 时触发场景过渡。
+
+```json
+{
+  "id": "conn-1",
+  "name": "连接器名称",
+  "type": "connector",
+  "transform": {
+    "position": [10, 0, 0],
+    "rotation": [0, 1.57, 0],
+    "scale": [2, 3, 1]
+  },
+  "connectorInfo": {
+    "to": [
+      {
+        "caveWorldId": "目标场景ID",
+        "transitionType": "seamless",
+        "transform": [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5, 0, 3, 1]
+      }
+    ]
+  },
+  "label": {
+    "variant": "beacon",
+    "text": "古庙遗址",
+    "thumbnail": "https://cdn/.../thumb.webp",
+    "visibility": { "maxDistance": 50 }
+  }
+}
+```
+
+#### label 字段（可选）
+
+始终可见的 3D 指引标签，仅对含 `portal` 目标的 connector 生效。
+
+| 字段                           | 类型                         | 说明                                                                   |
+| ------------------------------ | ---------------------------- | ---------------------------------------------------------------------- |
+| `label`                        | `ConnectorLabelDef \| false` | 省略时遵循 SDK `connectorLabel` prop；`false` 显式关闭                 |
+| `label.variant`                | `string`                     | 内置 `'beacon'`（默认）                                                |
+| `label.text`                   | `string`                     | 显示文案；缺省取目标场景 `metadata.name`，再缺省为「前方场景」         |
+| `label.icon`                   | `string`                     | 图标 URL                                                               |
+| `label.thumbnail`              | `string`                     | 缩略图 URL；缺省取目标场景 `metadata.thumbnail`                        |
+| `label.anchorOffset`           | `[x,y,z]`                    | 标签锚点相对 connector 中心的偏移；默认 `[0, scaleY/4+0.2, 0]`         |
+| `label.visibility.maxDistance` | `number`                     | 最大可见距离（米），默认 30                                            |
+| `label.visibility.minDistance` | `number`                     | 最小可见距离（米），默认 5；进入 box 时 SDK 也会隐藏                   |
+| `label.visibility.fadeRange`   | `number`                     | 淡入淡出范围，默认 5                                                   |
+| `label.custom`                 | `object`                     | 透传给自定义 `renderConnectorLabel`                                    |
+| `label.clickable`              | `boolean`                    | 点击标签是否触发 portal 跳转，默认 `true`；设为 `false` 时仅展示不可点 |
+
+```json
+{
+  "id": "conn-portal",
+  "name": "传送门",
+  "type": "connector",
+  "transform": { "position": [10, 0, 0], "rotation": [0, 1.57, 0], "scale": [2, 3, 1] },
+  "connectorInfo": {
+    "to": [{ "caveWorldId": "scene-b", "transitionType": "portal", "connectorId": "entry" }]
+  }
+}
+```
+
+纯 seamless connector 即使配置 `label` 也不会显示标签。
+
+#### 过渡类型
+
+| transitionType | 行为                                                                  | 专属字段                                                                                      |
+| -------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `seamless`     | 角色触碰 box 时自动切换：隐藏当前场景，显示目标场景                   | `transform`（Matrix4x4 列主序 16 元素数组，**从源场景到目标场景的对齐矩阵**——见下文方向说明） |
+| `portal`       | 角色触碰 box 时展示目的地列表，用户选择后传送到目标场景对应连接器位置 | `connectorId`（目标场景中的连接器 ID，决定传送位置和朝向）                                    |
+
+#### transform 字段说明
+
+- `position`：box 中心在 baseLayer 局部坐标系中的位置 `[x, y, z]`
+- `rotation`：Euler 角度 `[x, y, z]`（注意：与 CustomObject 使用的四元数不同）
+- `scale`：box 尺寸 `[width, height, depth]`
+
+#### seamless connectorInfo.to[].transform 方向约定
+
+`connectorInfo.to[].transform`（仅 `seamless` 使用）是一个 4x4 列主序矩阵 `M_raw`，
+**方向为「源场景 → 目标场景」**——即把一个点从源场景的模型局部坐标系
+（应用 `baseLayer.transform` 之前的坐标）映射到目标场景对应的模型局部坐标系：
+
+```
+p_target_local = M_raw × p_source_local
+```
+
+在渲染时，SDK 会基于此约定计算目标场景 `<group>` 的世界变换：
+
+```
+G_target = G_source × T_source × inverse(M_raw) × inverse(T_target)
+```
+
+其中 `T_source` / `T_target` 是各自 `baseLayer.transform` 对应的矩阵。