u-space 0.0.28 → 0.0.29

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.27`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.27` 作为直接托管 `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.28`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.28` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -64,11 +64,27 @@
 
 - 使用 `UManagerLoader.setPath()` 配置场景根目录，并通过一次 `loadAsync()` 完成 `SemanticLoader` + `SceneLoader` 组合加载。
 - `SceneLoader` 会自动跳过语义文件中已存在的 `id`，避免建筑、楼层或设备重复加载。
-- 通过 `viewer.objectManager` 获取 `SceneInstanceObject` 和 `FacilityInstanceObject`，再使用统一 `getSemanticBoundingBox()` + `viewer.controls.flyToBox()` 飞向单个实例。
+- 通过 `root.semanticGroup.getDefaultFacilityLayer()` 和 `root.sceneGroup.getDefaultSceneLayer()` 直接获取默认设备合批层和场景模型合批层。
+- 通过 `viewer.objectManager` 获取 `SceneInstanceObject` 和 `FacilityInstanceObject`，再直接使用 `viewer.controls.flyToObject()` 飞向单个实例。
 - 使用 `setSemanticHighlight()`、`setSemanticVisible()`、`setSemanticOpacity()` 等统一 API 控制实例，不需要关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
-- 示例把 `viewer`、`loader`、`root`、`semanticGroup`、`sceneGroup`、`sceneInstances` 和 `facilities` 暴露到 `window.uManagerExample`，方便在控制台调试。
+- 示例把 `viewer`、`loader`、`root`、`semanticGroup`、`sceneGroup`、`facilityLayer`、`sceneLayer`、`sceneInstances` 和 `facilities` 暴露到 `window.uManagerExample`，方便在控制台调试。
 
-## 6. `test_model_animation.html`：模型内置动画
+## 6. `test_umanager_dynamic_instances.html`：运行时动态实例
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_umanager_dynamic_instances.html)
+
+该示例把运行时实例新增、删除、恢复和按 ID 查询拆到独立场景中，避免和 `UManagerLoader` 的一体化加载流程混在一起。
+
+### 核心要点：
+
+- 创建 `SceneInstancedLayer` 并调用 `reserveSemanticBatch(url, template, capacity)` 预分配容量。
+- 通过 `SceneInstanceObject.setSemanticIdentity({ id, kind, name })` 设置实例独立身份字段，不依赖 `userData` 参与 layer 内部索引。
+- 同一个 layer 内 `semanticId` 必须唯一；重复 ID 的新增会返回 `false`，加入后修改身份字段会在下一次按 ID 查询时刷新索引。
+- 使用 `addSemanticInstances()` 批量新增实例，使用 `removeSemanticInstance(id)` / `removeSemanticInstances(id)` 按完整 `semanticId` 删除实例。
+- 使用 `getSemanticInstanceById(id)` 快速获取实例，返回对象可直接用于 `setSemanticHighlight()` 和 `viewer.controls.flyToObject()`。
+- 示例把 `viewer`、`layer`、`template`、`allInstances` 和 `removedInstances` 暴露到 `window.dynamicInstanceExample`。
+
+## 7. `test_model_animation.html`：模型内置动画
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
 
@@ -82,7 +98,7 @@
 - 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
 - 使用 `model.stopAnimation()` 停止动画播放。
 
-## 7. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+## 8. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
 
 该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
 
@@ -94,7 +110,7 @@
 - CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
 - 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
 
-## 8. `test_postprocessing.html`：后处理效果
+## 9. `test_postprocessing.html`：后处理效果
 
 该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
 
@@ -108,7 +124,7 @@
 - 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
 - 使用 `setOutputComposer(null)` 恢复默认渲染管线。
 
-## 9. `test_viewer_utils.html`：Viewer 工具方法
+## 10. `test_viewer_utils.html`：Viewer 工具方法
 
 该示例演示了 `Viewer` 新增的便捷方法：截图导出、背景切换、雾效控制和阴影开关。
 
@@ -120,7 +136,7 @@
 - 使用 `viewer.enableShadow()` / `viewer.disableShadow()` 控制阴影渲染。
 - 使用 `viewer.resize(width, height)` 手动触发尺寸更新。
 
-## 10. `test_camera_controls.html`：CameraControls 增强方法
+## 11. `test_camera_controls.html`：CameraControls 增强方法
 
 该示例演示了 `CameraControls` 的飞行定位、视角存取、锁定和二三维切换功能。
 
@@ -132,7 +148,7 @@
 - 使用 `viewer.controls.lock()` / `unlock()` 锁定或解锁相机控制。
 - 使用 `viewer.controls.setViewMode('2d')` / `setViewMode('3d')` 在二三维视图间切换。
 
-## 11. `test_object_manager.html`：ObjectManager 增强方法
+## 12. `test_object_manager.html`：ObjectManager 增强方法
 
 该示例演示了 `ObjectManager` 的显隐控制、孤立显示、透明度设置、包围盒查询和过滤功能。
 
@@ -144,7 +160,7 @@
 - 使用 `viewer.objectManager.getBoundingBox()` 查询所有对象的包围盒。
 - 使用 `viewer.objectManager.filter(predicate)` 按条件过滤对象。
 
-## 12. `test_material_effects.html`：MaterialEffects 增强效果
+## 13. `test_material_effects.html`：MaterialEffects 增强效果
 
 该示例演示了材质效果系统的线框、半透明、X 光和淡入淡出功能。
 
@@ -156,7 +172,7 @@
 - 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
 - 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
 
-## 13. `test_selection.html`：Selection 选择系统
+## 14. `test_selection.html`：Selection 选择系统
 
 该示例演示了对象选择系统的单选和框选功能。
 
@@ -167,7 +183,7 @@
 - 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
 - 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
 
-## 14. `test_measure.html`：MeasureTool 测量工具
+## 15. `test_measure.html`：MeasureTool 测量工具
 
 该示例演示了 3D 场景中的距离、面积和角度测量。
 
@@ -178,7 +194,7 @@
 - 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
 - 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
 
-## 15. `test_annotation.html`：AnnotationManager 标注管理
+## 16. `test_annotation.html`：AnnotationManager 标注管理
 
 该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
 
@@ -190,7 +206,7 @@
 - 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
 - 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
 
-## 16. `test_clipping.html`：ClippingTool 剖切工具
+## 17. `test_clipping.html`：ClippingTool 剖切工具
 
 该示例演示了剖切面的创建和实时调整。
 
@@ -201,7 +217,7 @@
 - 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
 - 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
 
-## 17. `test_lights.html`：LightManager 灯光管理
+## 18. `test_lights.html`：LightManager 灯光管理
 
 该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
 
@@ -212,7 +228,7 @@
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
 
-## 18. `test_fire.html`：WebGPU 体积火焰
+## 19. `test_fire.html`：WebGPU 体积火焰
 
 该示例演示了 `u-space/plugins/fire` 的 `FireEffect` 插件，封装 Three.js 官方体积火焰示例，在独立 volumetric pass 中模拟火焰和烟雾后叠加到主场景。
 

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.27'
+console.log(version); // e.g. '0.0.28'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

package/docs/mcp.md

@@ -86,7 +86,7 @@ export const codingAgent = new Agent({
 
 ## 示例检索
 
-MCP 文档索引包含 `examples/test_umanager_loader.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载语义楼层、Facilities 和非语义场景树的示例入口，以及 `window.uManagerExample` 控制台调试对象说明。
+MCP 文档索引包含 `examples/test_umanager_loader.html` 和 `examples/test_umanager_dynamic_instances.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载语义楼层、Facilities 和非语义场景树的示例入口，以及 `window.uManagerExample` 控制台调试对象说明；检索 `dynamic instances`、`getSemanticInstanceById` 或 `test_umanager_dynamic_instances` 可以找到运行时新增、删除、恢复和按 ID 查询 instanced 语义实例的示例。
 
 ## u-manager 检索范围
 
@@ -94,15 +94,16 @@ MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 UManagerLoader
 
 | 关键词 / API | 可检索内容 |
 | :----------- | :--------- |
-| `UManagerLoader` | 同时加载 `SemanticLoader` 和 `SceneLoader`、自动复用 semantic id 去重、返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`。 |
-| `SemanticInstanceObject` | 统一语义实例 API：`setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()`、`getSemanticBoundingBox()`、`setSemanticHighlight()`，覆盖楼层多边形、Facilities、SceneLoader path instances 和 fallback Model wrapper。 |
-| `SemanticModelInstancedLayer` | `SceneInstancedLayer` 与 `FacilityInstancedLayer` 的共享实现：模板 mesh 收集、合法 material groups、多材质 instancing、dirty-driven buffer sync、raycast hit remap 和可选相机实例裁剪。 |
-| `SceneLoader` | 场景树加载、语义 `ID` 去重、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
-| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、`userData.semanticKind = 'SceneInstances'`、`setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()`、`setSemanticOpacity()`、`getSemanticColor()`、`getSemanticOpacity()`、`setSemanticHighlight()`、`clearSemanticHighlight()`、`getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单模型、dirty 监听和事件目标。 |
+| `UManagerLoader` | 同时加载 `SemanticLoader` 和 `SceneLoader`、自动复用 semantic id 去重、返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`；可通过 `semanticGroup.getDefaultFacilityLayer()` 和 `sceneGroup.getDefaultSceneLayer()` 直接访问默认合批层。 |
+| `SemanticInstanceObject` | 统一语义实例 API：独立字段 `semanticId` / `semanticKind` / `semanticName`、`setSemanticIdentity()`、`setSemanticVisible()`、`setSemanticColor()`、`setSemanticOpacity()`、`getSemanticBoundingBox()`、`setSemanticHighlight()`，以及对象级 `boundingBox` / `boundingSphere` / `computeBoundingBox()` / `computeBoundingSphere()`，覆盖楼层多边形、Facilities、SceneLoader path instances 和 fallback Model wrapper，可直接用于 `controls.flyToObject()`。 |
+| `SemanticModelInstancedLayer` | `SceneInstancedLayer` 与 `FacilityInstancedLayer` 的共享实现：模板 mesh 收集、合法 material groups、多材质 instancing、`getSemanticInstances()`、`getSemanticInstanceById()`、运行时实例新增/删除、capacity 预分配与扩容、重复 `semanticId` 拒绝加入、身份字段变化后按需刷新 id 索引、dirty-driven buffer sync、transform 变化后渲染前同步 instance matrix、raycast hit remap 和可选相机实例裁剪；内部索引使用实例独立字段，不依赖 `userData`。 |
+| `SceneLoader` | 场景树加载、语义 `ID` 去重、返回 `SceneGroup`、重复 3D 模型按 `path` 自动合并、unsupported template 回退普通 `Model`。 |
+| `SceneGroup` | `SceneLoader.loadAsync()` 返回根组，保留原始场景树层级，并通过 `sceneLayer` / `getDefaultSceneLayer()` 暴露默认 `SceneInstancedLayer`。 |
+| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、`semanticKind = 'SceneInstances'`、`setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()`、`setSemanticOpacity()`、`getSemanticColor()`、`getSemanticOpacity()`、`setSemanticHighlight()`、`clearSemanticHighlight()`、对象级包围盒缓存 + `controls.flyToObject()` 飞向单模型、dirty 监听和事件目标。 |
 | `SceneInstancedLayer` | `SceneLoader` 内部批量渲染层、共享 `SemanticModelInstancedLayer`、dirty-driven instance buffer 同步、raycast hit remap。 |
-| `FacilityInstanceObject` | 楼层下的设备引用、`objectManager.getById()` 全局检索、`getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单设备、统一 `setSemantic*` 控制、fallback `Model` wrapper 和事件目标。 |
-| `FacilityInstancedLayer` | `SemanticGroup.facilityLayer`、`addSemanticBatch()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
-| `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`FacilityInstanceObject.setSemanticOpacity()`、普通 `Model` fallback wrapper 与 scene-level instancing 的一致 API。 |
+| `FacilityInstanceObject` | 楼层下的设备引用、`objectManager.getById()` 全局检索、对象级包围盒缓存 + `controls.flyToObject()` 飞向单设备、统一 `setSemantic*` 控制、fallback `Model` wrapper 和事件目标。 |
+| `FacilityInstancedLayer` | `SemanticGroup.facilityLayer` / `SemanticGroup.getDefaultFacilityLayer()`、`getSemanticInstances()`、`getSemanticInstanceById()`、`reserveSemanticBatch()`、`addSemanticInstance()` / `addSemanticInstances()`、`removeSemanticInstance()` / `removeSemanticInstances()`（支持单个 `semanticId` 字符串）、`removeSemanticBatch()`、`clearSemanticBatches()`、batch 创建条件、`setInstanceCulling()`、动态 Facilities batch、可选按相机视锥压缩 active instances、可选 `minScreenRadius` 屏幕尺寸裁剪、dirty-driven instance buffer 同步和 raycast hit remap。 |
+| `Facilities` | `SemanticLoader` 解析、`FloorMesh.getFacilityById()`、`FacilityInstanceObject.setSemanticOpacity()`、普通 `Model` fallback wrapper 与 scene-level instancing 的一致 API；`SemanticGroup` / `BuildingGroup` / `FloorMesh` 查询使用对象 `semanticId` 或显式别名，不扫描 `userData` ID。 |
 
 ## fire 检索范围
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",