u-space 0.0.25 → 0.0.27

package/docs/api-plugin-u-manager.md

@@ -57,7 +57,7 @@ floor.addEventListener('click', ({ event }) => {
 | `setFacilityOpacity(id \| object, opacity)` | 设置单个设备材质透明度，`opacity` 会被限制在 `0..1`。 |
 | `showAllFacilities()` / `hideAllFacilities()` | 显示或隐藏整次语义解析结果中的全部设备。 |
 | `showAllFloors()` | 显示所有建筑的所有楼层。 |
-| `planishFloors(kind?)` / `unplanishFloors(kind?)` | 压扁或恢复所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
+| `planishFloors(kind?)` / `unplanishFloors(kind?)` | 压扁或恢复所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面附近，同时添加稳定的轻微 Y 偏移以减少共面闪烁；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
 
 ### `BuildingGroup`
 
@@ -73,10 +73,13 @@ floor.addEventListener('click', ({ event }) => {
 | `addFloor(floor)` | 添加楼层，并同步加入 group。 |
 | `removeFloor(floor)` | 移除楼层，并同步从 group 移除。 |
 | `getFloorAt(index)` | 按楼层下标获取 `FloorMesh`。 |
+| `getFloorById(id)` | 按楼层语义 ID 获取 `FloorMesh`，内部使用 `Map` 索引。 |
 | `addElevator(elevator)` / `removeElevator(elevator)` | 添加或移除电梯井，并同步更新 group。 |
 | `getElevatorAt(index)` | 按下标获取电梯井 `ExtrudeMesh`。 |
+| `getElevatorById(id)` | 按电梯井语义 ID 获取电梯井，内部使用 `Map` 索引。 |
 | `addVent(vent)` / `removeVent(vent)` | 添加或移除通风井，并同步更新 group。 |
 | `getVentAt(index)` | 按下标获取通风井 `ExtrudeMesh`。 |
+| `getVentById(id)` | 按通风井语义 ID 获取通风井，内部使用 `Map` 索引。 |
 | `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层；也兼容传入楼层数组。 |
 | `isolateFloors(floors \| indexes)` | 只显示指定多个楼层，隐藏其他楼层。 |
 | `showAllFloors()` | 显示全部楼层。 |
@@ -88,7 +91,7 @@ floor.addEventListener('click', ({ event }) => {
 | `setFacilityOpacity(id \| object, opacity)` | 设置当前建筑内单个设备材质透明度。 |
 | `showAllFacilities()` | 显示整栋建筑内全部楼层设备。 |
 | `hideAllFacilities()` | 隐藏整栋建筑内全部楼层设备。 |
-| `planishFloors(kind?)` | 压扁所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面；传入 `kind` 时只压扁该语义类型，`kind` 可包含 `Facilities`。 |
+| `planishFloors(kind?)` | 压扁所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面附近，同时添加稳定的轻微 Y 偏移以减少共面闪烁；传入 `kind` 时只压扁该语义类型，`kind` 可包含 `Facilities`。 |
 | `unplanishFloors(kind?)` | 恢复所有楼层；默认恢复所有合并语义实例和 Facilities；传入 `kind` 时只恢复该语义类型，`kind` 可包含 `Facilities`。 |
 
 ### 电梯井和通风井
@@ -97,7 +100,9 @@ floor.addEventListener('click', ({ event }) => {
 
 ```typescript
 const elevator = building.getElevatorAt(0);
+const elevatorById = building.getElevatorById('ELEVATOR_001');
 const vent = building.getVentAt(0);
+const ventById = building.getVentById('VENT_001');
 
 if (elevator) {
   await viewer.controls.flyToObject(elevator);
@@ -116,22 +121,33 @@ if (vent) {
 
 `tree_models.matrix` 是相对父节点的本地矩阵；`SemanticLoader` 会沿树父级累乘得到设备世界矩阵，再转换为对应 `FloorMesh` 的局部矩阵。因此楼层移动、隔离或显示隐藏时设备会跟随楼层一起工作。即使某个 story 只有 `Facilities`、没有墙柱空间等合并几何，也会创建一个空的 `FloorMesh` 作为设备容器。
 
-Facilities 会在单次 `SemanticParser` 解析范围内按模型 URL 自动分组。静态模型会被转换为 scene-level `InstancedMesh` batch，挂到 `SemanticSceneGroup.facilityLayer`；每个设备仍会在所属 `FloorMesh` 下保留一个轻量引用，用于 `getFacilityById()`、显隐、颜色、透明度和 `viewer.objectManager` 检索。带动画、骨骼、morph target 或多材质 Mesh 的模型会自动回退为普通 `Model`，继续作为实际 `Object3D` 挂到所属 `FloorMesh`。
+Facilities 会在单次 `SemanticParser` 解析范围内按模型 URL 自动分组。静态模型会被转换为 scene-level `InstancedMesh` batch 并挂到 `SemanticSceneGroup.facilityLayer`；每个设备仍会在所属 `FloorMesh` 下保留一个轻量引用，用于 `getFacilityById()`、显隐、颜色、透明度和 `viewer.objectManager` 检索。设备 batch 使用普通 `Group` 包裹，以保证每帧渲染前都能执行相机实例裁剪和 hide/show 后的实例同步；带动画、骨骼、morph target 或缺少合法 `geometry.groups` 的多材质 Mesh 会自动回退为普通 `Model`，继续作为实际 `Object3D` 挂到所属 `FloorMesh`。
 
 `facilityLayer` 使用 `FacilityInstancedLayer`，并继承自 `BaseGroup`。当 `facilityLayer.visible = false` 时，layer 会阻止内部 `InstancedMesh` 继续参与射线检测，避免隐藏的批处理设备仍被点击命中；单个设备的显隐仍应通过楼层下的设备引用或 `showFacility()` / `hideFacility()` 控制。
 
-Instanced 设备为了支持单个设备的透明度控制，会把 batch 材质保持为 `transparent: true`，并通过 per-instance opacity attribute 控制每个设备的可见透明度；`setFacilityOpacity(id, 1)` 会恢复完全不透明显示，但不会把 batch 材质的 `transparent` 属性改回 `false`。`resetFacilityColor()` 只清除颜色 override，不影响透明度 override。普通 fallback `Model` 的颜色和透明度控制依赖 `MaterialEffects`，当前支持单材质 Mesh；多材质 Mesh fallback 会保留原始材质数组，支持挂载、检索和显隐，但不会改写颜色或透明度 override。
+Instanced 设备通过 per-instance opacity attribute 控制单个设备透明度。batch 材质默认沿用源材质的透明状态；只有源材质本身透明，或当前参与渲染的设备存在 `opacity < 1` 时，材质才会切到 `transparent: true`，`setFacilityOpacity(id, 1)` 可在没有其他半透明实例时回到不透明渲染队列。`resetFacilityColor()` 只清除颜色 override，不影响透明度 override。`FacilityInstancedLayer` 会在设备显隐、颜色、透明度、floor planish/unplanish 改变设备 transform，或相机矩阵、投影矩阵、viewport 高度变化时，在下一次渲染前同步实例矩阵、颜色、透明度和当前 active instance count。普通 fallback `Model` 的颜色和透明度控制依赖 `MaterialEffects`，单材质和多材质 Mesh 都会应用 override。
 
 加载成功后，设备引用会写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId` 和 `floorIndex`，并按 `Facility.ID` 注册到 `viewer.objectManager`。自动 instancing 的引用还会带有 `userData.instanced: true` 和 `userData.modelUrl`。
 
 ```typescript
+import { Box3 } from 'three';
+
 const floor = building.getFloorAt(0);
+const box = new Box3();
 
 const facility = floor.getFacilityById('FACILITY_001') ?? viewer.objectManager.getById('FACILITY_001');
 const facilityEntity = floor.getSemanticById('FACILITY_001');
 
 if (facility && facilityEntity?.type === 'object') {
-  await viewer.controls.flyToObject(facility);
+  const facilityBox =
+    typeof facility.getFacilityBoundingBox === 'function'
+      ? facility.getFacilityBoundingBox(box, true)
+      : box.setFromObject(facility);
+
+  await viewer.controls.flyToBox(facilityBox, {
+    viewpoint: 'rightFrontTop',
+    padding: 0.2,
+  });
 }
 
 const facilities = floor.getSemanticsByKind('Facilities');
@@ -144,9 +160,107 @@ semanticScene
   .showFacility('FACILITY_001');
 ```
 
+对 Facilities 推荐使用 `controls.flyToBox()` 飞向设备包围盒。instanced 设备引用是楼层下的轻量 `FacilityInstanceObject`，可通过 `getFacilityBoundingBox(box, true)` 取得完整世界包围盒；普通 fallback `Model` 也可以直接使用 `viewer.controls.flyToObject(facility)`。
+
+### `FacilityInstanceObject`
+
+`FacilityInstanceObject` 继承自 Three.js `Group`，表示一个被 scene-level `FacilityInstancedLayer` 批量渲染的设备引用。它会挂在所属 `FloorMesh` 下，用于 ID 检索、事件派发、显隐、颜色、透明度和包围盒查询；真正的设备几何不会作为它的子网格重复挂载，而是由 `SemanticSceneGroup.facilityLayer` 里的 `InstancedMesh` 统一渲染。
+
+通常不需要手动创建 `FacilityInstanceObject`。`SemanticParser` 在解析 `Facilities` 时会自动创建它，并写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId`、`floorIndex`、`instanced: true` 和 `modelUrl`。如果设备模型无法 instancing，则会回退为普通 `Model`，不会具备这些实例引用专用方法。
+
+加载完成后，instanced 设备也可以按 `Facility.ID` 从全局 `objectManager` 取回。推荐使用 `getFacilityBoundingBox(box, true)` 取得完整世界包围盒，再调用 `viewer.controls.flyToBox()`；如果取到的是普通 fallback `Model`，则继续用 `viewer.controls.flyToObject(facility)`。
+
+```typescript
+import { Box3 } from 'three';
+import { FacilityInstanceObject } from 'u-space/plugins/u-manager';
+
+const facility = viewer.objectManager.getById<FacilityInstanceObject>('FACILITY_001');
+
+if (facility?.isFacilityInstanceObject) {
+  const box = facility.getFacilityBoundingBox(new Box3(), true);
+
+  await viewer.controls.flyToBox(box, {
+    viewpoint: 'rightFrontTop',
+    padding: 0.2,
+    enableTransition: true,
+  });
+} else if (facility) {
+  await viewer.controls.flyToObject(facility, {
+    viewpoint: 'rightFrontTop',
+    padding: 0.2,
+  });
+}
+```
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `isFacilityInstanceObject` | 类型标记，值为 `true`。 |
+| `type` | Three.js 对象类型名，值为 `'FacilityInstanceObject'`。 |
+| `setLocalBounds(bounds)` | 设置设备模板在引用本地空间内的包围盒，并返回自身；主要由 `FacilityInstancedLayer.addFacilityBatch()` 在建 batch 时写入。 |
+| `getFacilityBoundingBox(target?, world?)` | 获取设备完整包围盒。`world = true` 时会应用 `matrixWorld`，适合传给 `viewer.controls.flyToBox()`；没有 bounds 时返回 empty `Box3`。 |
+| `setFacilityVisible(visible)` | 设置单个设备引用的 `visible`，并返回自身；渲染和射线检测都会跳过不可见引用。 |
+| `setFacilityColor(color)` | 设置单个设备的颜色 override，并返回自身。`color` 支持 Three.js `ColorRepresentation`。 |
+| `resetFacilityColor()` | 清除颜色 override，恢复使用源材质颜色，并返回自身；不会清除透明度 override。 |
+| `setFacilityOpacity(opacity)` | 设置单个设备透明度，并返回自身；值会被限制在 `0..1`。 |
+| `getFacilityColor(target?)` | 读取当前颜色 override；没有 override 时返回白色 `(1, 1, 1)`。 |
+| `hasFacilityColor()` | 判断当前设备是否存在颜色 override。 |
+| `getFacilityOpacity()` | 读取当前透明度 override。 |
+
+```typescript
+import { Box3 } from 'three';
+import { FacilityInstanceObject } from 'u-space/plugins/u-manager';
+
+const box = new Box3();
+const facility = floor.getFacilityById('FACILITY_001');
+
+if (facility instanceof FacilityInstanceObject) {
+  facility
+    .setFacilityColor('#29ccff')
+    .setFacilityOpacity(0.6)
+    .setFacilityVisible(true);
+
+  await viewer.controls.flyToBox(facility.getFacilityBoundingBox(box, true), {
+    viewpoint: 'rightFrontTop',
+    padding: 0.2,
+  });
+}
+```
+
+### `FacilityInstancedLayer`
+
+`FacilityInstancedLayer` 继承自 `BaseGroup`，是 scene-level Facilities 的批量渲染层。`SemanticSceneGroup.facilityLayer` 默认就是该类型；它会按模型 URL 把同一模板的静态设备合并为一个或多个 `InstancedMesh`，并用普通 `Group` 包裹每个模型 URL batch，保证设备显隐、颜色、透明度和相机实例裁剪能在每帧渲染前同步，同时保留每个楼层下的 `FacilityInstanceObject` 引用用于业务 API 和事件冒泡。
+
+使用 `SemanticLoader` 时通常不需要直接调用 `addFacilityBatch()`；只有自定义语义解析或自建设备 batch 时才需要手动创建 layer，然后通过 `semanticScene.setFacilityLayer(layer)` 挂回语义场景。
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `isFacilityInstancedLayer` | 类型标记，值为 `true`。 |
+| `type` | Three.js 对象类型名，值为 `'FacilityInstancedLayer'`。 |
+| `name` | 构造函数默认设为 `'Facilities'`。 |
+| `getInstanceCulling()` | 返回当前实例裁剪配置：`enabled`、`frustum`、`minScreenRadius`。 |
+| `setInstanceCulling(options)` | 设置实例裁剪配置，并返回自身。默认 `enabled: false`、`frustum: true`、`minScreenRadius: 0`；默认不按相机裁剪设备，避免相机距离影响设备显隐。需要性能压缩时可设置 `enabled: true` 开启视锥裁剪，或再把 `minScreenRadius` 设为大于 0 的值开启屏幕尺寸裁剪。 |
+| `addFacilityBatch(url, template, facilities)` | 尝试把同一模型 URL 的设备引用合并为 instanced batch。成功返回 `true`，失败返回 `false`，失败时调用方应回退为普通模型渲染。 |
+
+`addFacilityBatch(url, template, facilities)` 会从 `template` 收集可 instancing 的可见 `Mesh`，克隆源材质，并为每个 batch 建立 instance matrix、颜色和透明度 attribute。没有动画、没有骨骼、没有 morph target，且每个多材质 `Mesh` 都有合法 `geometry.groups` 的模板会进入 instancing；不满足条件、模板没有可用 Mesh 或 `facilities` 为空时会返回 `false`。
+
+渲染前，layer 会同步每个 `FacilityInstanceObject` 的世界矩阵、颜色和透明度，并只在数据变化时上传对应 buffer。默认情况下，相机移动不会改变设备 active instance 集合；显式调用 `setInstanceCulling({ enabled: true })` 后，layer 才会按当前渲染相机逐实例压缩 `InstancedMesh.count`，视锥外设备不会进入本帧实例 buffer；只有同时设置 `minScreenRadius > 0` 时，屏幕半径小于该阈值的设备才会被跳过。相机矩阵、投影矩阵或 viewport 高度未变化时不会重复压缩；设备显隐、透明度为 0、颜色/透明度变化或 `planish('Facilities')` / `unplanish('Facilities')` 改变 transform 时会标记 batch dirty。全部设备不可渲染时，内部 `InstancedMesh.visible` 会被关闭；只有被当前相机裁掉时，mesh 会保留可见并把 `count` 设为 0，以便相机移动后自动恢复。射线检测命中 batch 内实例时，`hit.object` 会被改写为对应的 `FacilityInstanceObject`，并附加 `facility`、`facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName` 和 `semanticIndex`，事件随后会按楼层引用对象继续冒泡。
+
+```typescript
+import { FacilityInstancedLayer, FacilityInstanceObject } from 'u-space/plugins/u-manager';
+
+const layer = new FacilityInstancedLayer();
+const refs = facilityItems.map(() => new FacilityInstanceObject());
+
+if (layer.addFacilityBatch('/models/camera.glb', templateObject, refs)) {
+  semanticScene.setFacilityLayer(layer);
+}
+```
+
+如果只想整体隐藏或禁用 scene-level batch，可以设置 `semanticScene.facilityLayer.visible = false`；如果只想控制单个设备，继续使用 `floor.showFacility(id)`、`semanticScene.setFacilityOpacity(id, opacity)` 或设备引用自身的 `setFacilityVisible()` / `setFacilityOpacity()`。
+
 ### `FloorMesh`
 
-`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。Facilities 通过楼层下的引用对象进行检索和控制；实际渲染可能来自 `SemanticSceneGroup.facilityLayer` 的 `InstancedMesh` batch，也可能是 fallback 的普通 `Model`。
+`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。楼层语义网格会按实例透明度拆分为不透明和透明两个材质通道；墙、柱、门等默认不透明实例会进入 opaque pipeline，`Spaces`、`Windows` 或通过 `setOpacityAt()` 改成半透明的实例会进入 transparent pipeline。Facilities 通过楼层下的引用对象进行检索和控制；实际渲染可能来自 `SemanticSceneGroup.facilityLayer` 的 `InstancedMesh` batch，也可能是 fallback 的普通 `Model`。
 
 这种结构的目标是让每个楼层通常只占一个主渲染 draw call，同时仍保留实例级控制能力。`xxxAt` 方法全部作用于单个语义实例；没有 `At` 后缀的方法作用于整个楼层 mesh。
 
@@ -187,7 +301,7 @@ semanticScene
 | `getBoundingBoxAt(index, target?, world?)` | 获取实例包围盒；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
 | `getBoundingSphereAt(index, target?, world?)` | 获取实例包围球；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
 | `computeBoundingBox()` / `computeBoundingSphere()` | 计算整个楼层的包围体。 |
-| `planish(kind?)` / `unplanish(kind?)` | 压扁或恢复楼层内所有合并语义实例和 Facilities；压平时按各自包围盒贴到楼层平面；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
+| `planish(kind?)` / `unplanish(kind?)` | 压扁或恢复楼层内所有合并语义实例和 Facilities；压平时按各自包围盒贴到楼层平面附近，并加入稳定的轻微 Y 偏移；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
 
 ### 飞向语义实例
 
@@ -204,7 +318,15 @@ floor.addEventListener('click', async ({ event }) => {
 
   if (intersect.semanticKind === 'Facilities') {
     const facility = intersect.facility ?? event.target;
-    await viewer.controls.flyToObject(facility);
+    const facilityBox =
+      typeof facility.getFacilityBoundingBox === 'function'
+        ? facility.getFacilityBoundingBox(box, true)
+        : box.setFromObject(facility);
+
+    await viewer.controls.flyToBox(facilityBox, {
+      viewpoint: 'rightFrontTop',
+      padding: 0.2,
+    });
     return;
   }
 
@@ -232,13 +354,17 @@ if (index !== undefined) {
 
 ### 楼层压扁
 
-`planish()` / `unplanish()` 默认作用于当前楼层的全部合并语义实例，包含墙、柱、空间、门窗、楼梯等语义几何，也包含楼层下的 Facilities 引用；传入 `kind` 时只处理该类型，例如 `floor.planish('Walls')` 或 `floor.planish('Facilities')`。所有被压平的实例都会按自身包围盒把压平后的薄片贴到楼层平面 `FloorMesh.pivot.y`，而不是围绕实例自身基点压缩；`unplanish()` 会恢复合并几何实例的原始矩阵，`unplanish('Facilities')` 会恢复设备原始 `position.y` 和 `scale.y`。instanced Facilities 会通过楼层下的 `FacilityInstanceObject` transform 同步到 `SemanticSceneGroup.facilityLayer`。
+`planish()` / `unplanish()` 默认作用于当前楼层的全部合并语义实例，包含墙、柱、空间、门窗、楼梯等语义几何，也包含楼层下的 Facilities 引用；传入 `kind` 时只处理该类型，例如 `floor.planish('Walls')` 或 `floor.planish('Facilities')`。所有被压平的实例都会按自身包围盒把压平后的薄片贴到楼层平面 `FloorMesh.pivot.y` 附近，而不是围绕实例自身基点压缩；压平时还会按语义类型和实例 ID 加入稳定的轻微 Y 偏移，减少门、墙或其他重叠实例之间的共面闪烁。`unplanish()` 会恢复合并几何实例的原始矩阵，`unplanish('Facilities')` 会恢复设备原始 `position.y` 和 `scale.y`。instanced Facilities 会通过楼层下的 `FacilityInstanceObject` transform 同步到 `SemanticSceneGroup.facilityLayer`。
 
 如果只想调整单个合并几何实例，可以使用 `setScaleAt()` 或 `setScaleYAt()`，它们会保留该语义对象自己的基点矩阵，因此压扁墙、柱、房间时不会被压到世界原点。
 
 ## `SceneLoader`
 
 从服务端场景包加载完整场景树（模型、组、形状、拉伸区域），并自动将所有已加载对象按 `id` 和 `sid` 注册到 `viewer.objectManager`。
+默认会尝试读取同一路径下的 `db/semantic_model.json`，如果场景树节点的 `id` 已存在于语义文件中，则跳过该节点，方便和 `SemanticLoader` 同时加载而不重复创建建筑或设备。
+对语义去重后仍保留的 3D 节点，`SceneLoader` 默认会按模型 `path` 自动合并重复静态模型：同一 `path` 的多个实例只加载一次模板，并由 `SceneInstancedLayer` 通过 `InstancedMesh` + `BundleGroup` 批量渲染。原场景树中仍会保留每个 `id` / `sid` 对应的 `SceneInstanceObject` 逻辑对象，用于业务检索、显隐、颜色、透明度、包围盒和事件派发。
+
+模板包含动画、骨骼、morph target、材质数组或没有可实例化网格时，会自动回退为普通 `Model` 渲染；调用侧不需要额外配置。
 
 ```typescript
 import { SceneLoader } from 'u-space/plugins/u-manager';
@@ -252,12 +378,49 @@ viewer.scene.add(group);
 
 **方法：**
 
-| 方法             | 说明                                                          |
-| :--------------- | :------------------------------------------------------------ |
-| `setKey(key)`    | 设置授权场景的 RSA 解密密钥。                                 |
-| `loadAsync()`    | 加载并解析场景，返回包含完整层级的 `Group`。                  |
-| `clearCache()`   | 从 `objectManager` 中移除此加载器注册的所有 ID。              |
-| `dispose()`      | 清除缓存并释放水印叠加层。                                    |
+| 方法                | 说明                                                                 |
+| :------------------ | :------------------------------------------------------------------- |
+| `setKey(key)`       | 设置授权场景的 RSA 解密密钥。                                        |
+| `loadAsync()`       | 加载并解析场景，返回去除语义重复节点后的 `Group`。                   |
+| `clearCache()`      | 从 `objectManager` 中移除此加载器注册的所有 ID。                     |
+| `dispose()`         | 清除缓存并释放水印叠加层。                                           |
+
+### `SceneInstanceObject`
+
+`SceneInstanceObject` 继承自 Three.js `Group`，表示一个由 `SceneInstancedLayer` 批量渲染的场景模型引用。它会保留在原场景树层级中，并注册到 `viewer.objectManager`，因此 `getById()`、`show()` / `hide()`、`isolate()`、`showAll()`、`setOpacity()` 和 `getBoundingBox()` 可以继续按单个模型 ID 使用。
+
+可用方法包括 `setSceneInstanceVisible(visible)`、`setSceneInstanceColor(color)`、`resetSceneInstanceColor()`、`setSceneInstanceOpacity(opacity)`、`getSceneInstanceOpacity()`、`getSceneInstanceBoundingBox(target?, world?)` 和 `markSceneInstanceRenderDirty()`。`MaterialEffects.highlightColor()` / `removeHighlightColor()` 也会识别该逻辑对象并写入 per-instance color / opacity。
+
+加载完成后可以按场景树节点 `id` 从 `objectManager` 取回 `SceneInstanceObject` 并直接传给 `viewer.controls.flyToObject()`。`SceneInstanceObject` 内部带有不可见的本地 bounds，因此不需要加载真实 Mesh 副本也能计算飞行包围盒。
+
+```typescript
+import { SceneInstanceObject } from 'u-space/plugins/u-manager';
+
+const object = viewer.objectManager.getById<SceneInstanceObject>('SCENE_NODE_ID');
+
+if (object?.isSceneInstanceObject) {
+  await viewer.controls.flyToObject(object, {
+    viewpoint: 'current',
+    padding: 0.2,
+    enableTransition: true,
+  });
+}
+```
+
+如果需要自己控制包围盒，也可以取世界包围盒后调用 `flyToBox()`：
+
+```typescript
+import { Box3 } from 'three/webgpu';
+
+const box = object.getSceneInstanceBoundingBox(new Box3(), true);
+await viewer.controls.flyToBox(box, { viewpoint: 'frontTop', padding: 0.2 });
+```
+
+射线检测命中批处理实例时，`intersect.object` 会被改写为对应的 `SceneInstanceObject`，并附加 `sceneInstance`、`sceneInstanceId` 和 `sceneInstanceIndex`，事件会按逻辑对象所在的原场景树继续冒泡。
+
+### `SceneInstancedLayer`
+
+`SceneInstancedLayer` 是 `SceneLoader` 内部使用的批量渲染层，默认 `name = 'SceneInstances'`。每个重复模型 URL 会生成一个 `BundleGroup` batch，batch 内按模板的可实例化 Mesh 创建 `InstancedMesh`。渲染前只在实例矩阵、显隐、颜色或透明度变化时同步 instance buffer；普通相机移动不会重新上传所有实例数据。
 
 ## `TopologiesLoader` / `TopologyParser`
 

package/docs/api-tools.md

@@ -221,7 +221,7 @@ annotationManager.add('label-01', {
 | `labelOffset`    | `{x, y, z}`              | `{0, 2, 0}` | 标签相对锚点的偏移。   |
 | `showLeaderLine` | `boolean`                | `true`      | 是否显示引线。         |
 | `lineColor`      | `ColorRepresentation`    | `0xffffff`  | 引线颜色。             |
-| `labelStyle`     | `Partial<CSSStyleDeclaration>` | —      | 自定义 CSS 样式。      |
+| `labelStyle`     | `AnnotationLabelStyle` | —      | 自定义 CSS 样式。      |
 
 ### `addText(text, position, options?)`
 

package/docs/changelog.md

@@ -2,6 +2,40 @@
 
 ## 未发布
 
+### 变更
+
+- **u-manager semantics** — `FacilityInstancedLayer` 的相机逐实例裁剪改为显式开启：默认不再按当前相机视锥或 `minScreenRadius` 压缩 active instances，避免相机距离影响设备显隐；需要性能压缩时可通过 `setInstanceCulling({ enabled: true })` 开启。
+- **u-manager semantics** — `FacilityInstancedLayer` 使用动态 `Group` 包裹 Facilities `InstancedMesh` batch，避免 Three.js WebGPU render bundle 缓存跳过子 mesh 的渲染前同步；`hideAllFacilities()` 后再 `showAllFacilities()` 不会复用过期 active instance 状态。
+- **u-manager semantics** — `FacilityInstancedLayer` 支持合法 `material[]` + `geometry.groups` 的设备模板进入 instancing；只有 groups 缺失或材质索引非法的多材质 Mesh 才回退为普通 `Model`。
+- **u-manager semantics** — Facilities instancing 会在相机矩阵、投影矩阵或 viewport 高度变化时重新压缩当前帧实例；设备显隐、颜色、透明度和 `planish('Facilities')` / `unplanish('Facilities')` 改变 transform 时刷新 instance data。
+- **u-manager semantics** — 全部设备隐藏或透明度为 0 时，`FacilityInstancedLayer` 会关闭空的内部 `InstancedMesh`；通过 `showAllFacilities()` 或单设备 API 恢复时会重新加入渲染同步。
+- **fire 插件** — 新增 `FireEffect`，封装 Three.js 官方 `webgpu_volume_fire` 体积火焰示例，支持 WebGPU 3D 流体模拟、烟雾散射、动态光照、体积阴影、output effect 叠加和 `cameraChange` 相机切换同步。
+- **u-manager loader** — `SceneLoader` 默认读取同路径 `db/semantic_model.json` 并按语义 `ID` 跳过重复场景树节点，支持与 `SemanticLoader` 同时加载。
+- **u-manager loader** — `SceneLoader` 默认按模型 `path` 合并重复静态 3D 节点，通过 `SceneInstancedLayer` 批量渲染，同时保留 `SceneInstanceObject` 逻辑对象用于单模型 ID 检索、显隐、颜色、透明度、包围盒和事件派发。
+- **docs/mcp** — 补充 `SceneInstanceObject` 通过 `objectManager.getById()` + `controls.flyToObject()` 飞向单个 path-instanced 场景模型、`FacilityInstanceObject` 通过 `getFacilityBoundingBox()` + `controls.flyToBox()` 飞向单个设备的示例与 MCP 检索说明。
+- **ObjectManager / MaterialEffects** — `setOpacity()`、`show()` / `hide()`、`isolate()`、`showAll()` 以及 `highlightColor()` / `removeHighlightColor()` 支持 `SceneInstanceObject` 的 per-instance 控制。
+- **u-manager loader** — `SceneLoader` 创建的根组、`GROUP` 和 `STUB` 节点改为 `BaseGroup`，隐藏后可通过对象自身 `raycast()` 返回值阻止子级继续参与递归射线检测。
+- **Viewer** — 默认使用 Three.js `reversedDepthBuffer` 替代 `logarithmicDepthBuffer`，减少 WebGPU 顶视角多层透明场景的 fragment 压力，同时保留远距离深度精度。
+
+## 0.0.26
+
+### 修复
+
+- **u-manager semantics** — `FloorMesh.planish()` 会在压平后的语义实例和 Facilities 上加入稳定的轻微 Y 偏移，减少门、墙等重叠薄片之间的共面闪烁。
+- **u-manager semantics** — `FloorMesh` 会按实例透明度把合并语义网格拆分到不透明和透明材质通道，避免墙、柱、门等完全不透明实例也走透明渲染队列，降低近距离压平场景的 overdraw 成本。
+- **u-manager semantics** — `BuildingGroup` 新增 `getFloorById()`、`getElevatorById()` 和 `getVentById()`，内部通过 `Map` 维护楼层、电梯井和通风井语义 ID 索引。
+- **u-manager semantics** — `FacilityInstancedLayer` 只在实例矩阵、颜色或透明度变化时上传对应 instance buffer，静态 Facilities 不再每帧重复提交全部实例数据；渲染前会按每个 Facility 实例的世界包围盒和当前相机视锥压缩本帧 active instance count，不再通过相机距离阈值裁剪设备。
+- **u-manager semantics** — 修复 Facilities 视锥裁剪在视角切换后可能沿用上一帧 active subset 的 `visible` / `boundingSphere` 状态，导致某些视角下设备整批隐藏的问题；instanced batch 会保留完整包围球，同时用 `count` 控制本帧 active 实例。
+- **u-manager semantics** — Instanced Facilities 的 batch 材质默认保持不透明，只有源材质本身透明或当前渲染实例存在半透明 opacity 时才切到透明队列，减少完全不透明设备在近距离视角下的 overdraw。
+- **MaterialEffects** — 高亮、呼吸色、线框和淡入淡出效果支持材质数组，确保多材质 Mesh 和 `FloorMesh` 双材质通道都能正确应用并恢复材质状态。
+- **docs/mcp** — 补充 Facilities auto instancing 的动态材质透明度、包围盒视锥裁剪、`controls.flyToBox()` 飞向设备，以及多材质 fallback 对颜色/透明度 override 的支持说明。
+
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.26`，Vercel 部署会继续按 `package.json` 注入当前版本。
+
+## 0.0.25
+
 ### 新增
 
 - **u-manager semantics** — 新增 `SemanticSceneGroup`，作为单次 `SemanticParser` 解析结果的顶层容器；`SemanticLoader.loadAsync()` / `SemanticParser.parseAsync()` 直接返回完整语义场景。
@@ -18,6 +52,10 @@
 - **u-manager semantics** — `FacilityInstancedLayer` 继承 `BaseGroup`，避免 `facilityLayer.visible = false` 后内部 `InstancedMesh` 仍参与射线检测并触发隐藏设备点击事件。
 - **u-manager semantics** — 移除语义设备解析里的 `sid` 检索和注册逻辑；Facilities 只按 `Facility.ID` 以及显式传入的别名进入楼层索引和 `viewer.objectManager`。
 
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.25`，Vercel 部署会继续按 `package.json` 注入当前版本。
+
 ## 0.0.23
 
 ### 新增

package/docs/examples-guide.md

@@ -4,7 +4,7 @@
 
 ## 运行方式与版本
 
-示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.23`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.23` 作为直接托管 `examples/` 时的 fallback。
+示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1`、`0.0.0.0` 或 `192.168.x.x` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.26`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.26` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -197,3 +197,15 @@
 - 支持 4 种预设：`indoor`（室内）、`outdoor`（室外）、`studio`（摄影棚）、`warehouse`（仓库）。
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
+
+## 17. `test_fire.html`：WebGPU 体积火焰
+
+该示例演示了 `u-space/plugins/fire` 的 `FireEffect` 插件，封装 Three.js 官方体积火焰示例，在独立 volumetric pass 中模拟火焰和烟雾后叠加到主场景。
+
+### 核心要点：
+
+- 使用 `FireEffect` 创建 WebGPU 体积火焰、烟雾、扰动、动态点光源和体积阴影。
+- 通过 `position` 和 `size` 设置体积盒底部中心和烟雾扩散约束范围。
+- 默认使用 `TeapotGeometry(0.8, 28)` 作为 emitter；也可以传入业务 `Object3D` 和自定义 `emitterGeometry`。
+- 通过 `fire.update()` 实时调整 `fireIntensity`、`smokeLifespan`、`emitterRadius` 等参数。
+- 插件使用 RenderPipeline output effect 接入，不占用业务侧的 `setOutputComposer()`。

package/docs/getting-started.md

@@ -125,7 +125,7 @@ box.addEventListener('pointerleave', (e) => {
 
 ```typescript
 import { version } from 'u-space';
-console.log(version); // e.g. '0.0.23'
+console.log(version); // e.g. '0.0.26'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

package/docs/index.md

@@ -56,6 +56,7 @@ features:
 | [curve-movement](./api-plugin-curve-movement) | 沿样条曲线移动相机或对象 |
 | [tracking-controls](./api-plugin-tracking-controls) | 相机跟随移动目标 |
 | [atmosphere](./api-plugin-atmosphere) | 天空背景、天空环境、太阳/月亮光照与阴影 |
+| [fire](./api-plugin-fire) | WebGPU 体积火焰、烟雾、湍流、动态光照与阴影 |
 | [object-controls](./api-plugin-object-controls) | 交互式移动、旋转、缩放 3D 对象 |
 | [topology-drawer](./api-plugin-topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |
 

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # u-space MCP
 
-`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括 `u-manager` 的 `SemanticLoader`、`SemanticSceneGroup`、`BuildingGroup`、`FloorMesh` 语义楼层 API、楼层 `Facilities` 设备检索与 scene-level auto instancing、设备显隐/颜色/透明度控制、电梯井/通风井语义体块，以及 atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置。
+`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括 `u-manager` 的 `SceneLoader` 语义去重与 path-based model instancing、`SceneInstanceObject` 场景模型引用、`SceneInstancedLayer` 批量渲染层、`SemanticLoader`、`SemanticSceneGroup`、`BuildingGroup`、`FloorMesh` 语义楼层 API、`FacilityInstanceObject` 设备引用、`FacilityInstancedLayer` scene-level batch 渲染层、Facilities auto instancing、camera-based active instance culling、dirty-driven instance sync、楼层 `Facilities` 设备检索与控制、电梯井/通风井语义体块，atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置，以及 fire 插件的 `FireEffect` WebGPU 体积火焰、烟雾、emitter、体积盒、动态光照和 output effect 接入方式。
 
 ## 安装与启动
 
@@ -84,6 +84,32 @@ export const codingAgent = new Agent({
 | `find_examples` | 查找示例和用法相关文档 |
 | `get_changelog` | 读取更新日志 |
 
+## u-manager 检索范围
+
+MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
+
+| 关键词 / API | 可检索内容 |
+| :----------- | :--------- |
+| `SceneLoader` | 场景树加载、语义 `ID` 去重、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
+| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、显隐、颜色、透明度、包围盒、`objectManager.getById()` + `controls.flyToObject()` 飞向单模型，以及事件目标。 |
+| `SceneInstancedLayer` | `SceneLoader` 内部批量渲染层、`BundleGroup` batch、dirty-driven instance buffer 同步、raycast hit remap。 |
+| `FacilityInstanceObject` | 楼层下的 instanced 设备引用、`objectManager.getById()` 全局检索、`getFacilityBoundingBox()` + `controls.flyToBox()` 飞向单设备、单设备显隐、颜色、透明度和事件目标。 |
+| `FacilityInstancedLayer` | `SemanticSceneGroup.facilityLayer`、`addFacilityBatch()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
+| `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`SemanticSceneGroup.setFacilityOpacity()`、普通 `Model` fallback 与 scene-level instancing 的差异。 |
+
+## fire 检索范围
+
+MCP 文档索引会同步 `docs/api-plugin-fire.md` 中的 FireEffect API、参数和示例。客户端可以直接检索以下关键词：
+
+| 关键词 / API | 可检索内容 |
+| :----------- | :--------- |
+| `FireEffect` | 插件创建、`enable()`、`update()`、`setEmitter()`、`reset()`、`disable()` 和 `dispose()`。 |
+| `fire` / `volumetric fire` | WebGPU 体积火焰、烟雾散射、curl noise、buoyancy、Jacobi pressure projection 和 raymarch 输出。 |
+| `emitterGeometry` / `emitterRadius` | 默认 `TeapotGeometry(0.8, 28)`、自定义 emitter 几何、业务 `Object3D` matrix 驱动和移动扰动半径。 |
+| `size` / `gridSize` | 体积盒世界范围、烟雾扩散边界和 3D 模拟网格尺寸。 |
+| `addOutputEffect` | `FireEffect` 通过 RenderPipeline output effect 叠加体积 pass，不占用业务 `setOutputComposer()`。 |
+| `keyLight` / `pointLight` | 体积阴影 spot light、跟随火焰核心的动态点光源和可关闭的内置光源。 |
+
 ## 包结构
 
 源码位于 `packages/u-space-mcp`。根目录只保留一个 MCP 发布入口；执行时会先递增 `u-space-mcp` 的 patch 版本，再从 `docs/*.md` 生成内置文档索引，编译 MCP 包，然后发布到 npm：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -62,9 +62,9 @@
     "3d-tiles-renderer": ">=0.4.28",
     "@takram/three-geospatial": ">=0.9.1",
     "@takram/three-atmosphere": ">=0.19.1",
-    "@types/three": ">=0.184.1",
+    "@types/three": ">=0.185.0",
     "camera-controls": ">=3.1.2",
-    "postprocessing": ">=6.39.1",
-    "three": ">=0.184.0"
+    "postprocessing": ">=6.39.2",
+    "three": ">=0.185.0"
   }
 }