createEngine

createEngine(options?) 是 @tripo3d/engine 的唯一入口。调用它返回一个已装配好所有子系统的 Engine 实例,后续通过 engine.mount() / engine.use() / engine.addSystem() 完成其余装配。

最小示例

import { createEngine } from '@tripo3d/engine';

const engine = createEngine();
engine.mount(document.querySelector('#canvas-host')!);

// 停止渲染
// engine.unmount();

// 销毁:释放 GPU 资源 / 事件监听 / 所有 system
// engine.dispose();

完整选项

名称	类型	默认值	说明
camera	EngineCameraOptions	—	相机配置,接受 perspective/orthographic 配置对象或自定义工厂函数。默认透视相机 fov=60
dpr	number | (dpr: number) => number	—	设备像素比。数值直接设置,函数则接收系统 devicePixelRatio 做动态映射
renderer	WebGLRendererParameters	—	传给 THREE.WebGLRenderer 构造函数的参数(antialias、alpha、preserveDrawingBuffer 等)
scene	() => THREE.Scene	—	自定义 Scene 工厂,默认返回空 Scene
plugins	EnginePlugin[]	—	创建时自动安装的插件数组,等价于创建后依次 engine.use(plugin)
systems	SystemDefinition[]	—	创建时自动注册的系统数组,等价于创建后依次 engine.addSystem(def)

相机配置

相机接受三种形态:

1. 透视相机(默认)

createEngine({
  camera: {
    type: 'perspective',
    fov: 45,
    near: 0.01,
    far: 1000,
    position: [4, 3, 6],
    lookAt: [0, 0, 0],
  },
});

名称	类型	默认值	说明
type	'perspective'	—	—
fov	number	60	视场角(度)
near	number	0.1	近平面
far	number	2000	远平面
position	[x, y, z]	—	初始位置
lookAt	[x, y, z]	—	初始朝向目标点

2. 正交相机

createEngine({
  camera: {
    type: 'orthographic',
    size: 5,
    near: -100,
    far: 100,
    position: [0, 0, 10],
  },
});

3. 自定义工厂

需要更复杂相机时,传一个函数——它在 view 初始化时被调用,收到当前视口尺寸,返回 Three.js 相机实例。

import { PerspectiveCamera } from 'three';

createEngine({
  camera: ({ width, height }) => {
    const cam = new PerspectiveCamera(50, width / height, 0.01, 1000);
    cam.position.set(0, 2, 5);
    return cam;
  },
});

Engine 实例 API

字段 / 方法	签名	说明
id	string	自动生成的引擎 id,用于日志/调试
view	EngineView	Three.js scene / camera / renderer 的容器
world	EngineWorld	ECS 世界入口
pipeline	EnginePipeline	渲染管线,管理 stage/pass
pointer	EnginePointer	指针服务
events	EngineEventBus	类型化事件总线
history	CommandHistory	命令式 undo/redo
lifecycle	EngineLifecycle	生命周期总线
plugins	EnginePlugin[]	已安装的插件列表(只读快照)
mount	(target: EngineMountTarget) => void	挂载 canvas 到 DOM,启动 raf 循环
unmount	() => void	停止 raf + 卸载 DOM(可再次 mount)
configureView	(def: EngineViewDefinition) => void	运行时更新视图配置(例如切换相机)
use	(plugin: EnginePlugin) => Engine	安装插件,返回自身以便链式调用
addSystem	(def: SystemDefinition<T>) => T	注册 System 并返回其暴露的实例(同一 def 幂等)
getSystem	(def) => T | undefined	查询已注册 System
hasSystem	(def) => boolean	布尔判断
dispose	() => void	彻底释放所有资源(之后实例不可用)

三类生命周期

• 创建期createEngine(options) 瞬时完成
  • options.plugins 逐个 use()
  • options.systems 逐个 addSystem()
• 挂载期engine.mount(target) 启动渲染
  • view 挂载到 DOM向 target 追加 canvas、overlay
  • pointer 绑定 DOM 事件
  • requestAnimationFrame 启动每帧驱动 lifecycle + pipeline
• 销毁期engine.dispose() 一次性释放
  • plugins 触发 dispose()
  • systems / world / pipeline / history / events 依次 clear
  • view unmount(释放 WebGLRenderer)

常见模式

链式装配

engine.use() 返回自身,addSystem 返回 system 实例——可以写出链式 + 平铺混合:

const engine = createEngine({ camera: { type: 'perspective', fov: 45 } })
  .use(createPluginVue());

const cameraSystem = engine.addSystem(CameraAddonSystem);
const modelSystem = engine.addSystem(ModelWorkbenchSystem);

在 Vue 里挂载

通常不手动调 mount,而是用 <EngineCanvas :engine="engine">——详见 Vue 集成。

<script setup lang="ts">
import { createEngine, EngineCanvas, createPluginVue } from '@tripo3d/engine/vue';
import { shallowRef } from 'vue';

const engine = shallowRef(createEngine().use(createPluginVue()));
</script>

<template>
  <EngineCanvas :engine="engine" auto-dispose />
</template>

mount / unmount 的可复用性

同一 Engine 实例可以 mount → unmount → mount 循环,state 保留。调 dispose() 后实例就废弃了。

相机热切换

运行中切换相机:

import { PerspectiveCamera, OrthographicCamera } from 'three';

function toggleOrtho() {
  engine.configureView({
    camera: () => new OrthographicCamera(-5, 5, 5, -5, 0.01, 100),
  });
}

下一步

• ECS — 在 engine.world 上创建实体与组件
• 插件系统 — 写自定义 Plugin / 使用 createPluginVue
• 渲染管线 — 添加 render pass
• Vue 集成 — <EngineCanvas> 与 useEngine()