3D engine that AI agents drive
Runtime: a live game loop
crucible/addons/runtime drives a renderer live. Films do not use it: a film renders every frame as a pure function of time and stays deterministic. The runtime is for a browser game, where a player, a script or a network message changes the next frame.
It loads only when imported, adds no dependency, and does not touch the film path.
import { CrucibleRenderer } from 'crucible';
import { createRuntime } from 'crucible/addons/runtime';
const renderer = new CrucibleRenderer(canvas, parts);
const runtime = createRuntime(renderer, {
mode: 'both',
fixedRate: 60,
frame: context => ({ eye: [0, 3, 8], target: [0, 1, 0], time: context.elapsedSeconds }),
systems: [inputSystem, physicsSystem, gameSystem],
});
runtime.start();
A runnable sample is bench/runtime-loop/index.html (npm run dev, then open /bench/runtime-loop/). It switches between the three modes and shows the frame-time readout.
Update modes
mode |
Calls per frame | context.alpha |
|---|---|---|
'fixed' |
fixedUpdate(step) as many times as whole steps fit in the elapsed time |
1 |
'variable' |
update(deltaSeconds) once |
1 |
'both' (default) |
fixedUpdate for the whole steps, then update(deltaSeconds) once |
leftover time divided by the step, from 0 to 1 |
Fixed steps use an accumulator. A frame that takes 25 ms at fixedRate: 100 runs two steps and keeps 5 ms for the next frame. In 'both' mode, draw the state between the last two fixed steps with alpha: drawn = previous + (current - previous) * alpha. That keeps a 20 Hz simulation smooth on a 144 Hz screen.
Two guards stop a slow frame from spiralling. A frame longer than maximumFrameSeconds (default 0.25) counts as that long, and one frame runs at most maximumStepsPerFrame fixed steps (default 8). Time beyond that is dropped and shows up in stats.droppedSeconds.
Options
| Option | Default | Meaning |
|---|---|---|
mode |
'both' |
'fixed', 'variable' or 'both' |
fixedStepSeconds or fixedRate |
1/60 s |
The fixed step, from 1/1000 to 1 s. Pass one of the two. |
maximumFrameSeconds |
0.25 |
Longest frame time the simulation accepts |
maximumStepsPerFrame |
8 |
Cap on fixed steps in one frame, up to 1000 |
systems |
[] |
System objects, in the order they run |
frame |
context => ({ time }) |
Returns the object passed to target.render. Move parts with renderer.updateParts here. |
pauseWhenHidden |
true |
Stop frames while the tab is hidden |
pauseWhenOffscreen |
true |
With element, stop frames while the canvas is scrolled out of view (an IntersectionObserver) |
element |
none | The canvas or its container, watched for pauseWhenOffscreen |
isIdle |
none | context => boolean, true when nothing changed: no system is moving anything and no temporal accumulation is converging. The loop then draws no frame and schedules none, so it costs no GPU and no CPU, until wake(). Without it the loop never sleeps, because a runtime cannot know whether its systems change the picture. |
idleSleep |
true |
false keeps drawing every frame even when isIdle says idle |
scheduler, clock, visibility, observe |
browser | { request(callback), cancel(handle) }, () => milliseconds, { hidden, subscribe(callback) } and (element, callback(onscreen)) => stop, injected by tests and headless runs |
clock must be a function returning milliseconds; leave it out to use performance.now(). A non-function is rejected when the runtime is created, rather than failing on the first frame.
The first argument is any object with render(frame), such as CrucibleRenderer.
Runtime methods
start()initialises the systems once and schedules frames; a system whoseinitthrew is initialised again by the nextstart().stop()ends the loop and drops the partial step; systems stay initialised, sostart()continues the same world.pause()andresume()hold and release the loop. The time spent paused is never simulated. A hidden tab pauses the same way and resumes when it shows again.wake()draws the next frame after input or a state change when the loop sleeps because ofisIdle;sleepingis true while it waits. Call it from your input handlers and whenever a system changes something. A frame that follows a sleep, a hidden tab or an offscreen pause starts with a zero time step, so the sleep is never simulated.step(milliseconds)runs one frame without a scheduler, for tests and for stepping while paused.addSystem(system, index),replaceSystem(name, system),removeSystem(name),getSystem(name)andsystems(the names, in order). A system added to a started runtime is initialised at once; a replaced or removed one is disposed.dispose()stops the loop and disposes every system in reverse order. The runtime cannot start again.statsis the frame-time readout:frames,frameMilliseconds(last),averageFrameMillisecondsandmaximumFrameMilliseconds(last 120 frames),framesPerSecond,updateMillisecondsandrenderMilliseconds(the last frame's split; the renderer call returns when it has submitted its work, so GPU time needs a timer query),fixedSteps,lastFixedSteps,droppedSeconds,alphaandelapsedSeconds.
System interface
Physics (live physics), input (input), player, animation graph, audio and game code plug in as systems. A system is a plain object. Only name is required; leave out any hook it does not need.
const system = {
name: 'physics', // unique string
init(context) {}, // once, when the loop first starts (or when added to a started runtime)
fixedUpdate(step, context) {}, // each fixed step; step is in seconds
update(delta, context) {}, // each frame in 'variable' and 'both' mode; delta is in seconds
dispose(context) {}, // when removed, replaced or the runtime is disposed
};
Rules a system can rely on:
- Systems run in array order for every hook, and dispose in reverse order. Put input first, then physics, animation, audio and game code.
- Hooks run on the page's main thread inside the frame. Keep them short; the cost shows in
stats.updateMilliseconds. - The
contextis one shared object, read only:runtime,target,mode,fixedStepSeconds,deltaSeconds,elapsedSecondsandalpha. Do not keep a copy; read it when needed. - A hook that throws stops the loop and rethrows the error with the system and hook name in its message.
- A system does not touch the film path, so the same scene still renders a deterministic film.
Errors from the runtime name the option and say what to pass, for example createRuntime mode must be one of fixed, variable, both.