u-space 0.0.11 → 0.0.13

package/dist/plugins/u-manager/loaders/SceneLoader.d.ts

@@ -1,5 +1,6 @@
 import { Group, Loader } from 'three/webgpu';
 import { type Viewer } from 'u-space';
+import type { ITreeData } from '../types';
 export interface SceneLoaderOptions {
 }
 export declare class SceneLoader extends Loader<unknown, SceneLoaderOptions> {
@@ -7,9 +8,17 @@ export declare class SceneLoader extends Loader<unknown, SceneLoaderOptions> {
     viewer: Viewer;
     key: string;
     cachedIds: Set<string>;
+    protected _resourceData: any;
+    protected _treeData: ITreeData[];
     constructor(viewer: Viewer);
     setKey(key: string): this;
-    loadAsync(options?: SceneLoaderOptions): Promise<Group<import("three").Object3DEventMap>>;
+    protected _preareTreeData(): Promise<void>;
+    /**
+     * 加载场景
+     * @param options
+     * @returns
+     */
+    loadAsync(options?: SceneLoaderOptions): Promise<Group>;
     clearCache(): void;
     dispose(): void;
 }

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

@@ -0,0 +1,15 @@
+import { BaseGroup } from 'u-space';
+import type { FloorMesh } from './FloorMesh';
+export declare class BuildingGroup extends BaseGroup {
+    isBuildingGroup: boolean;
+    type: string;
+    floorMeshes: FloorMesh[];
+    constructor();
+    addFloor(mesh: FloorMesh): this;
+    getFloorAt(index: number): FloorMesh;
+    removeFloor(mesh: FloorMesh): this;
+    isolateFloor(mesh: FloorMesh | number): this;
+    showAllFloors(): this;
+    planishFloors(): this;
+    unplanishFloors(): this;
+}

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

@@ -0,0 +1,41 @@
+import { Box3, Matrix4, Sphere, Vector3, Vector4, type Intersection, type Raycaster } from 'three/webgpu';
+import { BaseMesh } from 'u-space';
+import type { SemanticColor, SemanticGeometryEntry } from './types';
+export declare class FloorMesh extends BaseMesh {
+    #private;
+    isFloorMergedSemanticMesh: boolean;
+    type: string;
+    boundingBox: Box3 | null;
+    boundingSphere: Sphere | null;
+    wallsInstances: Map<string, number>;
+    columnsInstances: Map<string, number>;
+    spacesInstances: Map<string, number>;
+    doorsInstances: Map<string, number>;
+    windowsInstances: Map<string, number>;
+    semanticInstances: Map<string, number>;
+    constructor(entries: SemanticGeometryEntry[]);
+    planish(): void;
+    unplanish(): void;
+    get semanticCount(): number;
+    get instanceCount(): number;
+    getSemanticIndexById(id: string): number | undefined;
+    getSemanticIdAt(index: number): string;
+    getSemanticKindAt(index: number): import("./types").SemanticKind;
+    getSemanticNameAt(index: number): string | undefined;
+    setColorAt(index: number, color: SemanticColor): this;
+    getColorAt(index: number, target?: Vector4): Vector4;
+    setOpacityAt(index: number, opacity: number): this;
+    getOpacityAt(index: number): number;
+    setVisibleAt(index: number, visible: boolean): this;
+    getVisibleAt(index: number): boolean;
+    setMatrixAt(index: number, matrix: Matrix4): this;
+    setScaleAt(index: number, scale: number | Vector3, y?: number, z?: number): this;
+    getMatrixAt(index: number, matrix?: Matrix4): Matrix4;
+    getFinalMatrixAt(index: number, matrix?: Matrix4): Matrix4;
+    computeBoundingBox(): void;
+    computeBoundingSphere(): void;
+    getBoundingBoxAt(index: number, target?: Box3, world?: boolean): Box3 | null;
+    getBoundingSphereAt(index: number, target?: Sphere, world?: boolean): Sphere | null;
+    raycast(raycaster: Raycaster, intersects: Intersection[]): boolean | void;
+    dispose(): void;
+}

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

@@ -0,0 +1,8 @@
+import { Loader } from 'three/webgpu';
+import type { Viewer } from 'u-space';
+import { BuildingGroup } from './BuildingGroup';
+export declare class SemanticLoader extends Loader {
+    viewer: Viewer;
+    constructor(viewer: Viewer);
+    loadAsync(): Promise<BuildingGroup[]>;
+}

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

@@ -0,0 +1,5 @@
+import { BuildingGroup } from './BuildingGroup';
+import type { SemanticObject } from './semantic.types';
+export declare class SemanticParser {
+    parse(semanticData: SemanticObject): BuildingGroup[];
+}

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

@@ -0,0 +1,6 @@
+export * from './semantic.types';
+export * from './types';
+export * from './FloorMesh';
+export * from './BuildingGroup';
+export * from './SemanticParser';
+export * from './SemanticLoader';

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

@@ -0,0 +1,87 @@
+export interface Building {
+    ID: string;
+    Name: string;
+    Stories: number[];
+}
+export interface Polygon {
+    shape?: number[];
+}
+export interface Door {
+    Elevation: number;
+    Height: number;
+    ID: string;
+    Open: boolean;
+    Polygon?: Polygon;
+    Width: number;
+}
+export interface Column {
+    ID: string;
+    Elevation: number;
+    Height: number;
+    Polygon?: Polygon;
+}
+export interface Space {
+    CeilingHeight: number;
+    GroundHeight: number;
+    ID: string;
+    Name: string;
+    Polygon?: Polygon;
+}
+export interface Staircase {
+    Elevation: number;
+    ID: string;
+    Polyline: number[];
+    Spaces: number[];
+}
+export interface Story {
+    Columns?: any[];
+    Doors?: number[];
+    Elevation?: number;
+    Facilities?: any[];
+    FloorIndex?: any;
+    Height?: number;
+    ID?: string;
+    Name?: string;
+    Polygon?: Polygon;
+    Spaces?: number[];
+    Staircases?: number[];
+    Walls?: number[];
+    Windows?: number[];
+}
+export interface Wall {
+    Doors: any[];
+    Elevation: number;
+    Height: number;
+    ID: string;
+    Polygon?: Polygon;
+    Spaces: number[];
+    SubPolygons?: any;
+    VirtualWall: boolean;
+    Windows: any[];
+}
+export interface Window {
+    Elevation: number;
+    Height: number;
+    ID: string;
+    Open: boolean;
+    Polygon?: Polygon;
+    Width: number;
+}
+export interface Asset {
+    Generator: string;
+    GplUUID?: any;
+    Unit: string;
+    Version: string;
+    UBuilder?: any;
+}
+export interface SemanticObject {
+    Buildings?: Building[];
+    Doors?: Door[];
+    Spaces?: Space[];
+    Staircases?: Staircase[];
+    Stories?: Story[];
+    Walls?: Wall[];
+    Windows?: Window[];
+    Columns?: Column[];
+    Asset?: Asset;
+}

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

@@ -0,0 +1,25 @@
+import type { BufferGeometry, Color, Matrix4, Vector3, Vector4 } from 'three/webgpu';
+export type SemanticKind = 'WALL' | 'COLUMN' | 'SPACE' | 'Doors' | 'Windows';
+export type SemanticColor = Color | Vector3 | Vector4;
+export interface SemanticGeometryEntry {
+    id: string;
+    kind: SemanticKind;
+    name?: string;
+    geometry: BufferGeometry;
+    color: Vector4;
+}
+export interface SemanticObjectState {
+    id: string;
+    kind: SemanticKind;
+    name?: string;
+    index: number;
+    baseMatrix: Matrix4;
+    matrix: Matrix4;
+    finalMatrix: Matrix4;
+    geometry: BufferGeometry;
+    color: Vector4;
+    visible: boolean;
+}
+export interface ReadableAttribute {
+    getComponent(index: number, component: number): number;
+}

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

@@ -28,7 +28,7 @@ export interface ITreeData {
     sid: string;
     name: string;
     path: string | null;
-    renderType: 'GROUP' | '3D' | 'STUB' | 'POLYGON' | 'CIRCLE' | 'WATER_SURFACE' | 'DECAL' | 'AREA' | 'FLOOR' | 'ROOM' | 'GS';
+    renderType: 'GROUP' | '3D' | 'STUB' | 'POLYGON' | 'CIRCLE' | 'WATER_SURFACE' | 'DECAL' | 'AREA' | 'FLOOR' | 'ROOM' | 'DOOR' | 'STAIRCASE' | 'ELEVATOR' | 'VENT' | 'WINDOW' | 'GS';
     deviceCode: string | null;
     matrix: number[];
     familyId: string | null;

package/dist/src/effects/TSLEffects.d.ts

@@ -1,4 +1,4 @@
-import { type ColorRepresentation } from 'three';
+import { type ColorRepresentation } from 'three/webgpu';
 export declare class TSLEffects {
     static flow(parameters?: {
         baseColor?: ColorRepresentation;

package/dist/src/loaders/ModelLoaderManager.d.ts

@@ -13,7 +13,7 @@ export interface LoadParameters {
 }
 export declare class ModelLoaderManager {
     private static CACHE_NAME;
-    static fileLoader: FileLoader;
+    static fileLoader: FileLoader<string | ArrayBuffer>;
     static dracoLoader: DRACOLoader;
     static ktx2Loader: KTX2Loader;
     static gltfLoader: GLTFLoader;

package/dist/src/loaders/TextureLoaderManager.d.ts

@@ -5,7 +5,7 @@ export declare class TextureLoaderManager {
     static hdrLoader: HDRLoader;
     static cubeTextureLoader: CubeTextureLoader;
     static setLoadingManager(loadingManager: LoadingManager): void;
-    static loadAsyncTexture(url: string): Promise<import("three").Texture<HTMLImageElement>>;
+    static loadAsyncTexture(url: string): Promise<import("three").Texture<HTMLImageElement, import("three").TextureEventMap>>;
     static loadAsyncHDR(url: string): Promise<import("three").DataTexture>;
     static loadAsyncCubeTexture(path: string, urls: string[]): Promise<import("three").CubeTexture<unknown>>;
 }

package/dist/src/viewers/Viewer.d.ts

@@ -72,7 +72,7 @@ declare class Viewer extends EventDispatcher<ViewerEventMap> {
     render(frame?: number): Promise<void>;
     private animate;
     private _initRenderer;
-    createScene(): Scene;
+    createScene(): Scene<import("three").Object3DEventMap>;
     createPerspectiveCamera(): PerspectiveCamera;
     createOrthographicCamera(): OrthographicCamera;
     /**

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

@@ -1,9 +1,117 @@
 # u-manager
 
-`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性和相机视点。
+`u-manager` 是一套全面的加载器和解析器，用于从服务器路径流式传输、解密并显示结构化场景数据。支持场景、拓扑、动画、属性、相机视点和楼层语义模型。
 
 所有加载器均继承自 Three.js 的 `Loader`，并提供 `setPath(path)` 方法，在调用 `loadAsync()` 前配置基础数据目录。
 
+## `SemanticLoader`
+
+加载 `db/semantic_model.json` 楼层语义数据，并按建筑返回 `BuildingGroup[]`。每个建筑包含多个 `FloorMesh`，每个楼层把墙、柱、空间等语义对象合并为一个 TSL 材质驱动的网格。
+
+```typescript
+import { Vector3, Vector4 } from 'three';
+import { SemanticLoader } from 'u-space/plugins/u-manager';
+
+const loader = new SemanticLoader(viewer);
+loader.setPath('./scenes/my-scene');
+
+const buildings = await loader.loadAsync(); // BuildingGroup[]
+viewer.scene.add(...buildings);
+
+const building = buildings[0];
+const floor = building.getFloorAt(0);
+
+building.isolateFloor(floor);
+await viewer.controls.flyToObject(floor);
+
+floor.addEventListener('click', ({ event }) => {
+  const { target, intersect } = event;
+  const index = intersect.semanticIndex;
+
+  target.setColorAt(index, new Vector4(1, 0, 0, 0.5));
+  target.setScaleAt(index, new Vector3(1, 0.1, 1));
+  viewer.render();
+});
+```
+
+### `BuildingGroup`
+
+`BuildingGroup` 继承自 `BaseGroup`，用于组织一个建筑下的所有楼层。
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `floorMeshes` | 当前建筑内的 `FloorMesh[]`。 |
+| `addFloor(floor)` | 添加楼层，并同步加入 group。 |
+| `removeFloor(floor)` | 移除楼层，并同步从 group 移除。 |
+| `getFloorAt(index)` | 按楼层下标获取 `FloorMesh`。 |
+| `isolateFloor(floor \| index)` | 只显示指定楼层，隐藏其他楼层。 |
+| `showAllFloors()` | 显示全部楼层。 |
+| `planishFloors()` | 将所有楼层整体压扁。 |
+| `unplanishFloors()` | 恢复所有楼层整体缩放。 |
+
+### `FloorMesh`
+
+`FloorMesh` 继承自 `BaseMesh`，表示一个楼层。它不是 `BatchedMesh`，而是把同一楼层内的语义对象合并为一份几何，并通过 TSL + `DataTexture` 在 GPU 侧按 `semanticIndex` 控制颜色、透明度、显示隐藏和实例矩阵。
+
+这种结构的目标是让每个楼层通常只占一个主渲染 draw call，同时仍保留实例级控制能力。`xxxAt` 方法全部作用于单个语义实例；没有 `At` 后缀的方法作用于整个楼层 mesh。
+
+| 属性 / 方法 | 说明 |
+| :---------- | :--- |
+| `semanticCount` / `instanceCount` | 当前楼层语义实例数量。 |
+| `semanticInstances` | `Map<string, number>`，从语义对象 ID 映射到实例下标。 |
+| `wallsInstances` / `columnsInstances` / `spacesInstances` / `doorsInstances` / `windowsInstances` | 按语义类型维护的 ID 到实例下标映射。 |
+| `getSemanticIndexById(id)` | 根据语义 ID 获取实例下标。 |
+| `getSemanticIdAt(index)` | 获取实例语义 ID。 |
+| `getSemanticKindAt(index)` | 获取实例类型：`'WALL' \| 'COLUMN' \| 'SPACE' \| 'Doors' \| 'Windows'`。 |
+| `getSemanticNameAt(index)` | 获取实例名称；当前 `SPACE` 会从语义数据的 `Name` 写入，其他类型可能为 `undefined`。 |
+| `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`。 |
+| `getFinalMatrixAt(index, target?)` | 读取实例最终矩阵，包含语义对象原始基点矩阵。 |
+| `getBoundingBoxAt(index, target?, world?)` | 获取实例包围盒；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
+| `getBoundingSphereAt(index, target?, world?)` | 获取实例包围球；`world = true` 时包含 `FloorMesh.matrixWorld`。 |
+| `computeBoundingBox()` / `computeBoundingSphere()` | 计算整个楼层的包围体。 |
+| `planish()` / `unplanish()` | 压扁或恢复整个楼层 mesh。 |
+
+### 飞向语义实例
+
+点击、射线检测命中 `FloorMesh` 时，`intersect` 上会附加语义字段：`semanticIndex`、`semanticId`、`semanticKind`。可以直接用 `getBoundingBoxAt()` 获取实例的世界包围盒，然后让相机飞向该实例。
+
+```typescript
+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);
+
+  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()` 会缩放整个 `FloorMesh`，适合展示楼层整体。`setScaleAt()` 只缩放单个语义实例，并保留该语义对象自己的基点矩阵，因此压扁墙、柱、房间时不会被压到世界原点。
+
 ## `SceneLoader`
 
 从服务端场景包加载完整场景树（模型、组、形状、拉伸区域），并自动将所有已加载对象按 `id` 和 `sid` 注册到 `viewer.objectManager`。

package/docs/changelog.md

@@ -1,5 +1,12 @@
 # 更新日志
 
+## 0.0.12
+
+### 新增
+
+- **u-manager semantics** — 新增 `SemanticLoader`、`BuildingGroup`、`FloorMesh` 语义楼层 API，支持楼层隔离、实例级颜色/透明度/显隐/matrix/scale 控制，以及实例包围盒/包围球查询。
+- **u-space MCP** — 内置文档索引同步语义楼层 API，MCP 客户端可检索 `SemanticLoader`、`BuildingGroup` 和 `FloorMesh` 用法。
+
 ## 0.0.8
 
 ### 新增

package/docs/index.md

@@ -52,9 +52,15 @@ 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) | 天空/大气渲染（开发中） |
 | [object-controls](./api-plugin-object-controls) | 交互式移动、旋转、缩放 3D 对象 |
 | [topology-drawer](./api-plugin-topology-drawer) | 在场景任意表面交互式绘制拓扑路径图 |
+
+### MCP
+
+| 文档 | 说明 |
+| :--- | :--- |
+| [u-space MCP](./mcp) | 面向 Mastra、Claude Desktop、Cursor 等 MCP 客户端的只读文档检索服务器 |

package/docs/mcp.md

@@ -0,0 +1,96 @@
+# 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。
+
+## 安装与启动
+
+推荐通过 `npx` 使用已发布的 npm 包：
+
+```json
+{
+  "mcpServers": {
+    "uSpace": {
+      "command": "npx",
+      "args": ["-y", "u-space-mcp@latest"]
+    }
+  }
+}
+```
+
+本地开发文档时，可以通过 `--docs` 指向仓库里的 docs 目录：
+
+```json
+{
+  "mcpServers": {
+    "uSpace": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "u-space-mcp@latest",
+        "--docs",
+        "/Users/jiangqi/Desktop/xunwei/SoonSpace/u-space/docs"
+      ]
+    }
+  }
+}
+```
+
+也可以使用环境变量：
+
+```bash
+U_SPACE_DOCS_PATH=/path/to/u-space/docs npx -y u-space-mcp@latest
+```
+
+## Mastra 接入
+
+在 Mastra 中通过 `MCPClient` 使用 stdio 形式接入：
+
+```typescript
+import { MCPClient } from '@mastra/mcp';
+
+export const uSpaceMcpClient = new MCPClient({
+  id: 'u-space-mcp-client',
+  servers: {
+    uSpace: {
+      command: 'npx',
+      args: ['-y', 'u-space-mcp@latest'],
+      stderr: 'pipe',
+    },
+  },
+});
+```
+
+然后把工具挂到 Agent 上：
+
+```typescript
+export const codingAgent = new Agent({
+  // ...
+  tools: {
+    ...(await uSpaceMcpClient.listTools()),
+  },
+});
+```
+
+## 工具列表
+
+`u-space-mcp` 只提供只读工具：
+
+| 工具 | 说明 |
+| :--- | :--- |
+| `list_docs` | 列出可用文档页 |
+| `search_docs` | 按关键词、API 名、插件名或概念检索文档 |
+| `get_doc` | 按 path 或 id 读取单篇文档 |
+| `get_api_reference` | 面向 API / 类 / 方法 / 插件的检索 |
+| `find_examples` | 查找示例和用法相关文档 |
+| `get_changelog` | 读取更新日志 |
+
+## 包结构
+
+源码位于 `packages/u-space-mcp`。构建时会从根目录 `docs/*.md` 生成内置文档索引，并编译成可发布的 npm 包：
+
+```bash
+pnpm build:mcp
+pnpm publish:mcp
+```
+
+发布后的包不依赖本机绝对路径；只有在传入 `--docs` 或设置 `U_SPACE_DOCS_PATH` 时，才会读取本地文档目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,6 +29,8 @@
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "docs:deploy": "pnpm docs:build && vercel --prod",
+    "build:mcp": "pnpm --filter u-space-mcp build",
+    "publish:mcp": "npm publish ./packages/u-space-mcp --access public",
     "release": "npm version patch && pnpm build && npm publish --access=public"
   },
   "files": [
@@ -58,10 +60,10 @@
     "vitepress": "^1.6.4"
   },
   "peerDependencies": {
-    "3d-tiles-renderer": "^0.4.19",
-    "@takram/three-geospatial": "^0.6.0",
-    "@types/three": "^0.183.1",
-    "camera-controls": "^3.1.2",
-    "three": "^0.183.1"
+    "3d-tiles-renderer": ">=0.4.27",
+    "@takram/three-geospatial": ">=0.9.1",
+    "@types/three": ">=0.184.1",
+    "camera-controls": ">=3.1.2",
+    "three": ">=0.184.0"
   }
 }