# 更新日志 ## 未发布 ## 0.0.32 ### 修复与优化 - **Offscreen 在线示例场景源** — 保留本地 `examples/scenes/飞龙吾悦广场` 及其匹配密钥；GitHub 发布流程会在 Vercel 构建前拉取真实 Git LFS 对象，构建脚本也会拒绝仅含 pointer 的场景。超过 Vercel 单文件上限的场景资源会在部署产物中拆成 90 MiB 分片，由 render/decode Worker 流式还原，既避免把 LFS pointer 当作 JSON，也不替换原场景。 ### 文档 - **TSLEffects Outline** — 补齐 `TSLEffects.outline()`、`TSLOutlineOptions`、`TSLOutlineEffect`、RenderPipeline output-effect 接入、`InstanceObject` 渲染对象/bounds proxy 策略、资源释放、`test_outline.html` 在线示例及 MCP/LLM 检索入口。该效果最早随 `0.0.30` 发布，本次补全此前遗漏的文档发布面。 ## 0.0.31 ### 新增 - **嵌套模型 Decode Worker** — 新增 `u-space/worker/model-decoder` 和 `ModelLoaderManager.setDecodeWorker()`；静态 glTF/GLB/SBMX 可在 render Worker 之外完成 fetch/cache、SBMX 还原、JSON/base64/buffer 与图片解码，再以 transferable `ArrayBuffer` / `ImageBitmap` 交回 Three.js owner。协议使用单包 ACK backpressure、AbortSignal 和贴图内容身份复用，复杂 glTF 特性自动回退原 loader；Offscreen UManager 示例默认启用，并支持 `?modelDecodeWorker=off` A/B。 ### 修复与优化 - **Offscreen 在线示例** — Vercel 发布现在通过专用 Vite 配置构建 `examples/offscreen/test_umanager2_offscreen.html`，输出可直接运行的主线程 JavaScript、ES module Worker 和 Draco/Basis WASM 资源，不再让生产页面直接加载 TypeScript；Worker 的 HDR URL 同时兼容本地 `/textures/` 与线上 `/examples/textures/` 路径。 - **Offscreen Worker 超大贴图** — Worker runtime 同时覆盖 Three.js `ImageLoader` 与 `ImageBitmapLoader`；JPEG/PNG/GIF/WebP 任一边超过 WebGPU 默认 `8192` 上限时，在首次 `createImageBitmap()` 解码时等比缩小并保留 loader options/cache/abort 语义，避免 `Texture size` 继续级联为 `Invalid TextureView`、`Invalid BindGroup` 和 `Invalid CommandBuffer`。未知格式在解码后缩放并释放临时原图，源资产不会被修改。 - **Offscreen UManager 设备调试** — 增加上一个/下一个设备、飞向、高亮和清除命令；语义楼层、墙体、空间、门窗和设备默认全部显示，设备切换、飞向和清除不再改变其他对象显隐。 - **模型 Decode Worker 稳定性与安全性** — 外部 buffer/贴图恢复 `LoadingManager.resolveURL()` 和完整 item 生命周期，跨域依赖不再继承模型请求的授权 headers/credentials；增加 glTF 节点图规模、深度、环、多父节点与重复 child 校验，并把贴图内容身份缓存改为有界 LRU。decode Worker 崩溃会自动摘除并回退当前请求，`setDecodeWorker()` 返回实例绑定 disposer，AbortSignal 也覆盖普通 loader 路径；失败的 `Model` 内存缓存 Promise 会被清除以允许重试。 ## 0.0.30 ### 新增 - **TSLEffects Outline** — 新增 `TSLEffects.outline()` 可组合 output effect，支持普通 `Object3D` 与核心 `InstanceObject` 的可见/隐藏边缘描边、运行时选择和样式更新，以及在实例没有直接可描边渲染子树时使用世界包围盒代理；`examples/test_outline.html` 提供交互示例。 - **AO 示例** — 新增 `examples/test_ao.html`，通过 SSGI 的 `giIntensity: 0` 默认开启纯 AO，并提供遮蔽强度、半径和厚度实时调节。 - **RenderPipeline SSR** — 新增 `enableSSR()`、`updateSSR()` 和 `disableSSR()`，封装 Stochastic SSR、Temporal Reproject、Recurrent Denoise、velocity 以及双向历史反馈；提供完整 SSR 与降噪参数配置。 - **Viewer** — 新增可选 `pixelRatio` 构造参数，省略时继续使用 `Math.min(window.devicePixelRatio, 1.5)`。 - **Offscreen UManager 示例** — `examples/offscreen/test_umanager2_offscreen.html` 现在在 Worker 内启用 `SceneLoader.setEditableBatching()`、预热 WebGPU batch pipeline，并将渲染与 editable batch 统计传回主线程 HUD。 - **u-manager editable batching** — `SceneLoader.setEditableBatching()` 可把大型、主要静态的普通 Mesh 场景按材质和 Geometry 布局烘焙合并到 `SceneEditableBatchLayer`，同时保留 `SceneInstanceObject` 的显隐、颜色、高亮、bounds 和 raycast 映射；transform 或半透明修改会只 materialize 当前对象，透明/蒙皮/morph/自定义材质等不支持子集保持安全 fallback。 - **核心 Batches API** — 新增公共 `src/batches` 模块和 `EditableGeometryBatchLayer`，提供通用 source/build/unsupported 结果、TSL dirty 状态、typed materialize 事件、lazy BVH hit remap、统计与资源释放；`ModelInstancedLayer` 同步归入该模块，顶层 `u-space` 导入方式保持不变。 ### 变更 - **Offscreen Worker breaking** — 移除 callback 风格的 `defineWorkerViewer()`、`WorkerViewerSetup`、`WorkerViewerSetupResult` 和 `WorkerViewerContext`；改为在 module Worker 顶层 `await createWorkerViewer()`，并通过返回的 `WorkerViewerRuntime` 顺序调用 `status()`、`registerCommand()`、`onDispose()` 和 `ready()`。 - **InstanceObject materialize** — 将 `SceneInstanceObject` 私有的 materializer delegate 提升为核心 `InstanceObject.setInstanceMaterializer()` / `clearInstanceMaterializer()` / `materialize()` 协议；`SceneEditableBatchLayer` 改为核心 `EditableGeometryBatchLayer` 的 scene-specific 薄适配层，fallback 移除改用 typed `materialize` 事件。 ### 修复与优化 - **Offscreen UManager 帧率与楼壳显示** — 示例保留语义数据用于相机定位，但默认隐藏会半透明覆盖楼壳的高 draw-call 分析层；同时通过 Three.js 原生 `Scene.matrixWorldAutoUpdate` / `Object3D.updateWorldMatrix()` 关闭静态场景每帧整树矩阵遍历，并保留标准 RenderPipeline scene pass 以确保源模型透明对象正确合成。在不调整 pixel ratio 的情况下，目标场景持续拖拽可维持约 59–60 FPS。 - **Editable Geometry Batch 不透明材质** — 不透明 batch 不再复用动态 opacity 节点同时驱动 alpha 输出和 `maskNode`；源材质 opacity 路径保持不变，对象显隐改用独立布尔遮罩，修复建筑楼壳被错误显示为半透明的问题。 - **InstanceObject 静态矩阵更新** — 覆盖 Three.js 原生 `updateWorldMatrix()`，与 `updateMatrixWorld()` 共享世界矩阵/祖先显隐 dirty 检测；根 Scene 冻结自动矩阵更新后，显式更新单个实例或父 Group 仍会同步 instanced buffer，并让 editable batch 的变换差异正确触发 materialize。 - **Editable Geometry Batch 拾取** — 公共 `EditableGeometryBatchLayer` 继承 `BaseGroup`，内部未导出的 `EditableGeometryBatchMesh` 继承 `BaseMesh` 并在自定义 BVH raycast 前保留不可见短路；隐藏整个 editable layer 或单个 merged batch 后不会继续命中逻辑对象。 - **Editable Geometry Batch 生命周期** — 修复多个 layer 共用 inverse matrix、dirty transform 因旧 bounds 先被视锥裁剪、冻结根 Scene 下新挂载模型错过当帧世界矩阵、跨 layer materialize 后旧副本仍显示、materialize 对象共享模板材质、旧烘焙位置残留 BVH 命中、负缩放实例错误进入 merged/instanced path、重复实例生成幽灵几何、重复 build 累积资源、旧 layer dispose 清除新 materializer，以及 build 期间已 materialize 对象重复进入透明 fallback；`EditableGeometryBatchLayer` 现在是 one-shot builder。 - **Offscreen HUD** — renderer stats 改为 1 秒滚动窗口的 FPS、平均/p95/最大帧间隔、超过 25ms 的占比和样本数，并排除 demand 模式从静止恢复时的空闲间隔。 - **Offscreen Worker lifecycle** — 修复初始化期间销毁导致 `host.init()` 永久 pending、canvas 转移/初始 `postMessage()` 失败后未完成本地清理、dispose 后迟到的业务消息仍被派发、待发送 pointer move rAF 未取消、`ready()` 前加载失败未释放 Worker/GPU 资源，以及重复 `ArrayBuffer` transfer list 抛出 `DataCloneError`。 - **RenderPipeline SSGI** — 修正 AO/GI 合成，改为 `scene × AO + diffuse × GI`，确保 `aoIntensity` 与 `giIntensity` 分别作用于遮蔽和间接漫反射；同时兼容 Viewer 默认的 reversed depth 背景判断，并在与 SSR 同时启用时复用 diffuse MRT 附件。 - **RenderPipeline SSR** — 兼容 Viewer 默认的 `reversedDepthBuffer`：三个内部全屏 pass 会正确跳过 clear-depth 背景，同时保留 raw reversed depth 用于位置重建、ray marching 和 temporal history。 - **SSR 示例** — 新增 `examples/test_ssr.html`，并使用 1× drawing buffer、`maxDistance: 0.4`、静态 2048² 阴影和关闭默认性能面板的配置降低 GPU 开销。 ### 文档 - **docs/mcp** — 将核心 `InstanceObject` 的完整 API 归入 Objects 文档，并同步 u-manager 子类引用、LLM 摘要和 MCP 检索索引；运行时 API 未发生变化。 - **u-manager editable batching** — 补充 `setEditableBatching()` 配置、合并键、TSL 状态纹理、materialize/fallback 边界、统计字段、显存权衡、`test_umanager2.html` 示例和 MCP 检索范围。 - **OffscreenCanvas Worker** — 补充 `OffscreenViewerHost` 构造选项、方法、事件和统计字段，明确 `host.init()` / `initialized` 与一次性业务 `ready` 的边界，以及 `examples/offscreen/test_umanager2_offscreen.html` 的 editable batching、`compileAsync()` 预热、HUD 统计、静态根节点下 `InstanceObject` 显式矩阵提交、structured-clone/command 边界和 MCP 检索入口。 - **SSR** — 补充完整 RenderPipeline SSR API、时域/降噪配置、reversed-depth 兼容说明、性能建议与在线示例入口。 ## 0.0.29 ### 变更 - **u-manager breaking** — 通用实例基类和模型合批层从 `plugins/u-manager/instances` 移入核心；`InstanceObject` 位于 `src/instances`，`ModelInstancedLayer` / `InstanceCullingOptions` 位于 `src/batches`，均继续通过顶层 `u-space` 导出；旧 `SemanticInstanceObject` / `SemanticModelInstancedLayer` 命名不再保留。 - **u-manager breaking** — `ModelInstancedLayer` 移除旧的 `addSemanticBatch()` 公开入口，改为 `reserveBatch()`、`addInstance()` / `addInstances()`、`getInstanceById()`、`removeInstance()` / `removeInstances()`、`removeBatch()` 和 `clearBatches()`，支持运行时实例新增/删除、按 URL batch 的 capacity 预分配与扩容；`removeInstances()` 支持直接传单个字符串 `instanceId`，并且 layer 内部不再从 `instance.userData` 扫描 ID。 - **u-manager breaking** — `InstanceObject` 使用独立身份字段 `instanceId`、`instanceKind`、`instanceName` 和 `setInstanceIdentity()`；Scene / Facility instancing 的查询、删除和 raycast remap 都使用这些字段，`userData` 只保留原始业务元数据。 - **u-manager breaking** — `SemanticGroup`、`BuildingGroup` 和 `FloorMesh` 的 building/floor/facility 索引统一读取语义对象 ID、实例对象 `instanceId` 或显式传入的别名，不再把 `userData.id`、`userData.semanticId`、`userData.facilityId` 自动注册成查询 ID；`ModelInstancedLayer` 会拒绝重复 `instanceId` 的新增实例，并在身份字段变化后按需刷新 id 索引。 - **u-manager** — `InstanceObject` 新增对象级 `boundingBox`、`boundingSphere`、`computeBoundingBox()` 和 `computeBoundingSphere()`，`SceneInstanceObject`、`FacilityInstanceObject` 以及楼层语义代理可直接传给 `viewer.controls.flyToObject()`。 - **u-manager** — `ModelInstancedLayer` 的内部实例矩阵同步改为 WebGPU storage instanced buffer 路径，运行时新增或移动实例后会在下一帧立即同步 matrix；外部仍通过修改 `InstanceObject` transform 和 dirty sync 使用，不需要直接写内部 `InstancedMesh.instanceMatrix`。 - **u-manager** — `SemanticGroup` 新增 `getDefaultFacilityLayer()`，`SceneLoader.loadAsync()` 返回的 `SceneGroup` 新增 `sceneLayer` / `getDefaultSceneLayer()`，外部可直接获取默认 Facilities 和场景模型合批层。 - **docs/mcp** — 更新 u-manager 文档、Examples Guide、LLM 索引和 MCP 检索说明，推荐通过 `viewer.controls.flyToObject()` 飞向实例；`getInstanceBoundingBox(target, true)` 保留给手动合并或调整世界包围盒的场景。 ### 示例与文档 - **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.29`，Vercel 部署会继续按 `package.json` 注入当前版本。 ## 0.0.28 ### 新增 - **u-manager** — 新增 `UManagerLoader` 一体化入口，可同时加载 `SemanticLoader` 和 `SceneLoader`，返回带 `semanticGroup` / `sceneGroup` 直接属性的 `UManagerSceneGroup`，并复用 semantic id 去重避免重复建筑/设备。 - **examples/docs/mcp** — 新增 `examples/test_umanager_loader.html`，演示 `UManagerLoader` 一次加载语义楼层、Facilities 和非语义场景树，并补充 Examples Guide 与 MCP 检索入口。 ### 变更 - **u-manager breaking** — `SceneInstanceObject`、`FacilityInstanceObject` 和楼层多边形语义统一到 `InstanceObject` API：使用 `setInstanceVisible()`、`setInstanceColor()`、`setInstanceOpacity()`、`getInstanceBoundingBox()` 等方法，不再使用 scene/facility 专属实例方法。 - **u-manager** — 新增共享 `ModelInstancedLayer`，`SceneInstancedLayer` 和 `FacilityInstancedLayer` 共用同一套模型模板 instancing、material groups、多材质、dirty sync、raycast remap 和 fallback wrapper 逻辑。 - **ObjectManager / MaterialEffects** — 对语义实例的显隐、透明度和高亮控制统一识别 `InstanceObject`，不再维护 SceneInstance/FacilityInstance 两套特殊分支。 - **u-manager loader** — `SceneLoader` 不再解析场景树里的 `AREA`、`FLOOR`、`ROOM` 语义面；楼层、区域和房间统一由 `SemanticLoader` / `SemanticGroup` 处理，避免同一语义对象在组合加载时重复出现。 ### 示例与文档 - **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.28`，Vercel 部署会继续按 `package.json` 注入当前版本。 ## 0.0.27 ### 变更 - **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` 和 `FacilityInstanceObject` 通过 `objectManager.getById()` + `getInstanceBoundingBox()` + `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 压力，同时保留远距离深度精度。 ### 示例与文档 - **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.27`，Vercel 部署会继续按 `package.json` 注入当前版本。 ## 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** — 新增 `SemanticGroup`，作为单次 `SemanticParser` 解析结果的顶层容器；`SemanticLoader.loadAsync()` / `SemanticParser.parseAsync()` 直接返回完整语义场景。 - **u-manager semantics** — `SemanticGroup` 新增 `getBuildingById(id)`，支持按语义数据里的 `Building.ID` 获取建筑。 - **u-manager semantics** — `SemanticGroup` 和 `BuildingGroup` 的建筑/设备 ID 查询改为内部 `Map` 索引，并通过楼层设备索引版本自动同步，避免每次查询扫描数组。 - **u-manager semantics** — `FloorMesh.planish()` / `unplanish()`、`BuildingGroup.planishFloors()` / `unplanishFloors()` 和 `SemanticGroup.planishFloors()` / `unplanishFloors()` 会把所有合并语义实例和 Facilities 都按包围盒贴到楼层平面，而不是围绕实例自身基点压缩。 - **u-manager semantics** — 新增 scene-level Facilities auto instancing：同模型 URL 的静态设备会合并到 `SemanticGroup.facilityLayer` 的 `InstancedMesh` batch，同时保留楼层下的设备引用用于检索、显隐、颜色和透明度控制；带动画、骨骼、morph target 或多材质 Mesh 的设备自动回退为普通 `Model`。 - **u-manager semantics** — `SemanticGroup`、`BuildingGroup` 和 `FloorMesh` 新增 `getFacilityById()` 设备检索，返回的 `FacilityInstanceObject` 可通过统一 `setInstanceVisible()`、`setInstanceColor()`、`resetInstanceColor()` 和 `setInstanceOpacity()` 控制普通设备模型或 scene-level instanced 设备引用。 - **docs/mcp** — 补充 Facilities auto instancing 的材质透明度行为、`resetInstanceColor()` 语义，以及多材质 fallback 对颜色/透明度 override 的限制说明。 ### 修复 - **u-manager semantics** — 修复 scene-level instanced Facilities 的点击和指针事件派发：射线命中会映射回楼层下的 `FacilityInstanceObject`，并继续冒泡到所属 `FloorMesh`、`BuildingGroup` 和 `SemanticGroup`。 - **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 ### 新增 - **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 ### 新增 - **u-manager semantics** — `SemanticLoader` 支持解析建筑级 `Elevators` 和 `Vents`，以 `Polygon.shape` 作为底面轮廓、`Elevation` 作为底面高度、`TotalHeight` 作为拉伸高度生成 `ExtrudeMesh`，并通过 `BuildingGroup.elevatorMeshes`、`BuildingGroup.ventMeshes` 及 add/get/remove 方法管理。 ### 修复 - **透明语义体块渲染** — 电梯井/通风井在渲染阶段沿法线轻微内收，`Spaces` 实例使用稳定 per-instance 渲染偏移抖动，缓解与墙体或完全重叠空间共面时的 z-fighting。 - **atmosphere 插件** — 后处理链移除 aerial perspective 节点，保留 lens flare、tone mapping、temporal antialias 和 dithering；`scene.backgroundNode` 使用 `skyBackground()`，`scene.environmentNode` 使用 `skyEnvironment()`，并继续在关闭插件时恢复启用前的背景和环境节点。 ### 示例与文档 - **在线示例** — `examples/importmap.js` 的 CDN fallback 版本更新为 `0.0.21`，部署流程仍会优先按 `package.json` 注入当前版本。 ## 0.0.18 ### 变更 - **版本发布** — 同步发布包含新版大气插件实现、RenderPipeline output effects 和一键 MCP 发布脚本的 npm 包。 ## 0.0.17 ### 新增 - **atmosphere 插件** — `Atmosphere.enable(options)` 从占位实现升级为可用的大气渲染：支持 WGS84 经纬高定位、太阳/月亮方向、天空背景、天空环境、aerial perspective、lens flare、tone mapping、temporal antialias、dithering 和 `AtmosphereLight` 阴影。 - **RenderPipeline** — 新增 `addOutputEffect()` / `removeOutputEffect()` 与 `addMRTChannel()` / `removeMRTChannel()`，插件可追加输出后处理和独立 MRT 通道，不再占用业务侧 `setOutputComposer()`。 ### 变更 - **大气状态更新** — 大气插件在 `beforeRender` 中刷新相机 ECEF 位置、太阳/月亮方向和阴影 target，相机控制器驱动的移动也能逐帧更新大气状态。 - **MCP 发布** — 根目录 MCP 发布入口合并为 `pnpm publish:mcp`，命令会先递增 `u-space-mcp` 的 patch 版本，再构建文档索引并发布 npm 包。 ## 0.0.16 ### 新增 - **u-manager semantics** — `FloorMesh.planish(kind?)`、`FloorMesh.unplanish(kind?)`、`BuildingGroup.planishFloors(kind?)` 和 `BuildingGroup.unplanishFloors(kind?)` 支持按 `Walls`、`Columns`、`Spaces`、`Doors`、`Windows` 语义类型压平或恢复；`setScaleYAt(index, y)` 可只调整单个语义实例的 Y 轴缩放。 - **BaseMesh** — 默认开启 `castShadow` 与 `receiveShadow`，基础网格和继承自 `BaseMesh` 的对象会直接参与阴影投射与接收。 ### 变更 - **语义类型命名** — `SemanticKind` 统一为数据源字段风格：`Walls`、`Columns`、`Spaces`、`Doors`、`Windows`。 - **示例与依赖** — 更新 `load_tiles.html` 示例依赖，新增 `@takram/three-atmosphere`、`postprocessing` peer dependency，并将 Vite 外部依赖边界扩展到所有 `@takram/*` 包。 ## 0.0.12 ### 新增 - **u-manager semantics** — 新增 `SemanticLoader`、`BuildingGroup`、`FloorMesh` 语义楼层 API，支持楼层隔离、实例级颜色/透明度/显隐/matrix/scale 控制，以及实例包围盒/包围球查询。 - **u-space MCP** — 内置文档索引同步语义楼层 API，MCP 客户端可检索 `SemanticLoader`、`BuildingGroup` 和 `FloorMesh` 用法。 ## 0.0.8 ### 新增 - **Viewer** — `resize()`、`screenshot()`、`setBackground()`、`setEnvironment()`、`enableShadow()`/`disableShadow()`、`enableFog()`/`enableFogExp2()`/`disableFog()` - **CameraControls** — `flyTo()`、`getCameraViewpoint()`、`lock()`/`unlock()`、`setViewMode('2d' | '3d')` - **ObjectManager** — `show()`/`hide()`、`isolate()`、`showAll()`、`setOpacity()`、`getBoundingBox()`、`forEach()`、`filter()` - **InteractionManager** — `enable()`/`disable()`、`setInteractable()`、`addIgnore()`/`removeIgnore()` - **Selection** — 新增框选（rubber-band）和单选/多选/切换模块，支持 `select`/`deselect`/`change` 事件 - **MaterialEffects** — `wireframe()`/`removeWireframe()`、`transparent()`/`removeTransparent()`、`xray()`/`removeXray()`、`fadeIn()`/`fadeOut()` - **Model** — `getBoundingBox()`、`getCenter()`、`setMaterial()` - **SceneManager** — 新模块，多场景创建、注册、切换与序列化 - **LightManager** — 新模块，灯光便捷创建、4 种预设（indoor/outdoor/studio/warehouse）、Helper 可视化 - **MeasureTool** — 新工具，距离/面积/角度测量，结果可视化渲染到场景 - **ClippingTool** — 新工具，基于 WebGPU `ClippingGroup` 的剖切面与剖切盒 - **AnnotationManager** — 新工具，3D 引线标注 + HTML 浮动标签 - **示例** — 新增 8 个交互式示例页面 ### 修复 - **Selection** — 框选覆盖层改为挂载到容器元素（而非 canvas），修复框选矩形不可见的问题 - **ClippingTool** — 从 `renderer.clippingPlanes`（WebGL API）重写为 `ClippingGroup`（WebGPU API），修复剖切无效的问题 - **MaterialEffects** — fade 动画在对象移除场景后自动停止，避免内存泄漏 - **InteractionManager** — `dispose()` 中清除 `clickTimer`，避免定时器泄漏 - **LightManager** — 修复 `removeAll()`/`hideAllHelpers()` 中遍历 Map 同时删除的问题 - **ObjectManager** — `setOpacity()` 先检查 `isMesh` 再类型转换 - **ClippingTool** — `PlaneHelper` 颜色使用 `new Color(color).getHex()` 替代直接 `as number` - **MeasureTool** — 移除 WebGPU 不支持的 `linewidth` 属性 --- ## 0.0.7 ### 变更 - 文档拆分：将插件文档拆分为独立文件 - 新增 CameraControls 独立文档页 - 修复 getting-started 中的死链 - 修复 sbmx loader 示例使用新的 MaterialEffects API --- ## 0.0.6 ### 新增 - **MaterialEffects** — 可组合的材质特效系统，支持安全共享材质和 remove API - **RenderPipeline** — 内置 Bloom、SSGI、TRAA 后处理及 OutputComposer API - **CSSRenderer** — CSS2D / CSS2.5D / CSS3D 叠加渲染 HTML 元素 - 从 `package.json` 导出 `version`，统一示例 importmap --- ## 0.0.5 ### 变更 - 版本发布（无重大功能变更） --- ## 0.0.4 ### 新增 - **Model** — 动画播放支持（`playAnimation`、`stopAnimation`、`updateAnimation`） - **ViewerEventMap** — 事件回调新增 `delta` 时间参数 --- ## 0.0.3 ### 新增 - **ObjectControls** 插件 — 交互式移动、旋转、缩放 3D 对象 - **TopologyDrawer** 插件 — 在场景任意表面交互式绘制拓扑路径图 - **Topology** — `exportData()` / `importData()` 数据序列化 ### 变更 - **Interactions** — `contextmenu` 事件替换为 `rightclick` - **Poi** — 优化渲染性能，新增 `scaleFactor` 参数 - 文档全面完善：本地搜索、侧边栏优化、各插件文档页 --- ## 0.0.0 ### 新增 - 项目初始化：Viewer 核心、WebGPU 渲染器、场景/相机/控制器 - 模型加载系统：双层缓存（内存 + 持久化）、Draco/KTX2/Meshopt 支持 - 交互系统：射线检测、事件冒泡、自定义 3D 对象事件 - 对象系统：Model、Poi、Topology、基础网格（Sphere/Plane/Circle/Tube/Extrude/Shape） - ObjectManager 集中式对象注册 - 补间动画系统 - u-manager 插件：场景加载、动画、属性、视点管理 - tiles 插件：ArcGIS 3D 瓦片 / GIS 地球渲染 - minimap 插件：2D 小地图 - keyboard-controls 插件：WASD 键盘控制 - tracking-controls 插件：相机跟随 - atmosphere 插件：天空/大气渲染 - curve-movement 插件：曲线路径动画