API
Babylon Lite API|
createNullEngine

Function createNullEngine

  • Create a null engine — a device-less, surface-less EngineContext that runs the simulation half of Babylon Lite (physics stepping, animation evaluation, onBeforeRender callbacks, transform updates) without any GPU device or canvas.

    This is the Babylon Lite analogue of Babylon.js NullEngine: it lets a scene be driven headlessly on a server (plain Node, Deno, a Web Worker, a CI job) so you can run e.g. a Havok physics simulation and read back body transforms with zero rendering.

    • createSceneContext(engine, { defaultRenderTask: false }) — a scene with no frame-graph render task (so no swapchain / GPU resources are ever built).
    • onBeforeRender(scene, cb) callbacks (physics createHavokWorld registers its step this way).
    • stepScene(engine, scene, deltaMs) to advance one fixed step (replaces the browser requestAnimationFrame loop that startEngine uses).
    • Physics with primitive collider shapes (box/sphere/capsule/cylinder) whose geometry is given explicitly or derived from mesh.boundMin/boundMax.
    • Any rendering: startEngine, renderFrame, captureScreenshot, adding meshes with materials (their deferred GPU builders dereference the absent _device), surfaces, RTTs.
    • Mesh/convex-hull colliders that require node.worldMatrix (needs the render-side world-matrix pass). This is a follow-up.
    • High-precision / floating-origin matrices (they need the F64 allocator that createEngine installs). This is a follow-up.

    Parameters

    Returns EngineContext

    The returned object is deliberately a partial EngineContext: only the fields the device-less simulation/update path reads are populated (_device is intentionally absent). The single localized cast below is the whole cost of not yet splitting EngineContext from its mandatory _device/SurfaceContext members — a larger, separate refactor. Every rendering code path is unreachable on a null engine, so the missing GPU fields are never dereferenced.

    import { createNullEngine, stepScene } from "babylon-lite";
    import { createSceneContext, onBeforeRender } from "babylon-lite";

    const engine = createNullEngine();
    const scene = createSceneContext(engine, { defaultRenderTask: false });

    // e.g. real Havok physics — createHavokWorld registers its step via onBeforeRender
    // const world = createHavokWorld(scene, await HavokPhysics());

    const stepMs = 1000 / 60;
    for (let i = 0; i < 180; i++) stepScene(engine, scene, stepMs); // 3s, no rendering