u-space 0.0.27 → 0.0.28

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.26`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.26` 作为直接托管 `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.27`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.27` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 
@@ -54,7 +54,21 @@
 - 使用相机动画（`VisionsLoader` 和 `VisionsParser`）在场景中编排预定义的飞行路径。
 - 获取复杂的节点材质，并自定义 WebGPU 专属的 TSL（Three Shading Language）节点，如 `TSLEffects.fluid()`。
 
-## 5. `test_model_animation.html`：模型内置动画
+## 5. `test_umanager_loader.html`：UManagerLoader 一体化加载
+
+[在线演示](https://u-space-phi.vercel.app/examples/test_umanager_loader.html)
+
+该示例演示通过 `UManagerLoader` 在同一个路径下同时加载语义楼层、Facilities 和非语义场景树内容。加载结果会返回一个 `UManagerSceneGroup`，其中 `semanticGroup` 指向 `SemanticGroup`，`sceneGroup` 指向非语义场景组。
+
+### 核心要点：
+
+- 使用 `UManagerLoader.setPath()` 配置场景根目录，并通过一次 `loadAsync()` 完成 `SemanticLoader` + `SceneLoader` 组合加载。
+- `SceneLoader` 会自动跳过语义文件中已存在的 `id`，避免建筑、楼层或设备重复加载。
+- 通过 `viewer.objectManager` 获取 `SceneInstanceObject` 和 `FacilityInstanceObject`，再使用统一 `getSemanticBoundingBox()` + `viewer.controls.flyToBox()` 飞向单个实例。
+- 使用 `setSemanticHighlight()`、`setSemanticVisible()`、`setSemanticOpacity()` 等统一 API 控制实例，不需要关心底层是合并几何、`InstancedMesh` 还是 fallback `Model`。
+- 示例把 `viewer`、`loader`、`root`、`semanticGroup`、`sceneGroup`、`sceneInstances` 和 `facilities` 暴露到 `window.uManagerExample`，方便在控制台调试。
+
+## 6. `test_model_animation.html`：模型内置动画
 
 [在线演示](https://u-space-phi.vercel.app/examples/test_model_animation.html)
 
@@ -68,7 +82,7 @@
 - 使用 `model.playAnimation(name)` 按名称播放单个动画，`model.playAllAnimations()` 播放全部。
 - 使用 `model.stopAnimation()` 停止动画播放。
 
-## 6. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
+## 7. `test_css_renderer.html`：CSS2D / CSS2.5D / CSS3D 渲染器
 
 该示例演示了如何在 3D 场景中叠加渲染 HTML 元素，展示三种 CSS 渲染模式的效果差异。
 
@@ -80,7 +94,7 @@
 - CSS2.5D 和 CSS3D 对象需要设置 `scale`（通常 `0.01`），因为 HTML 元素的像素尺寸远大于 3D 世界单位。
 - 渲染器采用懒加载，仅在首次创建对应类型对象时初始化。
 
-## 7. `test_postprocessing.html`：后处理效果
+## 8. `test_postprocessing.html`：后处理效果
 
 该示例演示了 `RenderPipeline` 的内置后处理功能，包括 Bloom、SSGI、TRAA 以及自定义后处理组合器。
 
@@ -94,7 +108,7 @@
 - 使用 `viewer.renderPipeline.setOutputComposer()` 自定义后处理链（示例中实现了灰度滤镜）。
 - 使用 `setOutputComposer(null)` 恢复默认渲染管线。
 
-## 8. `test_viewer_utils.html`：Viewer 工具方法
+## 9. `test_viewer_utils.html`：Viewer 工具方法
 
 该示例演示了 `Viewer` 新增的便捷方法：截图导出、背景切换、雾效控制和阴影开关。
 
@@ -106,7 +120,7 @@
 - 使用 `viewer.enableShadow()` / `viewer.disableShadow()` 控制阴影渲染。
 - 使用 `viewer.resize(width, height)` 手动触发尺寸更新。
 
-## 9. `test_camera_controls.html`：CameraControls 增强方法
+## 10. `test_camera_controls.html`：CameraControls 增强方法
 
 该示例演示了 `CameraControls` 的飞行定位、视角存取、锁定和二三维切换功能。
 
@@ -118,7 +132,7 @@
 - 使用 `viewer.controls.lock()` / `unlock()` 锁定或解锁相机控制。
 - 使用 `viewer.controls.setViewMode('2d')` / `setViewMode('3d')` 在二三维视图间切换。
 
-## 10. `test_object_manager.html`：ObjectManager 增强方法
+## 11. `test_object_manager.html`：ObjectManager 增强方法
 
 该示例演示了 `ObjectManager` 的显隐控制、孤立显示、透明度设置、包围盒查询和过滤功能。
 
@@ -130,7 +144,7 @@
 - 使用 `viewer.objectManager.getBoundingBox()` 查询所有对象的包围盒。
 - 使用 `viewer.objectManager.filter(predicate)` 按条件过滤对象。
 
-## 11. `test_material_effects.html`：MaterialEffects 增强效果
+## 12. `test_material_effects.html`：MaterialEffects 增强效果
 
 该示例演示了材质效果系统的线框、半透明、X 光和淡入淡出功能。
 
@@ -142,7 +156,7 @@
 - 使用 `MaterialEffects.fadeOut(object)` / `fadeIn(object)` 执行淡入淡出动画。
 - 使用 `MaterialEffects.removeHighlightColor(object)` 恢复原始材质状态。
 
-## 12. `test_selection.html`：Selection 选择系统
+## 13. `test_selection.html`：Selection 选择系统
 
 该示例演示了对象选择系统的单选和框选功能。
 
@@ -153,7 +167,7 @@
 - 使用 `selection.enableBoxSelection()` 开启鼠标框选模式。
 - 框选模式下可配合 `viewer.controls.lock()` 避免框选与相机旋转冲突。
 
-## 13. `test_measure.html`：MeasureTool 测量工具
+## 14. `test_measure.html`：MeasureTool 测量工具
 
 该示例演示了 3D 场景中的距离、面积和角度测量。
 
@@ -164,7 +178,7 @@
 - 使用 `measureTool.measureAngle(pointA, vertex, pointC)` 测量夹角。
 - 测量结果以可视化线条渲染到场景中，返回的 `MeasureResult` 包含数值和单位。
 
-## 14. `test_annotation.html`：AnnotationManager 标注管理
+## 15. `test_annotation.html`：AnnotationManager 标注管理
 
 该示例演示了 3D 标注的创建、更新和管理，配合 `CSSRenderer` 实现 HTML 浮动标签。
 
@@ -176,7 +190,7 @@
 - 使用 `updateContent()` 动态更新标注内容，`updatePosition()` 移动标注位置。
 - 使用 `hideAll()` / `showAll()` 批量控制标注显隐。
 
-## 15. `test_clipping.html`：ClippingTool 剖切工具
+## 16. `test_clipping.html`：ClippingTool 剖切工具
 
 该示例演示了剖切面的创建和实时调整。
 
@@ -187,7 +201,7 @@
 - 使用滑块通过 `clippingTool.setPlaneConstant()` 实时调整剖切位置。
 - 使用 `showHelper()` / `hideHelper()` 切换剖切面可视化辅助。
 
-## 16. `test_lights.html`：LightManager 灯光管理
+## 17. `test_lights.html`：LightManager 灯光管理
 
 该示例演示了灯光管理器的灯光预设和 Helper 可视化功能。
 
@@ -198,7 +212,7 @@
 - 使用 `showAllHelpers()` / `hideAllHelpers()` 显示或隐藏灯光辅助可视化。
 - 每种预设会自动清除旧灯光并创建新的灯光组合。
 
-## 17. `test_fire.html`：WebGPU 体积火焰
+## 18. `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.26'
+console.log(version); // e.g. '0.0.27'
 
 // 也可以通过全局变量访问
 console.log(window.__USPACE__.version);

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` 的 `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 接入方式。
+`u-space-mcp` 是面向 `u-space` 文档的 Model Context Protocol（MCP）服务器。它把当前文档打包成只读 MCP 工具，方便 Mastra、Claude Desktop、Cursor 等 MCP 客户端在回答 `u-space` API、插件和示例问题时直接检索官方文档，包括 `u-manager` 的 `UManagerLoader` 一体化加载入口、`SceneLoader` 语义去重与 path-based model instancing、统一 `SemanticInstanceObject` API、`SemanticModelInstancedLayer` 共享模型合批层、`SceneInstanceObject` 场景模型引用、`SceneInstancedLayer` 批量渲染层、`SemanticLoader`、`SemanticGroup`、`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,18 +84,25 @@ export const codingAgent = new Agent({
 | `find_examples` | 查找示例和用法相关文档 |
 | `get_changelog` | 读取更新日志 |
 
+## 示例检索
+
+MCP 文档索引包含 `examples/test_umanager_loader.html` 的说明。检索 `UManagerLoader example`、`test_umanager_loader` 或 `UManagerLoader 用法` 可以找到一体化加载语义楼层、Facilities 和非语义场景树的示例入口，以及 `window.uManagerExample` 控制台调试对象说明。
+
 ## u-manager 检索范围
 
-MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
+MCP 文档索引会同步 `docs/api-plugin-u-manager.md` 中的 UManagerLoader、SemanticInstanceObject、SceneLoader、SceneInstanceObject、SceneInstancedLayer 和 Facilities 详细 API。客户端可以直接检索以下关键词：
 
 | 关键词 / 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` 检索、显隐、颜色、透明度、包围盒、`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 的差异。 |
+| `SceneInstanceObject` | `SceneLoader` path instancing 下的单模型逻辑引用、`id` / `sid` 检索、`userData.semanticKind = 'SceneInstances'`、`setSemanticVisible()`、`setSemanticColor()`、`resetSemanticColor()`、`setSemanticOpacity()`、`getSemanticColor()`、`getSemanticOpacity()`、`setSemanticHighlight()`、`clearSemanticHighlight()`、`getSemanticBoundingBox()` + `controls.flyToBox()` 飞向单模型、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。 |
 
 ## fire 检索范围
 

package/package.json

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

package/dist/plugins/u-manager/semantics/objects/SemanticSceneGroup.d.ts

@@ -1,31 +0,0 @@
-import { type ColorRepresentation, type Object3D } from 'three/webgpu';
-import { BaseGroup } from 'u-space';
-import type { BuildingFacilityReference, BuildingGroup } from './BuildingGroup';
-import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
-export declare class SemanticSceneGroup extends BaseGroup {
-    #private;
-    isSemanticSceneGroup: boolean;
-    type: string;
-    buildings: BuildingGroup[];
-    facilityLayer: Object3D | null;
-    constructor();
-    addBuilding(group: BuildingGroup): this;
-    getBuildingAt(index: number): BuildingGroup;
-    getBuildingById(id: string): BuildingGroup | undefined;
-    getBuildings(): BuildingGroup[];
-    removeBuilding(group: BuildingGroup): this;
-    get floorMeshes(): FloorMesh[];
-    setFacilityLayer(layer: Object3D | null): this;
-    showAllFacilities(): this;
-    hideAllFacilities(): this;
-    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
-    setFacilityVisible(facility: BuildingFacilityReference, visible: boolean): this;
-    showFacility(facility: BuildingFacilityReference): this;
-    hideFacility(facility: BuildingFacilityReference): this;
-    setFacilityColor(facility: BuildingFacilityReference, color: ColorRepresentation): this;
-    resetFacilityColor(facility: BuildingFacilityReference): this;
-    setFacilityOpacity(facility: BuildingFacilityReference, opacity: number): this;
-    showAllFloors(): this;
-    planishFloors(kind?: FloorSemanticKind): this;
-    unplanishFloors(kind?: FloorSemanticKind): this;
-}