u-manager

u-manager 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点、楼层、井道和设备语义模型。

所有加载器均继承自 Three.js 的 Loader，并提供 setPath(path) 方法，在调用 loadAsync() 前配置基础数据目录。

`UManagerLoader`

UManagerLoader 是推荐的一体化入口。它会在同一路径下同时加载 SemanticLoader 和 SceneLoader：语义文件中已经存在的 id 会由 SceneLoader 自动跳过，避免建筑、楼层、设备被重复创建；非语义场景树节点仍会正常加载。返回值是一个 UManagerSceneGroup，可直接通过 semanticGroup 访问 SemanticGroup，通过 sceneGroup 访问非语义场景组。

typescript

import { UManagerLoader } from 'u-space/plugins/u-manager';

const loader = new UManagerLoader(viewer);
loader.setPath('./scenes/my-scene');
loader.setKey('YOUR_LICENSE_KEY');

const group = await loader.loadAsync();
viewer.scene.add(group);

const semanticGroup = group.semanticGroup;
const sceneGroup = group.sceneGroup;
const facilityLayer = semanticGroup.getDefaultFacilityLayer();
const sceneLayer = sceneGroup.getDefaultSceneLayer();

完整可运行示例见 examples/test_umanager_loader.html。该示例展示了如何从返回根组中直接读取 semanticGroup / sceneGroup，通过 getDefaultFacilityLayer() / getDefaultSceneLayer() 获取默认合批层，并通过 viewer.objectManager 获取 SceneInstanceObject / FacilityInstanceObject 后调用统一 viewer.controls.flyToObject()、setInstanceHighlight()、setInstanceVisible() 和 setInstanceOpacity()。运行时动态新增/删除 batch 实例的示例见 examples/test_umanager_dynamic_instances.html。

`SemanticLoader`

加载 db/semantic_model.json 楼层语义数据。loadAsync() 返回顶层 SemanticGroup，用于组织整次语义解析产生的建筑、楼层以及 scene-level facility layer。每个建筑包含多个 FloorMesh，每个楼层把墙、柱、空间、楼梯等语义对象合并为一个 TSL 材质驱动的网格；建筑级电梯井和通风井会使用 ExtrudeMesh 独立渲染。语义模型包含 Facilities 时，SemanticLoader 会额外读取 SceneMetadata.json 指向的 tree_models，按场景授权配置解密，再把对应设备模型挂载到所属楼层。

typescript

import { Vector3, Vector4 } from 'three';
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 semanticGroup = await loader.loadAsync(); // SemanticGroup
viewer.scene.add(semanticGroup);

const building = semanticGroup.getBuildingAt(0);
const floor = building.getFloorAt(0);

building.isolateFloor(floor);
await viewer.controls.flyToObject(floor);

floor.addEventListener('click', ({ event }) => {
  const { currentTarget, intersect } = event;
  if (!intersect) return;

  const index = intersect.semanticIndex;

  currentTarget.setColorAt(index, new Vector4(1, 0, 0, 0.5));
  currentTarget.setScaleAt(index, new Vector3(1, 0.1, 1));
  viewer.render();
});

所有可按 ID 操作的实例都会尽量暴露统一的 InstanceObject API。楼层多边形语义使用轻量 FloorSemanticInstanceObject 代理合并几何中的一个实例；Facilities 和 SceneLoader path instancing 使用同一套模型实例化底层。业务代码优先使用 setInstanceVisible()、setInstanceColor()、setInstanceOpacity() 和 viewer.controls.flyToObject(instance)，而不是关心底层是合并几何、InstancedMesh 还是 fallback Model。

完整的继承字段、方法、颜色模式、包围盒和 dirty 同步语义见核心 InstanceObject API。

InstanceObject 也按 Three.js 对象级包围盒约定提供 boundingBox、boundingSphere、computeBoundingBox() 和 computeBoundingSphere()。它们缓存的是实例本地坐标包围体，Box3.setFromObject() 会自动调用 computeBoundingBox() 并应用 matrixWorld，因此 viewer.controls.flyToObject() 可以直接飞向 SceneInstanceObject、FacilityInstanceObject 和楼层实例代理。需要手动处理世界包围盒时，仍可使用 getInstanceBoundingBox(target, true)。

`SemanticGroup`

SemanticGroup 继承自 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。
`getDefaultFacilityLayer()`	返回当前默认 `FacilityInstancedLayer`；没有可实例化 Facilities 时返回 `null`。
`getFacilityById(id)`	在整次语义解析结果中按 `Facility.ID` 或显式别名查找设备。
`showAllFacilities()` / `hideAllFacilities()`	显示或隐藏整次语义解析结果中的全部设备。
`showAllFloors()`	显示所有建筑的所有楼层。
`planishFloors(kind?)` / `unplanishFloors(kind?)`	压扁或恢复所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面附近，同时添加稳定的轻微 Y 偏移以减少共面闪烁；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。

`BuildingGroup`

BuildingGroup 继承自 BaseGroup，用于组织一个建筑下的所有楼层、电梯井和通风井。设备语义对象不会直接挂到 BuildingGroup；能 instancing 的设备会渲染到 SemanticGroup.facilityLayer，同时在对应 FloorMesh 下保留可检索、可控制的轻量引用。

建筑内设备 ID 到楼层的关系由内部 Map 索引维护，并通过楼层设备索引版本自动同步。

属性 / 方法	说明
`floorMeshes`	当前建筑内的 `FloorMesh[]`。
`elevatorMeshes`	当前建筑内由 `Elevators` 语义生成的 `ExtrudeMesh[]`。
`ventMeshes`	当前建筑内由 `Vents` 语义生成的 `ExtrudeMesh[]`。
`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()`	显示全部楼层。
`getFacilityById(id)`	在当前建筑的楼层中按 `Facility.ID` 或 `FloorMesh.addFacility()` 显式传入的别名查找设备。
`showAllFacilities()`	显示整栋建筑内全部楼层设备。
`hideAllFacilities()`	隐藏整栋建筑内全部楼层设备。
`planishFloors(kind?)`	压扁所有楼层；默认覆盖所有合并语义实例和 Facilities，并按包围盒贴到楼层平面附近，同时添加稳定的轻微 Y 偏移以减少共面闪烁；传入 `kind` 时只压扁该语义类型，`kind` 可包含 `Facilities`。
`unplanishFloors(kind?)`	恢复所有楼层；默认恢复所有合并语义实例和 Facilities；传入 `kind` 时只恢复该语义类型，`kind` 可包含 `Facilities`。

电梯井和通风井

SemanticLoader 会读取 semantic_model.json 中建筑引用的 Elevators 和 Vents。每个井道使用 Polygon.shape 作为底面轮廓，Elevation 作为底面高度，TotalHeight 作为拉伸高度，并以 building 级 ExtrudeMesh 加入 BuildingGroup。

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);
}

if (vent) {
  building.removeVent(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 并挂到 SemanticGroup.facilityLayer；每个设备仍会在所属 FloorMesh 下保留一个 FacilityInstanceObject 实例引用，用于 getFacilityById()、显隐、颜色、透明度、包围盒和 viewer.objectManager 检索。设备 batch 使用普通 Group 包裹，以保证每帧渲染前都能执行相机实例裁剪和 hide/show 后的实例同步；带动画、骨骼、morph target 或缺少合法 geometry.groups 的多材质 Mesh 会自动回退为普通 Model，但普通 Model 也会挂到同一个 FacilityInstanceObject wrapper 下，对外 API 不变。

facilityLayer 使用 FacilityInstancedLayer，并继承自 BaseGroup。当 facilityLayer.visible = false 时，layer 会阻止内部 InstancedMesh 继续参与射线检测，避免隐藏的批处理设备仍被点击命中；单个设备的显隐应先通过 getFacilityById() 或 viewer.objectManager.getById() 取回实例，再调用 setInstanceVisible() 控制。

Instanced 设备通过 per-instance opacity attribute 控制单个设备透明度。batch 材质默认沿用源材质的透明状态；只有源材质本身透明，或当前参与渲染的设备存在 opacity < 1 时，材质才会切到 transparent: true，setInstanceOpacity(1) 可在没有其他半透明实例时回到不透明渲染队列。resetInstanceColor() 只清除颜色 override，不影响透明度 override。FacilityInstancedLayer 会在设备显隐、颜色、透明度、floor planish/unplanish 改变设备 transform，或相机矩阵、投影矩阵、viewport 高度变化时，在下一次渲染前同步实例矩阵、颜色、透明度和当前 active instance count。普通 fallback Model 的颜色和透明度控制由 wrapper 委托到 MaterialEffects，单材质和多材质 Mesh 都会应用 override。

加载成功后，BuildingGroup、FloorMesh 仍会保留自身的 semanticId、semanticKind 和 semanticName；设备引用则使用通用 InstanceObject 身份字段 instanceId、instanceKind 和 instanceName。SemanticGroup.getBuildingById()、BuildingGroup.getFloorById()、BuildingGroup.getFacilityById()、FloorMesh.getFacilityById() 以及 ModelInstancedLayer 的查询、删除和 raycast remap 都使用这些对象字段或显式传入的别名，不再从 userData.id、userData.semanticId、userData.facilityId 里扫描 ID。userData 只保留原始业务元数据，例如 facilityId、spaces、twinsIdentifier、storyId、floorIndex、instanced 和 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, {
    viewpoint: 'rightFrontTop',
    padding: 0.2,
  });
}

const facilities = floor.getSemanticsByKind('Facilities');

facility
  .setInstanceColor('#ff5533')
  .setInstanceOpacity(0.45)
  .resetInstanceColor()
  .setInstanceVisible(true);

对 Facilities 推荐直接使用 controls.flyToObject() 飞向设备。无论设备实际渲染来自 InstancedMesh 还是 fallback Model，FacilityInstanceObject 都会暴露本地 boundingBox / boundingSphere，让 Three.js 的 Box3.setFromObject() 能计算完整世界包围盒。

`FacilityInstanceObject`

FacilityInstanceObject 继承自统一的 InstanceObject，表示一个设备实例引用。它会挂在所属 FloorMesh 下，用于 ID 检索、事件派发、显隐、颜色、透明度和包围盒查询；如果设备可以 instancing，真正几何由 SemanticGroup.facilityLayer 里的 InstancedMesh 统一渲染；如果不能 instancing，fallback Model 会作为它的子对象挂载。

完整的继承字段、方法、颜色模式、包围盒和 dirty 同步语义见核心 InstanceObject API。

通常不需要手动创建 FacilityInstanceObject。SemanticParser 在解析 Facilities 时会自动创建它，并通过 setInstanceIdentity() 写入 instanceId、instanceKind 和 instanceName。userData.instanced 表示当前设备是否由 InstancedMesh 渲染；fallback 时仍然保留同一套实例 API。

加载完成后，设备可以按 Facility.ID 从全局 objectManager 取回，并直接传给 viewer.controls.flyToObject()。如果需要自己合并多个对象或调整包围盒，也可以继续调用 getInstanceBoundingBox(box, true)。

typescript

import { FacilityInstanceObject } from 'u-space/plugins/u-manager';

const facility = viewer.objectManager.getById<FacilityInstanceObject>('FACILITY_001');

if (facility?.isFacilityInstanceObject) {
  await viewer.controls.flyToObject(facility, {
    viewpoint: 'rightFrontTop',
    padding: 0.2,
    enableTransition: true,
  });
}

属性 / 方法	说明
`isFacilityInstanceObject`	类型标记，值为 `true`。
`type`	Three.js 对象类型名，值为 `'FacilityInstanceObject'`。
`instanceId`	实例独立 ID，设备默认等于 `Facility.ID`；layer 的按 ID 查询、删除和 raycast remap 都使用该字段。
`instanceKind`	实例类型，设备为 `'Facilities'`。
`instanceName`	实例显示名称，设备默认使用 `Facility.Name`。
loader-created bounds	`ModelInstancedLayer.addInstances()` / `reserveBatch()` 会在建 batch 时通过继承的 `setInstanceBounds()` 写入模板包围盒，因此实例可直接传给 `viewer.controls.flyToObject()`。
`userData.instanced`	`true` 表示由 `FacilityInstancedLayer` 批量渲染；`false` 表示 fallback `Model` 挂在当前对象下。

typescript

import { FacilityInstanceObject } from 'u-space/plugins/u-manager';

const facility = floor.getFacilityById('FACILITY_001');

if (facility instanceof FacilityInstanceObject) {
  facility
    .setInstanceColor('#29ccff')
    .setInstanceOpacity(0.6)
    .setInstanceVisible(true);

  await viewer.controls.flyToObject(facility, {
    viewpoint: 'rightFrontTop',
    padding: 0.2,
  });
}

`FacilityInstancedLayer`

FacilityInstancedLayer 继承自 ModelInstancedLayer，是 scene-level Facilities 的批量渲染层。SemanticGroup.facilityLayer 默认就是该类型；它会按模型 URL 把同一模板的静态设备合并为一个或多个 InstancedMesh，并用普通 Group 包裹每个模型 URL batch，保证设备显隐、颜色、透明度和相机实例裁剪能在每帧渲染前同步，同时保留每个楼层下的 FacilityInstanceObject 引用用于业务 API 和事件冒泡。

使用 SemanticLoader 时通常不需要直接调用 addInstances()；只有自定义语义解析、运行时新增设备或自建设备 batch 时才需要手动创建 layer，然后通过 semanticGroup.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 的值开启屏幕尺寸裁剪。
`getInstances()`	返回当前 layer 内全部实例对象数组。
`getInstanceById(id)`	根据实例对象的 `instanceId` 快速获取实例；找不到时返回 `undefined`。
`hasInstance(id)`	判断当前 layer 是否包含对应 `instanceId` 的实例。
`reserveBatch(url, template, capacity)`	为某个模型 URL 预分配 batch 容量。适合接下来会多次运行时新增实例的场景，成功返回 `true`，模板不支持 instancing 时返回 `false`。
`addInstance(url, template, instance)`	向某个模型 URL 的 batch 新增一个实例。成功返回 `true`，失败时调用方应回退为普通模型渲染。
`addInstances(url, template, instances)`	向某个模型 URL 的 batch 批量新增实例。推荐运行时新增多个实例时优先使用，避免连续单个新增造成重复扩容检查。
`removeInstance(instanceOrId)`	删除一个实例，可传实例对象或完整 `instanceId`。删除成功返回 `true`。
`removeInstances(instancesOrIds)`	删除一个或多个实例。可传单个实例对象、单个字符串 `instanceId`，或混合实例对象和 ID 的 iterable；返回实际删除数量。
`removeBatch(url)`	删除某个模型 URL 的完整 batch，释放对应内部 `InstancedMesh` 和 cloned materials。
`clearBatches()`	清空当前 layer 的所有模型 batch，并返回自身。

addInstances(url, template, instances) 会按模型 URL 复用或创建 batch，从 template 收集可 instancing 的可见 Mesh，克隆源材质，并为每个 batch 建立 instance matrix、颜色和透明度 attribute。没有动画、没有骨骼、没有 morph target，且每个多材质 Mesh 都有合法 geometry.groups 的模板会进入 instancing；不满足条件、模板没有可用 Mesh、instances 为空，或待加入实例的 instanceId 与当前 layer 内已有实例重复时会返回 false。

动态新增时，layer 会维护每个 URL batch 的 capacity。容量足够时，新增实例只会写入逻辑数组、注册 dirty callback 并标记下一帧同步；容量不足时才按 2 倍增长策略重建该 URL 下的内部 InstancedMesh 和 attribute buffer。运行时需要连续新增大量实例时，推荐先调用 reserveBatch(url, template, expectedCount)，再调用 addInstances()。删除实例不会立即收缩 GPU buffer；只有 batch 为空、调用 removeBatch() 或 clearBatches() 时才释放内部渲染资源。

外部代码不需要直接写内部 InstancedMesh.instanceMatrix。要移动、旋转或缩放实例时，直接修改对应 InstanceObject 的 transform 即可；transform 的世界矩阵发生变化时会自动标记实例 dirty，ModelInstancedLayer 会在下一次渲染前把世界矩阵同步到内部 instance matrix 并设置 instanceMatrix.needsUpdate = true。因此即使底层使用 WebGPU storage instanced buffer，公开更新方式仍然是面向实例对象：

typescript

const instance = layer.getInstanceById('FACILITY_001');

if (instance) {
  instance.position.set(10, 0, 5);
  viewer.render();
}

如果应用为静态大场景关闭了根 Scene 的 matrixWorldAutoUpdate，修改单个实例后还需显式调用 instance.updateWorldMatrix(true, false) 和 viewer.invalidate()；修改包含实例的父 Group 时调用 group.updateWorldMatrix(true, true)。这会执行 InstanceObject 的原生方法覆盖并触发 dirty callback，不需要直接调用 layer 内部同步方法。

删除 API 支持单个字符串 ID，不需要为了删除一个实例额外包一层数组。下面两个调用等价，都会按完整 ID 删除实例：

typescript

layer.removeInstance('FACILITY_001');
layer.removeInstances('FACILITY_001');

渲染前，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，并从实例对象字段附加 instanceObject、instanceObjectId、instanceKind、instanceName 和 instanceIndex，事件随后会按楼层引用对象继续冒泡。

typescript

import { FacilityInstancedLayer, FacilityInstanceObject } from 'u-space/plugins/u-manager';

const layer = new FacilityInstancedLayer();
const refs = facilityItems.map(() => new FacilityInstanceObject());

layer.reserveBatch('/models/camera.glb', templateObject, refs.length + 100);

if (layer.addInstances('/models/camera.glb', templateObject, refs)) {
  semanticGroup.setFacilityLayer(layer);
}

// 运行时按完整字符串 ID 删除一个实例；返回实际删除数量。
layer.removeInstances('FACILITY_001');

如果只想整体隐藏或禁用 scene-level batch，可以设置 semanticGroup.facilityLayer.visible = false；如果只想控制单个设备，推荐从 floor.getFacilityById(id) 或 viewer.objectManager.getById(id) 取回 FacilityInstanceObject 后调用 setInstanceVisible() / setInstanceOpacity()。

`ModelInstancedLayer`

ModelInstancedLayer 是核心 src/batches 模块导出的公共类，也是 SceneInstancedLayer 和 FacilityInstancedLayer 的共享实现。它负责模板 mesh 收集、材质克隆、InstancedMesh 创建、运行时实例新增/删除、capacity 扩容、instance matrix/color/opacity buffer 同步、raycast hit remap、fallback 判定和可选相机实例裁剪。模板 mesh 会保持独立，避免跨楼壳合并后破坏透明排序和局部包围体；射线通过实例包围体后，三角形数量较高的静态模板几何会按需建立并复用 three-mesh-bvh，小几何或不受支持的几何布局自动保留 Three.js 默认路径。普通静态模型可以由调用方对明确的热点 root 使用 enableMeshBVHRaycast(root)，避免对整个大型场景自动建树造成首击卡顿。layer 内部只依赖 InstanceObject 的 instanceId、instanceKind、instanceName 独立字段，不再扫描 instance.userData 的 facilityId、id 或 sid。getInstanceById() / removeInstances(id) 会按需刷新 id 索引；新增实例时如果发现重复 instanceId 会拒绝加入，避免同一个 layer 内出现不确定查询结果。通用 API 见 Batches API。

`FloorMesh`

FloorMesh 继承自 BaseMesh，表示一个楼层。它不是 BatchedMesh，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + DataTexture 在 GPU 侧按 semanticIndex 控制颜色、透明度、显示隐藏和实例矩阵。楼层语义网格会按实例透明度拆分为不透明和透明两个材质通道；墙、柱、门等默认不透明实例会进入 opaque pipeline，Spaces、Windows 或通过 setOpacityAt() 改成半透明的实例会进入 transparent pipeline。Facilities 通过楼层下的引用对象进行检索和控制；实际渲染可能来自 SemanticGroup.facilityLayer 的 InstancedMesh batch，也可能是 fallback 的普通 Model。

这种结构的目标是让每个楼层通常只占一个主渲染 draw call，同时仍保留实例级控制能力。xxxAt 方法全部作用于单个语义实例；没有 At 后缀的方法作用于整个楼层 mesh。

属性 / 方法	说明
`semanticCount` / `instanceCount`	当前楼层语义实例数量。
`semanticInstances`	`Map<string, number>`，从语义对象 ID 映射到实例下标。
`wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` / `staircasesInstances`	按语义类型维护的 ID 到实例下标映射。
`semanticEntities`	`Map<string, FloorSemanticEntity>`，统一索引楼层内合并几何语义和 `Facilities` 对象语义。
`facilityObjectsById`	`Map<string, FacilityInstanceObject>`，按 `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' \| 'Staircases'`。
`getSemanticNameAt(index)`	获取实例名称；当前 `Spaces` 会从语义数据的 `Name` 写入，其他类型可能为 `undefined`。
`getSemanticObjectAt(index)`	获取合并几何实例对应的 `FloorSemanticInstanceObject` 轻量对象。
`showAllFacilities()`	显示当前楼层的全部设备对象。
`hideAllFacilities()`	隐藏当前楼层的全部设备对象。
`addFacility(object, ids?)`	把设备对象挂到楼层，并按对象 `instanceId` 和显式 `ids` 建立检索别名。不会从 `object.userData` 自动扫描 ID。
`getFacilityById(id)`	根据 `Facility.ID` 或别名获取设备对象。
`getFacilityAt(index)`	按楼层设备数组下标获取设备对象。
`getFacilities()`	获取当前楼层全部设备对象。
`removeFacility(facility)`	按设备对象或 ID 从楼层移除设备，并同步清理检索索引。
`setColorAt(index, color)` / `getColorAt(index, target?)`	修改或读取实例颜色，支持 `Color`、`Vector3`、`Vector4`。
`setOpacityAt(index, opacity)` / `getOpacityAt(index)`	修改或读取实例透明度。
`setVisibleAt(index, visible)` / `getVisibleAt(index)`	修改或读取实例显隐状态。
`setMatrixAt(index, matrix)` / `getMatrixAt(index, target?)`	设置或读取实例附加矩阵。
`setScaleAt(index, scale, y?, z?)`	修改实例缩放，支持 `number` 或 `Vector3`。
`setScaleYAt(index, y)`	只修改实例 Y 轴缩放，保留 X/Z 缩放和已有位移、旋转。
`getFinalMatrixAt(index, target?)`	读取实例最终矩阵，包含语义对象原始基点矩阵。
`getBoundingBoxAt(index, target?, world?)`	获取实例包围盒；`world = true` 时包含 `FloorMesh.matrixWorld`。
`getBoundingSphereAt(index, target?, world?)`	获取实例包围球；`world = true` 时包含 `FloorMesh.matrixWorld`。
`computeBoundingBox()` / `computeBoundingSphere()`	计算整个楼层的包围体。
`planish(kind?)` / `unplanish(kind?)`	压扁或恢复楼层内所有合并语义实例和 Facilities；压平时按各自包围盒贴到楼层平面附近，并加入稳定的轻微 Y 偏移；传入 `kind` 时只作用于该语义类型，`kind` 可包含 `Facilities`。

飞向语义实例

点击、射线检测命中 FloorMesh 里的语义几何或设备时，intersect 上会附加语义字段：semanticIndex、semanticId、semanticKind 和 semanticObject。普通楼层语义几何的事件目标是 FloorSemanticInstanceObject；instanced Facilities 的事件目标是楼层下的 FacilityInstanceObject 引用，事件会继续冒泡到所属 FloorMesh、BuildingGroup 和 SemanticGroup。因此楼层监听器中应使用 event.currentTarget 操作楼层，用 intersect.semanticObject 或 event.target 取得具体语义实例。

typescript

import { Box3 } from 'three';

const box = new Box3();

floor.addEventListener('click', async ({ event }) => {
  const { currentTarget, intersect } = event;
  if (!intersect) return;

  if (intersect.semanticKind === 'Facilities') {
    const facility = intersect.semanticObject ?? event.target;

    await viewer.controls.flyToObject(facility, {
      viewpoint: 'rightFrontTop',
      padding: 0.2,
    });
    return;
  }

  if (intersect.semanticObject) {
    await viewer.controls.flyToObject(intersect.semanticObject, {
      viewpoint: 'rightFrontTop',
      padding: 0.2,
    });
    return;
  }

  const semanticBox = currentTarget.getBoundingBoxAt(intersect.semanticIndex, box, true);

  if (semanticBox) {
    await viewer.controls.flyToBox(semanticBox, {
      viewpoint: 'rightFrontTop',
      padding: 0.2,
    });
  }
});

如果要根据 ID 操作对象，先通过 getSemanticIndexById(id) 转为实例下标。

typescript

const index = floor.getSemanticIndexById('SPACE_001');

if (index !== undefined) {
  floor.setVisibleAt(index, false);
  viewer.render();
}

楼层压扁

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 同步到 SemanticGroup.facilityLayer。

如果只想调整单个合并几何实例，可以使用 setScaleAt() 或 setScaleYAt()，它们会保留该语义对象自己的基点矩阵，因此压扁墙、柱、房间时不会被压到世界原点。

`SceneLoader`

从服务端场景包加载完整场景树（模型、组、基础形状），并自动将所有已加载对象按 id 和 sid 注册到 viewer.objectManager。默认会尝试读取同一路径下的 db/semantic_model.json，如果场景树节点的 id 已存在于语义文件中，则跳过该节点，方便和 SemanticLoader 同时加载而不重复创建建筑或设备。对语义去重后仍保留的 3D 节点，SceneLoader 默认会按模型 path 自动合并重复静态模型：同一 path 的多个实例只加载一次模板，并由 SceneInstancedLayer 通过共享的 ModelInstancedLayer 批量渲染。原场景树中仍会保留每个 id / sid 对应的 SceneInstanceObject 逻辑对象，用于业务检索、显隐、颜色、透明度、包围盒和事件派发。

如果场景主要由大量普通 Mesh 组成，并且比默认的同 URL instancing 更重视 draw call 和可渲染节点数量，可以显式调用 setEditableBatching()。该模式会把兼容 Mesh 的变换烘焙到顶点，再按材质和 Geometry 布局合并为少量 SceneEditableBatchLayer Mesh；逻辑 SceneInstanceObject 仍留在原场景树中。它是静态 Geometry batching，不是 InstancedMesh、WebGPU indirect draw 或 compute rasterizer。

两种 layer 是 SceneLoader 的可替换主渲染策略，不存在继承关系：默认模式把 SceneInstancedLayer 设为 SceneGroup.sceneLayer；启用 editable batching 且至少生成一个 merged batch 时改为 SceneEditableBatchLayer。后者只接收兼容的不透明静态 Mesh；不兼容模板或子 Mesh 会继续尝试放入一个名为 SceneEditableBatchFallback 的独立 SceneInstancedLayer，重复 fallback 无法 instancing 时才退回普通 Model。因此 SceneGroup.sceneLayer / getDefaultSceneLayer() 只暴露主 SceneEditableBatchLayer，fallback SceneInstancedLayer 是同一 SceneGroup 下的辅助渲染层，不会替换主 layer；如果没有生成任何 merged Mesh，主 layer 会被移除并返回 null，即使同级 fallback 仍然存在。

模板包含动画、骨骼、morph target、非法多材质 groups 或没有可实例化网格时，会自动回退为普通 Model 渲染；fallback Model 会挂在同一个 SceneInstanceObject 下，因此调用侧不需要额外配置。

typescript

import { SceneLoader } from 'u-space/plugins/u-manager';

const sceneLoader = new SceneLoader(viewer);
sceneLoader.setPath('./scenes/my-scene');
sceneLoader.setKey('YOUR_LICENSE_KEY'); // 官方授权场景必需
sceneLoader.setEditableBatching({
  maxVerticesPerBatch: 1_500_000,
  maxIndicesPerBatch: 4_500_000,
  freezeAnimations: true,
});
const group = await sceneLoader.loadAsync(); // SceneGroup
viewer.scene.add(group);

const sceneLayer = group.getDefaultSceneLayer();

方法：

方法	说明
`setKey(key)`	设置授权场景的 RSA 解密密钥。
`setEditableBatching(options?)`	开启可编辑静态 Geometry batching。传 `true` 使用默认选项，传 `false` 关闭；默认关闭。
`loadAsync()`	加载并解析场景，返回去除语义重复节点后的 `SceneGroup`。
`clearCache()`	从 `objectManager` 中移除此加载器注册的所有 ID。
`dispose()`	清除缓存并释放水印叠加层。

可编辑静态合批：`setEditableBatching()`

setEditableBatching(options) 是面向大型、主要静态但仍需按对象操作的场景的 opt-in 路径。开启后，SceneLoader 会把所有保留的 3D 节点创建为 SceneInstanceObject，不再只处理重复 path；每个唯一模型 URL 仍只加载一次模板。

typescript

import {
  SceneLoader,
  type SceneEditableBatchOptions,
  type SceneEditableBatchStats,
} from 'u-space/plugins/u-manager';

const options: SceneEditableBatchOptions = {
  maxVerticesPerBatch: 1_500_000,
  maxIndicesPerBatch: 4_500_000,
  freezeAnimations: true,
};

const sceneLoader = new SceneLoader(viewer).setEditableBatching(options);
const sceneGroup = await sceneLoader.loadAsync();
viewer.scene.add(sceneGroup);

const stats = sceneGroup.userData.editableBatch as SceneEditableBatchStats | undefined;
console.table(stats);

配置：

字段	默认值	说明
`maxVerticesPerBatch`	`1_500_000`	单个 merged Geometry 的最大顶点数；超过后开始新 chunk。
`maxIndicesPerBatch`	`4_500_000`	单个 merged Geometry 的最大索引数；超过后开始新 chunk。
`freezeAnimations`	`false`	`false` 时含 animation clip 或 mixer 的模板整体 fallback；`true` 时烘焙当前姿态，后续播放动画前必须先 materialize。SkinnedMesh 和 morph target 始终 fallback。

合并规则

每个候选 Mesh 会生成稳定的 material key 和 geometry-layout key。只有以下状态完全兼容的 Mesh 才进入同一组：

材质类型、颜色/粗糙度等序列化参数，以及贴图源和 sampler/transform 配置一致。
Geometry 的 indexed/non-indexed 类型、index 数组类型、attribute 名称、itemSize、normalized、数组类型和 gpuType 一致。Geometry 内容和顶点数量可以不同。
castShadow、receiveShadow 和 renderOrder 一致。

合并前会为每个源 Mesh 克隆 Geometry，并应用以下矩阵：

text

inverse(batchLayer.matrixWorld) × instance.matrixWorld × meshLocalMatrix

随后为全部顶点写入 batchObjectIndex attribute，再通过 mergeGeometries() 生成 merged Mesh。批次达到顶点或索引上限时自动切分，因此每个兼容组可能生成多个 draw call。

该方案会把重复模板的顶点展开到 merged Geometry，通常以更高的 GPU 顶点内存换取更少的 draw calls 和可渲染 Mesh 遍历；重复率极高、几何较大的同模板对象仍可能更适合原生 SceneInstancedLayer。

对象级状态与 materialize

合批后，每个逻辑对象在 Float DataTexture 中占一个 RGBA texel，batch NodeMaterial 通过 TSL colorNode 和独立布尔 maskNode 读取 batchObjectIndex 对应的颜色与显隐状态；不透明 batch 保留源材质原有的 opacity 路径。因此以下操作只会把对象标记为 dirty，并立即更新 CPU 状态纹理数据，GPU 在下一帧上传，不会重新合并 Geometry：

setInstanceVisible() 和父级显隐变化。
setInstanceColor() / resetInstanceColor()。
不引入半透明的 setInstanceHighlight() / clearInstanceHighlight()。

如果对象的世界 transform 与烘焙矩阵不同，或者有效 opacity 低于 0.999，该对象会自动 materialize()：原始完整模板被 clone 为普通 Model，其中每个材质为当前实例独立克隆，然后挂到当前 SceneInstanceObject 下，同时 merged batch 中的旧副本被 mask 掉并从 BVH 命中过滤。根 Scene 使用 matrixWorldAutoUpdate = false 时，transform 修改后必须调用该对象的 updateWorldMatrix(true, false)，或在父 Group 上调用 updateWorldMatrix(true, true)，才能提交新世界矩阵并立即触发 dirty/materialize 检测。该同步发生在内部 batch 视锥裁剪前，从屏幕外移动到屏幕内也不会丢失。materialize 是单向操作；对象不会在恢复原矩阵或不透明度后自动重新进入 batch，需要重新加载场景。也可以提前显式调用：

typescript

const object = viewer.objectManager.getById<SceneInstanceObject>('SCENE_NODE_ID');
const model = object?.materialize();

if (model) {
  object.position.x += 2;
  object.setInstanceOpacity(0.5);
  await viewer.render();
}

Fallback 与透明材质

透明材质、opacity < 0.999、SkinnedMesh、morph target、多材质数组、自定义 NodeMaterial / onBeforeCompile、非标准 Geometry 布局、负行列式变换和未冻结动画不会进入 merged batch。负 determinant 会按实例拆分；同模板的正 determinant 实例仍可合并，而负缩放实例直接使用普通 Model，不会继续进入同样不支持负缩放的 SceneInstancedLayer。混合模板会只合并兼容的不透明 Mesh，并生成一个隐藏这些已合并 Mesh 的 fallback 模板来保留透明或其他不支持的子 Mesh；build 期间已经因初始 opacity materialize 的实例不会再次加入透明 fallback。其余同 URL fallback 有多个实例时仍由 SceneInstancedLayer 渲染，单例则使用普通 Model。

这条边界用于保留透明排序、蒙皮/变形和自定义 shader 行为。不要通过强制改成不透明材质来提高合批率。

Raycast 与统计

merged Mesh 首次实际拾取时会按需建立 three-mesh-bvh。命中结果通过 faceIndex → vertexIndex → batchObjectIndex 映射回原始 SceneInstanceObject，因此 intersect.object 仍是业务逻辑对象；已经 materialize 的对象不会在旧烘焙位置继续产生命中。

SceneEditableBatchStats 写入 sceneGroup.userData.editableBatch：

字段	说明
`instances`	进入 editable batch 状态表的逻辑对象数。
`sourceMeshes`	合并前的兼容源 Mesh 数。
`batches`	最终 merged Mesh 数。
`drawCallsSaved`	`sourceMeshes - batches` 的理论 draw-call 减少量，不包含多 pass 放大。
`vertices` / `indices`	烘焙后的总顶点数和索引数，用于评估显存代价。
`unsupportedInstances`	需要完整或部分 fallback 的逻辑对象数。
`unsupportedByReason`	按 `transparent`、`animation`、`skinned`、`morph`、`material-array`、`geometry-layout`、`negative-scale` 等原因统计。

WebGPU 首次创建大量 batch material pipeline 时可能出现短暂的 shader 编译开销。如果产品不希望首个可见帧展示未完成的材质，可在需求渲染模式下暂时停止相机控制产生的 render invalidation，完成 compileAsync() 后再提交首帧；examples/test_umanager2.html 展示了这一流程。

`SceneGroup`

SceneGroup 继承自 BaseGroup，是 SceneLoader.loadAsync() 的返回根组。它保留 tree_models.json 解析后的原始父子层级，并把重复静态模型的默认合批渲染层挂在 sceneLayer，方便外部直接访问，而不需要遍历 children。

属性 / 方法	说明
`isSceneGroup`	固定为 `true`，用于判断对象是否为 `SceneLoader` 根组。
`sceneLayer`	默认 path instancing 下为 `SceneInstancedLayer`；启用 editable batching 后为 `SceneEditableBatchLayer`；没有可合批模型时为 `null`。
`setSceneLayer(layer)`	设置 `SceneInstancedLayer` 或 `SceneEditableBatchLayer`；传入 `null` 会移除已有 layer。
`getDefaultSceneLayer()`	返回当前默认场景渲染层；没有可合批模型时返回 `null`。

`SceneInstanceObject`

SceneInstanceObject 继承自统一的 InstanceObject，表示一个由 SceneInstancedLayer、SceneEditableBatchLayer 或 fallback 普通模型渲染的场景模型引用。它会保留在原场景树层级中，并注册到 viewer.objectManager，因此 getById()、show() / hide()、isolate()、showAll()、setOpacity() 和 getBoundingBox() 可以继续按单个模型 ID 使用。

完整的继承字段、方法、颜色模式、包围盒和 dirty 同步语义见核心 InstanceObject API。

SceneInstanceObject 本身只增加场景模型标记：isSceneInstanceObject = true、type = 'SceneInstanceObject'、instanceKind = 'SceneInstances'。加载器会把场景树节点的 id 和 sid 都注册到 viewer.objectManager，因此同一个对象可以通过任一 ID 取回。对重复模型的 instanced 路径，instanceId 默认等于场景树节点 id，instanceName 默认等于节点名称；userData.instanced = true，并保留 modelPath 和 modelUrl 等原始加载元数据。如果模板不支持 instancing，会退回普通 Model，但仍挂在同一个 SceneInstanceObject 下，对外 API 不变。

识别字段：

字段	说明
`isSceneInstanceObject`	固定为 `true`，用于判断对象是否来自 `SceneLoader` 的场景实例。
`type`	固定为 `SceneInstanceObject`。
`instanceId`	实例独立 ID，默认等于场景树节点 `id`；layer 的按 ID 查询、删除和 raycast remap 都使用该字段。
`instanceKind`	实例类型，场景实例为 `'SceneInstances'`。
`instanceName`	实例显示名称，默认等于场景树节点名称。
`userData.id` / `userData.sid`	原始场景树节点 ID；两个 ID 都会注册到 `viewer.objectManager`。
`userData.instanced`	加载时选择 batch 路径的元数据。editable batch 对象 materialize 后该字段不作为实时状态；使用 `getInstanceRenderObject()` 是否非空判断当前是否已有普通渲染对象。
`userData.modelPath` / `userData.modelUrl`	instanced 场景实例对应的模型相对路径和完整 URL。

方法：

方法	说明
继承的实例 API	完整定义见核心 `InstanceObject` API；包含身份、bounds、fallback render object、显隐、颜色、透明度、高亮和 dirty callback。
`materialize()`	如果对象由 `SceneEditableBatchLayer` 渲染，clone 原始完整模板并将当前对象从 merged/fallback batch 中移出；默认 path instancing 或普通 fallback 下返回已有 render object 或 `null`。

MaterialEffects.highlightColor() / removeHighlightColor() 会识别 SceneInstanceObject 并调用 setInstanceHighlight() / clearInstanceHighlight()，不会直接修改共享 batch 材质。ObjectManager.setOpacity()、ObjectManager.hide()、ObjectManager.show() 也会通过统一 API 作用到单个实例。

加载完成后可以按场景树节点 id 从 objectManager 取回 SceneInstanceObject，再直接传给 viewer.controls.flyToObject()。SceneInstanceObject 内部带有本地 boundingBox 缓存能力，因此不需要加载真实 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,
  });
}

颜色、透明度和显隐可以直接链式调用：

typescript

object
  ?.setInstanceColor('#29ccff')
  .setInstanceOpacity(0.55)
  .setInstanceVisible(true);

object?.setInstanceHighlight('#ffb703', 0.75, true);
object?.clearInstanceHighlight();
object?.resetInstanceColor();

如果需要自己控制包围盒，也可以取世界包围盒后调用 flyToBox()：

typescript

import { Box3 } from 'three/webgpu';

const box = object.getInstanceBoundingBox(new Box3(), true);
await viewer.controls.flyToBox(box, { viewpoint: 'frontTop', padding: 0.2 });

射线检测命中批处理实例时，intersect.object 会被改写为对应的 SceneInstanceObject，并附加 instanceObject、instanceObjectId、instanceKind: 'SceneInstances'、instanceName 和 instanceIndex。Three.js 原生的 intersect.instanceId 仍保留为内部 InstancedMesh 的数字实例下标，事件会按逻辑对象所在的原场景树继续冒泡。

`SceneInstancedLayer`

SceneInstancedLayer 是 SceneLoader 内部使用的批量渲染层，默认 name = 'SceneInstances'。它继承自 ModelInstancedLayer，每个重复模型 URL 会生成一个 batch，batch 内按模板的可实例化 Mesh 创建 InstancedMesh。渲染前只在实例矩阵、显隐、颜色或透明度变化时同步 instance buffer；普通相机移动不会重新上传所有实例数据。

`SceneEditableBatchLayer`

SceneEditableBatchLayer 继承自核心 EditableGeometryBatchLayer<SceneInstanceObject>，后者继承自 BaseGroup。它是 setEditableBatching() 创建的 scene-specific 静态 Geometry 合并层，默认 name = 'SceneEditableBatches'；通用的材质/Geometry 分组、变换烘焙、chunk 切分、TSL 状态纹理、materialize、lazy BVH 和资源释放都由核心层实现。内部未导出的 EditableGeometryBatchMesh 继承自 BaseMesh；隐藏整个 layer 或单个 batch Mesh 时，ignoreInvisibleWhenRaycast 会在进入自定义 BVH raycast 前停止命中，阴影属性仍由对应源 Mesh 的 castShadow / receiveShadow 覆盖。

它不继承 SceneInstancedLayer。开启 editable batching 且生成 merged Mesh 时，SceneEditableBatchLayer 是 SceneGroup.sceneLayer 的主层；不兼容的重复 fallback 由同级、名称为 SceneEditableBatchFallback 的 SceneInstancedLayer 辅助渲染，单例或仍不支持 instancing 的对象使用挂在 SceneInstanceObject 下的普通 Model。没有 merged Mesh 时主 layer 为 null，辅助 fallback 不会被 getDefaultSceneLayer() 返回。

通常由 SceneLoader 管理，不需要业务代码直接调用 scene adapter 的 addTemplate() / build()，也不需要自行处理 materialize 后的 fallback 移除。公开的 stats 和 options 可用于诊断；materialize 通知使用继承的类型化 materialize 事件，释放独立创建的 layer 时应调用 dispose()。如果要在其他插件或应用中直接复用同一机制，应使用核心 EditableGeometryBatchLayer 的 addSource() API。

`TopologiesLoader` / `TopologyParser`

加载拓扑图数据并将其转换为 Topology 对象。

typescript

import { TopologiesLoader } from 'u-space/plugins/u-manager';

const loader = new TopologiesLoader();
loader.setPath('./scenes/my-scene');
const topologies = await loader.loadAsync(); // Topology[]
viewer.scene.add(...topologies);

`VisionsLoader` / `VisionsParser`

加载命名相机视点，并将相机飞行到指定视点。

typescript

import { VisionsLoader, VisionsParser } from 'u-space/plugins/u-manager';

const visionsLoader = new VisionsLoader();
visionsLoader.setPath('./scenes/my-scene');
const visionsData = await visionsLoader.loadAsync();
// visionsData 是 Record<string, IVisions[]>

const visionsParser = new VisionsParser(viewer);

// 飞行到指定视点
await visionsParser.flyTo(visionsData['HOME'][0]);

// 飞行到主（默认）视点
await visionsParser.flyToPrimary(visionsData['HOME']);

IVisions 字段：

字段	类型	说明
`camera`	`'P' \| 'O'`	相机类型：透视或正交。
`position`	`IVector3`	相机世界位置。
`target`	`IVector3`	相机朝向目标点。
`zoom`	`number`	相机缩放级别。
`primary`	`boolean`	是否为默认视点。

`AnimationsLoader` / `AnimationsParser`

加载关键帧动画数据，并通过 tweenAnimation 驱动 Object3D 的变换。

typescript

import { AnimationsLoader, AnimationsParser } from 'u-space/plugins/u-manager';

const animLoader = new AnimationsLoader();
animLoader.setPath('./scenes/my-scene');
const animationsData = await animLoader.loadAsync(); // IAnimations[]

// 查找特定对象的动画
const data = animationsData.find((a) => a.modelId === myModel.userData.id);

const parser = new AnimationsParser(viewer, myModel);
parser.initTransform(); // 保存初始位置/旋转/缩放

await parser.play(data.keyframes); // 播放动画序列

// 中途停止
parser.stop();

// 重置到初始变换
parser.reset();

`PropertiesLoader`

加载与模型关联的结构化属性元数据（如 BIM 属性）。

typescript

import { PropertiesLoader } from 'u-space/plugins/u-manager';

const propsLoader = new PropertiesLoader();
propsLoader.setPath('./scenes/my-scene');
const properties = await propsLoader.loadAsync(); // IProperties[]

// 查找模型的属性
const modelProps = properties.filter(p => p.modelId === myModel.userData.id);

IProperties 字段：

字段	类型	说明
`modelId`	`string`	关联模型的 ID。
`group`	`string`	属性分组/类别名称。
`key`	`string`	属性键名。
`value`	`string \| null`	属性值。
`label`	`string \| null`	属性的显示标签。

u-manager ​

UManagerLoader ​

SemanticLoader ​

SemanticGroup ​

BuildingGroup ​

电梯井和通风井 ​

设施设备 ​

FacilityInstanceObject ​

FacilityInstancedLayer ​

ModelInstancedLayer ​

FloorMesh ​

飞向语义实例 ​

楼层压扁 ​

SceneLoader ​

可编辑静态合批：setEditableBatching() ​

合并规则 ​

对象级状态与 materialize ​

Fallback 与透明材质 ​

Raycast 与统计 ​

SceneGroup ​

SceneInstanceObject ​

SceneInstancedLayer ​

SceneEditableBatchLayer ​

TopologiesLoader / TopologyParser ​

VisionsLoader / VisionsParser ​

AnimationsLoader / AnimationsParser ​

PropertiesLoader ​

u-manager

`UManagerLoader`

`SemanticLoader`

`SemanticGroup`

`BuildingGroup`

电梯井和通风井

设施设备

`FacilityInstanceObject`

`FacilityInstancedLayer`

`ModelInstancedLayer`

`FloorMesh`

飞向语义实例

楼层压扁

`SceneLoader`

可编辑静态合批：`setEditableBatching()`

合并规则

对象级状态与 materialize

Fallback 与透明材质

Raycast 与统计

`SceneGroup`

`SceneInstanceObject`

`SceneInstancedLayer`

`SceneEditableBatchLayer`

`TopologiesLoader` / `TopologyParser`

`VisionsLoader` / `VisionsParser`

`AnimationsLoader` / `AnimationsParser`

`PropertiesLoader`