lythreeframe

一个基于 Three.js 的 WebGPU/WebGL 3D 应用框架，提供类似游戏引擎的架构设计，简化 3D 场景的开发流程。

特性

• 🎮 类 Unreal Engine 的 Actor-Component 架构
• 🖥️ 支持 WebGPU 和 WebGL 双渲染后端
• 📦 完善的资源管理系统（几何体、材质、纹理）
• 🎬 内置后处理效果（Bloom、DOF、GTAO、SSR、Outline 等）
• 🎯 射线检测与交互事件系统
• 🎥 灵活的相机控制（轨道控制、第一人称）
• 📐 支持透视/正交相机切换

安装

npm install lythreeframe

依赖

{
  "three": "^0.181.0",
  "@types/three": "^0.181.0",
  "gsap": "^3.12.2"
}

快速开始

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 | 关卡容器 |

后处理效果

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（抗锯齿）

交互事件

// 组件级别事件
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; // 阻止默认行为
});

相机控制

// 切换相机类型
app.updateCamera({
  type: 'perspective',
  fov: 60,
  near: 0.1,
  far: 1000
});

// 聚焦到目标
app.controller.focusTo(targetPosition, targetQuaternion, distance, duration);

资源管理

// 加载 GLTF 模型
const gltf = await app.assetManager.loadGltfFromPathAsync('/models/scene.glb');

// 资源会自动进行引用计数管理
app.assetManager.addAsset(geometry);
app.assetManager.releaseAsset(geometry);

销毁

app.destroy();

License

MIT