u-space 0.0.22 → 0.0.25

package/dist/plugins/u-manager/semantics/SemanticLoader.d.ts

@@ -1,8 +1,14 @@
 import { Loader } from 'three/webgpu';
 import type { Viewer } from 'u-space';
-import { BuildingGroup } from './objects/BuildingGroup';
+import { SemanticSceneGroup } from './objects/SemanticSceneGroup';
 export declare class SemanticLoader extends Loader {
+    #private;
     viewer: Viewer;
+    key: string;
+    cachedIds: Set<string>;
     constructor(viewer: Viewer);
-    loadAsync(): Promise<BuildingGroup[]>;
+    setKey(key: string): this;
+    loadAsync(): Promise<SemanticSceneGroup>;
+    clearCache(): void;
+    dispose(): void;
 }

package/dist/plugins/u-manager/semantics/SemanticParser.d.ts

@@ -1,5 +1,15 @@
-import { BuildingGroup } from './objects/BuildingGroup';
+import { type LoadingManager, type Object3D } from 'three/webgpu';
+import { SemanticSceneGroup } from './objects/SemanticSceneGroup';
 import type { SemanticObject } from './semantic.types';
+import type { ITreeData } from '../types';
+export interface SemanticParserOptions {
+    treeData?: ITreeData[];
+    path?: string;
+    manager?: LoadingManager;
+    registerObject?: (id: string, object: Object3D) => void;
+}
 export declare class SemanticParser {
-    parse(semanticData: SemanticObject): BuildingGroup[];
+    #private;
+    parse(semanticData: SemanticObject): SemanticSceneGroup;
+    parseAsync(semanticData: SemanticObject, options?: SemanticParserOptions): Promise<SemanticSceneGroup>;
 }

package/dist/plugins/u-manager/semantics/index.d.ts

@@ -5,5 +5,7 @@ export * from './objects/VerticalShaftMesh';
 export * from './objects/ElevatorMesh';
 export * from './objects/VentMesh';
 export * from './objects/BuildingGroup';
+export * from './objects/SemanticSceneGroup';
+export * from './objects/FacilityInstancedLayer';
 export * from './SemanticParser';
 export * from './SemanticLoader';

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

@@ -1,9 +1,12 @@
+import type { ColorRepresentation, Object3D } from 'three/webgpu';
 import { BaseGroup } from 'u-space';
 import type { ElevatorMesh } from './ElevatorMesh';
-import type { FloorMesh } from './FloorMesh';
-import type { SemanticKind } from '../types';
+import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
 import type { VentMesh } from './VentMesh';
+export type BuildingFloorReference = FloorMesh | number;
+export type BuildingFacilityReference = Object3D | string;
 export declare class BuildingGroup extends BaseGroup {
+    #private;
     isBuildingGroup: boolean;
     type: string;
     floorMeshes: FloorMesh[];
@@ -11,6 +14,7 @@ export declare class BuildingGroup extends BaseGroup {
     ventMeshes: VentMesh[];
     constructor();
     addFloor(mesh: FloorMesh): this;
+    hasFloor(mesh: FloorMesh): boolean;
     getFloorAt(index: number): FloorMesh;
     removeFloor(mesh: FloorMesh): this;
     addElevator(mesh: ElevatorMesh): this;
@@ -19,8 +23,22 @@ export declare class BuildingGroup extends BaseGroup {
     addVent(mesh: VentMesh): this;
     getVentAt(index: number): VentMesh;
     removeVent(mesh: VentMesh): this;
-    isolateFloor(mesh: FloorMesh | number): this;
+    isolateFloor(floor: BuildingFloorReference | BuildingFloorReference[]): this;
+    isolateFloors(floors: BuildingFloorReference[]): this;
     showAllFloors(): this;
-    planishFloors(kind?: SemanticKind): this;
-    unplanishFloors(kind?: SemanticKind): 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;
+    syncFacilityIndexes(): this;
+    get facilityIndexVersion(): number;
+    getFacilityIndexIds(): MapIterator<string>;
+    getFacilityIndexObjects(): MapIterator<Object3D<import("three").Object3DEventMap>>;
+    planishFloors(kind?: FloorSemanticKind): this;
+    unplanishFloors(kind?: FloorSemanticKind): this;
 }

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

@@ -0,0 +1,22 @@
+import { Box3, Color, Group, Object3D, type ColorRepresentation } from 'three/webgpu';
+import { BaseGroup } from 'u-space';
+export declare class FacilityInstanceObject extends Group {
+    #private;
+    isFacilityInstanceObject: boolean;
+    type: string;
+    setLocalBounds(bounds: Box3): this;
+    setFacilityVisible(visible: boolean): this;
+    setFacilityColor(color: ColorRepresentation): this;
+    resetFacilityColor(): this;
+    setFacilityOpacity(opacity: number): this;
+    getFacilityColor(target?: Color): Color;
+    hasFacilityColor(): boolean;
+    getFacilityOpacity(): number;
+}
+export declare class FacilityInstancedLayer extends BaseGroup {
+    #private;
+    isFacilityInstancedLayer: boolean;
+    type: string;
+    constructor();
+    addFacilityBatch(url: string, template: Object3D, facilities: FacilityInstanceObject[]): boolean;
+}

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

@@ -1,20 +1,42 @@
-import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type Intersection, type Raycaster } from 'three/webgpu';
+import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type ColorRepresentation, type Intersection, type Object3D, type Raycaster } from 'three/webgpu';
 import { BaseMesh, type InteractionEvent, type InteractionEventMap } from 'u-space';
 import type { SemanticColor, SemanticGeometryEntry, SemanticKind } from '../types';
+type FacilityReference = Object3D | string;
+type FacilitySemanticKind = 'Facilities';
+export type FloorSemanticKind = SemanticKind | FacilitySemanticKind;
+export interface FloorGeometrySemanticEntity {
+    type: 'geometry';
+    kind: SemanticKind;
+    id: string;
+    name?: string;
+    index: number;
+}
+export interface FloorFacilitySemanticEntity {
+    type: 'object';
+    kind: FacilitySemanticKind;
+    id: string;
+    name?: string;
+    index: number;
+    object: Object3D;
+    aliases: string[];
+}
+export type FloorSemanticEntity = FloorGeometrySemanticEntity | FloorFacilitySemanticEntity;
 type FloorMeshEventPayload<T> = T extends {
     event: InteractionEvent;
 } ? {
     event: FloorMeshInteractionEvent;
 } : T;
-export interface FloorMeshIntersection extends Intersection<FloorMesh> {
+export interface FloorMeshIntersection extends Intersection<Object3D> {
     semanticId: string;
-    semanticKind: SemanticKind;
+    semanticKind: FloorSemanticKind;
     semanticName?: string;
     semanticIndex: number;
     instanceId: number;
+    facility?: Object3D;
+    facilityId?: string;
 }
 export type FloorMeshInteractionEvent = Omit<InteractionEvent, 'target' | 'currentTarget' | 'intersect'> & {
-    readonly target: FloorMesh;
+    readonly target: Object3D<InteractionEventMap>;
     currentTarget: FloorMesh;
     readonly intersect: FloorMeshIntersection | null;
 };
@@ -25,6 +47,7 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, MeshStandardNode
     #private;
     isFloorMergedSemanticMesh: boolean;
     type: string;
+    pivot: Vector3;
     boundingBox: Box3 | null;
     boundingSphere: Sphere | null;
     wallsInstances: Map<string, number>;
@@ -34,15 +57,35 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, MeshStandardNode
     windowsInstances: Map<string, number>;
     staircasesInstances: Map<string, number>;
     semanticInstances: Map<string, number>;
+    semanticEntities: Map<string, FloorSemanticEntity>;
+    facilityObjectsById: Map<string, Object3D>;
+    facilityObjects: Object3D[];
+    facilityIndexVersion: number;
     constructor(entries: SemanticGeometryEntry[]);
-    planish(kind?: SemanticKind): this;
-    unplanish(kind?: SemanticKind): this;
+    planish(kind?: FloorSemanticKind): this;
+    unplanish(kind?: FloorSemanticKind): this;
     get semanticCount(): number;
     get instanceCount(): number;
     getSemanticIndexById(id: string): number | undefined;
+    getSemanticById(id: string): FloorSemanticEntity | undefined;
+    getSemantics(): FloorSemanticEntity[];
+    getSemanticsByKind(kind: FloorSemanticKind): FloorSemanticEntity[];
     getSemanticIdAt(index: number): string;
     getSemanticKindAt(index: number): SemanticKind;
     getSemanticNameAt(index: number): string | undefined;
+    showAllFacilities(): this;
+    hideAllFacilities(): this;
+    addFacility(object: Object3D, ids?: string | string[]): this;
+    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
+    getFacilityAt(index: number): Object3D<import("three").Object3DEventMap>;
+    getFacilities(): Object3D<import("three").Object3DEventMap>[];
+    setFacilityVisible(facility: FacilityReference, visible: boolean): this;
+    showFacility(facility: FacilityReference): this;
+    hideFacility(facility: FacilityReference): this;
+    setFacilityColor(facility: FacilityReference, color: ColorRepresentation): this;
+    resetFacilityColor(facility: FacilityReference): this;
+    setFacilityOpacity(facility: FacilityReference, opacity: number): this;
+    removeFacility(facility: FacilityReference): this;
     setColorAt(index: number, color: SemanticColor): this;
     getColorAt(index: number, target?: Vector4): Vector4;
     setOpacityAt(index: number, opacity: number): this;

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

@@ -0,0 +1,31 @@
+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;
+}

package/dist/plugins/u-manager/semantics/semantic.types.d.ts

@@ -35,11 +35,17 @@ export interface Staircase {
     Polyline: number[];
     Spaces: number[];
 }
+export interface Facility {
+    ID: string;
+    Name: string;
+    Spaces: number[];
+    TwinsIdentifier: string;
+}
 export interface Story {
     Columns?: any[];
     Doors?: number[];
     Elevation?: number;
-    Facilities?: any[];
+    Facilities?: number[];
     FloorIndex?: any;
     Height?: number;
     ID?: string;
@@ -103,6 +109,7 @@ export interface Asset {
 export interface SemanticObject {
     Buildings?: Building[];
     Doors?: Door[];
+    Facilities?: Facility[];
     Spaces?: Space[];
     Staircases?: Staircase[];
     Stories?: Story[];

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

@@ -1,12 +1,12 @@
 # u-manager
 
-`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点、楼层和井道语义模型。
+`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点、楼层、井道和设备语义模型。
 
 所有加载器均继承自 Three.js 的 `Loader`，并提供 `setPath(path)` 方法，在调用 `loadAsync()` 前配置基础数据目录。
 
 ## `SemanticLoader`
 
-加载 `db/semantic_model.json` 楼层语义数据，并按建筑返回 `BuildingGroup[]`。每个建筑包含多个 `FloorMesh`，每个楼层把墙、柱、空间等语义对象合并为一个 TSL 材质驱动的网格；建筑级电梯井和通风井会使用 `ExtrudeMesh` 独立渲染。
+加载 `db/semantic_model.json` 楼层语义数据。`loadAsync()` 返回顶层 `SemanticSceneGroup`，用于组织整次语义解析产生的建筑、楼层以及 scene-level facility layer。每个建筑包含多个 `FloorMesh`，每个楼层把墙、柱、空间、楼梯等语义对象合并为一个 TSL 材质驱动的网格；建筑级电梯井和通风井会使用 `ExtrudeMesh` 独立渲染。语义模型包含 `Facilities` 时，`SemanticLoader` 会额外读取 `SceneMetadata.json` 指向的 `tree_models`，按场景授权配置解密，再把对应设备模型挂载到所属楼层。
 
 ```typescript
 import { Vector3, Vector4 } from 'three';
@@ -14,11 +14,12 @@ import { SemanticLoader } from 'u-space/plugins/u-manager';
 
 const loader = new SemanticLoader(viewer);
 loader.setPath('./scenes/my-scene');
+loader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景解析 tree_models 时必需
 
-const buildings = await loader.loadAsync(); // BuildingGroup[]
-viewer.scene.add(...buildings);
+const semanticScene = await loader.loadAsync(); // SemanticSceneGroup
+viewer.scene.add(semanticScene);
 
-const building = buildings[0];
+const building = semanticScene.getBuildingAt(0);
 const floor = building.getFloorAt(0);
 
 building.isolateFloor(floor);
@@ -34,9 +35,35 @@ floor.addEventListener('click', ({ event }) => {
 });
 ```
 
+### `SemanticSceneGroup`
+
+`SemanticSceneGroup` 继承自 `BaseGroup`，是单次 `SemanticParser` 解析结果的顶层容器。它管理所有 `BuildingGroup`，并把跨楼层共享的 Facilities `InstancedMesh` 渲染层作为建筑的同级对象挂在 `facilityLayer`，而不是挂到某个 `BuildingGroup` 内。
+
+建筑 ID 和设备 ID 查询使用内部 `Map` 索引维护；`getBuildingById()`、`getFacilityById()` 以及单设备控制方法不会通过数组扫描查找语义对象。
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `buildings` | 当前语义场景内的 `BuildingGroup[]`。 |
+| `facilityLayer` | scene-level 设备渲染层；同模型 URL 的静态设备会合并为 `InstancedMesh` batch。 |
+| `addBuilding(group)` / `removeBuilding(group)` | 添加或移除建筑，并同步更新 group 子节点。 |
+| `getBuildingAt(index)` / `getBuildingById(id)` / `getBuildings()` | 按下标、`Building.ID` 或整体列表获取建筑。 |
+| `floorMeshes` | 聚合返回所有建筑内的 `FloorMesh[]`。 |
+| `setFacilityLayer(layer)` | 设置跨楼层设备渲染层；传入 `null` 会移除已有 layer。 |
+| `getFacilityById(id)` | 在整次语义解析结果中按 `Facility.ID` 或显式别名查找设备。 |
+| `showFacility(id \| object)` / `hideFacility(id \| object)` | 显示或隐藏单个设备。 |
+| `setFacilityVisible(id \| object, visible)` | 设置单个设备显隐状态。 |
+| `setFacilityColor(id \| object, color)` | 设置单个设备材质颜色。 |
+| `resetFacilityColor(id \| object)` | 清除单个设备颜色 override，恢复模型原始颜色；透明度 override 不受影响。 |
+| `setFacilityOpacity(id \| object, opacity)` | 设置单个设备材质透明度，`opacity` 会被限制在 `0..1`。 |
+| `showAllFacilities()` / `hideAllFacilities()` | 显示或隐藏整次语义解析结果中的全部设备。 |
+| `showAllFloors()` | 显示所有建筑的所有楼层。 |
+| `planishFloors(kind?)` / `unplanishFloors(kind?)` | 压扁或恢复所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
+
 ### `BuildingGroup`
 
-`BuildingGroup` 继承自 `BaseGroup`，用于组织一个建筑下的所有楼层、电梯井和通风井。
+`BuildingGroup` 继承自 `BaseGroup`，用于组织一个建筑下的所有楼层、电梯井和通风井。设备语义对象不会直接挂到 `BuildingGroup`；能 instancing 的设备会渲染到 `SemanticSceneGroup.facilityLayer`，同时在对应 `FloorMesh` 下保留可检索、可控制的轻量引用。
+
+建筑内设备 ID 到楼层的关系由内部 `Map` 索引维护，并通过楼层设备索引版本自动同步。
 
 | 属性 / 方法 | 说明 |
 | :---------- | :--- |
@@ -50,10 +77,19 @@ floor.addEventListener('click', ({ event }) => {
 | `getElevatorAt(index)` | 按下标获取电梯井 `ExtrudeMesh`。 |
 | `addVent(vent)` / `removeVent(vent)` | 添加或移除通风井，并同步更新 group。 |
 | `getVentAt(index)` | 按下标获取通风井 `ExtrudeMesh`。 |
-| `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层。 |
+| `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层；也兼容传入楼层数组。 |
+| `isolateFloors(floors \| indexes)` | 只显示指定多个楼层，隐藏其他楼层。 |
 | `showAllFloors()` | 显示全部楼层。 |
-| `planishFloors(kind?)` | 压扁所有楼层；传入 `kind` 时只压扁该语义类型。 |
-| `unplanishFloors(kind?)` | 恢复所有楼层；传入 `kind` 时只恢复该语义类型。 |
+| `getFacilityById(id)` | 在当前建筑的楼层中按 `Facility.ID` 或显式别名查找设备。 |
+| `showFacility(id \| object)` / `hideFacility(id \| object)` | 显示或隐藏当前建筑内的单个设备。 |
+| `setFacilityVisible(id \| object, visible)` | 设置当前建筑内单个设备显隐状态。 |
+| `setFacilityColor(id \| object, color)` | 设置当前建筑内单个设备材质颜色。 |
+| `resetFacilityColor(id \| object)` | 清除当前建筑内单个设备颜色 override。 |
+| `setFacilityOpacity(id \| object, opacity)` | 设置当前建筑内单个设备材质透明度。 |
+| `showAllFacilities()` | 显示整栋建筑内全部楼层设备。 |
+| `hideAllFacilities()` | 隐藏整栋建筑内全部楼层设备。 |
+| `planishFloors(kind?)` | 压扁所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面；传入 `kind` 时只压扁该语义类型，`kind` 可包含 `Facilities`。 |
+| `unplanishFloors(kind?)` | 恢复所有楼层；默认恢复所有合并语义实例和 Facilities；传入 `kind` 时只恢复该语义类型，`kind` 可包含 `Facilities`。 |
 
 ### 电梯井和通风井
 
@@ -74,9 +110,43 @@ if (vent) {
 
 电梯井和通风井会在渲染阶段沿法线轻微内收，减少与墙体共面时的闪面。`Spaces` 实例也会使用稳定的 per-instance 渲染偏移抖动，缓解完全重叠空间之间的 z-fighting；这些偏移只影响渲染顶点，不改变语义 ID、实例矩阵和包围体查询的使用方式。
 
+### 设施设备
+
+`SemanticLoader` 会从 `Stories[].Facilities` 读取设备索引，再从顶层 `Facilities` 数组取得 `Facility` 数据，并使用 `Facility.ID` 在解密后的 `tree_models` 中查找同 ID 节点。只有带 `renderType: '3D'` 和模型 `path` 的节点会被加载。
+
+`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`。
+
+`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。
+
+加载成功后，设备引用会写入 `userData.facilityId`、`semanticId`、`semanticKind: 'Facilities'`、`semanticName`、`spaces`、`twinsIdentifier`、`storyId` 和 `floorIndex`，并按 `Facility.ID` 注册到 `viewer.objectManager`。自动 instancing 的引用还会带有 `userData.instanced: true` 和 `userData.modelUrl`。
+
+```typescript
+const floor = building.getFloorAt(0);
+
+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 facilities = floor.getSemanticsByKind('Facilities');
+
+semanticScene.hideFacility('FACILITY_001');
+semanticScene
+  .setFacilityColor('FACILITY_001', '#ff5533')
+  .setFacilityOpacity('FACILITY_001', 0.45)
+  .resetFacilityColor('FACILITY_001')
+  .showFacility('FACILITY_001');
+```
+
 ### `FloorMesh`
 
-`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。
+`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。Facilities 通过楼层下的引用对象进行检索和控制；实际渲染可能来自 `SemanticSceneGroup.facilityLayer` 的 `InstancedMesh` batch，也可能是 fallback 的普通 `Model`。
 
 这种结构的目标是让每个楼层通常只占一个主渲染 draw call，同时仍保留实例级控制能力。`xxxAt` 方法全部作用于单个语义实例；没有 `At` 后缀的方法作用于整个楼层 mesh。
 
@@ -84,11 +154,29 @@ if (vent) {
 | :---------- | :--- |
 | `semanticCount` / `instanceCount` | 当前楼层语义实例数量。 |
 | `semanticInstances` | `Map<string, number>`，从语义对象 ID 映射到实例下标。 |
-| `wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` | 按语义类型维护的 ID 到实例下标映射。 |
+| `wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` / `staircasesInstances` | 按语义类型维护的 ID 到实例下标映射。 |
+| `semanticEntities` | `Map<string, FloorSemanticEntity>`，统一索引楼层内合并几何语义和 `Facilities` 对象语义。 |
+| `facilityObjectsById` | `Map<string, Object3D>`，按 `Facility.ID` 或显式别名查找设备引用。 |
+| `facilityObjects` | 当前楼层挂载的设备引用数组。 |
 | `getSemanticIndexById(id)` | 根据语义 ID 获取实例下标。 |
+| `getSemanticById(id)` | 根据语义 ID 或设备别名获取统一语义实体。 |
+| `getSemantics()` | 获取楼层内全部语义实体，包含合并几何和设备对象。 |
+| `getSemanticsByKind(kind)` | 按语义类型过滤实体；`kind` 可以是 `Walls`、`Columns`、`Spaces`、`Doors`、`Windows`、`Staircases` 或 `Facilities`。 |
 | `getSemanticIdAt(index)` | 获取实例语义 ID。 |
-| `getSemanticKindAt(index)` | 获取实例类型：`'Walls' \| 'Columns' \| 'Spaces' \| 'Doors' \| 'Windows'`。 |
+| `getSemanticKindAt(index)` | 获取合并几何实例类型：`'Walls' \| 'Columns' \| 'Spaces' \| 'Doors' \| 'Windows' \| 'Staircases'`。 |
 | `getSemanticNameAt(index)` | 获取实例名称；当前 `Spaces` 会从语义数据的 `Name` 写入，其他类型可能为 `undefined`。 |
+| `showAllFacilities()` | 显示当前楼层的全部设备对象。 |
+| `hideAllFacilities()` | 隐藏当前楼层的全部设备对象。 |
+| `addFacility(object, ids?)` | 把设备对象挂到楼层，并按显式 ID、`facilityId`、`semanticId`、`id` 建立检索别名。 |
+| `getFacilityById(id)` | 根据 `Facility.ID` 或别名获取设备对象。 |
+| `getFacilityAt(index)` | 按楼层设备数组下标获取设备对象。 |
+| `getFacilities()` | 获取当前楼层全部设备对象。 |
+| `showFacility(id \| object)` / `hideFacility(id \| object)` | 显示或隐藏当前楼层内的单个设备。 |
+| `setFacilityVisible(id \| object, visible)` | 设置当前楼层内单个设备显隐状态。 |
+| `setFacilityColor(id \| object, color)` | 设置当前楼层内单个设备材质颜色。 |
+| `resetFacilityColor(id \| object)` | 清除当前楼层内单个设备颜色 override。 |
+| `setFacilityOpacity(id \| object, opacity)` | 设置当前楼层内单个设备材质透明度。 |
+| `removeFacility(facility)` | 按设备对象或 ID 从楼层移除设备，并同步清理检索索引。 |
 | `setColorAt(index, color)` / `getColorAt(index, target?)` | 修改或读取实例颜色，支持 `Color`、`Vector3`、`Vector4`。 |
 | `setOpacityAt(index, opacity)` / `getOpacityAt(index)` | 修改或读取实例透明度。 |
 | `setVisibleAt(index, visible)` / `getVisibleAt(index)` | 修改或读取实例显隐状态。 |
@@ -99,11 +187,11 @@ if (vent) {
 | `getBoundingBoxAt(index, target?, world?)` | 获取实例包围盒；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
 | `getBoundingSphereAt(index, target?, world?)` | 获取实例包围球；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
 | `computeBoundingBox()` / `computeBoundingSphere()` | 计算整个楼层的包围体。 |
-| `planish(kind?)` / `unplanish(kind?)` | 压扁或恢复楼层语义实例；传入 `kind` 时只作用于该语义类型。 |
+| `planish(kind?)` / `unplanish(kind?)` | 压扁或恢复楼层内所有合并语义实例和 Facilities；压平时按各自包围盒贴到楼层平面；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。 |
 
 ### 飞向语义实例
 
-点击、射线检测命中 `FloorMesh` 时，`intersect` 上会附加语义字段：`semanticIndex`、`semanticId`、`semanticKind`。可以直接用 `getBoundingBoxAt()` 获取实例的世界包围盒，然后让相机飞向该实例。
+点击、射线检测命中 `FloorMesh` 里的语义几何或设备时，`intersect` 上会附加语义字段：`semanticIndex`、`semanticId`、`semanticKind`。普通楼层语义几何的事件目标是 `FloorMesh`；instanced Facilities 的事件目标是楼层下的 `FacilityInstanceObject` 引用，事件会继续冒泡到所属 `FloorMesh`、`BuildingGroup` 和 `SemanticSceneGroup`。因此楼层监听器中应使用 `event.currentTarget` 操作楼层，用 `intersect.facility` 或 `event.target` 取得设备对象。
 
 ```typescript
 import { Box3 } from 'three';
@@ -111,8 +199,16 @@ import { Box3 } from 'three';
 const box = new Box3();
 
 floor.addEventListener('click', async ({ event }) => {
-  const { target, intersect } = event;
-  const semanticBox = target.getBoundingBoxAt(intersect.semanticIndex, box, true);
+  const { currentTarget, intersect } = event;
+  if (!intersect) return;
+
+  if (intersect.semanticKind === 'Facilities') {
+    const facility = intersect.facility ?? event.target;
+    await viewer.controls.flyToObject(facility);
+    return;
+  }
+
+  const semanticBox = currentTarget.getBoundingBoxAt(intersect.semanticIndex, box, true);
 
   if (semanticBox) {
     await viewer.controls.flyToBox(semanticBox, {
@@ -136,7 +232,9 @@ if (index !== undefined) {
 
 ### 楼层压扁
 
-`planish()` / `unplanish()` 默认作用于当前楼层的全部语义实例；传入 `kind` 时只处理该类型，例如 `floor.planish('Walls')`。如果只想调整单个实例，可以使用 `setScaleAt()` 或 `setScaleYAt()`，它们会保留该语义对象自己的基点矩阵，因此压扁墙、柱、房间时不会被压到世界原点。
+`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`。
+
+如果只想调整单个合并几何实例，可以使用 `setScaleAt()` 或 `setScaleYAt()`，它们会保留该语义对象自己的基点矩阵，因此压扁墙、柱、房间时不会被压到世界原点。
 
 ## `SceneLoader`
 

package/docs/changelog.md

@@ -2,7 +2,34 @@
 
 ## 未发布
 
-暂无。
+### 新增
+
+- **u-manager semantics** — 新增 `SemanticSceneGroup`，作为单次 `SemanticParser` 解析结果的顶层容器；`SemanticLoader.loadAsync()` / `SemanticParser.parseAsync()` 直接返回完整语义场景。
+- **u-manager semantics** — `SemanticSceneGroup` 新增 `getBuildingById(id)`，支持按语义数据里的 `Building.ID` 获取建筑。
+- **u-manager semantics** — `SemanticSceneGroup` 和 `BuildingGroup` 的建筑/设备 ID 查询改为内部 `Map` 索引，并通过楼层设备索引版本自动同步，避免每次查询扫描数组。
+- **u-manager semantics** — `FloorMesh.planish()` / `unplanish()`、`BuildingGroup.planishFloors()` / `unplanishFloors()` 和 `SemanticSceneGroup.planishFloors()` / `unplanishFloors()` 会把所有合并语义实例和 Facilities 都按包围盒贴到楼层平面，而不是围绕实例自身基点压缩。
+- **u-manager semantics** — 新增 scene-level Facilities auto instancing：同模型 URL 的静态设备会合并到 `SemanticSceneGroup.facilityLayer` 的 `InstancedMesh` batch，同时保留楼层下的设备引用用于检索、显隐、颜色和透明度控制；带动画、骨骼、morph target 或多材质 Mesh 的设备自动回退为普通 `Model`。
+- **u-manager semantics** — `SemanticSceneGroup`、`BuildingGroup` 和 `FloorMesh` 新增单个设备控制 API：`getFacilityById()`、`showFacility()`、`hideFacility()`、`setFacilityVisible()`、`setFacilityColor()`、`resetFacilityColor()` 和 `setFacilityOpacity()`，同时支持普通设备模型和 scene-level instanced 设备引用。
+- **docs/mcp** — 补充 Facilities auto instancing 的材质透明度行为、`resetFacilityColor()` 语义，以及多材质 fallback 对颜色/透明度 override 的限制说明。
+
+### 修复
+
+- **u-manager semantics** — 修复 scene-level instanced Facilities 的点击和指针事件派发：射线命中会映射回楼层下的 `FacilityInstanceObject`，并继续冒泡到所属 `FloorMesh`、`BuildingGroup` 和 `SemanticSceneGroup`。
+- **u-manager semantics** — `FacilityInstancedLayer` 继承 `BaseGroup`，避免 `facilityLayer.visible = false` 后内部 `InstancedMesh` 仍参与射线检测并触发隐藏设备点击事件。
+- **u-manager semantics** — 移除语义设备解析里的 `sid` 检索和注册逻辑；Facilities 只按 `Facility.ID` 以及显式传入的别名进入楼层索引和 `viewer.objectManager`。
+
+## 0.0.23
+
+### 新增
+
+- **u-manager semantics** — `BuildingGroup` 新增 `isolateFloors(floors)`，支持按多个 `FloorMesh` 或楼层下标同时隔离显示多个楼层；`isolateFloor()` 继续兼容单楼层调用，并可接收数组作为便捷写法。
+- **u-manager semantics** — `SemanticLoader` 新增 `Facilities` 解析：从 `Stories[].Facilities` 索引读取顶层设备语义，用 `Facility.ID` 匹配解密后的 `tree_models` 设备节点，沿父级累乘本地矩阵得到设备世界矩阵，加载 3D 设备模型并转换为楼层局部矩阵后挂载到对应 `FloorMesh`。
+- **u-manager semantics** — `FloorMesh` 新增楼层设备检索与统一语义实体 API：`getFacilityById()`、`getFacilityAt()`、`getFacilities()`、`removeFacility()`、`showAllFacilities()`、`hideAllFacilities()`、`getSemanticById()`、`getSemantics()` 和 `getSemanticsByKind('Facilities')`；`BuildingGroup.showAllFacilities()/hideAllFacilities()` 支持批量显示或隐藏整栋建筑内的楼层设备。
+- **u-space MCP** — 文档索引同步楼层 `Facilities` 解析和检索 API，MCP 客户端可检索设备按楼层挂载、`tree_models` 解密匹配、本地矩阵父级累乘和世界坐标转换规则。
+
+### 示例与文档
+
+- **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.23`，部署流程仍会优先按 `package.json` 注入当前版本。
 
 ## 0.0.21
 

package/docs/examples-guide.md

@@ -4,7 +4,7 @@
 
 ## 运行方式与版本
 
-示例统一通过 `examples/importmap.js` 注入 Import Map。本地通过 `localhost`、`127.0.0.1` 或 `0.0.0.0` 访问时会加载仓库里的 `../dist/` 构建产物；在线部署或非本地域名访问时会从 jsDelivr 加载当前发布版本 `u-space@0.0.21`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.21` 作为直接托管 `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.23`。Vercel 文档部署会继续把 `__VERSION__` 占位符替换为 `package.json` 中的版本号，源码里的 `0.0.23` 作为直接托管 `examples/` 时的 fallback。
 
 插件示例可以在页面加载 `importmap.js` 前通过 `window.__IMPORTS__` 声明额外依赖。将 `u-space/plugins/<name>` 的值设为 `true` 时，`importmap.js` 会自动在本地和 CDN 路径之间切换。
 

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

package/docs/index.md

@@ -52,7 +52,7 @@ features:
 | [keyboard-controls](./api-plugin-keyboard-controls) | WASD / 方向键控制相机移动与旋转 |
 | [minimap](./api-plugin-minimap) | 2D 小地图叠加层 |
 | [tiles](./api-plugin-tiles) | ArcGIS 3D 瓦片 / GIS 地球渲染 |
-| [u-manager](./api-plugin-u-manager) | 场景加载、语义楼层、语义井道、拓扑、动画、属性、视点管理 |
+| [u-manager](./api-plugin-u-manager) | 场景加载、语义楼层、语义井道、楼层设备、拓扑、动画、属性、视点管理 |
 | [curve-movement](./api-plugin-curve-movement) | 沿样条曲线移动相机或对象 |
 | [tracking-controls](./api-plugin-tracking-controls) | 相机跟随移动目标 |
 | [atmosphere](./api-plugin-atmosphere) | 天空背景、天空环境、太阳/月亮光照与阴影 |

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`、`BuildingGroup`、`FloorMesh` 语义楼层 API、电梯井/通风井语义体块，以及 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` 的 `SemanticLoader`、`SemanticSceneGroup`、`BuildingGroup`、`FloorMesh` 语义楼层 API、楼层 `Facilities` 设备检索与 scene-level auto instancing、设备显隐/颜色/透明度控制、电梯井/通风井语义体块，以及 atmosphere 插件的 `skyBackground()`、`skyEnvironment()` 和 RenderPipeline output effect 配置。
 
 ## 安装与启动
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.22",
+  "version": "0.0.25",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,7 +29,7 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:deploy": "pnpm docs:build && vercel --prod",
-    "publish:mcp": "npm --prefix ./packages/u-space-mcp version patch --no-git-tag-version && pnpm --filter u-space-mcp build && npm publish ./packages/u-space-mcp --access public --ignore-scripts",
+    "publish:mcp": "npm --prefix ./packages/u-space-mcp version patch && pnpm --filter u-space-mcp build && npm publish ./packages/u-space-mcp --access public --ignore-scripts",
     "release": "npm version patch && pnpm build && npm publish --access=public"
   },
   "files": [