u-space 0.0.28 → 0.0.30

package/docs/api-objects.md

@@ -26,6 +26,213 @@
 | :--------------------------- | :-------- | :----- | :--------------------------------------------------------------- |
 | `ignoreInvisibleWhenRaycast` | `boolean` | `true` | 为 `true` 时，不可见的组在射线检测时会被跳过（不参与碰撞）。     |
 
+## `InstanceObject`
+
+`InstanceObject` 是核心包导出的统一实例对象基类。无论实例最终由合并楼层几何、`InstancedMesh`、`EditableGeometryBatchLayer` 还是 fallback `Model` 渲染，业务代码都可以使用相同的身份、显隐、颜色、透明度、高亮、包围盒和 materialize API。
+
+```typescript
+import {
+  InstanceObject,
+  isInstanceObject,
+  INSTANCE_COLOR_MODE_NONE,
+  INSTANCE_COLOR_MODE_OVERRIDE,
+  INSTANCE_COLOR_MODE_TINT,
+} from 'u-space';
+```
+
+### 类型和常量
+
+#### `InstanceStyle`
+
+| 属性        | 类型            | 说明                                                    |
+| :---------- | :-------------- | :------------------------------------------------------ |
+| `color`     | `Color \| null` | 当前样式颜色；`null` 表示不使用实例颜色。               |
+| `colorMode` | `number`        | 当前颜色模式，值为下表中的颜色模式常量。                |
+| `opacity`   | `number`        | 当前透明度，实例设置 API 会将其限制在 `0` 到 `1` 之间。 |
+
+#### `InstanceObjectOptions`
+
+| 属性          | 类型     | 必填 | 默认值             | 说明                       |
+| :------------ | :------- | :--- | :----------------- | :------------------------- |
+| `boundsName?` | `string` | 否   | `'InstanceBounds'` | 内部手动包围盒节点的名称。 |
+
+#### `InstanceIdentity`
+
+| 属性    | 类型             | 必填 | 说明                                                    |
+| :------ | :--------------- | :--- | :------------------------------------------------------ |
+| `id?`   | `string \| null` | 否   | 实例 ID。省略时保持原值，显式传 `null` 时清为空字符串。 |
+| `kind?` | `string \| null` | 否   | 实例类型。省略时保持原值，显式传 `null` 时清为空字符串。 |
+| `name?` | `string \| null` | 否   | 实例名称。省略时保持原值，显式传 `null` 时清为空字符串。 |
+
+`InstanceIdentity` 的三个字段都可省略且可为 `null`：省略的字段保持不变，显式传入 `null` 会将对应身份字段清为空字符串。
+
+#### 颜色模式常量
+
+| 常量                           | 值  | 说明                                           |
+| :----------------------------- | :-: | :--------------------------------------------- |
+| `INSTANCE_COLOR_MODE_NONE`     | `0` | 不使用实例颜色。                               |
+| `INSTANCE_COLOR_MODE_OVERRIDE` | `1` | 使用指定颜色覆盖原材质颜色。                   |
+| `INSTANCE_COLOR_MODE_TINT`     | `2` | 将指定颜色作为 tint 与原材质颜色混合。         |
+
+### 字段
+
+| 字段             | 类型                | 默认值             | 说明                                                     |
+| :--------------- | :------------------ | :----------------- | :------------------------------------------------------- |
+| `isInstanceObject` | `boolean`           | `true`             | 实例对象标识，供 `isInstanceObject()` 类型守卫使用。      |
+| `type`             | `string`            | `'InstanceObject'` | Three.js 对象类型名称。                                  |
+| `instanceId`       | `string`            | `''`               | 实例 ID。                                                |
+| `instanceKind`     | `string`            | `''`               | 实例类型。                                               |
+| `instanceName`     | `string`            | `''`               | 实例名称。                                               |
+| `geometry`         | `BufferGeometry`    | 空几何体           | 实例对象公开的兼容几何体字段。                           |
+| `boundingBox`      | `Box3 \| null`      | `null`             | 本地坐标包围盒缓存。                                     |
+| `boundingSphere`   | `Sphere \| null`    | `null`             | 本地坐标包围球缓存。                                     |
+
+### 构造函数
+
+#### `new InstanceObject(options?)`
+
+```typescript
+const instance = new InstanceObject({ boundsName: 'FloorBounds' });
+```
+
+`options` 的类型为 `InstanceObjectOptions`；省略时使用默认的内部包围盒节点名称 `InstanceBounds`。
+
+### 身份和样式
+
+身份、显隐和基础样式方法都返回当前实例，可以链式调用：
+
+```typescript
+const instance = new InstanceObject()
+  .setInstanceIdentity({ id: 'room-101', kind: 'room', name: '会议室 101' })
+  .setInstanceVisible(true)
+  .setInstanceColor('#4f8cff')
+  .setInstanceOpacity(0.65);
+
+instance.setInstanceHighlight('#ffff00', 0.9);
+instance.clearInstanceHighlight();
+instance.resetInstanceColor();
+```
+
+| 方法 | 返回值 | 说明 |
+| :--- | :----- | :--- |
+| `setInstanceIdentity(identity: InstanceIdentity)` | `this` | 更新身份字段；省略字段保持不变，`null` 将对应字段清为空字符串。 |
+| `setInstanceVisible(visible: boolean)` | `this` | 设置实例显隐并标记渲染数据需要同步。 |
+| `setInstanceColor(color: ColorRepresentation)` | `this` | 设置基础覆盖色，颜色模式变为 `INSTANCE_COLOR_MODE_OVERRIDE`。 |
+| `resetInstanceColor()` | `this` | 清除基础颜色，颜色模式恢复为 `INSTANCE_COLOR_MODE_NONE`。 |
+| `setInstanceOpacity(opacity: number)` | `this` | 设置基础透明度；传入值会被限制在 `0` 到 `1` 之间。 |
+| `getInstanceColor(target = new Color())` | `Color` | 将当前生效样式的颜色写入 `target` 并返回；未设置颜色时返回白色。 |
+| `hasInstanceColor()` | `boolean` | 当前生效样式是否包含颜色。 |
+| `getInstanceOpacity()` | `number` | 返回当前生效样式的透明度。 |
+| `setInstanceHighlight(color: ColorRepresentation, opacity: number, overwrite = false)` | `this` | 设置临时高亮；默认使用 `INSTANCE_COLOR_MODE_TINT`，`overwrite` 为 `true` 时使用覆盖模式，透明度会被限制在 `0` 到 `1` 之间。 |
+| `clearInstanceHighlight()` | `this` | 清除临时高亮并恢复基础样式。 |
+| `getInstanceColorMode()` | `number` | 返回当前生效样式的颜色模式。 |
+
+临时高亮优先于基础颜色和透明度；`clearInstanceHighlight()` 会恢复基础样式。默认场景矩阵自动更新开启时，实例 transform 的世界矩阵发生变化会自动触发 dirty callback，所属 `ModelInstancedLayer` 会在下一次渲染前同步 instance buffer。业务代码只需修改 `position`、`rotation`、`quaternion` 或 `scale`，不需要直接写内部 instance matrix，也不需要手动调用 `InstanceObject.updateMatrixWorld()`。
+
+如果为大型静态场景显式设置了 `viewer.scene.matrixWorldAutoUpdate = false`，renderer 不会再遍历该根节点，修改后必须用 Three.js 原生方法提交受影响范围并请求新帧：
+
+```typescript
+instance.position.set(10, 0, 5);
+instance.updateWorldMatrix(true, false);
+viewer.invalidate();
+
+// 修改父 Group 时更新整个受影响子树。
+group.updateWorldMatrix(true, true);
+viewer.invalidate();
+```
+
+`InstanceObject` 覆盖了原生 `updateWorldMatrix(updateParents, updateChildren)` 和 `updateMatrixWorld(force)`，两条路径都会检测世界矩阵及祖先显隐变化并触发 dirty callback。对 Group 使用 `updateChildren: true` 时，后代 `InstanceObject` 也会执行该检测；editable batch 中与烘焙矩阵不同的 `SceneInstanceObject` 会按合批规则 materialize。
+
+### 包围盒和相机定位
+
+`boundingBox` 和 `boundingSphere` 是本地坐标缓存；`computeBoundingBox()` 与 `computeBoundingSphere()` 会按需更新它们。`getInstanceBoundingBox(target, true)` 返回世界坐标包围盒。
+
+| 方法 | 返回值 | 说明 |
+| :--- | :----- | :--- |
+| `setInstanceBounds(bounds: Box3)` | `this` | 克隆并设置手动本地包围盒；空包围盒会被忽略。 |
+| `computeBoundingBox()` | `void` | 计算并缓存本地坐标包围盒。 |
+| `computeBoundingSphere()` | `void` | 基于本地包围盒计算并缓存本地坐标包围球。 |
+| `getInstanceBoundingBox(target = new Box3(), world = false)` | `Box3` | 将包围盒写入 `target`；`world` 为 `true` 时返回世界坐标结果。 |
+
+实例可以直接交给相机控制器定位：
+
+```typescript
+await viewer.controls.flyToObject(instance);
+```
+
+当实例没有可供计算的渲染几何体，或业务端已经拥有精确范围时，可以手动提供本地包围盒并按需获取世界范围：
+
+```typescript
+import { Box3, Vector3 } from 'three/webgpu';
+
+instance
+  .setInstanceBounds(new Box3(
+    new Vector3(-2, 0, -3),
+    new Vector3(2, 4, 3),
+  ))
+  .position.set(100, 0, 50);
+
+const worldBounds = instance.getInstanceBoundingBox(new Box3(), true);
+```
+
+### Fallback 渲染对象
+
+`setInstanceRenderObject()` 用于挂载无法进入合并几何或 `InstancedMesh` 管线的 fallback Three.js 对象。`InstanceObject` 会将当前显隐、颜色、透明度和高亮语义统一应用到该对象。
+
+| 方法 | 返回值 | 说明 |
+| :--- | :----- | :--- |
+| `setInstanceRenderObject(object: Object3D \| null)` | `this` | 替换 fallback 渲染对象；传入 `null` 时解除当前对象。 |
+| `getInstanceRenderObject()` | `Object3D \| null` | 返回当前 fallback 渲染对象。 |
+| `setInstanceMaterializer(materializer)` | `this` | 设置 batching 实现使用的低层 materialize delegate；传入 `null` 时解除。普通业务通常不直接调用。 |
+| `clearInstanceMaterializer(materializer?)` | `this` | 不传参数时直接解除；传入 delegate 时只在当前 delegate 与其相同时解除，用于安全释放 materializer 所有权。 |
+| `materialize()` | `Object3D \| null` | 调用当前 materializer；未连接 materializer 时返回已有 fallback render object 或 `null`。 |
+
+```typescript
+import { Model } from 'u-space';
+
+const fallbackModel = new Model();
+await fallbackModel.loadAsync({ url: '/models/special-room.glb' });
+
+instance
+  .setInstanceRenderObject(fallbackModel)
+  .setInstanceColor('#ff8a3d')
+  .setInstanceOpacity(0.8);
+```
+
+`EditableGeometryBatchLayer` 会自动连接 `setInstanceMaterializer()`，并在 dispose 时通过所有权匹配安全解除。当实例 transform 或半透明状态无法继续由烘焙 Geometry 表达时，layer 会 clone 完整模板、克隆独立材质并挂到当前实例，同时立即提交新对象的世界矩阵并让其他 active layer 隐藏同一实例的旧烘焙副本；业务也可以显式调用 `instance.materialize()`。完整构建、unsupported fallback 和事件语义见 [Batches API](./api-batches#editablegeometrybatchlayer)。
+
+### Dirty callback
+
+| 方法 | 返回值 | 说明 |
+| :--- | :----- | :--- |
+| `onInstanceRenderDirty(callback: () => void)` | `() => boolean` | 注册 dirty callback，并返回用于取消订阅的函数。 |
+| `markInstanceRenderDirty()` | `this` | 立即通知所有已注册的 dirty callback。 |
+
+保存并调用取消订阅函数，避免监听方销毁后遗留回调：
+
+```typescript
+const dirtyInstances = new Set<InstanceObject>();
+const unsubscribe = instance.onInstanceRenderDirty(() => {
+  dirtyInstances.add(instance);
+});
+
+// 不再需要监听时
+unsubscribe();
+dirtyInstances.delete(instance);
+```
+
+### 类型守卫
+
+#### `isInstanceObject(object)`
+
+`isInstanceObject(object: Object3D): object is InstanceObject` 检查对象的 `isInstanceObject` 标识，并在 TypeScript 中将其收窄为 `InstanceObject`。
+
+```typescript
+if (isInstanceObject(object)) {
+  object.setInstanceHighlight('#ffff00', 1);
+}
+```
+
 ## 模型
 
 `Model` 类继承自 `BaseGroup`（进而继承自 `THREE.Group`），简化了异步加载 `glb`、`gltf` 等外部 3D 模型的流程，内置多层缓存支持。