createEngine
createEngine(options?) 创建完整且初始 stopped 的 Engine。模块可以在 SSR 环境导入，但调用工厂需要 browser document 与 WebGL。
最小用法
import { createEngine } from '@tripo3d/engine';
const engine = createEngine();
document.querySelector('#viewer')!.append(engine.canvas);
engine.start();Engine 自己创建 Canvas，业务只负责把 engine.canvas 放进 DOM。Core 不提供 mount/unmount/remount/onMount。
选项
const engine = createEngine({
renderer: {
alpha: true,
antialias: false,
},
pixelRatio: [1, 2],
pipeline: {
// 可选：显式开启离屏 MSAA；默认保持 0。
samples: 0,
stencil: false,
},
plugins: [myPlugin],
});| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
renderer | Omit<WebGLRendererParameters, canvas | context | outputBufferType> | — | 传给原生 WebGLRenderer。alpha 默认 true，antialias 默认 false；三个设备 identity 字段由 Engine 独占。 |
pixelRatio | number | device | readonly [min, max] | device | 固定 DPR、设备 DPR 或设备 DPR 静态保护区间。 |
pipeline | PipelineOptions | — | 私有 Composer render target 的 samples 与 stencil 能力；samples 默认 0，与 renderer.antialias 独立。 |
plugins | readonly Plugin[] | — | 仅构造期按顺序安装；按 identity 去重。 |
所有普通参数与 Plugin shape 都在取得原生资源前校验。Plugin setup、浏览器资源或初始 resize 任一步失败时，构造会终结已取得 owner 并抛出首因；不会返回半可用 Engine。
默认对象
createEngine() 会创建：
engine.canvas与engine.renderer；engine.world，其根是与原生Scene一一对应的 Entity；engine.camera：PerspectiveCamera(45, 1, 0.01, 1000)，位置z = 3；engine.view：绑定默认 World/Camera 的全屏 RenderView；engine.pipeline与engine.pointer。
只有默认 View 的 viewport 或 Canvas 尺寸变化会自动更新默认 Camera aspect。业务 View 的 Camera 由业务维护投影和 world matrix。
启停与尺寸
engine.start();
console.log(engine.running, engine.size);
engine.stop(); // 不释放场景或 GPU 资源
engine.start(); // 重新测量 Canvas，resume 首帧 delta = 0start() 幂等，stop() 也幂等。ResizeObserver 在 Engine 生命周期内持续观察 Canvas；即使 stopped，尺寸变化仍可提交。start 会再主动测量一次，覆盖 detached/hidden 期间遗漏的变化。
DPR 策略：
- 数字：固定 DPR；
'device'：跟随设备 DPR；[min, max]：跟随设备 DPR，但将其限制在静态区间内。
Engine 不采样帧率，也不会因为模型导入或其他运行时掉帧自动修改 DPR。只有 Canvas 逻辑尺寸或真实设备 DPR 变化才会进入 resize transaction。
Engine 控制面
| 名称 | 签名 | 说明 |
|---|---|---|
createEntity / getEntity | (root?) => Entity / (object) => Entity | undefined | 全量接纳 parentless raw subtree，或反查一一 binding。 |
createWorld / destroyWorld | (root?) => World / (world) => boolean | 创建或销毁额外 World；默认 World 不能单独销毁。 |
addSystem / getSystem / removeSystem | Definition identity based | 管理 Engine-global System owner。 |
onEvent / onceEvent / emitEvent | EngineEvent token based | 同步类型化事件。 |
start / stop | () => void | 控制唯一 frame loop。 |
dispose | () => void | 发布不可逆终态并尽力释放全部 Engine owner。 |
dispose
try {
engine.dispose();
} catch (error) {
// 一个清理错误保持原 identity；多个错误为 AggregateError。
}dispose 先停止观察与帧循环，并让公开 topology 不再可见；随后清理 System、Pass、World/Entity/Script、Pointer、Plugin、内部 Composer/Pass 与 renderer。业务终态回调即使抛错，也不会阻止 sibling owner 与 renderer-last 尝试。
第一次调用即发布 engine.disposed === true。不要把第二次调用当成 recovery：它只保持幂等，不重试业务回调。