lythreeframe 1.2.62 → 1.2.64

package/README.md

@@ -1,3 +1,162 @@
 # lythreeframe
 
-Three.js 封装
+一个基于 Three.js 的 WebGPU/WebGL 3D 应用框架，提供类似游戏引擎的架构设计，简化 3D 场景的开发流程。
+
+## 特性
+
+- 🎮 类 Unreal Engine 的 Actor-Component 架构
+- 🖥️ 支持 WebGPU 和 WebGL 双渲染后端
+- 📦 完善的资源管理系统（几何体、材质、纹理）
+- 🎬 内置后处理效果（Bloom、DOF、GTAO、SSR、Outline 等）
+- 🎯 射线检测与交互事件系统
+- 🎥 灵活的相机控制（轨道控制、第一人称）
+- 📐 支持透视/正交相机切换
+
+## 安装
+
+```bash
+npm install lythreeframe
+```
+
+## 依赖
+
+```json
+{
+  "three": "^0.180.0",
+  "@types/three": "^0.181.0",
+  "gsap": "^3.12.2"
+}
+```
+
+## 快速开始
+
+```typescript
+import { ThreeJsApp, BoxActor, DirectionalLightActor, AmbientLightActor } from 'lythreeframe';
+
+// 创建应用
+const app = new ThreeJsApp({
+  viewportParam: {
+    elementId: 'canvas-container'
+  }
+});
+
+// 添加光源
+const dirLight = new DirectionalLightActor(app);
+dirLight.setPosition(5, 10, 5);
+app.world.addActor(dirLight);
+
+const ambLight = new AmbientLightActor(app);
+app.world.addActor(ambLight);
+
+// 添加物体
+const box = new BoxActor(app);
+box.setPosition(0, 1, 0);
+app.world.addActor(box);
+```
+
+## 核心架构
+
+### ThreeJsApp
+应用入口，管理整个 3D 应用的生命周期。
+
+### World
+场景管理器，负责 Actor 的添加、移除和 Tick 更新。
+
+### Viewport
+视口管理，处理渲染器创建、窗口缩放和后处理管线。
+
+### Controller
+输入控制器，处理鼠标交互、射线检测和相机控制。
+
+### Actor / Component
+- `Actor`: 场景中的实体对象，包含一个或多个 Component
+- `SceneComponent`: 具有 3D 变换的组件基类
+- `MeshComponent`: 网格渲染组件
+
+## 内置 Actor
+
+| Actor | 说明 |
+|-------|------|
+| `BoxActor` | 立方体 |
+| `PlaneActor` | 平面 |
+| `DirectionalLightActor` | 平行光 |
+| `AmbientLightActor` | 环境光 |
+| `SkyActor` | 天空盒 |
+| `LevelActor` | 关卡容器 |
+
+## 后处理效果
+
+```typescript
+import { ThreeJsApp, PostProcessStepType } from 'lythreeframe';
+
+const app = new ThreeJsApp({
+  viewportParam: { elementId: 'container' },
+  postProcessParam: {
+    steps: [
+      { type: PostProcessStepType.Bloom, enabled: true, param: { threshold: 0.8, strength: 0.5, radius: 0.5 } },
+      { type: PostProcessStepType.FXAA, enabled: true }
+    ]
+  }
+});
+```
+
+支持的后处理效果：
+- Bloom（泛光）
+- DOF（景深）
+- GTAO（环境光遮蔽）
+- SSR（屏幕空间反射）
+- Outline（轮廓描边）
+- FXAA / SMAA（抗锯齿）
+
+## 交互事件
+
+```typescript
+// 组件级别事件
+component.onClickDelegate.add(() => console.log('clicked'));
+component.onHoverBeginDelegate.add(() => console.log('hover begin'));
+
+// Actor 级别事件
+actor.onClickDelegate.add((component) => console.log('actor clicked'));
+
+// 控制器级别事件
+app.controller.onComponentClickDelegate.add((event) => {
+  console.log('component:', event.component);
+  event.handled = true; // 阻止默认行为
+});
+```
+
+## 相机控制
+
+```typescript
+// 切换相机类型
+app.updateCamera({
+  type: 'perspective',
+  fov: 60,
+  near: 0.1,
+  far: 1000
+});
+
+// 聚焦到目标
+app.controller.focusTo(targetPosition, targetQuaternion, distance, duration);
+```
+
+## 资源管理
+
+```typescript
+// 加载 GLTF 模型
+const gltf = await app.assetManager.loadGltfFromPathAsync('/models/scene.glb');
+
+// 资源会自动进行引用计数管理
+app.assetManager.addAsset(geometry);
+app.assetManager.releaseAsset(geometry);
+```
+
+## 销毁
+
+```typescript
+app.destroy();
+```
+
+## License
+
+MIT