u-space 0.0.0-alpha.2 → 0.0.2

package/docs/api-viewer.md

@@ -1,8 +1,8 @@
 # Viewer API
 
-The `Viewer` is the core class of `u-space`. It encapsulates the WebGPU Renderer, Scene, Camera, Controls, and various managers into an easy-to-use interface.
+`Viewer` 是 `u-space` 的核心类，它将 WebGPU 渲染器、场景、相机、控制器以及各种管理器封装为一个易用的接口。
 
-## Constructor
+## 构造函数
 
 ```typescript
 new Viewer(options: ViewerOptions)
@@ -10,37 +10,37 @@ new Viewer(options: ViewerOptions)
 
 ### `ViewerOptions`
 
-| Property          | Type                       | Required | Description                                                                                                           |
-| :---------------- | :------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- |
-| `el`              | `HTMLElement`              | Yes      | The DOM element where the WebGPURenderer's canvas will be injected.                                                   |
-| `rendererOptions` | `WebGPURendererParameters` | No       | Options passed directly to the underlying `WebGPURenderer`. By default, it uses high-performance settings for WebGPU. |
-
-## Properties
-
-The `Viewer` instance exposes several core Three.js and `u-space` components.
-
-| Property             | Type                                        | Description                                                                                                             |
-| :------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------- |
-| `el`                 | `HTMLElement`                               | The container element.                                                                                                  |
-| `renderer`           | `WebGPURenderer`                            | The underlying WebGPU renderer instance.                                                                                |
-| `scene`              | `Scene`                                     | The main Three.js scene. Background defaults to `0x000000`.                                                             |
-| `camera`             | `PerspectiveCamera` \| `OrthographicCamera` | The active camera.                                                                                                      |
-| `controls`           | `CameraControls`                            | Camera controls (powered by `camera-controls` library).                                                                 |
-| `renderPipeline`     | `RenderPipeline`                            | Manages post-processing passes and the final render call.                                                               |
-| `timer`              | `Timer`                                     | Three.js `Timer` instance for accurate delta time tracking each frame.                                                  |
-| `roomEnvironment`    | `RoomEnvironment`                           | Provides a default room-like IBL environment map for the scene.                                                         |
-| `info`               | `Info`                                      | Renders renderer diagnostics (draw calls, triangles, etc.) as an overlay.                                               |
-| `viewerHelper`       | `ViewerHelper`                              | Exposes utility helpers (e.g., axes, grid display) for development/debugging.                                           |
-| `interactionManager` | `InteractionManager`                        | Manages pointer events and raycasting on objects.                                                                       |
-| `objectManager`      | `ObjectManager`                             | A utility for registering and retrieving objects by ID or name.                                                         |
-| `frameloop`          | `'always'` \| `'demand'`                    | Sets the rendering mode. Default is `'demand'` (render only when required). Set to `'always'` for continuous rendering. |
-| `frameCount`         | `number`                                    | Internal counter of pending render frames. Incremented by `render()`.                                                   |
-
-## Methods
+| 属性              | 类型                       | 必填 | 说明                                                                                                           |
+| :---------------- | :------------------------- | :--- | :------------------------------------------------------------------------------------------------------------- |
+| `el`              | `HTMLElement`              | 是   | WebGPURenderer 的 canvas 将被注入到此 DOM 元素中。                                                             |
+| `rendererOptions` | `WebGPURendererParameters` | 否   | 直接传递给底层 `WebGPURenderer` 的选项。默认使用 WebGPU 的高性能配置。                                         |
+
+## 属性
+
+`Viewer` 实例暴露了若干核心 Three.js 和 `u-space` 组件。
+
+| 属性                 | 类型                                        | 说明                                                                                                              |
+| :------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
+| `el`                 | `HTMLElement`                               | 容器元素。                                                                                                        |
+| `renderer`           | `WebGPURenderer`                            | 底层 WebGPU 渲染器实例。                                                                                          |
+| `scene`              | `Scene`                                     | 主 Three.js 场景，背景默认为 `0x000000`。                                                                         |
+| `camera`             | `PerspectiveCamera` \| `OrthographicCamera` | 当前激活的相机。                                                                                                  |
+| `controls`           | `CameraControls`                            | 相机控制器（基于 `camera-controls` 库）。                                                                         |
+| `renderPipeline`     | `RenderPipeline`                            | 管理后处理通道和最终渲染调用。                                                                                    |
+| `timer`              | `Timer`                                     | Three.js `Timer` 实例，用于每帧精确的 delta time 跟踪。                                                           |
+| `roomEnvironment`    | `RoomEnvironment`                           | 为场景提供默认的类室内 IBL 环境贴图。                                                                             |
+| `info`               | `Info`                                      | 以叠加层的形式渲染渲染器诊断信息（绘制调用次数、三角面数量等）。                                                   |
+| `viewerHelper`       | `ViewerHelper`                              | 提供实用辅助工具（如坐标轴、网格显示），用于开发/调试。                                                           |
+| `interactionManager` | `InteractionManager`                        | 管理对象的指针事件和射线检测。                                                                                    |
+| `objectManager`      | `ObjectManager`                             | 用于按 ID 或名称注册和检索对象的工具。                                                                            |
+| `frameloop`          | `'always'` \| `'demand'`                    | 设置渲染模式。默认为 `'demand'`（仅在需要时渲染）。设置为 `'always'` 可开启持续渲染。                             |
+| `frameCount`         | `number`                                    | 待渲染帧的内部计数器，调用 `render()` 时递增。                                                                    |
+
+## 方法
 
 ### `init()`
 
-Initializes the renderer asynchronously. This must be called if you need to ensure the renderer (like setting up environments or plugins) is fully ready.
+异步初始化渲染器。如果需要确保渲染器（如环境设置或插件）完全就绪，必须调用此方法。
 
 ```typescript
 await viewer.init();
@@ -48,18 +48,18 @@ await viewer.init();
 
 ### `render(frame?: number)`
 
-Requests a render frame. In `'demand'` frameloop mode, this must be called whenever the scene changes visually to update the canvas. `frame` specifies how many frames to render (default `1`). Returns a `Promise<void>` that resolves after the frame is rendered.
+请求渲染一帧。在 `'demand'` 模式下，每当场景发生视觉变化时必须调用此方法来更新画布。`frame` 指定渲染的帧数（默认 `1`）。返回一个在帧渲染完成后 resolve 的 `Promise<void>`。
 
 ```typescript
 viewer.render();
 
-// Await the rendered frame
+// 等待帧渲染完成
 await viewer.render();
 ```
 
 ### `setCamera(camera: PerspectiveCamera | OrthographicCamera)`
 
-Sets a custom camera for the viewer and automatically updates the controls and interaction manager to use it.
+为查看器设置自定义相机，并自动更新控制器和交互管理器以使用该相机。
 
 ```typescript
 const customCamera = new PerspectiveCamera(75, width / height, 0.1, 1000);
@@ -68,7 +68,7 @@ viewer.setCamera(customCamera);
 
 ### `setCameraByType(type: 'perspective' | 'orthographic')`
 
-Convenience method to switch the camera type while maintaining the viewer context.
+便捷方法，在保持查看器上下文的同时切换相机类型。
 
 ```typescript
 viewer.setCameraByType('orthographic');
@@ -76,7 +76,7 @@ viewer.setCameraByType('orthographic');
 
 ### `createScene()`
 
-Creates and returns a new `Scene` with a black background. Called internally by the constructor but can be used to reset/replace the scene.
+创建并返回一个黑色背景的新 `Scene`。由构造函数内部调用，也可用于重置/替换场景。
 
 ```typescript
 viewer.scene = viewer.createScene();
@@ -84,7 +84,7 @@ viewer.scene = viewer.createScene();
 
 ### `createPerspectiveCamera()`
 
-Creates a `PerspectiveCamera` with sensible defaults (50° fov, near `0.1`, far `1e5`, positioned at `(5, 5, 5)`).
+使用合理的默认值创建 `PerspectiveCamera`（视角 50°，近裁 `0.1`，远裁 `1e5`，位置在 `(5, 5, 5)`）。
 
 ```typescript
 const camera = viewer.createPerspectiveCamera();
@@ -93,7 +93,7 @@ viewer.setCamera(camera);
 
 ### `createOrthographicCamera()`
 
-Creates an `OrthographicCamera` sized to the container element, near `0.1`, far `1e5`, positioned at `(5, 5, 5)`.
+创建与容器元素等大的 `OrthographicCamera`，近裁 `0.1`，远裁 `1e5`，位置在 `(5, 5, 5)`。
 
 ```typescript
 const camera = viewer.createOrthographicCamera();
@@ -102,18 +102,18 @@ viewer.setCamera(camera);
 
 ### `dispose()`
 
-Cleans up the viewer, removing the canvas from the DOM, removing event listeners, and disposing of the renderer and environment maps to prevent memory leaks.
+清理查看器，从 DOM 中移除 canvas，移除事件监听，并释放渲染器和环境贴图，以防止内存泄漏。
 
 ```typescript
 viewer.dispose();
 ```
 
-## Events
+## 事件
 
-The viewer extends `EventDispatcher` and fires the following events:
+Viewer 继承自 `EventDispatcher`，会触发以下事件：
 
-- `beforeControlsUpdate`: Fired before `CameraControls` update. Emitter provides `{ time: number }`.
-- `afterControlsUpdate`: Fired after `CameraControls` update. Emitter provides `{ time: number }`.
-- `beforeRender`: Fired immediately before `renderer.render` is called. Emitter provides `{ time: number }`.
-- `afterRender`: Fired immediately after `renderer.render` completes. Emitter provides `{ time: number }`.
-- `cameraChange`: Fired when `setCamera` is called. Emitter provides `{ camera: Camera }`.
+- `beforeControlsUpdate`：在 `CameraControls` 更新之前触发，提供 `{ time: number }`。
+- `afterControlsUpdate`：在 `CameraControls` 更新之后触发，提供 `{ time: number }`。
+- `beforeRender`：在 `renderer.render` 调用之前立即触发，提供 `{ time: number }`。
+- `afterRender`：在 `renderer.render` 完成之后立即触发，提供 `{ time: number }`。
+- `cameraChange`：调用 `setCamera` 时触发，提供 `{ camera: Camera }`。

package/docs/examples-guide.md

@@ -1,48 +1,48 @@
-# Examples Guide
+# 示例指南
 
-`u-space` contains an extensive `examples/` directory that demonstrates the engine's capabilities. Below are a few key examples and what they teach you about the system.
+`u-space` 的 `examples/` 目录中包含了大量演示引擎功能的示例。以下是几个关键示例及其所展示的系统特性。
 
-## 1. `demo01.html`: Basic Setup & Interactivity
+## 1. `demo01.html`：基础配置与交互
 
-This example demonstrates the absolute bare-minimum setup required to get a 3D scene rendering via WebGPU, as covered in the [Getting Started](./getting-started.md) guide.
+该示例演示了通过 WebGPU 渲染 3D 场景所需的最少配置，与 [快速上手](./getting-started.md) 指南中的内容一致。
 
-### Key Takeaways:
+### 核心要点：
 
-- Injecting the `Viewer` into a DOM element.
-- Setting the scene background using WebGPU `Color`.
-- Adding primitive geometries (like `BoxGeometry`).
-- Enabling global interaction via `viewer.interactionManager.pointerMoveEventsEnabled`.
-- Attaching DOM-style event listeners (`click`, `pointerenter`, `pointerleave`) natively to 3D meshes.
+- 将 `Viewer` 注入 DOM 元素。
+- 使用 WebGPU `Color` 设置场景背景。
+- 添加基础几何体（如 `BoxGeometry`）。
+- 通过 `viewer.interactionManager.pointerMoveEventsEnabled` 启用全局交互。
+- 像操作 DOM 元素一样，为 3D 网格原生绑定事件监听（`click`、`pointerenter`、`pointerleave`）。
 
-## 2. `test_loader.html`: Model Caching Mechanics
+## 2. `test_loader.html`：模型缓存机制
 
-This example dives deep into the `u-space` Model Loader pipeline and explains the differences between runtime cache and browser persistent cache.
+该示例深入解析了 `u-space` 的模型加载管线，阐明运行时缓存与浏览器持久化缓存之间的区别。
 
-### Key Takeaways:
+### 核心要点：
 
-- Utilizing the global `Model` class to load `.glb` files asynchronously via `Model.prototype.loadAsync()`.
-- Demystifying `cache: true` (which retains the model node in RAM for instant cloning/instantiation).
-- Demystifying `persistent: true` (which uses the Service Worker / Cache Storage API to cache the actual network request bytes).
-- Demonstrates how to register these loaded asynchronous assets into the `viewer.objectManager` securely.
-- Provides examples on programmatically flushing the caches using `Model.clearMemoryCache()` and `Model.clearPersistentCache()`.
+- 使用全局 `Model` 类通过 `Model.prototype.loadAsync()` 异步加载 `.glb` 文件。
+- 理解 `cache: true`（将模型节点保留在内存中，可实现即时克隆/实例化）。
+- 理解 `persistent: true`（使用 Service Worker / Cache Storage API 对实际网络请求数据进行持久化缓存）。
+- 演示如何将这些异步加载的资源安全地注册到 `viewer.objectManager`。
+- 提供通过 `Model.clearMemoryCache()` 和 `Model.clearPersistentCache()` 手动清除缓存的示例。
 
-## 3. `load_tiles.html`: GIS & Earth Rendering
+## 3. `load_tiles.html`：GIS 与地球渲染
 
-This example uses the external `3d-tiles-renderer` peer dependency securely wrapped by a `u-space` plugin to render massive level-of-detail GIS globes.
+该示例使用外部对等依赖 `3d-tiles-renderer`，通过 `u-space` 插件安全封装后，渲染大规模 LOD GIS 地球。
 
-### Key Takeaways:
+### 核心要点：
 
-- Instantiating complex plugins (`ArcgisTilesRenderer`) dynamically passing the core viewer reference.
-- Using `viewer.frameloop = 'always'` since tiles stream asynchronously and continuously update the viewport.
-- Fetching specific Longitude and Latitude positions using the plugin's `invalidate(lon, lat, zoom)` method.
+- 动态实例化复杂插件（`ArcgisTilesRenderer`），并传入核心 viewer 引用。
+- 由于瓦片是异步流式加载并持续更新视口的，需使用 `viewer.frameloop = 'always'`。
+- 通过插件的 `invalidate(lon, lat, zoom)` 方法定位到指定的经纬度位置。
 
-## 4. `test_umanager.html`: Scene Compositions & Parsers
+## 4. `test_umanager.html`：场景组合与解析器
 
-This robust example combines multiple tools, illustrating how to build complete applications instead of just placing single models.
+该综合示例融合了多种工具，展示如何构建完整的应用程序，而不仅仅是放置单个模型。
 
-### Key Takeaways:
+### 核心要点：
 
-- Initializing multiple Plugins concurrently (minimap, tracking, keyboard-controls) and toggling their state via `.enable()` / `.disable()`.
-- Streaming structured scene layouts, parsing scene descriptions (`SceneLoader`, `TopologiesLoader`).
-- Working with camera animations (`VisionsLoader` and `VisionsParser`) to choreograph pre-defined flight paths securely within the scene.
-- Retrieving complex Node materials and customizing WebGPU specific TSL (Three Shading Language) nodes like `TSLEffects.fluid()`.
+- 同时初始化多个插件（minimap、tracking、keyboard-controls），并通过 `.enable()` / `.disable()` 切换其状态。
+- 流式传输结构化场景布局，解析场景描述（`SceneLoader`、`TopologiesLoader`）。
+- 使用相机动画（`VisionsLoader` 和 `VisionsParser`）在场景中编排预定义的飞行路径。
+- 获取复杂的节点材质，并自定义 WebGPU 专属的 TSL（Three Shading Language）节点，如 `TSLEffects.fluid()`。

package/docs/getting-started.md

@@ -1,26 +1,26 @@
-# Getting Started with `u-space`
+# 快速上手 `u-space`
 
-`u-space` is a WebGPU-ready 3D engine built on top of Three.js. This guide will show you how to set up a basic `u-space` application.
+`u-space` 是一个基于 Three.js 的 WebGPU 3D 引擎。本指南将向你展示如何搭建一个基础的 `u-space` 应用。
 
-## Installation
+## 安装
 
-Ensure you have `@types/three` and `three` installed as peer dependencies. If you plan to use interactions, you might also need `camera-controls`.
+确保已将 `@types/three` 和 `three` 安装为对等依赖。如果你计划使用交互功能，还需要安装 `camera-controls`。
 
 ```bash
 pnpm install three camera-controls
 ```
 
-## Basic Setup
+## 基础配置
 
-Here is a minimal example of setting up a `u-space` `Viewer` and adding an interactive object to the scene.
+以下是一个最小示例，展示如何初始化 `u-space` 的 `Viewer` 并向场景中添加一个可交互对象。
 
-### 1. HTML Structure
+### 1. HTML 结构
 
-Create an element to house your 3D viewer.
+创建一个容纳 3D 查看器的元素。
 
 ```html
 <!DOCTYPE html>
-<html lang="en">
+<html lang="zh">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -28,14 +28,14 @@ Create an element to house your 3D viewer.
   </head>
   <body style="margin: 0">
     <div id="app" style="width: 100vw; height: 100vh"></div>
-    <!-- Script goes here -->
+    <!-- 脚本放这里 -->
   </body>
 </html>
 ```
 
 ### 2. Import Maps
 
-Since `u-space` relies on Three.js WebGPU features, it's recommended to set up an import map to resolve the WebGPU build of Three.js.
+由于 `u-space` 依赖 Three.js 的 WebGPU 特性，建议配置 Import Map 以解析 Three.js 的 WebGPU 构建版本。
 
 ```html
 <script type="importmap">
@@ -51,9 +51,9 @@ Since `u-space` relies on Three.js WebGPU features, it's recommended to set up a
 </script>
 ```
 
-### 3. Initialize Viewer & Add Objects
+### 3. 初始化 Viewer 并添加对象
 
-Now, initialize the `Viewer` and add a basic Three.js object to the scene.
+初始化 `Viewer` 并向场景中添加一个基础 Three.js 对象。
 
 ```html
 <script type="module">
@@ -62,48 +62,49 @@ Now, initialize the `Viewer` and add a basic Three.js object to the scene.
 
   const app = document.getElementById('app');
 
-  // Initialize the viewer
+  // 初始化查看器
   const viewer = new Viewer({
     el: app,
-    rendererOptions: { forceWebGL: false }, // Prefer WebGPU
+    rendererOptions: { forceWebGL: false }, // 优先使用 WebGPU
   });
+  await viewer.init();
 
-  // Set background color
+  // 设置背景颜色
   viewer.scene.background = new Color(0x666666);
 
-  // Add a grid
+  // 添加网格辅助线
   const gridHelper = new GridHelper(10, 10);
   viewer.scene.add(gridHelper);
 
-  // Add a Box
+  // 添加一个立方体
   const geometry = new BoxGeometry(1, 1, 1);
   const material = new MeshBasicMaterial({ color: 0xff0000 });
   const box = new Mesh(geometry, material);
   box.position.set(0, 0.5, 0);
   viewer.scene.add(box);
 
-  // Render the scene
+  // 渲染场景
   viewer.render();
 </script>
 ```
 
-### 4. Enable Interactions
+### 4. 启用交互
 
-`u-space` has a built-in `InteractionManager`. You can easily add event listeners to your 3D objects.
+`u-space` 内置了 `InteractionManager`，可以轻松为 3D 对象添加事件监听。
 
 ```javascript
-// Enable pointer move events
+// 启用指针移动事件
 viewer.interactionManager.targetObjects = [];
 viewer.interactionManager.pointerMoveEventsEnabled = true;
 
-// Add click event
+// 添加点击事件
 box.addEventListener('click', (e) => {
-  console.log('Clicked at:', e.event.intersect.point);
+  console.log('点击位置：', e.event.intersect.point);
   material.color.set(Math.random() * 0xffffff);
-  viewer.render(); // Request a new frame
+  viewer.render(); // 请求新一帧渲染
 });
 
-// Add hover events
+// 添加悬停事件
 box.addEventListener('pointerenter', (e) => {
   document.body.style.cursor = 'pointer';
   material.color.set(0x00ff00);
@@ -117,15 +118,15 @@ box.addEventListener('pointerleave', (e) => {
 });
 ```
 
-And that's it! You now have a basic `u-space` application up and running.
+这样就完成了！你现在拥有一个基础的 `u-space` 应用。
 
-## Next Steps
+## 下一步
 
-- Learn more about the [Viewer API](./api-viewer.md)
-- Explore how to [load Models and work with Objects](./api-objects.md)
-- Understand the [Interaction System](./api-interactions.md)
-- Register and retrieve objects with the [Managers API](./api-managers.md)
-- Add tile maps, minimap, keyboard controls and more with the [Plugins API](./api-plugins.md)
-- Animate properties with the [Animations API](./api-animations.md)
-- Apply visual effects with the [Effects API](./api-effects.md)
-- Browse the [Examples Guide](./examples-guide.md)
+- 深入了解 [Viewer API](./api-viewer.md)
+- 探索如何 [加载模型与使用对象](./api-objects.md)
+- 理解 [交互系统](./api-interactions.md)
+- 使用 [Managers API](./api-managers.md) 注册和检索对象
+- 通过 [Plugins API](./api-plugins.md) 添加瓦片地图、小地图、键盘控制等功能
+- 使用 [Animations API](./api-animations.md) 为属性添加动画
+- 使用 [Effects API](./api-effects.md) 应用视觉特效
+- 浏览 [示例指南](./examples-guide.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-space",
-  "version": "0.0.0-alpha.2",
+  "version": "0.0.2",
   "type": "module",
   "types": "dist/src/index.d.ts",
   "module": "dist/index.js",
@@ -28,7 +28,8 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "docs:deploy": "pnpm docs:build && vercel --prod"
+    "docs:deploy": "pnpm docs:build && vercel --prod",
+    "release": "npm publish --access=public"
   },
   "files": [
     "dist",
@@ -63,4 +64,4 @@
     "camera-controls": "^3.1.2",
     "three": "^0.183.1"
   }
-}
+}