u-space 0.0.16 → 0.0.18

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

@@ -1,7 +1,27 @@
-import { Box3, Matrix4, Sphere, Vector3, Vector4, type Intersection, type Raycaster } from 'three/webgpu';
-import { BaseMesh } from 'u-space';
+import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type Intersection, type Raycaster } from 'three/webgpu';
+import { BaseMesh, type InteractionEvent, type InteractionEventMap } from 'u-space';
 import type { SemanticColor, SemanticGeometryEntry, SemanticKind } from './types';
-export declare class FloorMesh extends BaseMesh {
+type FloorMeshEventPayload<T> = T extends {
+    event: InteractionEvent;
+} ? {
+    event: FloorMeshInteractionEvent;
+} : T;
+export interface FloorMeshIntersection extends Intersection<FloorMesh> {
+    semanticId: string;
+    semanticKind: SemanticKind;
+    semanticName?: string;
+    semanticIndex: number;
+    instanceId: number;
+}
+export type FloorMeshInteractionEvent = Omit<InteractionEvent, 'target' | 'currentTarget' | 'intersect'> & {
+    readonly target: FloorMesh;
+    currentTarget: FloorMesh;
+    readonly intersect: FloorMeshIntersection | null;
+};
+export type FloorMeshEventMap = {
+    [K in keyof InteractionEventMap]: FloorMeshEventPayload<InteractionEventMap[K]>;
+};
+export declare class FloorMesh extends BaseMesh<BufferGeometry, MeshStandardNodeMaterial, FloorMeshEventMap> {
     #private;
     isFloorMergedSemanticMesh: boolean;
     type: string;
@@ -40,3 +60,4 @@ export declare class FloorMesh extends BaseMesh {
     raycast(raycaster: Raycaster, intersects: Intersection[]): boolean | void;
     dispose(): void;
 }
+export {};

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

@@ -13,6 +13,10 @@ export interface SSGIConfig {
     thickness?: number;
 }
 export type OutputNodeComposer = (scenePass: PassNode) => Node;
+export type OutputNodeEffect = ((scenePass: PassNode, inputNode: Node) => Node) & {
+    includesTemporalAntialias?: boolean;
+    includesOutputTransform?: boolean;
+};
 type Args = [ConstructorParameters<typeof RenderPipelineBase>[0], Scene, Camera];
 export declare class RenderPipeline extends RenderPipelineBase {
     #private;
@@ -31,6 +35,10 @@ export declare class RenderPipeline extends RenderPipelineBase {
     /** @deprecated Use `setOutputComposer(null)` instead */
     resetCurrentOutputNode(): void;
     setOutputComposer(composer: OutputNodeComposer | null): void;
+    addOutputEffect(effect: OutputNodeEffect): this;
+    removeOutputEffect(effect: OutputNodeEffect): this;
+    addMRTChannel(name: string, node: Node): this;
+    removeMRTChannel(name: string): this;
     enableBloom(config?: BloomConfig): void;
     disableBloom(): void;
     updateBloom(config: Partial<BloomConfig>): void;

package/docs/api-objects.md

@@ -12,6 +12,8 @@
 
 | 属性                         | 类型      | 默认值 | 说明                                                           |
 | :--------------------------- | :-------- | :----- | :------------------------------------------------------------- |
+| `castShadow`                 | `boolean` | `true` | 默认参与阴影投射；可在单个对象上改为 `false`。                 |
+| `receiveShadow`              | `boolean` | `true` | 默认接收阴影；可在不需要阴影的网格上改为 `false`。             |
 | `ignoreInvisibleWhenRaycast` | `boolean` | `true` | 为 `true` 时，不可见的网格在射线检测时会被跳过（不参与碰撞）。 |
 
 ### `BaseGroup`

package/docs/api-plugin-atmosphere.md

@@ -1,10 +1,102 @@
 # atmosphere
 
-天空和大气渲染插件。目前为占位实现，`enable()` / `disable()` / `dispose()` 方法可用，但尚未实现具体功能。
+天空和大气渲染插件，基于 `@takram/three-atmosphere` 的 WebGPU 节点实现。启用后会接入 Viewer 的 `renderer.contextNode`、`scene.backgroundNode` 和 RenderPipeline 的 output effect/MRT 扩展点，提供天空背景、太阳光、aerial perspective 大气透视、lens flare、tone mapping 和 temporal antialias。
 
 ```typescript
 import { Atmosphere } from 'u-space/plugins/atmosphere';
 
 const atmosphere = new Atmosphere(viewer);
-atmosphere.enable();
+atmosphere.enable({
+  longitude: 120.002269,
+  latitude: 30.284849,
+  height: 4,
+});
 ```
+
+## API
+
+### `new Atmosphere(viewer)`
+
+创建大气插件实例。
+
+### `enable(options?)`
+
+开启大气效果。重复调用时等同于 `update(options)`。
+
+```typescript
+atmosphere.enable({
+  longitude: 120.002269,
+  latitude: 30.284849,
+  height: 4,
+  date: new Date(),
+  showSun: true,
+  showMoon: true,
+  showStars: true,
+});
+```
+
+### `update(options?)`
+
+更新大气参数，不会重新创建插件实例。
+
+```typescript
+atmosphere.update({
+  date: new Date('2026-06-16T12:00:00+08:00'),
+  showStars: false,
+});
+```
+
+### `setLocation(longitude, latitude, height?)`
+
+更新场景本地原点对应的 WGS84 经纬高。`longitude`、`latitude` 使用角度，`height` 使用米。
+
+### `setDate(date)`
+
+更新太阳和月亮方向。`date` 支持 `Date` 或时间戳。
+
+### `disable()`
+
+关闭大气效果并恢复启用前的 `backgroundNode`、`environmentNode` 和 `renderer.contextNode`。
+
+### `dispose()`
+
+释放插件资源，等同于 `disable()`。
+
+## Options
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `longitude` | `number` | `0` | 本地场景原点的经度，单位为度 |
+| `latitude` | `number` | `0` | 本地场景原点的纬度，单位为度 |
+| `height` | `number` | `0` | 本地场景原点高度，单位为米 |
+| `date` | `Date \| number` | 当天本地时间 08:00 | 用于计算太阳和月亮方向 |
+| `showSun` | `boolean` | `true` | 显示太阳 |
+| `showMoon` | `boolean` | `true` | 显示月亮 |
+| `showStars` | `boolean` | `true` | 显示星空 |
+| `showGround` | `boolean` | `false` | 是否渲染大气地面 |
+| `useSkyEnvironment` | `boolean` | `true` | 是否使用天空节点作为 `scene.environmentNode` |
+| `raymarchScattering` | `boolean` | `true` | 是否启用 raymarch scattering |
+| `lighting` | `boolean` | `true` | aerial perspective 是否包含光照 |
+| `transmittance` | `boolean` | `true` | aerial perspective 是否包含透射 |
+| `inscattering` | `boolean` | `true` | aerial perspective 是否包含内散射 |
+| `moonScattering` | `boolean` | `true` | 是否包含月光散射 |
+| `lensFlare` | `boolean` | `true` | 是否在 aerial perspective 后启用 lens flare |
+| `temporalAntialias` | `boolean` | `true` | 是否在大气后处理链中启用 temporal antialias |
+| `dithering` | `boolean` | `true` | 是否在 temporal antialias 后追加 dithering |
+| `toneMapping` | `ToneMapping \| false` | `AgXPunchyToneMapping` | 大气后处理链使用的 tone mapping；设为 `false` 可跳过 |
+| `toneMappingExposure` | `number` | `3` | 大气 tone mapping 曝光值 |
+| `castShadow` | `boolean` | `true` | 是否让大气太阳光投射阴影 |
+| `shadowMapSize` | `number` | `4096` | 阴影贴图尺寸 |
+| `shadowCameraSize` | `number` | `180` | directional shadow 正交相机覆盖范围，越小越清晰但覆盖范围越窄 |
+| `shadowCameraNear` | `number` | `10` | shadow camera near |
+| `shadowCameraFar` | `number` | `6000` | shadow camera far |
+| `shadowBias` | `number` | `-0.00002` | 阴影深度偏移 |
+| `shadowNormalBias` | `number` | `0.001` | 法线方向阴影偏移，用于缓解 shadow acne；过大会让底部阴影产生脱离感 |
+| `shadowRadius` | `number` | `1.5` | PCF 阴影采样半径，用于柔化轻微锯齿 |
+| `shadowDistance` | `number` | `3000` | 大气方向光与 target 的距离 |
+
+## 注意事项
+
+`Atmosphere` 不会占用 `viewer.renderPipeline.setOutputComposer()`。它通过 output effect 追加大气后处理；开启 `temporalAntialias` 时才会注册独立的 `atmosphereVelocity` MRT 通道，并会避免和 RenderPipeline 自带 TRAA 重复运行。业务设置自定义 composer 时，大气 output effect 和它的输出变换开关都会被 RenderPipeline 跳过，让 composer 保持完整接管输出的原语义。
+
+如果看到明显的方形阴影边界，通常是 `shadowCameraSize` 小于当前可见场景范围。可以调大该值，或让相机 target 更贴近需要观察的区域。阴影偏糊时优先减小 `shadowCameraSize` 或增大 `shadowMapSize`；底部阴影有脱离感时优先减小 `shadowNormalBias`；边缘仍有轻微锯齿时可略微增大 `shadowRadius`。

package/docs/api-render-pipeline.md

@@ -7,13 +7,15 @@
 ```
 Stage 1: pass(scene, camera) + MRT（按需配置 output/emissive/normal/velocity）
     ↓
-Stage 2: 后处理链（二选一）
+Stage 2: 后处理链
     ├─ 内置模式: SSGI → Bloom（按启用状态组合）
     └─ 自定义模式: outputComposer(scenePass) → Node
     ↓
-Stage 3: TRAA 时间抗锯齿
+Stage 3: Output Effects（仅默认/内置模式，插件/扩展追加效果）
     ↓
-Stage 4: Overlay Passes（blendColor 叠加 ViewerHelper 等）
+Stage 4: TRAA 时间抗锯齿
+    ↓
+Stage 5: Overlay Passes（blendColor 叠加 ViewerHelper 等）
     ↓
 outputNode = 最终结果
 ```
@@ -88,7 +90,7 @@ viewer.renderPipeline.disableTRAA();
 
 ## 自定义后处理（OutputComposer）
 
-使用 `setOutputComposer` 可完全覆盖内置后处理链，接收 `scenePass` 返回自定义的 TSL 节点。
+使用 `setOutputComposer` 可完全覆盖内置后处理链，接收 `scenePass` 返回自定义的 TSL 节点。自定义 composer 会保持最终输出语义，不再叠加插件注册的 output effects。
 
 ```typescript
 import { luminance, vec4 } from 'three/tsl';
@@ -104,6 +106,20 @@ viewer.renderPipeline.setOutputComposer((scenePass) => {
 viewer.renderPipeline.setOutputComposer(null);
 ```
 
+## Output Effects
+
+插件可使用 `addOutputEffect` 在默认/内置后处理链之后追加效果，而不占用业务侧的 `setOutputComposer()`。如果业务设置了自定义 composer，output effects 会被跳过，由 composer 自己负责完整输出。
+
+```typescript
+const effect = (scenePass, inputNode) => inputNode;
+viewer.renderPipeline.addOutputEffect(effect);
+viewer.renderPipeline.removeOutputEffect(effect);
+```
+
+如果 effect 已经调用了 `renderOutput()`，可设置 `effect.includesOutputTransform = true`，管线只会在该 effect 实际生效时关闭默认输出变换。
+
+如需额外 MRT 输出通道，可用 `addMRTChannel` / `removeMRTChannel` 注册，不会污染核心依赖。
+
 ## Overlay Passes
 
 用于叠加辅助渲染层（如 ViewerHelper），始终在后处理链之后执行。

package/docs/changelog.md

@@ -1,5 +1,17 @@
 # 更新日志
 
+## 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
 
 ### 新增

package/docs/mcp.md

@@ -86,7 +86,7 @@ export const codingAgent = new Agent({
 
 ## 包结构
 
-源码位于 `packages/u-space-mcp`。发布时会先从根目录 `docs/*.md` 生成内置文档索引，并编译成可发布的 npm 包：
+源码位于 `packages/u-space-mcp`。根目录只保留一个 MCP 发布入口；执行时会先从 `docs/*.md` 生成内置文档索引，编译 MCP 包，然后发布到 npm：
 
 ```bash
 pnpm publish:mcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -29,8 +29,7 @@
     "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": "pnpm build:mcp && npm publish ./packages/u-space-mcp --access public --ignore-scripts",
+    "publish:mcp": "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": [