createEngine()

创建完整、初始 stopped 的 Engine 3.0 组合根。

签名

function createEngine(options?: CreateEngineOptions): Engine;

选项

名称	类型	默认值	说明
renderer	Omit<WebGLRendererParameters, canvas | context | outputBufferType>	—	原生 renderer 参数；alpha 默认 true，antialias 默认 false，设备 identity 由 Engine 独占。
pixelRatio	number | device | readonly [min, max]	device	固定 DPR、设备 DPR 或设备 DPR 静态保护区间；不根据运行时帧率自动切换。
pipeline	PipelineOptions	—	内部 render targets 的 samples/stencil；samples 默认 0，与 Canvas antialias 独立。
plugins	readonly Plugin[]	—	构造期静态安装并按 identity 去重。

最小用法

const engine = createEngine();

host.append(engine.canvas);
engine.start();

Engine 创建唯一 Canvas/WebGLRenderer、默认 World/View/Camera、Pipeline 与 Pointer。业务不能注入 Canvas/context，也不需要 mount API。

常用字段

名称	签名	说明
canvas	HTMLCanvasElement	Engine 创建并终身持有的唯一 Canvas。
renderer	WebGLRenderer	Engine 创建并直接暴露的原生 renderer。
world / worlds	World / readonly World[]	默认 World 与全部 live World 的只读投影。
camera / view	PerspectiveCamera / RenderView	默认相机和默认全屏 View。
pipeline / pointer	Pipeline / Pointer	渲染计划和鼠标事件控制面。
size / running / disposed	readonly state	尺寸快照、帧循环与终态事实。

常用操作

const entity = engine.createEntity(object3D);
engine.world.root.add(entity);
engine.getEntity(object3D);

const world = engine.createWorld();
engine.destroyWorld(world);

engine.addSystem(System);
engine.setSystemEnabled(System, false);
engine.removeSystem(System);

engine.onEvent(Event, handler);
engine.emitEvent(Event, payload);

engine.start();
engine.stop();
engine.dispose();

所有权

Engine dispose 会释放自己创建的设备、内部 Pipeline 资源、全部 World/Entity/Script/System，以及接纳 Entity 子树的标准 Three.js 资源；其中 userData.shared === true 的标准资源会保留。需要强制释放时，在终态前调用独立 disposeObject3D()。业务创建并借入的额外 Camera 和原生 Pass 由业务释放。

dispose 为同步终态 best-effort：单错原样抛出，多错形成 AggregateError，第二次调用不重试业务 callback。

相关

• createEngine 指南
• Engine 声明
• CreateEngineOptions 声明