u-space 0.0.0-alpha.1 → 0.0.1

package/README.md

@@ -2,6 +2,8 @@
 
 The library based on three.js with WebGPURenderer.
 
+**[📖 Documentation](https://u-space-phi.vercel.app)**
+
 ## Install
 
 ```bash

package/docs/api-animations.md

@@ -0,0 +1,78 @@
+# Animations API
+
+`u-space` 提供了 `Tween` 类和 `tweenAnimation` 辅助函数，用于对任意数值属性进行动画处理。两者都是对 [`@tweenjs/tween.js`](https://github.com/tweenjs/tween.js) 的轻量封装，并自动与 `Viewer` 渲染循环集成。
+
+## `tweenAnimation`
+
+对任意对象属性执行动画的最简方式，返回一个在动画完成后 resolve 的 `Promise`。
+
+```typescript
+import { tweenAnimation } from 'u-space';
+
+const source = { x: 0, y: 0, z: 0 };
+
+await tweenAnimation(
+  viewer,
+  source,                      // 可变的起始状态（每帧被修改）
+  { x: 10, y: 5, z: 10 },    // 目标状态
+  {
+    duration: 1500,            // 毫秒
+    delay: 0,
+    mode: 'Cubic.InOut',
+    repeat: false,
+    yoyo: false,
+  },
+  (current) => {
+    // 每帧以插值结果调用
+    myObject.position.set(current.x, current.y, current.z);
+  },
+);
+```
+
+### `AnimationOptions`
+
+| 属性       | 类型                        | 默认值          | 说明                                               |
+| :--------- | :-------------------------- | :-------------- | :------------------------------------------------- |
+| `duration` | `number`                    | `1000`          | 动画时长（毫秒）。                                 |
+| `delay`    | `number`                    | `0`             | 开始延迟（毫秒）。                                 |
+| `mode`     | `AnimationModeType`         | `'Linear.None'` | 缓动函数。                                         |
+| `repeat`   | `number \| boolean`         | `false`         | 额外重复次数，或 `true` 表示无限循环。             |
+| `yoyo`     | `boolean`                   | `false`         | 在每个循环周期反向播放。                           |
+
+### `AnimationModeType`
+
+支持所有标准缓动模式：
+
+`Linear.None` · `Quadratic.In/Out/InOut` · `Cubic.In/Out/InOut` · `Quartic.In/Out/InOut` · `Quintic.In/Out/InOut` · `Sinusoidal.In/Out/InOut` · `Exponential.In/Out/InOut` · `Circular.In/Out/InOut` · `Elastic.In/Out/InOut` · `Back.In/Out/InOut` · `Bounce.In/Out/InOut`
+
+## `Tween`
+
+提供完全控制的底层类。继承自 `tween.js` 的基础 `Tween`，并通过 `addEventListener('afterControlsUpdate', ...)` 挂入 `Viewer` 事件循环。
+
+```typescript
+import { Tween } from 'u-space';
+
+const source = { opacity: 1 };
+
+const tween = new Tween(viewer, source)
+  .to({ opacity: 0 }, 800)
+  .easingByMode('Sinusoidal.Out')
+  .onUpdate((s) => {
+    myMaterial.opacity = s.opacity;
+    viewer.render();
+  })
+  .onComplete(() => console.log('完成'));
+
+tween.start();
+// tween.stop();
+```
+
+### 方法
+
+| 方法                      | 说明                                                            |
+| :------------------------ | :-------------------------------------------------------------- |
+| `easingByMode(mode)`      | 使用 `AnimationModeType` 设置缓动函数的便捷简写。               |
+| `start(time?)`            | 启动补间并注册到 viewer 循环中。                                |
+| `stop()`                  | 停止补间并从 viewer 循环中注销。                                |
+
+其他方法（`to`、`delay`、`repeat`、`yoyo`、`onUpdate`、`onComplete`、`onStop`、`onStart`）均继承自 `tween.js` 的基础 `Tween` 类。

package/docs/api-effects.md

@@ -0,0 +1,118 @@
+# Effects API
+
+`u-space` 提供了两个基于 Three.js 着色语言（TSL/WebGPU 节点）的静态特效工具：`MaterialEffects` 用于为对象应用高亮状态，`TSLEffects` 用于生成动态颜色节点模式。
+
+## `MaterialEffects`
+
+静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`，会自动遍历所有子网格。
+
+### `MaterialEffects.highlight(object, options?)`
+
+为对象中所有网格应用颜色/透明度高亮。使用 `userData` 和 TSL 节点图，多个对象可共享同一节点图实例，各自保持独立状态。
+
+```typescript
+import { MaterialEffects } from 'u-space';
+
+// 以 50% 透明度高亮为红色
+MaterialEffects.highlight(myModel, {
+  enabled: true,
+  color: 0xff0000,
+  opacity: 0.5,
+  overwrite: false, // false = 叠加（相乘），true = 完全替换颜色
+});
+
+// 禁用高亮
+MaterialEffects.highlight(myModel, { enabled: false });
+```
+
+### `HighlightOptions`
+
+| 属性        | 类型                  | 默认值      | 说明                                                                         |
+| :---------- | :-------------------- | :---------- | :--------------------------------------------------------------------------- |
+| `enabled`   | `boolean`             | `true`      | 启用或禁用高亮特效。                                                         |
+| `color`     | `ColorRepresentation` | `0xff0000`  | 高亮颜色。                                                                   |
+| `opacity`   | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
+| `overwrite` | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
+
+> **注意：** `highlight` 会在所有受影响的网格上设置 `material.transparent = true`，并注入 `colorNode`/`opacityNode`。目前不可逆，若需恢复须手动重置这些节点。
+
+---
+
+## `TSLEffects`
+
+静态工厂类，返回 TSL 颜色节点。将返回值赋给 `NodeMaterial` 的 `material.colorNode` 即可应用动态着色器特效。持续动画需要 `viewer.frameloop = 'always'`。
+
+### `TSLEffects.flow(parameters?)`
+
+沿网格 UV X 轴方向的定向光扫效果，适用于道路、管道和流线。
+
+```typescript
+import { TSLEffects } from 'u-space';
+
+myTubeMesh.material.colorNode = TSLEffects.flow({
+  baseColor: 0x001133,
+  flowColor: 0x00aaff,
+  speed: 1.5,
+  scale: 4.0,
+  intensity: 6.0,
+});
+viewer.frameloop = 'always';
+```
+
+**参数：**
+
+| 属性        | 类型                  | 默认值      | 说明                                              |
+| :---------- | :-------------------- | :---------- | :------------------------------------------------ |
+| `baseColor` | `ColorRepresentation` | `0xffffff`  | 背景/底色。                                       |
+| `flowColor` | `ColorRepresentation` | `0x00ff00`  | 扫光高亮颜色。                                    |
+| `speed`     | `number`              | `1.0`       | 动画速度（越高扫光越快）。                        |
+| `scale`     | `number`              | `3.0`       | 图案的空间频率。                                  |
+| `intensity` | `number`              | `4.0`       | 峰值锐度，值越高光束越细。                        |
+
+### `TSLEffects.breathe(parameters?)`
+
+在两种颜色之间随时间振荡的脉冲发光效果，适合状态指示器和警报。
+
+```typescript
+myMesh.material.colorNode = TSLEffects.breathe({
+  baseColor: 0x333333,
+  breathColor: 0x00ff88,
+  speed: 2.0,
+  intensity: 3.0,
+});
+```
+
+**参数：**
+
+| 属性          | 类型                  | 默认值      | 说明                               |
+| :------------ | :-------------------- | :---------- | :--------------------------------- |
+| `baseColor`   | `ColorRepresentation` | `0xffffff`  | 低/静息状态的颜色。                |
+| `breathColor` | `ColorRepresentation` | `0x00ff00`  | 峰值亮度时的颜色。                 |
+| `speed`       | `number`              | `1.0`       | 振荡速度。                         |
+| `intensity`   | `number`              | `2.0`       | 控制峰值的锐度。                   |
+
+### `TSLEffects.fluid(parameters?)`
+
+噪声扭曲的流动效果，适用于水面、等离子体或有机流动材质。
+
+```typescript
+myPlaneMesh.material.colorNode = TSLEffects.fluid({
+  baseColor: 0x002244,
+  flowColor: 0x0066ff,
+  speed: 0.5,
+  scale: 2.0,
+  intensity: 1.5,
+  distortion: 0.3,
+});
+```
+
+**参数：**
+
+| 属性         | 类型                  | 默认值      | 说明                                          |
+| :----------- | :-------------------- | :---------- | :-------------------------------------------- |
+| `baseColor`  | `ColorRepresentation` | `0xffffff`  | 基础颜色。                                    |
+| `flowColor`  | `ColorRepresentation` | `0x0000ff`  | 流体高亮颜色。                                |
+| `speed`      | `number`              | `1.0`       | 动画速度。                                    |
+| `scale`      | `number`              | `1.0`       | 噪声图案的 UV 缩放比例。                      |
+| `intensity`  | `number`              | `1.0`       | 流体图案的锐度。                              |
+| `distortion` | `number`              | `0.5`       | 采样前噪声对 UV 的扭曲程度。                  |

package/docs/api-interactions.md

@@ -1,64 +1,109 @@
 # Interactions API
 
-The `InteractionManager` provides a unified way to handle user input (mouse, touch, pointer) over 3D scenes. It resolves the raycasting from screen space to world space and dispatches corresponding events directly directly to the intersected 3D objects.
+`InteractionManager` 提供了一种统一的方式来处理 3D 场景中的用户输入（鼠标、触摸、指针）。它将屏幕空间的射线检测转换为世界空间坐标，并将对应事件直接分发到被命中的 3D 对象上。
 
-The `InteractionManager` is automatically instantiated within the `Viewer` at `viewer.interactionManager`.
+`InteractionManager` 在 `Viewer` 内部自动实例化，可通过 `viewer.interactionManager` 访问。
 
-## Enabling Interaction Events
+## 启用交互事件
 
-By default, pointer move events might be disabled for performance reasons. You need to enable them if you want hover and drag effects. This should be explicitly set for interactive applications.
+出于性能考虑，指针移动事件默认可能处于禁用状态。如需悬停和拖拽效果，必须显式开启。
 
 ```typescript
-// Enable events on mouse move (like pointerenter and pointerleave)
+// 启用鼠标移动事件（如 pointerenter 和 pointerleave）
 viewer.interactionManager.pointerMoveEventsEnabled = true;
 ```
 
-### Targeting Objects
+### 目标对象
 
-You can limit which objects the raycaster checks.
+可以限制射线检测所针对的对象范围。
 
 ```typescript
-// Default behavior: checks the entire scene
+// 默认行为：检测整个场景
 viewer.interactionManager.targetObjects = [];
 
-// Check only specific objects
+// 仅检测指定对象
 // viewer.interactionManager.targetObjects = [myBox, myModel];
 ```
 
-## Adding Event Listeners
+## 添加事件监听
 
-Because `u-space` objects (and `BaseMesh`, `BaseGroup` by extension) support custom events, you can attach listeners natively just like a DOM element.
+由于 `u-space` 对象（以及继承自 `BaseMesh`、`BaseGroup` 的对象）支持自定义事件，你可以像操作 DOM 元素一样原生地绑定监听器。
 
 ```typescript
 const myBox = new Mesh(geometry, material);
 viewer.scene.add(myBox);
 
-// Example listener attached directly to the 'Mesh' or 'Model'
+// 直接在 Mesh 或 Model 上绑定监听器
 myBox.addEventListener('click', (eventData) => {
-  // The underlying pointer event and raycast intersection information
+  // 底层指针事件和射线检测数据
   const intersect = eventData.event.intersect;
 
-  console.log('Clicked at position:', intersect.point);
+  console.log('点击位置：', intersect.point);
 });
 ```
 
-## Supported Events
+## 支持的事件类型
 
-The following event types can be listened to on interactive objects:
+以下事件类型可在可交互对象上监听：
 
-- `click`: Fired when the pointer clicks on an object.
-- `dblclick`: Fired when the object is double-clicked rapidly.
-- `pointerdown`: Fired when a pointer button is depressed over an object.
-- `pointerup`: Fired when a pointer button is released, generally following a `pointerdown`.
-- `pointerenter`: Fired when the cursor or pointer enters the boundaries of an object.
-- `pointerleave`: Fired when the cursor or pointer leaves the boundaries of an object.
+- `click`：指针点击对象时触发（过滤：长按或大幅移动后忽略）。
+- `dblclick`：快速双击对象时触发。
+- `contextmenu`：右键点击时触发（阻止默认浏览器上下文菜单）。
+- `pointerdown`：指针按键在对象上按下时触发。
+- `pointerup`：指针按键在对象上释放时触发。
+- `pointermove`：指针在对象上移动时触发，需要 `pointerMoveEventsEnabled = true`。
+- `pointerenter`：光标进入对象范围时触发，需要 `pointerMoveEventsEnabled = true`。
+- `pointerleave`：光标离开对象范围时触发，需要 `pointerMoveEventsEnabled = true`。
 
-### Event Propagation
+### 事件冒泡
 
-To stop an event from continuing to pass through the intersection hierarchy (e.g., clicking on a model inside a larger bounding box), you can stop its propagation using the event payload:
+事件会沿父级链向上冒泡。若要阻止事件继续传播，可调用事件载荷上的 `stopPropagation()`：
 
 ```typescript
 myObject.addEventListener('click', (e) => {
   e.event.stopPropagation();
 });
 ```
+
+## `InteractionEvent`
+
+传递给所有监听回调的事件对象，位于 `event` 键下。
+
+### 属性
+
+| 属性            | 类型                                       | 说明                                                                        |
+| :-------------- | :----------------------------------------- | :-------------------------------------------------------------------------- |
+| `type`          | `InteractionEventType`                     | 事件类型字符串（如 `'click'`）。                                            |
+| `target`        | `Object3D`                                 | 触发事件的原始 3D 对象（第一个命中点）。                                    |
+| `currentTarget` | `Object3D`                                 | 冒泡链中当前处理事件的对象。                                                |
+| `intersect`     | `Intersection \| null`                     | Three.js 射线检测数据：`point`、`face`、`distance`、`uv` 等。               |
+| `originalEvent` | `PointerEvent \| MouseEvent`               | 原始 DOM 指针/鼠标事件。                                                    |
+
+### 方法
+
+#### `stopPropagation()`
+
+阻止事件继续向上冒泡。
+
+## `InteractionManager` API
+
+### 属性
+
+| 属性                       | 类型                          | 默认值  | 说明                                                       |
+| :------------------------- | :---------------------------- | :------ | :--------------------------------------------------------- |
+| `targetObjects`            | `Object3D[] \| null`          | `null`  | 射线检测的目标对象。`null` 表示检测所有场景子对象。        |
+| `pointerMoveEventsEnabled` | `boolean`                     | `false` | 启用 `pointermove`、`pointerenter`、`pointerleave` 事件。  |
+
+### 方法
+
+#### `setCamera(camera)`
+
+更新用于射线检测的相机。由 `viewer.setCamera()` 自动调用。
+
+#### `dispose()`
+
+移除所有 DOM 事件监听，清理内部状态。
+
+```typescript
+viewer.interactionManager.dispose();
+```

package/docs/api-managers.md

@@ -1,35 +1,35 @@
 # Managers API
 
-`u-space` utilizes specialized managers for handling specific domain logic, such as `ObjectManager` for caching and registering 3D objects.
+`u-space` 使用专用管理器来处理特定领域的逻辑，例如用于缓存和注册 3D 对象的 `ObjectManager`。
 
 ## ObjectManager
 
-The `ObjectManager` provides a centralized dictionary/map layer to easily retrieve complex models or specific meshes by string IDs or string names without having to recursively traverse the Three.js scene graph.
+`ObjectManager` 提供了一个集中式字典/映射层，让你无需递归遍历 Three.js 场景图，就能通过字符串 ID 或字符串名称轻松检索复杂模型或特定网格。
 
-The default instance is available via `viewer.objectManager`.
+默认实例可通过 `viewer.objectManager` 访问。
 
-### Adding Objects
+### 添加对象
 
-When you add an object to the manager, you must provide a unique identifier.
+向管理器添加对象时，必须提供唯一标识符。
 
 ```typescript
 const myModel = new Model();
-// ... load logic
+// ... 加载逻辑
 
-// Add with a specific unique ID
+// 用指定的唯一 ID 添加
 viewer.objectManager.add('my-unique-car-id', myModel);
 
-// An object can be registered under multiple IDs
+// 一个对象可以注册多个 ID
 viewer.objectManager.add('player-vehicle', myModel);
 ```
 
-### Retrieving Objects
+### 检索对象
 
-The manager gives you fast access to your objects.
+管理器提供快速访问对象的方法。
 
 #### `getById(id: string)`
 
-Retrieves exactly one object (or `undefined`) matching the specific ID.
+精确检索与指定 ID 匹配的一个对象（或 `undefined`）。
 
 ```typescript
 const car = viewer.objectManager.getById('my-unique-car-id');
@@ -37,10 +37,10 @@ const car = viewer.objectManager.getById('my-unique-car-id');
 
 #### `getByName(name: string)`
 
-Because Three.js objects can share the same `.name` property, this method returns a `Set<Object3D>` encompassing all registered objects that match the requested name.
+由于 Three.js 对象可以共享同一个 `.name` 属性，此方法返回一个 `Set<Object3D>`，包含所有与指定名称匹配的已注册对象。
 
 ```typescript
-// Assuming myModel.name = 'sedan'
+// 假设 myModel.name = 'sedan'
 const sedans = viewer.objectManager.getByName('sedan');
 
 sedans.forEach((vehicle) => {
@@ -48,7 +48,58 @@ sedans.forEach((vehicle) => {
 });
 ```
 
-### Utility Methods
+#### `getByType(type: string)`
 
-- `getAll()`: Returns all tracked objects.
-- `size`: Returns the total number of objects currently tracked by the manager.
+返回一个 `Set<Object3D>`，包含所有 `object.type` 与指定类型匹配的已注册对象。
+
+```typescript
+const models = viewer.objectManager.getByType('Model');
+```
+
+#### `getObjectIds(object: Object3D)`
+
+返回给定对象已注册的所有 ID 的 `Set<string>`。
+
+```typescript
+const ids = viewer.objectManager.getObjectIds(myModel);
+```
+
+### 移除对象
+
+#### `remove(object: Object3D)`
+
+从所有内部映射中移除该对象及其所有关联 ID。
+
+```typescript
+viewer.objectManager.remove(myModel);
+```
+
+#### `removeById(id: string)`
+
+移除注册在指定 ID 下的对象。
+
+```typescript
+viewer.objectManager.removeById('my-unique-car-id');
+```
+
+#### `removeByName(name: string)`
+
+移除所有具有指定 `.name` 的对象。
+
+```typescript
+viewer.objectManager.removeByName('sedan');
+```
+
+#### `removeByType(type: string)`
+
+移除所有具有指定 `.type` 的对象。
+
+```typescript
+viewer.objectManager.removeByType('Model');
+```
+
+### 工具方法
+
+- `getAll()`：返回所有已跟踪对象的 `Set<Object3D>`。
+- `clear()`：从所有内部映射中移除所有对象。
+- `size`：返回当前管理器跟踪的唯一对象总数。