3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
// Live input layer: an open registry of input sources, named actions and axes, and a runtime system that samples them once
// per fixed step. A source is any object that emits named values (keyboard, mouse, gamepad, MIDI, a script, an agent).
// Nothing here is a fixed list: game code registers its own sources and maps controls to its own actions.
// Events write the live control state at any time; the snapshot game logic reads changes only when the runtime samples,
// so a fixed-step game sees the same state for the whole step. See docs/input.md.
export { deviceMotionSource, INPUT_SOURCE_LIMITS, recordInput, replaySource, touchSource } from './input-sources.js';
export const INPUT_LIMITS = Object.freeze({
maximumSources: 16,
maximumControls: 512,
maximumActions: 128,
maximumAxes: 64,
maximumBindings: 16,
defaultButtonThreshold: 0.5,
defaultDeadZone: 0.15,
});
const AXIS_FIELDS = ['bindings', 'deadZone', 'smoothing'];
function describe(value) {
return value === null ? 'null' : typeof value;
}
function requireName(value, label) {
if (typeof value !== 'string' || value === '') {
throw new TypeError(`${label} must be a non-empty string, got ${describe(value)}.`);
}
return value;
}
function normalizeBindings(bindings, label) {
if (!Array.isArray(bindings) || bindings.length === 0 || bindings.length > INPUT_LIMITS.maximumBindings) {
throw new RangeError(`${label} must be an array of 1 to ${INPUT_LIMITS.maximumBindings} control names such as "keyboard/Space".`);
}
return bindings.map(binding => {
const entry = typeof binding === 'string' ? { control: binding, scale: 1 } : binding;
if (entry === null || typeof entry !== 'object') {
throw new TypeError(`${label} entries must be a control name or { control, scale }, got ${describe(binding)}.`);
}
const scale = entry.scale === undefined ? 1 : entry.scale;
if (!Number.isFinite(scale)) {
throw new TypeError(`${label} scale must be a finite number, got ${String(entry.scale)}.`);
}
return { control: requireName(entry.control, `${label} control`), scale };
});
}
function applyDeadZone(value, deadZone) {
const magnitude = Math.abs(value);
if (magnitude <= deadZone) return 0;
return Math.sign(value) * Math.min(1, (magnitude - deadZone) / (1 - deadZone));
}
export function createInput(options = {}) {
const buttonThreshold = options.buttonThreshold ?? INPUT_LIMITS.defaultButtonThreshold;
if (!Number.isFinite(buttonThreshold) || buttonThreshold <= 0 || buttonThreshold > 1) {
throw new RangeError(`createInput buttonThreshold must be a number above 0 and up to 1, got ${String(buttonThreshold)}.`);
}
const controls = new Map(); // "source/name" -> { value, pressedLatch, releasedLatch }
const actionBindings = new Map();
const axisBindings = new Map();
const sources = new Map(); // name -> { source, emit, attached }
let started = false;
let disposed = false;
let snapshot = { actions: new Map(), axes: new Map() };
const controlListeners = new Set();
const sampleListeners = new Set();
function assertAlive() {
if (disposed) throw new Error('This input was disposed. Call createInput again.');
}
function setControl(controlName, value) {
assertAlive();
requireName(controlName, 'setControl control');
if (!Number.isFinite(value)) {
throw new TypeError(`setControl value for "${controlName}" must be a finite number (1 or 0 for a button), got ${String(value)}.`);
}
let control = controls.get(controlName);
if (control === undefined) {
if (controls.size >= INPUT_LIMITS.maximumControls) {
throw new RangeError(`Input already has ${INPUT_LIMITS.maximumControls} controls. Reuse control names, or call releaseControls for sources that went away.`);
}
control = { value: 0, pressedLatch: false, releasedLatch: false };
controls.set(controlName, control);
}
const wasDown = control.value >= buttonThreshold;
const isDown = value >= buttonThreshold;
if (isDown && !wasDown) control.pressedLatch = true;
if (!isDown && wasDown) control.releasedLatch = true;
control.value = value;
for (const listener of [...controlListeners]) listener(controlName, value);
}
function addListener(listeners, listener, label) {
if (typeof listener !== 'function') throw new TypeError(`${label} needs a function, got ${describe(listener)}.`);
listeners.add(listener);
return () => listeners.delete(listener);
}
function releaseControls(sourceName) {
for (const [controlName, control] of controls) {
if (sourceName !== undefined && !controlName.startsWith(`${sourceName}/`)) continue;
if (control.value !== 0) setControl(controlName, 0);
}
}
function attach(entry) {
if (entry.attached || typeof entry.source.attach !== 'function') {
entry.attached = true;
return;
}
entry.attached = true;
entry.source.attach(entry.emit);
}
function registerSource(source) {
assertAlive();
if (source === null || typeof source !== 'object') {
throw new TypeError(`An input source must be an object like { name, attach(emit), poll(emit), dispose() }, got ${describe(source)}.`);
}
const name = requireName(source.name, 'An input source name');
if (name.includes('/')) throw new RangeError(`Input source name "${name}" must not contain "/". Use "midi", not "midi/1".`);
for (const hook of ['attach', 'poll', 'endSample', 'dispose']) {
if (source[hook] !== undefined && typeof source[hook] !== 'function') {
throw new TypeError(`Input source "${name}" ${hook} must be a function or left out, got ${describe(source[hook])}.`);
}
}
if (sources.has(name)) throw new RangeError(`An input source named "${name}" is already registered. Pass another name, or unregisterSource first.`);
if (sources.size >= INPUT_LIMITS.maximumSources) {
throw new RangeError(`Input already has ${INPUT_LIMITS.maximumSources} sources. Unregister one before adding "${name}".`);
}
const foreignControls = new Set();
const emit = (controlName, value) => setControl(`${name}/${controlName}`, value);
emit.releaseAll = () => {
releaseControls(name);
for (const controlName of foreignControls) {
if (controls.has(controlName)) setControl(controlName, 0);
}
};
if (source.writesAnyControl === true) {
// Only a source that declares writesAnyControl (a replay) may write full control names. They are tracked so
// releaseAll and unregisterSource clean them up.
emit.control = (controlName, value) => {
foreignControls.add(controlName);
setControl(controlName, value);
};
}
const entry = { source, emit, attached: false, foreignControls };
sources.set(name, entry);
if (started) attach(entry);
return api;
}
// Returns the thrown error in a box so one failing source cannot stop the others from being disposed.
function disposeSource(entry) {
try {
entry.source.dispose?.();
} catch (error) {
return { error };
}
return null;
}
function unregisterSource(name) {
const entry = sources.get(name);
if (entry === undefined) throw new RangeError(`No input source named "${String(name)}". Registered: ${[...sources.keys()].join(', ') || 'none'}.`);
const disposeFailure = disposeSource(entry);
sources.delete(name);
entry.emit.releaseAll();
for (const controlName of [...controls.keys()]) {
if (controlName.startsWith(`${name}/`) || entry.foreignControls.has(controlName)) controls.delete(controlName);
}
if (disposeFailure) throw disposeFailure.error;
return api;
}
function bindAction(name, bindings) {
assertAlive();
requireName(name, 'bindAction name');
if (!actionBindings.has(name) && actionBindings.size >= INPUT_LIMITS.maximumActions) {
throw new RangeError(`Input already has ${INPUT_LIMITS.maximumActions} actions. Reuse a name or unbindAction first.`);
}
actionBindings.set(name, normalizeBindings(bindings, `Action "${name}" bindings`));
return api;
}
function bindAxis(name, definition) {
assertAlive();
requireName(name, 'bindAxis name');
if (definition !== null && typeof definition === 'object' && !Array.isArray(definition)) {
const unknown = Object.keys(definition).find(field => !AXIS_FIELDS.includes(field));
if (unknown !== undefined) throw new RangeError(`Axis "${name}" has the unknown field "${unknown}". Use one of: ${AXIS_FIELDS.join(', ')}.`);
}
const bindings = Array.isArray(definition) ? definition : definition?.bindings;
const deadZone = (Array.isArray(definition) ? undefined : definition?.deadZone) ?? INPUT_LIMITS.defaultDeadZone;
const smoothing = (Array.isArray(definition) ? undefined : definition?.smoothing) ?? 0;
if (!Number.isFinite(smoothing) || smoothing < 0 || smoothing >= 1) {
throw new RangeError(`Axis "${name}" smoothing must be a number from 0 (none) up to but not including 1, got ${String(smoothing)}. Each sample moves the axis (1 - smoothing) of the way to its target.`);
}
if (!Number.isFinite(deadZone) || deadZone < 0 || deadZone >= 1) {
throw new RangeError(`Axis "${name}" deadZone must be a number from 0 up to but not including 1, got ${String(deadZone)}.`);
}
if (!axisBindings.has(name) && axisBindings.size >= INPUT_LIMITS.maximumAxes) {
throw new RangeError(`Input already has ${INPUT_LIMITS.maximumAxes} axes. Reuse a name or unbindAxis first.`);
}
axisBindings.set(name, { bindings: normalizeBindings(bindings, `Axis "${name}" bindings`), deadZone, smoothing, smoothed: 0 });
return api;
}
function sample() {
assertAlive();
for (const entry of sources.values()) entry.source.poll?.(entry.emit);
const actions = new Map();
for (const [name, bindings] of actionBindings) {
const state = { held: false, pressed: false, released: false };
for (const { control: controlName } of bindings) {
const control = controls.get(controlName);
if (control === undefined) continue;
if (control.value >= buttonThreshold) state.held = true;
if (control.pressedLatch) state.pressed = true;
if (control.releasedLatch) state.released = true;
}
actions.set(name, state);
}
const axes = new Map();
for (const [name, axis] of axisBindings) {
let total = 0;
for (const { control: controlName, scale } of axis.bindings) {
total += (controls.get(controlName)?.value ?? 0) * scale;
}
const target = applyDeadZone(Math.max(-1, Math.min(1, total)), axis.deadZone);
axis.smoothed = axis.smoothing === 0 ? target : axis.smoothed + (target - axis.smoothed) * (1 - axis.smoothing);
axes.set(name, axis.smoothed);
}
for (const control of controls.values()) {
control.pressedLatch = false;
control.releasedLatch = false;
}
snapshot = { actions, axes };
// Listeners hear the sample end before sources reset their pulses, so a reset (a tap going back to 0) is
// recorded under the next sample number, the way a live game sees it.
for (const listener of [...sampleListeners]) listener();
for (const entry of sources.values()) entry.source.endSample?.(entry.emit);
}
function actionState(name) {
const state = snapshot.actions.get(name);
if (state !== undefined) return state;
if (!actionBindings.has(name)) {
throw new RangeError(`No action named "${String(name)}". Bind it first: input.bindAction("${String(name)}", ["keyboard/Space"]).`);
}
return { held: false, pressed: false, released: false }; // bound but not sampled yet
}
function getAxis(name) {
const value = snapshot.axes.get(name);
if (value !== undefined) return value;
if (!axisBindings.has(name)) {
throw new RangeError(`No axis named "${String(name)}". Bind it first: input.bindAxis("${String(name)}", { bindings: ["gamepad/0.axis0"] }).`);
}
return 0;
}
function dispose() {
if (disposed) return;
const failures = [...sources.values()].reverse().map(disposeSource).filter(Boolean);
sources.clear();
controls.clear();
actionBindings.clear();
axisBindings.clear();
snapshot = { actions: new Map(), axes: new Map() };
controlListeners.clear();
sampleListeners.clear();
disposed = true;
if (failures.length > 0) throw failures[0].error;
}
const api = {
name: options.name ?? 'input',
registerSource,
unregisterSource,
bindAction,
bindAxis,
unbindAction(name) {
snapshot.actions.delete(name);
return actionBindings.delete(name);
},
unbindAxis(name) {
snapshot.axes.delete(name);
return axisBindings.delete(name);
},
setControl,
press: controlName => setControl(controlName, 1),
release: controlName => setControl(controlName, 0),
releaseControls,
sample,
// Observers for recording: the first hears every control change, the second the end of every sample.
// Each returns a function that removes the listener.
onControlChange: listener => addListener(controlListeners, listener, 'onControlChange'),
onSample: listener => addListener(sampleListeners, listener, 'onSample'),
isHeld: name => actionState(name).held,
wasPressed: name => actionState(name).pressed,
wasReleased: name => actionState(name).released,
getAxis,
get sources() {
return [...sources.keys()];
},
// Runtime system hooks. Fixed-step games sample once per fixed step; a variable-only loop samples once per frame.
init() {
assertAlive();
started = true;
for (const entry of sources.values()) attach(entry);
},
fixedUpdate() {
sample();
},
update(delta, context) {
if (context?.mode === 'variable') sample();
},
dispose,
};
for (const source of options.sources ?? []) registerSource(source);
for (const [name, bindings] of Object.entries(options.actions ?? {})) bindAction(name, bindings);
for (const [name, definition] of Object.entries(options.axes ?? {})) bindAxis(name, definition);
return api;
}
// Keyboard: controls are "keyboard/<KeyboardEvent.code>", for example keyboard/Space or keyboard/KeyW.
export function keyboardSource(options = {}) {
const target = options.target ?? globalThis;
const blurTarget = options.blurTarget ?? globalThis;
let handlers = null;
return {
name: 'keyboard',
attach(emit) {
assertTarget(target, 'keyboardSource target');
handlers = {
keydown: event => { if (!event.repeat) emit(event.code, 1); },
keyup: event => emit(event.code, 0),
blur: () => emit.releaseAll(),
};
target.addEventListener('keydown', handlers.keydown);
target.addEventListener('keyup', handlers.keyup);
blurTarget.addEventListener?.('blur', handlers.blur);
},
dispose() {
if (handlers === null) return;
target.removeEventListener('keydown', handlers.keydown);
target.removeEventListener('keyup', handlers.keyup);
blurTarget.removeEventListener?.('blur', handlers.blur);
handlers = null;
},
};
}
// Mouse and pointer: "mouse/button0".. for buttons (touch and pen report as button0), "mouse/x" and "mouse/y" in client
// pixels, and "mouse/deltaX", "mouse/deltaY" as movement summed since the last sample (works under pointer lock).
export function mouseSource(options = {}) {
const target = options.target ?? globalThis;
const blurTarget = options.blurTarget ?? globalThis;
let handlers = null;
let movementX = 0;
let movementY = 0;
return {
name: 'mouse',
attach(emit) {
assertTarget(target, 'mouseSource target');
handlers = {
pointerdown: event => {
emit(`button${event.button ?? 0}`, 1);
if (options.pointerLockElement?.requestPointerLock) options.pointerLockElement.requestPointerLock();
},
pointerup: event => emit(`button${event.button ?? 0}`, 0),
pointermove: event => {
emit('x', event.clientX ?? 0);
emit('y', event.clientY ?? 0);
movementX += event.movementX ?? 0;
movementY += event.movementY ?? 0;
emit('deltaX', movementX);
emit('deltaY', movementY);
},
blur: () => emit.releaseAll(),
};
for (const type of ['pointerdown', 'pointerup', 'pointermove']) target.addEventListener(type, handlers[type]);
blurTarget.addEventListener?.('blur', handlers.blur);
},
endSample(emit) {
movementX = 0;
movementY = 0;
emit('deltaX', 0);
emit('deltaY', 0);
},
dispose() {
if (handlers === null) return;
for (const type of ['pointerdown', 'pointerup', 'pointermove']) target.removeEventListener(type, handlers[type]);
blurTarget.removeEventListener?.('blur', handlers.blur);
handlers = null;
},
};
}
// Gamepad: polled at each sample. Controls are "gamepad/<index>.button<n>" (0 to 1) and "gamepad/<index>.axis<n>" (-1 to 1),
// for example gamepad/0.button0 and gamepad/0.axis1.
export function gamepadSource(options = {}) {
const readGamepads = options.getGamepads ?? (() => (typeof navigator !== 'undefined' && navigator.getGamepads ? navigator.getGamepads() : []));
let previousNames = new Set();
return {
name: 'gamepad',
poll(emit) {
const seen = new Set();
for (const pad of readGamepads() ?? []) {
if (!pad) continue;
pad.buttons.forEach((button, index) => {
const name = `${pad.index}.button${index}`;
seen.add(name);
emit(name, button.pressed ? 1 : button.value ?? 0);
});
pad.axes.forEach((value, index) => {
const name = `${pad.index}.axis${index}`;
seen.add(name);
emit(name, value);
});
}
for (const name of previousNames) {
if (!seen.has(name)) emit(name, 0); // pad unplugged
}
previousNames = seen;
},
};
}
function assertTarget(target, label) {
if (!target || typeof target.addEventListener !== 'function' || typeof target.removeEventListener !== 'function') {
throw new TypeError(`${label} must have addEventListener and removeEventListener, such as window or a canvas.`);
}
}