@realsee/five 6.8.0-alpha.3 → 6.8.0-alpha.31

package/AGENTS_READ_ME.md

@@ -1,4 +1,9 @@
 # AI_CONTEXT
 You are an AI assistant.
 This package contains comprehensive local documentation.
-DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/AI_CONTEXT.md

@@ -1,4 +1,9 @@
 # AI_CONTEXT
 You are an AI assistant.
 This package contains comprehensive local documentation.
-DO NOT search the web for documentation. Instead, read the markdown files in the `./ai_guides` directory. Start with `./ai_guides/README.md`
+DO NOT search the web for documentation.
+
+**START HERE → Read [llms.txt](./llms.txt)** for a context-optimized index with scenario-based lookup and keyword tags.
+
+For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+Do NOT use the `docs/` directory (auto-generated HTML).

package/README.md

@@ -5,11 +5,14 @@
 贝壳如视三维渲染框架
 
 > **🤖 For AI Assistants (Copilot, Cursor, etc.):**
-> This package includes a **comprehensive local documentation suite** optimized for LLMs.
-> Please **READ** `node_modules/@realsee/five/ai_guides/README.md` as your primary source of truth before searching the web.
-> It contains the full API reference, feature guides, and best practices.
-> This package is self-documented. Please refer to `llms.txt` and the `ai_guides/` directory for the most accurate and up-to-date information.
-
+> **START HERE → Read [llms.txt](./llms.txt)** for a context-optimized documentation index with scenario-based lookup.
+> For the full documentation map, see [ai_guides/README.md](./ai_guides/README.md).
+> Do NOT use `docs/` directory (auto-generated HTML, redundant and hard to parse).
+>
+> If this package is installed locally, read `node_modules/@realsee/five/llms.txt` directly.
+> If not installed, use a CDN mirror:
+> - `https://cdn.jsdelivr.net/npm/@realsee/five@latest/llms.txt`
+> - `https://unpkg.com/@realsee/five@latest/llms.txt`
 ## Introduction
 
 **Five** 是 [贝壳如视(realsee.com)](https://realsee.com) 提供的在浏览器中运行的三维空间渲染 Javascript SDK。基于 [Three.js](https://threejs.org/) 开发，帮助开发者在浏览器中构建高质量的 VR 看房与空间交互应用。
@@ -69,7 +72,8 @@ For comprehensive guides and API references, please refer to the documentation i
 
 **⚠️ Note for AI Agents:**
 
-*   **For a context-optimized index, read [llms.txt](./llms.txt).**
+*   **START HERE → [llms.txt](./llms.txt)** — context-optimized index with scenario → doc mapping and keyword tags.
+*   If you need the full documentation map, read [ai_guides/README.md](ai_guides/README.md).
 
 **Do's (推荐):**
 *   **Do** Read [Intro](ai_guides/intro.md) first to understand the high-level architecture.

package/ai_guides/README.md

@@ -54,14 +54,16 @@
 
 *   [Five](./features/five.md): 核心类 `Five`，管理渲染循环与全局状态。
 *   [Work](./features/work.md): 数据载体，描述三维空间的数据结构 (VR 看房数据)。
+*   [Panorama UV](./features/pano-uv.md): 全景图 UV 与空间方向转换工具。
 *   [Mode](./features/mode.md): 五种核心浏览模式 (Panorama, Floorplan, Topview, Model, Map)。
 *   [State](./features/state.md): 状态管理 (Pose, Mode, PanoIndex)，用于复原场景。
-*   [Coordinate System](./features/coordnate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
+*   [Coordinate System](./features/coordinate-system.md): 坐标系定义 (右手坐标系, Y轴向上)。
 
 ### 3. Data & Resource (数据与资源)
 数据加载与资源管理配置。
 
 *   [Load External Model](./features/load-external-model.md): 加载外部 3D 模型 (GLTF, OBJ 等)。
+*   [Load Progress](./features/load-progress.md): 监控模型与全景图的加载进度 (Loaded/Refined)。
 *   [Multi-Work (Sandbox)](./features/multi-work.md): 多 Work 加载与沙盘场景管理。
 *   [Request Proxy](./features/request-proxy.md): 请求拦截与代理 (CDN 替换、鉴权)。
 *   [Image Options](./features/image-options.md): 图片资源配置 (CDN, 格式, 尺寸)。
@@ -72,6 +74,11 @@
 *   [Pano Tile](./features/pano-tile.md): 全景瓦片渲染机制（高分辨率分片加载）。
 *   [Model](./features/model.md): 内置模型渲染 (Mesh/Geometry)。
 *   [Postprocessing](./features/postprocessing.md): 后处理效果 (Pass, EffectComposer)。
+*   [Flowing Light 2D Pass](./features/flowing-light-2d-pass.md): 屏幕空间流光特效(InstancedMesh 优化)。
+*   [Flowing Light 3D Pass](./features/flowing-light-3d-pass.md): 3D 世界坐标流光特效(InstancedMesh 优化)。
+*   [Gaussian Blur Pass](./features/gaussian-blur-pass.md): 高斯模糊特效。
+*   [Material](./features/material.md): 材质参数配置 (透明度、点云大小、顶点标记)。
+*   [Pano Filter](./features/pano-filter.md): 全景图滤镜 (亮度、对比度、色温调节)。
 *   [Get Screen Pixels](./features/get-screen-pixels.md): 获取屏幕像素 (放大镜/截图)。
 *   [Move Pano Effect](./features/move-pano-effect.md): 全景点位切换的过渡效果。
 *   [Clipper](./features/clipper.md): 模型裁切功能 (房屋剖面)。
@@ -89,16 +96,46 @@
 ### 6. Advanced & Extensions (进阶与扩展)
 复杂配置与功能扩展。
 
-*   [Plugin](./plugin.md): 插件开发指南。
+*   [Plugin](./features/plugin.md): 插件开发指南。
+*   [ViewLayer](./features/view-layer.md): 视图层。
 *   [Parameter](./features/parameter.md): Five 初始化详细参数配置。
 
 ### 7. Meta & Support (其他)
 *   [Support](./support.md): 浏览器兼容性。
 *   [AI Documentation Guidelines](./ai-doc-guidelines.md): AI 文档编写与维护规范 (必读)。
 *   Release Notes: 版本更新记录。
+    *   [6.8](./release_notes/6.8.md)
     *   [6.7](./release_notes/6.7.md)
     *   [6.6](./release_notes/6.6.md)
 
+## Common Scenarios (场景 → 文档速查)
+
+> **Keyword Search Tip:** Each doc in `features/` has a `tags` yaml block at the bottom with Chinese and English keywords. Use these for keyword matching when the scenario table below doesn't cover your need.
+
+| Scenario | Docs | Tags |
+| :--- | :--- | :--- |
+| 点击拾取物体 / Object picking | [Raycast](./features/raycast.md) | click, hit-test, floor-detection, 碰撞检测, 物体选择 |
+| 3D 标签 / HTML overlay on 3D point | [Screen Project](./features/screen-project.md) | label, HUD, tooltip, 坐标转换, 3D转2D |
+| 全景滤镜 / 色温调节 / Color correction | [Pano Filter](./features/pano-filter.md) | warm, cool, brightness, contrast, saturation, 暖色, 冷色, 饱和度 |
+| 加载外部 GLTF/OBJ/FBX 模型 | [Load External Model](./features/load-external-model.md) | gltf, glb, ply, splat, fbx, draco, point-cloud, dispose |
+| 相机巡航 / 自动导览 / Camera fly-through | [Camera Animation](./features/camera-animation.md) | rotate, zoom, auto-tour, 运镜, 旋转, 缩放 |
+| 截图 / 放大镜 / Screen capture | [Get Screen Pixels](./features/get-screen-pixels.md) | magnifier, screenshot, color-picker, 取色器 |
+| 模型裁切 / 房屋剖面 | [Clipper](./features/clipper.md) | clipping-box, section-view, discard, 开盖, 剖面 |
+| 流光特效 / Flowing light effect | [Flowing Light 2D](./features/flowing-light-2d-pass.md), [Flowing Light 3D](./features/flowing-light-3d-pass.md) | 光带, 导航路径, 动态路径, instanced |
+| 模糊特效 / Blur effect | [Gaussian Blur Pass](./features/gaussian-blur-pass.md) | 毛玻璃, 背景虚化, gaussian |
+| 保存/恢复场景状态 | [State](./features/state.md) | snapshot, save, restore, 快照, 场景还原 |
+| 多场景切换 / 沙盘 | [Multi-Work](./features/multi-work.md) | sandbox, 多户型, 拼接, workCode |
+| 请求鉴权 / CDN 替换 | [Request Proxy](./features/request-proxy.md) | authentication, token, url-rewrite, cors, 私有化 |
+| 插件开发 | [Plugin](./features/plugin.md) | lifecycle, extension, baseplugin, 状态管理 |
+| 事件监听 / 拦截默认行为 | [Event](./features/event.md) | preventDefault, waitUntil, on, off, gesture, 回调 |
+| 手势交互 / 自定义拖拽 | [Gesture](./features/gesture.md) | tap, pan, pinch, press, 触摸, 鼠标 |
+| 后处理特效 / 自定义 Shader | [Postprocessing](./features/postprocessing.md) | effect-composer, addPass, edl, 描边, 景深 |
+| 材质 / 透明度 / 点云样式 | [Material](./features/material.md) | opacity, pointcloud, roof, ceiling, 天花板, 顶点标记 |
+| 模式切换 / 全景↔模型↔户型图 | [Mode](./features/mode.md) | panorama, floorplan, mapview, topview, VR |
+| 全景高清瓦片 / 分片加载 | [Pano Tile](./features/pano-tile.md) | LOD, tile, 按需加载, 高清全景 |
+| 图片 CDN / 私有化部署 | [Image Options](./features/image-options.md) | avif, webp, cdn, private-deployment |
+| 加载进度 / 首屏优化 | [Load Progress](./features/load-progress.md) | refined, loaded, loading-bar, 首屏 |
+
 ## Terminology Summary
 
 *   **Work**: 包含全景图、模型、户型数据的 JSON 对象。
@@ -111,3 +148,4 @@
 ```yaml
 tags: [index, readme, guide, map]
 ```
+

package/ai_guides/ai-doc-guidelines.md

@@ -20,11 +20,40 @@
 - **代码缩进**: 强制使用 **两个空格** 缩进。
 - **相对路径**: 内部文档链接必须使用 **相对路径**（如 `./state.md`）。
 - **Schema**: 必须提供 TypeScript Interface 定义，并保留关键字段的注释（JSDoc）。
+    - **精简原则**: 仅展示核心与常用字段，避免列出所有内部或废弃字段。
+- **Configuration**: 对于参数较多的配置项，建议按 **“常用 (Common)”**、**“进阶 (Advanced)”**、**“内部 (Internal)”** 进行分类表格展示，并在内部参数处添加“不建议修改”的警告。
+- **Source Link**: 引用源码文件时，请在 `## Schema` 章节中使用 `> **Definition**: [InterfaceName](../../path/to/source.ts)` 的格式。**支持多个链接**（如 `[Five](...), [EventTypes](...)`），以便完整覆盖相关类型。**必须** 指向 `lib/` 目录下的 `.ts` 文件。构建脚本会自动将其转换为发布包中的 `.d.ts` 链接。
+- **Related**: 文档末尾建议包含 `## Related` 章节，提供相关文档的**相对路径链接**。
+    - **语义化**: 链接文字应准确反映目标文档的主题（如 `[Coordinate System](./coordinate.md)`）。
 - **Metadata**: 结尾必须包含 YAML 格式的 `tags`。
+- **文档拆分与审查**: 单个文档应保持精简。若内容过多需拆分为新专题，**必须**在创建新文件前向用户确认并获得批准，严禁擅自创建新文件。
+
+## 最佳实践 (Best Practices)
+
+### 1. 变量命名语义化 (Semantic Variable Naming)
+在示例代码中，变量名应准确反映其通用性或特定上下文。
+- **Good**: `parentParameter` (暗示可用于 Model, ViewLayer 等多种父级)
+- **Bad**: `modelParam` (若该逻辑同样适用于 ViewLayer，则会误导用户)
+
+### 2. 区分属性与方法 (Property vs Method)
+明确区分“直接访问属性”与“调用方法计算”。
+- 若 API 设计为 Getter (如 `parameter.opacity`)，文档应引导用户直接访问属性，避免混淆使用 `get()` 方法。
+- 对于涉及计算或继承的逻辑 (如 `resolveValue()`)，应显式说明其与直接访问的区别。
+
+### 3. 显式说明默认行为 (Explicit Default Behavior)
+对于有默认值或继承逻辑的方法，务必说明“不传参”时的行为。
+- 例如：`resolveValue()` 不传参时仅计算默认值；传入 `upstream` 时会包含继承逻辑。
 
 ## 标准模板结构 (Standard Template Structure)
 
-新建文档时，请参考独立模板文件：[template.md](./template.md)。
+无论是**新建文档**还是**维护现有文档**，都请参考独立模板文件：[template.md](./template.md)。
+
+- **新建文档**: 直接复制模板内容开始编写。
+- **维护文档**: 在修改现有文档时，请检查其结构是否符合模板要求（如 Schema 的 Definition 引用、Configuration 的分类等）。如果发现结构过时，请顺手将其标准化。
+- **特殊说明 (Special Notes)**:
+    - **模板链接格式 (Template Link Format)**:
+        - 模板(`template.md`)中所有的占位符链接（如 `Definition` 处的 `[InterfaceName](...)` 或 `Related` 处的 `[RelatedConcept](...)`）均使用了**代码块**包裹，以避免构建时因路径不存在而报错。
+        - **AI 操作**: 在编写正式文档时，**必须将其还原为可点击的标准 Markdown 链接**（即去掉反引号），并确保路径指向真实存在的文件。
 
 请严格遵循该模板的结构，以保证文档风格一致性。
 
@@ -56,6 +85,7 @@
     *   如果修改了 API 签名 -> 更新对应的 `Schema` 和 `Examples`。
     *   如果废弃了功能 -> 在文档中添加 `> [!WARNING] Deprecated` 提示。
 3.  **更新索引**: 如果是新功能，确保将其添加到 `ai_guides/README.md` 的合适章节中。
+4.  **同步 llms.txt**: 若新增了文档或修改了文档路径，**必须**同步更新项目根目录下的 `llms.txt`，确保外部索引与 `ai_guides/` 保持一致。
 
 ### 场景 B：API 文档同步 (Sync API Doc)
 定期检查 `ai_guides/api.md` 的完整性：

package/ai_guides/api.md

@@ -64,9 +64,12 @@ interface FiveInitArgs {
   /** Max FPS limit. false = unlimited. Default: false */
   maxFps?: number | false;
 
-  /** Mode transition duration in ms. Default: 800 */
+  /** Mode transition duration in ms. Default: 1000 */
   modeChangeDuration?: number;
 
+  /** Enable mouse wheel zoom. Default: true */
+  enableWheel?: boolean;
+
   /** Initial plugins to load. */
   plugins?: FivePlugin[];
 
@@ -75,17 +78,34 @@ interface FiveInitArgs {
 
   /** Dynamic texture configuration for optimization. */
   textureOptions?: TextureOptions;
+
+  /** Request URL interceptor for auth/CDN. */
+  requestProxy?: (url: string) => string | Promise<string>;
+
+  /** Per-mode configuration (panorama, mapview, floorplan, topview, model). */
+  panorama?: PanoramaConfig;
+  mapview?: MapviewConfig;
+  floorplan?: FloorplanConfig;
+  topview?: TopviewConfig;
+  model?: ModelConfig;
 }
 ```
 
+> 详细的模式配置参数见 [Mode](./features/mode.md#configuration)。
+> 图片加载策略见 [ImageOptions](./features/image-options.md)。
+> 请求代理见 [Request Proxy](./features/request-proxy.md)。
+> 完整初始化参数见 [Five](./features/five.md) 和 [Parameter](./features/parameter.md)。
+
 ## Core Methods
 
 ### `load(work, state?, options?)`
 Loads a "Work" (dataset) into the Five instance.
 
-- **work**: The data object containing scene information (panorama, model, etc.).
+- **work**: The data object (`LooseWork` or `Work`) containing scene information.
 - **state**: Initial state overrides. `"inherit"`, `"initial"`, or a `State` object.
-- **options**: Loading options (e.g., transition duration).
+- **options**: Loading options (e.g., transition duration, `mode: "add" | "replace"`).
+
+> 详见 [Work](./features/work.md) 和 [Multi-Work](./features/multi-work.md)。
 
 ### `appendTo(element, size?)`
 Mounts the Five canvas to a DOM element.
@@ -100,6 +120,8 @@ Updates the current state (position, mode, etc.).
 - **immediately**: If `true`, skips animation.
 - **userAction**: Marks the change as triggered by user interaction.
 
+> 详见 [State](./features/state.md)。
+
 ### `changeMode(mode, state?, options?)`
 Switches the viewing mode (e.g., from `Panorama` to `Model`).
 
@@ -107,11 +129,29 @@ Switches the viewing mode (e.g., from `Panorama` to `Model`).
 - **state**: Target state after mode change.
 - **options**: Animation duration and effect.
 
+> 详见 [Mode](./features/mode.md)。
+
 ### `moveToPano(panoIndex, options?)`
 Moves to a specific panorama spot.
 
 - **panoIndex**: Index of the panorama.
-- **options**: `{ effect?: MovePanoEffect, duration?: number }`.
+- **options**: `{ effect?: MovePanoEffect, duration?: number, effectEasing?: Function }`.
+
+> 详见 [Move Pano Effect](./features/move-pano-effect.md) 和 [Camera Animation](./features/camera-animation.md)。
+
+### `updateCamera(pose, duration, userAction?)`
+Animates the camera to a target pose without changing pano index.
+
+- **pose**: Partial `Pose` object (longitude, latitude, fov, etc.).
+- **duration**: Animation duration in ms.
+- **returns**: `Promise<void>` (rejects if interrupted).
+
+> 详见 [Camera Animation](./features/camera-animation.md)。
+
+### `ready(args?)`
+Returns a Promise that resolves when Five is stable (state synced, model loaded, optionally tiles loaded).
+
+- **args**: `{ tile?: boolean }` — if `tile: true` in Panorama mode, waits for tile loading.
 
 ### `refresh(size?)`
 Resizes the renderer to fit the container or specified size.
@@ -126,18 +166,35 @@ Projects a 3D point to 2D screen coordinates.
 - **testModel**: `boolean` (default `false`). If `true`, checks for occlusion.
 - **returns**: `THREE.Vector2` (Screen Space, px) or `null`.
 
-### `getPixels(x, y, width, height)`
+> 详见 [Screen & Space Projection](./features/screen-project.md)。
+
+### `getPixels(options)`
 Get pixel data from the renderer (e.g. for color picking or magnifier).
 
-- **x, y**: Coordinate of the lower-left corner (Screen Space).
-- **width, height**: Size of the rectangle.
+- **options**: `{ x, y, width, height, pixelRatio?, flipY?, buffer?, skipPanorama?, helperVisible? }`
 - **returns**: `Uint8Array` (RGBA data).
 
+> 详见 [Get Screen Pixels](./features/get-screen-pixels.md)。
+
 ### `intersectRaycaster(raycaster)`
 (On `five.model`) Performs raycasting against the scene models.
 
-- **raycaster**: `THREE.Raycaster`.
-- **returns**: `THREE.Intersection[]`.
+- **raycaster**: `THREE.Raycaster` (supports extended props: `firstHitOnly`, `hitFilter`, `sortByDistance`, `floorIndex`).
+- **returns**: `THREE.Intersection[]` (extended with `tile`, `viewLayer`, `model` fields).
+
+> 详见 [Raycast](./features/raycast.md)。
+
+### `addPass(pass)` / `removePass(pass)`
+Add or remove a post-processing pass to/from the rendering chain.
+
+- **pass**: `FivePass` instance (e.g. `GaussianBlurPass`, `FlowingLight2DPass`).
+
+> 详见 [Postprocessing](./features/postprocessing.md)。
+
+### `updateConfiguration(config)`
+Dynamically update mode configurations after initialization (e.g., panorama, mapview settings).
+
+> 详见 [Mode](./features/mode.md#动态修改配置-update-configuration)。
 
 ### `dispose()`
 Destroys the Five instance and releases resources.
@@ -161,6 +218,8 @@ interface State {
 
 ## Data Structures
 
+> 以下为核心数据结构摘要。完整定义见 [Work](./features/work.md)、[State](./features/state.md)、[Model](./features/model.md)。
+
 ### `Work`
 The main data object containing the scene description.
 
@@ -187,6 +246,16 @@ interface WorkObserver {
   accessibleNodes: number[]; // Indices of reachable points
   images: WorkImage;         // Panorama image URLs
   active: boolean;           // Whether the point is enabled
+
+  // Coordinate Methods
+  getWorldPosition(): THREE.Vector3;
+  getWorldStandingPosition(): THREE.Vector3;
+
+  // UV Conversion Methods
+  vectorToEquirectangularUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector2;
+  equirectangularUvToVector(uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
+  vectorToCubemapUv(vector: THREE.Vector3, uvOrigin?: 'top-left' | 'bottom-left'): [CubeFace, THREE.Vector2];
+  cubemapUvToVector(cubeFace: CubeFace, uv: THREE.Vector2, uvOrigin?: 'top-left' | 'bottom-left'): THREE.Vector3;
 }
 ```
 
@@ -204,10 +273,17 @@ These events follow a standard naming convention and provide typed event objects
 
 | Event Name | Description | Payload |
 | :--- | :--- | :--- |
-| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `{ pointers, event, ... }` |
-| `gesture.pan` | Triggered on pan/drag. | `{ pointers, ... }` |
-| `gesture.pinch` | Triggered on pinch/zoom. | `{ scale, ... }` |
-| `gesture.press` | Triggered on long press. | `{ pointers, ... }` |
+| `gesture.tap` | Triggered on tap/click. Replaces `wantsTapGesture`. | `GestureEvent` |
+| `gesture.dbltap` | Triggered on double tap/click. | `GestureEvent` |
+| `gesture.pan` | Triggered on pan/drag. | `GestureEvent` |
+| `gesture.pinch` | Triggered on pinch/zoom. | `GestureEvent` |
+| `gesture.press` | Triggered on long press. | `GestureEvent` |
+| `gesture.mousewheel` | Triggered on mouse wheel scroll. | `GestureEvent` |
+| `gesture.mousemove` | Triggered on mouse move. | `GestureEvent` |
+| `gesture.momentum` | Triggered on inertia movement after pan. | `GestureEvent` |
+| `gesture.fire` | Triggered when any gesture event fires. | `GestureEvent` |
+
+> 手势事件详解及不同 Mode 下的默认行为见 [Gesture](./features/gesture.md)。
 
 #### State & Mode
 
@@ -217,16 +293,34 @@ These events follow a standard naming convention and provide typed event objects
 | `state.change` | Triggered when state changes (frequent). | `StateEvent` |
 | `camera.update` | Triggered when camera pose updates. | `CameraEvent` |
 
+> 状态管理详见 [State](./features/state.md)，模式切换详见 [Mode](./features/mode.md)。
+
 #### Lifecycle & Resources
 
 | Event Name | Description | Payload |
 | :--- | :--- | :--- |
 | `works.load` | Triggered when work data starts loading. | `WorksEvent` |
+| `works.ready` | Triggered when work data is loaded and controller is ready. | `WorksEvent` |
 | `models.load` | Triggered when models are loaded. | `ModelSceneEvent` |
+| `models.refined` | Triggered when all models finish texture refinement. | `ModelSceneEvent` |
+| `model.load` | Triggered when a single model geometry is loaded. | `ModelEvent` |
+| `model.tileLoad` | Triggered when a 3D tile is loaded. | `ModelTileEvent` |
+| `model.tileUnload` | Triggered when a 3D tile is unloaded. | `ModelTileEvent` |
+| `model.changeShownFloor` | Triggered when floor visibility changes. | `ModelEvent` |
+| `model.error` | Triggered when model loading fails. | `ModelErrorEvent` |
+| `pano.prepare` | Triggered before switching to a new pano. `ExtendableEvent`, supports `waitUntil`. | `PanoPrepareEvent` |
 | `pano.arrived` | Triggered when arrival at a panorama node. | `PanoEvent` |
+| `pano.moving` | Triggered during pano transition animation. | `PanoEvent` |
+| `pano.error` | Triggered when pano loading or movement fails. | `PanoEvent` |
+| `pano.texture.progress` | Triggered when panorama texture loading progresses. | `PanoTextureEvent` |
 | `render` | Triggered after each render frame. | `RenderEvent` |
+| `render.prepare` | Triggered before each render frame. | `RenderEvent` |
 | `error` | Triggered on internal errors. | `Error` |
 
+> 事件系统详解见 [Event](./features/event.md)。手势事件详解见 [Gesture](./features/gesture.md)。
+> `pano.prepare` 的 `waitUntil` / `preventDefault` 用法见 [Event - Event 对象](./features/event.md#event-对象)。
+> 模型生命周期事件见 [Model](./features/model.md#events) 和 [Load Progress](./features/load-progress.md)。
+
 ### Legacy Events (Deprecated)
 
 Older events are still supported for compatibility but should be avoided in new code.

package/ai_guides/features/3dtile.md

@@ -1,122 +1,26 @@
-# 3DTile
+# 3DTile (3D 瓦片)
 
 - **Summary**: Five 用于加载和渲染大规模三维场景的核心模块，支持动态 LOD 调度与流式加载。
-- **Schema**: 通过 Parameter 配置 LOD、显存与并发控制。
-- **Concepts**: LOD, SSE, Cache Management, ViewLayer。
+- **Schema**: 对应 `ParameterTilesetValue` 接口，通过 Parameter 配置 LOD、显存与并发控制。
+- **Concepts**: LOD (细节层级), SSE (屏幕空间误差), Cache Management (显存管理), ViewLayer (视图层)。
+- **Configuration**: 包含画质精度、显存配额、几何误差、并发请求等详细参数。
 - **Examples**: 画质平衡与多图层优化。
 
 ## Schema
 
-3DTile 的核心配置通过 `Parameter` 系统进行控制。以下是 `ParameterValue` 接口中与 3DTile 调度相关的关键字段。
+> **Definition**: [ParameterTilesetValue](../../five/model/parameter.d.ts)
+
+以下是 `ParameterTilesetValue` 的 TypeScript 定义摘要：
 
 ```typescript
-interface Tile3DParameterValue {
-  // --- 核心画质控制 ---
-  /**
-   * 屏幕空间误差阈值 (Screen Space Error, SSE)
-   * 单位: 像素
-   * 默认值: 16
-   * 说明: 控制加载精度的核心参数。
-   * - 值越小: 画质越高，加载更精细的瓦片，网络/渲染压力越大。
-   * - 值越大: 画质越低，性能越好。
-   */
+export interface ParameterTilesetValue {
+  /** 屏幕空间误差阈值 (像素) */
   maxScreenSpaceError: number;
-
-  // --- 显存与内存管理 ---
-  /**
-   * 最大显存占用
-   * 单位: MB
-   * 默认值: 512
-   * 说明: 当已加载瓦片的显存占用超过此阈值时，引擎会自动卸载不可见或低优先级的瓦片。
-   */
+  /** 最大显存占用 (MB) */
   maxMemoryUsage: number;
-
-  /**
-   * 是否开启基于内存的动态 SSE 调整
-   * 默认值: false
-   * 说明: 开启后，引擎会根据当前显存占用情况自动调整 maxScreenSpaceError。
-   * - 目标: 尽量占满 maxMemoryUsage 设定的显存配额。
-   * - 行为: 实际使用的 SSE 会在 1.0 到 maxScreenSpaceError 之间动态变化。
-   */
-  memoryAdjustedScreenSpaceError: boolean;
-
-  // --- 几何误差控制 ---
-  /**
-   * 最小几何误差 (精度上限锁)
-   * 默认值: 0
-   * 说明: 当瓦片的几何误差小于此值时，强制停止细分。
-   * - 作用: 限制加载的最精细层级，防止过度细分。
-   * - 场景: 数据本身层级过深，或者不需要看清极微小细节时，调大此值可显著节省性能。
-   */
+  /** 最小几何误差 (精度上限锁) */
   minGeometricError: number;
-
-  /**
-   * 最大几何误差 (最低精度保证)
-   * 默认值: 10000
-   * 说明: 当瓦片的几何误差大于此值时，强制继续细分，直到误差小于此值。
-   * - 作用: 设定模型允许的最粗糙程度。
-   * - 场景: 无论相机距离多远，都希望模型至少保持一定的精细度（例如不希望看到过于简化的多边形）时，调小此值。
-   */
-  maxGeometricError: number;
-
-  // --- LOD 层级控制 (不推荐) ---
-  /**
-   * 最小 LOD 层级
-   * 默认值: 0
-   * 说明: 限制加载的最小层级深度 (Tree Depth)。即小于此层级的瓦片（更粗糙的）不会被显示。
-   * - 建议: 推荐优先使用 maxGeometricError。两者都用于控制模型显示的“最粗糙”程度（下限）。
-   */
-  minLevelOfDetail: number;
-
-  /**
-   * 最大 LOD 层级
-   * 默认值: 20
-   * 说明: 限制加载的最大层级深度 (Tree Depth)。即大于此层级的瓦片（更精细的）不会被加载。
-   * - 建议: 推荐优先使用 minGeometricError。两者都用于控制模型显示的“最精细”程度（上限）。
-   */
-  maxLevelOfDetail: number;
-
-  // --- 剔除策略 ---
-  /**
-   * 视锥体剔除
-   * 默认值: true
-   * 说明: 是否不加载/渲染相机视锥体之外的瓦片。
-   */
-  cameraCulling: boolean;
-
-  /**
-   * 是否预加载兄弟节点
-   * 默认值: true
-   * 说明: 是否在加载当前瓦片时，同时预加载其兄弟节点（同一层级的其他瓦片）。
-   */
-  loadSiblings: boolean;
-  /**
-   * 是否允许跳级加载
-   * 默认值: false
-   * 说明: 是否在加载当前瓦片时，允许跳级加载。
-   * - 作用: 在快速移动视角或直接跳转到深层级位置时，跳过中间层级的瓦片，直接加载目标精度的瓦片。
-   * - 场景: 倾斜摄影等外表面模型，为了减少请求数并加快最终形态的呈现（可能会看到明显的从空白到精细的跳变）。
-   */
-  skipLevelOfDetail: boolean;
-
-  // --- 网络并发控制 ---
-  /**
-   * 最大并发请求数
-   * 范围: 0 - 20
-   * 默认值: 4
-   * 说明: 同时进行的最大网络下载请求数。建议保持默认，过大可能阻塞主线程或导致拥堵。
-   */
-  maxRequests: number;
-
-  /**
-   * 请求优先级策略
-   * 默认值: 'SCREEN_SPACE_ERROR'
-   * 选项:
-   * - 'SCREEN_SPACE_ERROR': 优先加载 SSE 最大的瓦片 (最影响视觉质量的部分)。
-   * - 'SCREEN_LEVEL_VERTICAL': 优先加载垂直方向层级较高的瓦片 (通常用于多楼层建筑，优先加载当前楼层)。
-   * - 'SCREEN_VERTICAL': 优先加载屏幕垂直方向的瓦片。
-   */
-  requestOrder: 'SCREEN_SPACE_ERROR' | 'SCREEN_LEVEL_VERTICAL' | 'SCREEN_VERTICAL';
+  // ... 更多字段见下方配置表
 }
 ```
 
@@ -143,49 +47,53 @@ LOD (Level of Detail) 是 3DTile 的核心机制。引擎不会一次性加载
     *   **范围**: 实际 SSE 会在 `1.0` (极高画质) 到 `maxScreenSpaceError` (设定底线) 之间波动。
     *   **场景**: 适合显存充足但希望自动平衡画质的场景。
 
-### 3. 并发控制 (Max Requests)
+### 3. ViewLayer 与 3DTile
 
-为了平衡网络加载与渲染性能，3DTile 限制了最大并发请求数。
-
-*   **默认值**: 4
-*   **建议**: 保持默认值，避免设置过大导致网络拥堵。
-*   **影响**: 增加并发数可能提升加载速度，但也会增加服务器压力。
+目前所有的 `ViewLayer` 在底层都是一个 `Tile3D` 实例。它们各自拥有独立的：
+*   **配置**: `maxScreenSpaceError`, `maxMemoryUsage` 等参数互不干扰。
+*   **缓存**: 显存配额各自独立计算。
 
-### 4. 格式支持 (Supported Formats)
+> **注意**: 即使是通过 `file_url` 加载的单体模型（如 `.obj`, `.at3d`），在 Five 内部也会被封装为 `Tile3D` 实例进行统一管理。
 
-Five 的 3DTile 引擎支持多种 3D Tiles 1.0/1.1 规范的瓦片格式及主流压缩标准。
+## Configuration
 
-*   **瓦片格式**:
-    *   **B3DM (Batched 3D Model)**: 传统的 3D Tiles 格式，用于建筑模型。
-    *   **PNTS (Point Cloud)**: 传统的点云格式。
-    *   **GLB / GLTF**: 3D Tiles 1.1 标准推荐的格式，支持 Mesh 和点云。
-*   **压缩与优化**:
-    *   **[Draco](https://google.github.io/draco/)**: 几何压缩，显著减小模型体积。
-    *   **[Meshopt](https://github.com/zeux/meshoptimizer)**: 另一种高效的几何压缩算法。
-    *   **[KTX2](https://github.com/KhronosGroup/KTX-Software) / [BasisU](https://github.com/BinomialLLC/basis_universal)**: 纹理压缩，大幅降低显存占用并提升上传速度。
+以下表格列出了控制 3DTile 加载与性能调度的所有可用参数。
 
-### 5. ViewLayer 与 3DTile
+### Core Quality & Performance (核心画质与性能)
 
-目前所有的 `ViewLayer` 在底层都是一个 `Tile3D` 实例。它们各自拥有独立的：
-*   **配置**: `maxScreenSpaceError`, `maxMemoryUsage` 等参数互不干扰。
-*   **缓存**: 显存配额各自独立计算。
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxScreenSpaceError` | `number` | `16` | **核心参数**。屏幕空间误差阈值 (像素)。<br>值越小画质越高，性能开销越大。建议范围 8-32。 |
+| `maxMemoryUsage` | `number` | `512` | 最大显存占用 (MB)。超限后自动触发 LRU 淘汰机制。 |
+| `memoryAdjustedScreenSpaceError` | `boolean` | `false` | 是否开启基于内存的动态 SSE 调整。<br>开启后引擎会自动调整 SSE 以尽量占满显存配额。 |
+| `cameraCulling` | `boolean` | `true` | 是否开启视锥体剔除 (不加载视野外的瓦片)。**建议始终开启**。 |
 
-> **注意**: 即使是通过 `file_url` 加载的单体模型（如 `.obj`, `.at3d`），在 Five 内部也会被封装为 `Tile3D` 实例进行统一管理。
+### Geometric Error Control (几何误差控制)
 
-### 6. Lod 参数调整
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minGeometricError` | `number` | `0` | 最小几何误差 (精度上限锁)。<br>当瓦片误差小于此值时停止细分。可用于限制过高精度的加载。 |
+| `maxGeometricError` | `number` | `10000` | 最大几何误差 (最低精度保证)。<br>强制细分直到误差小于此值。可用于避免模型过于模糊。 |
 
-优先修改 `maxScreenSpaceError` 而不是 `minLevelOfDetail` `maxGeometricError`。 SSE 是更直接、更符合渲染逻辑的 LOD 控制指标，而 `minLevelOfDetail` `maxGeometricError` 更关注数据切片方式，容易引入错误的 LOD 决策。
+### Network & Loading (网络与加载)
 
-可以适当开启 `memoryAdjustedScreenSpaceError` 动态调整 SSE，以平衡画质与显存占用。但是同时，需要合理配置 `maxScreenSpaceError` 与 `maxMemoryUsage`，避免出现内存整体占用过高导致 Crash 问题。
-- `maxScreenSpaceError` 尽量设置较为大的值，比如 32 / 48，根据场景和设备性能调整。
-- `maxMemoryUsage` 建议根据设备显存和场景复杂度调整。
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxRequests` | `number` | `4` | 最大并发请求数。建议保持默认，避免网络拥堵。 |
+| `requestOrder` | `string` | `'SCREEN_SPACE_ERROR'` | 请求优先级策略。<br>`'SCREEN_SPACE_ERROR'`: 优先加载 SSE 大的瓦片；<br>`'SCREEN_LEVEL_VERTICAL'`: 优先加载垂直层级高的。 |
+| `loadSiblings` | `boolean` | `true` | 是否预加载兄弟节点。 |
+| `skipLevelOfDetail` | `boolean` | `false` | 是否允许跳级加载 (跳过中间层级直接加载高精瓦片)。 |
 
-在特定场景，比如 **全景模式下** 不需要很高清的模型，可以定义上限的 `maxLevelOfDetail` `minGeometricError` 来限制加载层级优化性能。
+### Legacy LOD Control (不推荐)
 
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `minLevelOfDetail` | `number` | `0` | 最小 LOD 层级 (Tree Depth)。建议使用 `maxGeometricError` 替代。 |
+| `maxLevelOfDetail` | `number` | `20` | 最大 LOD 层级 (Tree Depth)。建议使用 `minGeometricError` 替代。 |
 
 ## Examples
 
-### 调整画质与内存平衡
+### 1. Adjusting Quality & Memory (调整画质与内存平衡)
 
 在移动端或性能受限设备上，建议适当降低画质以保证流畅度。
 
@@ -208,7 +116,7 @@ parameter.set('maxMemoryUsage', 1024);
 parameter.reset('maxScreenSpaceError', 'maxMemoryUsage');
 ```
 
-### 多 ViewLayer 优化
+### 2. Multi-ViewLayer Optimization (多 ViewLayer 优化)
 
 在对比查看或多楼层场景中，通常存在多个 `ViewLayer`。为了避免资源竞争，建议对非焦点的 ViewLayer 进行降级处理。
 
@@ -253,12 +161,12 @@ console.log((tileset as any).cacheMemoryUsageInBytes / 1024 / 1024 + ' MB');
 
 ## Related
 
-*   [parameter.md](./parameter.md): 了解参数的继承关系及材质、点云相关配置。
-*   [model.md](./model.md): 了解 Model 和 ViewLayer 的关系。
-*   [work.md](./work.md): 了解 Work 数据结构。
+*   [Parameter](./parameter.md): 了解参数的继承关系及材质、点云相关配置。
+*   [Model](./model.md): 了解 Model 和 ViewLayer 的关系。
+*   [Work](./work.md): 了解 Work 数据结构。
 
 ---
 
 ```yaml
-tags: [3dtile, viewLayer, performance, lod, optimization]
+tags: [大场景, 瓦片, 显存, 画质, 性能优化, 流式加载, 3dtile, viewLayer, performance, lod, optimization, tile-loading, memory, sse, screen-space-error]
 ```