@driftengine/script 3.61.0

package/dist/bindings/core.js

@@ -0,0 +1,814 @@
+/**
+ * The wired `drift/*` surfaces other than audio, in one file because each is a table.
+ *
+ * A binding is a **description plus a lookup**. Nothing here is new engine code, and if a binding
+ * needed the engine to grow a function, that function would belong in the package owning the
+ * subsystem and this would then describe it like any other.
+ *
+ * **What is deliberately absent, and why**, because an empty module is a decision rather than an
+ * oversight:
+ *
+ * - **`drift/core`.** §11 gives its provider as `startLoop` and `LoopHooks`. A script does not call
+ *   those — they are what *drives* a script. There is nothing for a script to call, so the module
+ *   is not registered rather than registered empty, and a target does not claim it.
+ * - **`drift/xr`.** No provider: Track I is the one track nobody has taken, and the linker refuses
+ *   the module by name. **Twelve names stood in this list beside it and every one of them has since
+ *   been bound** — `render`, `ui`, `2d`, `terrain`, `ecs`, `prefab`, `navigation`, `behavior`,
+ *   `network`, `rollback`, `editor` and `ai` — and this sentence went on calling them unprovided,
+ *   because a comment listing what is missing has no guard on it and goes stale in the one
+ *   direction nothing checks.
+ */
+import { ActionMap, CinematicCamera, ColliderSet, RemoteSaveStore, MessageQueue, PhysicsWorld, SceneNode, angleDelta, boxCollider, createRayHit, hashToUnit, mulberry32, wrapAngle, } from '@driftengine/core';
+import { defineCapability } from 'driftscript';
+export const TIME_MODULE = 'drift/time';
+export const RANDOM_MODULE = 'drift/random';
+export const EVENTS_MODULE = 'drift/events';
+export const PERSISTENCE_MODULE = 'drift/persistence';
+export const SCENE_MODULE = 'drift/scene';
+export const PHYSICS_MODULE = 'drift/physics';
+export const INPUT_MODULE = 'drift/input';
+export const CAMERA_MODULE = 'drift/camera';
+const define = (module, name, params, returns, effects, deterministic, doc) => defineCapability({
+    module,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    deterministic,
+    doc,
+    implementation: `${module}.${name}`,
+});
+/**
+ * Handles a script holds and passes back, never reads into.
+ *
+ * A field on any of these would be a promise about a representation the engine could then never
+ * change — the design's safe-handle rule. `Node` is the one a script touches most, and it is still
+ * opaque: a position is read through a capability rather than off the object.
+ */
+export const CORE_TYPES = [
+    { module: SCENE_MODULE, name: 'Node', doc: 'A node in the transform hierarchy.' },
+    /*
+     * The frame's weather, already sampled. **A state and not a profile**, which is the whole of why
+     * a script may read it inside the fixed step: a profile plus a clock is a wall-clock read, and a
+     * `WindState` is what the field said at a time somebody else chose.
+     */
+    { module: SCENE_MODULE, name: 'Wind', doc: 'The wind as it was sampled this frame.' },
+    {
+        module: PHYSICS_MODULE,
+        name: 'Colliders',
+        doc: 'A set of convex colliders with a spatial hash.',
+    },
+    /*
+     * `PhysicsWorld`, not `World`: `drift/ecs` already registers that name, and the registry refuses
+     * two hosts claiming one — at registration, where somebody can act on it, rather than at a
+     * resolution nobody can see. An entity world and a rigid body world are genuinely two things.
+     */
+    {
+        module: PHYSICS_MODULE,
+        name: 'PhysicsWorld',
+        doc: 'A rigid body world, stepped on the fixed clock.',
+    },
+    {
+        module: INPUT_MODULE,
+        name: 'Actions',
+        doc: 'A bound action map: what the player is pressing.',
+    },
+    { module: CAMERA_MODULE, name: 'Camera', doc: 'A cinematic camera.' },
+    {
+        module: EVENTS_MODULE,
+        name: 'Queue',
+        doc: 'A priority message queue with dedupe and a ceiling.',
+    },
+    { module: PERSISTENCE_MODULE, name: 'Store', doc: 'A key-value store the consumer supplied.' },
+];
+/**
+ * `drift/time` — the loop's three clocks, and the one that is deterministic is not here.
+ *
+ * All three carry `clock.read`, so **none may be called from a `@deterministic` function** — and
+ * that is right even for the fixed step. A simulation is *given* its delta as a parameter; a
+ * simulation that reached out and read one has stopped being a function of its inputs, which is
+ * what replay depends on.
+ */
+export const TIME_CAPABILITIES = [
+    define(TIME_MODULE, 'fixedDelta', [], 'f32', ['clock.read'], false, 'The fixed simulation step, in seconds. Prefer the `dt` your function was given.'),
+    define(TIME_MODULE, 'frameDelta', [], 'f32', ['clock.read'], false, 'Seconds since the previous rendered frame, after clamping.'),
+    define(TIME_MODULE, 'wallDelta', [], 'f32', ['clock.read'], false, 'Seconds of real time since the previous frame, unclamped. Outside the boundary in every sense.'),
+    define(TIME_MODULE, 'elapsed', [], 'f32', ['clock.read'], false, 'Seconds since the loop started.'),
+];
+/**
+ * `drift/random` — a seeded generator whose sequence is **frozen**.
+ *
+ * Deterministic by construction, so a `@deterministic` function may call it. That is the whole
+ * reason it is a capability rather than a `std/*` function: the sequence is a promise about *this
+ * engine's* stored replays, and a standard library that shipped its own would either break that
+ * promise or silently become the thing that defines it.
+ */
+export const RANDOM_CAPABILITIES = [
+    define(RANDOM_MODULE, 'unit', [{ name: 'seed', type: 'u32' }], 'f32', ['pure'], true, 'A value from 0 to 1 for a seed. The same seed always gives the same value.'),
+    define(RANDOM_MODULE, 'range', [
+        { name: 'seed', type: 'u32' },
+        { name: 'low', type: 'f32' },
+        { name: 'high', type: 'f32' },
+    ], 'f32', ['pure'], true, 'A value between two bounds for a seed.'),
+    define(RANDOM_MODULE, 'index', [
+        { name: 'seed', type: 'u32' },
+        { name: 'count', type: 'u32' },
+    ], 'u32', ['pure'], true, 'An index into a collection of `count` items. Zero for an empty one.'),
+];
+/** `drift/events` — the engine's priority queue, with dedupe over a window and a backlog ceiling. */
+export const EVENTS_CAPABILITIES = [
+    define(EVENTS_MODULE, 'push', [
+        { name: 'queue', type: 'Queue' },
+        { name: 'id', type: 'String' },
+        { name: 'priority', type: 'f32' },
+        { name: 'holdFor', type: 'f32' },
+    ], 'void', ['pure'], true, 'Queue a message by identity. A repeat of the same id inside the dedupe window is dropped.'),
+    define(EVENTS_MODULE, 'current', [{ name: 'queue', type: 'Queue' }], 'String?', ['pure'], true, "The id of the message showing now, if any. The queue carries identity and priority; the words are the consumer's."),
+    define(EVENTS_MODULE, 'clear', [{ name: 'queue', type: 'Queue' }], 'void', ['pure'], true, 'Drop everything queued.'),
+];
+/** `drift/persistence` — the store the consumer supplied, which may be a browser, a server or nothing. */
+export const PERSISTENCE_CAPABILITIES = [
+    define(PERSISTENCE_MODULE, 'read', [
+        { name: 'store', type: 'Store' },
+        { name: 'key', type: 'String' },
+    ], 'String?', ['persistence.read'], false, 'What is stored under a key. Absent when nothing is, which is ordinary rather than exceptional.'),
+    define(PERSISTENCE_MODULE, 'write', [
+        { name: 'store', type: 'Store' },
+        { name: 'key', type: 'String' },
+        { name: 'value', type: 'String' },
+    ], 'void', ['persistence.write'], false, 'Store a value under a key.'),
+    define(PERSISTENCE_MODULE, 'remove', [
+        { name: 'store', type: 'Store' },
+        { name: 'key', type: 'String' },
+    ], 'void', ['persistence.write'], false, 'Forget a key.'),
+    /*
+     * **The two a script needs when the store answers later, and the one it cannot have.**
+     *
+     * A `RemoteSaveStore` writes into a queue that drains behind the synchronous surface, so a write
+     * that reads back correctly may not have landed anywhere. A script drawing a "saving" indicator
+     * has to be able to ask. Both answer honestly for a *synchronous* store too — a browser store
+     * has nothing pending and is always idle — so this is not a capability that only works for one
+     * implementation.
+     *
+     * **`flush` is not bound**, and the reason is the language rather than the engine: it answers a
+     * promise and DriftScript has no await, so a binding would either block or hand back something
+     * a script cannot hold. A consumer flushes from TypeScript, at the one place it knows it is
+     * leaving.
+     */
+    define(PERSISTENCE_MODULE, 'saveStatus', [{ name: 'store', type: 'Store' }], 'String', ['persistence.read'], false, 'Whether writes have landed: `idle`, `pending`, `saving` or `failed`. A store that writes synchronously is always `idle`, which is the true answer rather than a stub.'),
+    define(PERSISTENCE_MODULE, 'pendingSaves', [{ name: 'store', type: 'Store' }], 'u32', ['persistence.read'], false, 'How many keys are waiting to reach the backend. Zero for a store that writes synchronously.'),
+];
+/**
+ * `drift/scene` — the transform hierarchy from Phase 1.1.
+ *
+ * Reads are deterministic and writes are not, which is the boundary drawn per capability rather
+ * than per module. A simulation may ask where something is; moving it is a change to the world.
+ */
+export const SCENE_CAPABILITIES = [
+    define(SCENE_MODULE, 'positionX', [{ name: 'node', type: 'Node' }], 'f32', ['scene.read'], true, "A node's local x."),
+    define(SCENE_MODULE, 'positionY', [{ name: 'node', type: 'Node' }], 'f32', ['scene.read'], true, "A node's local y."),
+    define(SCENE_MODULE, 'positionZ', [{ name: 'node', type: 'Node' }], 'f32', ['scene.read'], true, "A node's local z."),
+    define(SCENE_MODULE, 'setPosition', [
+        { name: 'node', type: 'Node' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+    ], 'void', ['scene.write'], false, 'Move a node, marking it and its subtree for a world update.'),
+    define(SCENE_MODULE, 'setScale', [
+        { name: 'node', type: 'Node' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+    ], 'void', ['scene.write'], false, 'Scale a node.'),
+    define(SCENE_MODULE, 'setRotation', [
+        { name: 'node', type: 'Node' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+        { name: 'radians', type: 'f32' },
+    ], 'void', ['scene.write'], false, 'Rotate a node about an axis.'),
+    /*
+     * **The wind, read by a behaviour rather than by the renderer.**
+     *
+     * The per-vertex channel bends geometry to this same wind in the vertex stage; these four let a
+     * script ask the question a behaviour asks — take shelter in a gust, luff a sail, turn downwind.
+     *
+     * **Deterministic, and that is a claim rather than a convenience.** `wind.ts` builds the signal
+     * as a fundamental plus integer harmonics, repeating exactly at the fundamental's period,
+     * precisely so a replay watched an hour later sees the gust the original run saw. A non-integer
+     * harmonic would look organic and never close, and these would then be reading a wall clock
+     * through a handle. The comment in that file is the thing holding this up.
+     *
+     * **`f32` and not `float`**, which every capability here takes: `float` is width-polymorphic and
+     * one returning it must also take one, or `defineCapability` throws. These take a `Wind`.
+     */
+    define(SCENE_MODULE, 'windDirectionX', [{ name: 'wind', type: 'Wind' }], 'f32', ['scene.read'], true, "The prevailing wind's x, normalised; zero when there is no wind to have a direction."),
+    define(SCENE_MODULE, 'windDirectionZ', [{ name: 'wind', type: 'Wind' }], 'f32', ['scene.read'], true, "The prevailing wind's z, normalised; zero when there is no wind to have a direction."),
+    define(SCENE_MODULE, 'windSpeed', [{ name: 'wind', type: 'Wind' }], 'f32', ['scene.read'], true, 'How hard it is blowing, metres a second, never negative.'),
+    define(SCENE_MODULE, 'windGust', [{ name: 'wind', type: 'Wind' }], 'f32', ['scene.read'], true, 'The gust alone, -1 to 1, for a behaviour that wants the deviation and not the total.'),
+    define(SCENE_MODULE, 'distance', [
+        { name: 'a', type: 'Node' },
+        { name: 'b', type: 'Node' },
+    ], 'f32', ['scene.read'], true, 'The distance between two nodes, in local space.'),
+];
+/**
+ * `drift/physics` — bodies, contacts, queries and forces. **Not joints, not the controller and not
+ * ragdolls**, which is what this line said until 2026-08-27 and what none of the thirty-six
+ * capabilities below has ever done.
+ *
+ * **This module was two read-only functions until 2026-08-26**, and its own comment said why: there
+ * was no solver to write into, and a capability that pretended otherwise would have been the mock
+ * the design refused. Track B built the solver, so the surface is real — but the sentence that
+ * announced it was written from the *track's* deliverables rather than from this list, which is the
+ * same failure as a binding written from memory of what a camera ought to have. A reader looking
+ * for `joint` here found a comment that promised one.
+ *
+ * **Six of the thirty-six are `nearestWithin` and its accessors, added 2026-08-28**, and they exist
+ * because a consumer reported that `anyWithin` answers *whether* and never *what*. A script could
+ * already find the nearest entity — `drift/ecs` grew `findNearest` and `nearest` for that — and
+ * could not find the nearest wall, so what is in reach of a character was decided in TypeScript.
+ *
+ * **The two `within` questions measure different volumes, and the names cannot say so on their
+ * own.** `anyWithin` tests the axis-aligned *box* around the sphere, because that is what the
+ * collider hash indexes and testing anything narrower would cost a pass it does not need for a
+ * yes-or-no. `nearestWithin` is already walking each candidate to rank it, so it measures the
+ * sphere exactly and answers false where `anyWithin` answers true — a collider that reaches only
+ * the box corners. Both say which they do, on themselves, because a reader comparing the two names
+ * would have no reason to suspect it.
+ *
+ * **It measures to a collider's bounds rather than to the shape inside them**, which is the one
+ * place this surface is coarser than the sweep beside it. `ColliderSet`'s own header draws that
+ * line: the bounds are the broad phase and the shape resolves a contact, so a proximity answer that
+ * ran the convex sweep per candidate per frame would be paying contact prices for a distance. The
+ * documentation on each accessor says bounds, so nobody reads a banked slab's box as its surface.
+ *
+ * **What is missing, and the design question that is why it is still missing**: `JointDesc` carries
+ * twenty optional fields, so a script-side constructor is either an enormous signature or a builder
+ * this language has no shape for. That is a decision somebody has to take deliberately, and taking
+ * it badly would put a wrong-by-construction surface in front of every script author. Recorded here
+ * rather than guessed at.
+ *
+ * **Two parameters are required here that TypeScript leaves optional**, which is step four of the
+ * note at the top of `host.ts`, and both are the same shape of trap — an omission that produces a
+ * *wrong result* rather than an error:
+ *
+ * - **A raycast's layer mask.** Omitted, the first thing a ray finds is very often the body it
+ *   started inside, because `raycastWorld` reports that body at fraction zero deliberately. A
+ *   TypeScript caller has the context to know when that matters; a script author meets it first and
+ *   reads it as the engine seeing through walls.
+ * - **An impulse's application point.** Omitted, the impulse goes through the centre of mass and
+ *   produces no rotation whatever. Nothing throws; a crate simply slides instead of tumbling, which
+ *   reads as a broken impulse rather than as a missing argument.
+ *
+ * **Every body and event index is `i32`, not `u32`.** `hitBody` has to be able to answer −1, and a
+ * script has no cast, so a mixed surface would make the obvious code — raycast, check the body,
+ * apply an impulse to it — impossible to write. One signed type throughout costs nothing and is
+ * what a query result already is.
+ *
+ * **A raycast's result is read back through separate accessors**, in the same shape `input.axisX`
+ * and `input.axisY` already use for a vector. A script has no way to receive an engine record, and
+ * inventing a flattened signature would drift from the real one the first time a hit gains a field —
+ * which is the reasoning `drift/camera` gives for leaving `cut` out. *What it costs* is that a hit
+ * is only valid until the next `raycast` on the same world, and the documentation says so on every
+ * accessor.
+ */
+export const PHYSICS_CAPABILITIES = [
+    define(PHYSICS_MODULE, 'colliderCount', [{ name: 'colliders', type: 'Colliders' }], 'u32', ['physics.read'], true, 'How many colliders a set holds.'),
+    define(PHYSICS_MODULE, 'colliderCapacity', [{ name: 'colliders', type: 'Colliders' }], 'u32', ['physics.read'], true, 'How many slots the set has allocated, live or not. Equal to `colliderCount` until a group is removed; after that the live colliders are sparse within it.'),
+    define(PHYSICS_MODULE, 'colliderBytes', [{ name: 'colliders', type: 'Colliders' }], 'u32', ['physics.read'], true, 'What the set costs in memory, in bytes. The slots and shapes are exact; the spatial index includes an estimate of per-object overhead a JavaScript engine does not expose.'),
+    /*
+     * **A builder rather than one call, because a script has no list to hand across.** A region is
+     * many boxes and one group, so a per-box call returning a group would mint one group per box and
+     * give a streamer nothing to drop.
+     *
+     * **`end` returns the handle, not `begin`.** The group does not exist until the boxes are in, and
+     * a handle issued before that would be a promise the binding could only keep by inventing an id
+     * the engine had not minted.
+     */
+    define(PHYSICS_MODULE, 'beginColliderGroup', [{ name: 'colliders', type: 'Colliders' }], 'void', ['physics.write'], false, 'Open a group. Add boxes with `addColliderBox`, then `endColliderGroup` to put them in and get the handle back.'),
+    define(PHYSICS_MODULE, 'addColliderBox', [
+        { name: 'colliders', type: 'Colliders' },
+        { name: 'cx', type: 'f32' },
+        { name: 'cy', type: 'f32' },
+        { name: 'cz', type: 'f32' },
+        { name: 'hx', type: 'f32' },
+        { name: 'hy', type: 'f32' },
+        { name: 'hz', type: 'f32' },
+    ], 'void', ['physics.write'], false, 'A box in the open group, by centre and half-extents — the same numbers a mesh builder takes, so nothing is authored twice. Nothing is queryable until `endColliderGroup`.'),
+    define(PHYSICS_MODULE, 'endColliderGroup', [{ name: 'colliders', type: 'Colliders' }], 'u32', ['physics.write'], false, 'Put the open group into the set and return the handle that drops it again. Keep the handle: it is the only way to remove those colliders.'),
+    define(PHYSICS_MODULE, 'removeColliderGroup', [
+        { name: 'colliders', type: 'Colliders' },
+        { name: 'group', type: 'u32' },
+    ], 'void', ['physics.write'], false, 'Drop a group and everything in it. Refuses a handle the set does not hold, and refuses the colliders the set was constructed with — a set meant to stream is constructed empty.'),
+    define(PHYSICS_MODULE, 'anyWithin', [
+        { name: 'colliders', type: 'Colliders' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+        { name: 'radius', type: 'f32' },
+    ], 'bool', ['physics.read'], true, 'Whether any collider overlaps the *box* around a sphere. The cheapest answer there is, and it over-reports a collider that only reaches the box corners. `nearestWithin` measures the sphere.'),
+    define(PHYSICS_MODULE, 'nearestWithin', [
+        { name: 'colliders', type: 'Colliders' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+        { name: 'radius', type: 'f32' },
+    ], 'bool', ['physics.read'], true, 'Find the closest collider within a radius and record it. Read the result with the `near` functions. Valid until the next `nearestWithin` on this set.'),
+    define(PHYSICS_MODULE, 'nearCollider', [{ name: 'colliders', type: 'Colliders' }], 'i32', ['physics.read'], true, 'The collider the last `nearestWithin` on this set found, or \u22121.'),
+    define(PHYSICS_MODULE, 'nearX', [{ name: 'colliders', type: 'Colliders' }], 'f32', ['physics.read'], true, 'The closest point on that collider\u2019s bounds, along x \u2014 the point on the wall rather than the wall\u2019s centre.'),
+    define(PHYSICS_MODULE, 'nearY', [{ name: 'colliders', type: 'Colliders' }], 'f32', ['physics.read'], true, 'The closest point on that collider\u2019s bounds, along y.'),
+    define(PHYSICS_MODULE, 'nearZ', [{ name: 'colliders', type: 'Colliders' }], 'f32', ['physics.read'], true, 'The closest point on that collider\u2019s bounds, along z.'),
+    define(PHYSICS_MODULE, 'nearDistance', [{ name: 'colliders', type: 'Colliders' }], 'f32', ['physics.read'], true, 'How far that collider\u2019s bounds are, in metres. Zero when the query point is inside them.'),
+    define(PHYSICS_MODULE, 'bodyCount', [{ name: 'world', type: 'PhysicsWorld' }], 'i32', ['physics.read'], true, 'How many bodies the world holds.'),
+    define(PHYSICS_MODULE, 'bodyX', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's world position along x."),
+    define(PHYSICS_MODULE, 'bodyY', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's world position along y."),
+    define(PHYSICS_MODULE, 'bodyZ', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's world position along z."),
+    define(PHYSICS_MODULE, 'bodyVelX', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's velocity along x, in metres per second."),
+    define(PHYSICS_MODULE, 'bodyVelY', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's velocity along y, in metres per second."),
+    define(PHYSICS_MODULE, 'bodyVelZ', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's velocity along z, in metres per second."),
+    define(PHYSICS_MODULE, 'bodyMass', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'f32', ['physics.read'], true, "A body's mass in kilograms, or zero where it has none because it is static or kinematic."),
+    define(PHYSICS_MODULE, 'sleeping', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'bool', ['physics.read'], true, 'Whether a body has been still long enough to stop being solved.'),
+    define(PHYSICS_MODULE, 'raycast', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+        { name: 'dx', type: 'f32' },
+        { name: 'dy', type: 'f32' },
+        { name: 'dz', type: 'f32' },
+        { name: 'maxDistance', type: 'f32' },
+        { name: 'mask', type: 'i32' },
+    ], 'bool', ['physics.read'], true, 'Cast a ray and record what it hit. `mask` is required: without one the first thing a ray finds is often the body it started inside. Read the result with the `hit` functions.'),
+    define(PHYSICS_MODULE, 'hitBody', [{ name: 'world', type: 'PhysicsWorld' }], 'i32', ['physics.read'], true, 'The body the last `raycast` on this world found, or −1. Valid until the next raycast.'),
+    define(PHYSICS_MODULE, 'hitX', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'Where the last raycast struck, along x. Valid until the next raycast.'),
+    define(PHYSICS_MODULE, 'hitY', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'Where the last raycast struck, along y. Valid until the next raycast.'),
+    define(PHYSICS_MODULE, 'hitZ', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'Where the last raycast struck, along z. Valid until the next raycast.'),
+    define(PHYSICS_MODULE, 'hitNormalX', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'The surface normal the last raycast struck, along x.'),
+    define(PHYSICS_MODULE, 'hitNormalY', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'The surface normal the last raycast struck, along y.'),
+    define(PHYSICS_MODULE, 'hitNormalZ', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'The surface normal the last raycast struck, along z.'),
+    define(PHYSICS_MODULE, 'hitFraction', [{ name: 'world', type: 'PhysicsWorld' }], 'f32', ['physics.read'], true, 'How far along the ray the last hit was, from 0 to 1.'),
+    define(PHYSICS_MODULE, 'contactCount', [{ name: 'world', type: 'PhysicsWorld' }], 'i32', ['physics.read'], true, 'How many contact events the last step produced. Drain them after stepping, never during.'),
+    define(PHYSICS_MODULE, 'contactKind', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'index', type: 'i32' },
+    ], 'i32', ['physics.read'], true, "An event's kind: 0 entered, 1 still touching, 2 left."),
+    define(PHYSICS_MODULE, 'contactA', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'index', type: 'i32' },
+    ], 'i32', ['physics.read'], true, 'The lower-indexed body of a contact event.'),
+    define(PHYSICS_MODULE, 'contactB', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'index', type: 'i32' },
+    ], 'i32', ['physics.read'], true, 'The higher-indexed body of a contact event.'),
+    define(PHYSICS_MODULE, 'applyImpulse', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+        { name: 'px', type: 'f32' },
+        { name: 'py', type: 'f32' },
+        { name: 'pz', type: 'f32' },
+        { name: 'atX', type: 'f32' },
+        { name: 'atY', type: 'f32' },
+        { name: 'atZ', type: 'f32' },
+    ], 'void', ['physics.write'], false, 'Apply an impulse at a world point. The point is required: through the centre of mass an impulse produces no rotation at all, which reads as a broken impulse rather than a missing argument.'),
+    define(PHYSICS_MODULE, 'applyForce', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+        { name: 'fx', type: 'f32' },
+        { name: 'fy', type: 'f32' },
+        { name: 'fz', type: 'f32' },
+        { name: 'dt', type: 'f32' },
+        { name: 'atX', type: 'f32' },
+        { name: 'atY', type: 'f32' },
+        { name: 'atZ', type: 'f32' },
+    ], 'void', ['physics.write'], false, 'A force applied for one step, which is an impulse of force times dt. The point is required for the same reason.'),
+    define(PHYSICS_MODULE, 'setVelocity', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+        { name: 'vx', type: 'f32' },
+        { name: 'vy', type: 'f32' },
+        { name: 'vz', type: 'f32' },
+    ], 'void', ['physics.write'], false, "Set a body's velocity outright, waking its island."),
+    define(PHYSICS_MODULE, 'setPosition', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+    ], 'void', ['physics.write'], false, 'Move a body outright. A teleport rather than a push: the broadphase moves with it.'),
+    define(PHYSICS_MODULE, 'wake', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'body', type: 'i32' },
+    ], 'void', ['physics.write'], false, 'Wake a body and everything sharing its island, because a sleeping neighbour would settle it again.'),
+    define(PHYSICS_MODULE, 'setGravity', [
+        { name: 'world', type: 'PhysicsWorld' },
+        { name: 'x', type: 'f32' },
+        { name: 'y', type: 'f32' },
+        { name: 'z', type: 'f32' },
+    ], 'void', ['physics.write'], false, "The world's gravity, in metres per second squared."),
+];
+/** `drift/input` — Track H, complete: action maps, rebinding, gamepad, pointer and touch. */
+export const INPUT_CAPABILITIES = [
+    define(INPUT_MODULE, 'down', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'bool', ['input.read'], false, 'Whether an action is held.'),
+    define(INPUT_MODULE, 'pressed', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'bool', ['input.read'], false, 'Whether an action went down this frame.'),
+    define(INPUT_MODULE, 'axisX', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'f32', ['input.read'], false, "A directional action's horizontal component, shortened to the rim with the vertical one so a keyboard diagonal is not faster than a straight line. For two independent controls such as throttle and steering, read rawAxisX instead."),
+    define(INPUT_MODULE, 'axisY', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'f32', ['input.read'], false, "A directional action's vertical component, shortened to the rim with the horizontal one. For two independent controls, read rawAxisY instead."),
+    /*
+     * **The pair that is not normalised, and the reason both pairs exist.** `axisX` and `axisY` treat
+     * an action's two axes as one direction, which is right on foot and wrong at a wheel: throttle
+     * and steering are two controls that happen to share an action, and dividing both by √2 means a
+     * driver holding forward and left can never reach full lock while accelerating. A consumer lost
+     * two weeks to that in TypeScript before anybody looked at `ActionMap.vector`, and a script
+     * author reading `axisX` would have met it identically, because this binding calls that method.
+     *
+     * Added rather than corrected in place: `axisX` behaves as it always has, because changing what
+     * it returns would make every scripted character quietly faster on a diagonal.
+     */
+    define(INPUT_MODULE, 'rawAxisX', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'f32', ['input.read'], false, "An action's horizontal axis on its own, not shortened against the vertical one. This is what a throttle or a steering input wants: holding two keys gives a full 1 on each."),
+    define(INPUT_MODULE, 'rawAxisY', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'action', type: 'String' },
+    ], 'f32', ['input.read'], false, "An action's vertical axis on its own, not shortened against the horizontal one."),
+    /*
+     * **Rumble answers a boolean and a script has to read it**, which is the whole reason this row
+     * exists in the shape it does. Most pads on most browsers have no motors, so a settings screen
+     * that offers the control unconditionally is offering something a player's hardware ignores. The
+     * host layer answers false rather than accepting the call and doing nothing quietly, and these
+     * three carry that answer across the language boundary unchanged.
+     *
+     * `input.write` does not exist as an effect and this does not invent one: driving a motor is a
+     * write to the *host*, which is what `host` already means, and it is outside the deterministic
+     * boundary for the same reason `audio.write` is — a replay must not be able to tell whether the
+     * player's pad was plugged in.
+     */
+    define(INPUT_MODULE, 'canRumble', [{ name: 'actions', type: 'Actions' }], 'bool', ['host'], false, 'Whether the pad these actions read has motors this browser can drive. Grey the control out when it is false; most pads on most browsers cannot.'),
+    define(INPUT_MODULE, 'rumble', [
+        { name: 'actions', type: 'Actions' },
+        { name: 'durationMs', type: 'f32' },
+        { name: 'strong', type: 'f32' },
+        { name: 'weak', type: 'f32' },
+    ], 'bool', ['host'], false, 'Rumble for a duration in milliseconds, at two magnitudes in [0, 1]: `strong` is the low-frequency motor and `weak` the high-frequency one. Answers whether the platform took it; false is a real answer, not an error.'),
+    define(INPUT_MODULE, 'stopRumble', [{ name: 'actions', type: 'Actions' }], 'bool', ['host'], false, 'Stop whatever that pad is playing. Answers whether the platform took it.'),
+];
+/**
+ * `drift/camera` — the cinematic cameras, and **only what they actually have**.
+ *
+ * The first version of this binding described `lookAt` and `setPosition`. `CinematicCamera` has
+ * neither: it has `cut`, `snap`, `shotAgeSec` and `update`. The implementation reached them through
+ * an optional-call cast, so a script calling `camera.lookAt(…)` compiled, linked, ran, and did
+ * **nothing** — the silent no-op this repository's rules forbid, arriving by way of a binding
+ * written from memory of what a camera ought to have rather than from the class.
+ *
+ * `cut` is deliberately still absent: it takes a `ShotParams`, and a script has no way to construct
+ * an engine record yet. Binding it would mean inventing a flattened signature that drifts from the
+ * real one the first time a shot gains a field. It waits for a way to express the record.
+ */
+export const CAMERA_CAPABILITIES = [
+    define(CAMERA_MODULE, 'snap', [{ name: 'camera', type: 'Camera' }], 'void', ['scene.write'], false, 'Jump the camera to where it is heading, skipping the ease. What a scene cut needs.'),
+    define(CAMERA_MODULE, 'shotAge', [{ name: 'camera', type: 'Camera' }], 'f32', ['scene.read'], true, 'Seconds since the current shot began. A read, so a deterministic function may ask.'),
+];
+const some = (value) => ({ tag: 'some', value });
+const none = { tag: 'none' };
+/**
+ * Round a double to the nearest single, because every signature in this file is declared `f32`.
+ *
+ * **Still correct at language 1.5.0, and the reason is worth writing down beside it.** That release
+ * introduced a `float` type meaning "`f32` or `f64`, the same one throughout the call", and moved
+ * `std/math`'s rounding out of its implementations to the call site — because a library that
+ * rounded every result would be destroying precision the moment a call resolved to double. The
+ * language's own note to hosts is therefore: implement a `float` capability once, in double, and do
+ * **not** round; and rounding stays right for a signature left written `f32`.
+ *
+ * Every capability here is written `f32` and none is written `float`, so this is the second case
+ * and it is unchanged. **What would make it wrong** is somebody widening one of these signatures to
+ * `float` and leaving the call here — at which point a double-precision call would be silently
+ * narrowed by the host after the compiler had promised it would not be.
+ */
+const f = Math.fround;
+export function timeImplementation(clocks) {
+    return {
+        fixedDelta: () => f(clocks.fixedDelta()),
+        frameDelta: () => f(clocks.frameDelta()),
+        wallDelta: () => f(clocks.wallDelta()),
+        elapsed: () => f(clocks.elapsed()),
+    };
+}
+/**
+ * The seeded generator, dispatching to core's frozen sequence.
+ *
+ * `index` returns 0 for an empty collection rather than an error, because "pick from nothing" has
+ * one sane answer and a script asking is usually mid-way through a list that will have items next
+ * frame.
+ */
+export function randomImplementation() {
+    return {
+        unit: (seed) => f(hashToUnit(seed)),
+        range: (seed, low, high) => f(low + hashToUnit(seed) * (high - low)),
+        index: (seed, count) => count <= 0 ? 0 : Math.floor(hashToUnit(seed) * count) % count,
+    };
+}
+export function eventsImplementation() {
+    return {
+        push(queue, id, priority, holdFor) {
+            /* `holdFor` arrives in seconds because units erase to the base unit, and the queue counts in
+               milliseconds. Converting here rather than exposing milliseconds to a script keeps every
+               duration in the language one kind of number. */
+            queue.push({ id, priority, durationMs: holdFor * 1000 });
+        },
+        current(queue) {
+            const message = queue.current;
+            return message === null ? none : some(message.id);
+        },
+        clear(queue) {
+            queue.clear();
+        },
+    };
+}
+export function persistenceImplementation() {
+    return {
+        read(store, key) {
+            const value = store.read(key);
+            /* `null` becomes `none`, which is the whole reason this is a capability rather than a direct
+               call: the language has no null, so the boundary is where one stops existing. */
+            return value === null ? none : some(value);
+        },
+        write(store, key, value) {
+            store.write(key, value);
+        },
+        remove(store, key) {
+            store.remove(key);
+        },
+        /* `instanceof` rather than a duck-typed property check: a store that happens to carry a
+           `status` field meaning something else would otherwise be read as this one. */
+        saveStatus: (store) => store instanceof RemoteSaveStore ? store.status : 'idle',
+        pendingSaves: (store) => (store instanceof RemoteSaveStore ? store.pending : 0),
+    };
+}
+export function sceneImplementation() {
+    return {
+        positionX: (node) => f(node.position[0]),
+        positionY: (node) => f(node.position[1]),
+        positionZ: (node) => f(node.position[2]),
+        setPosition: (node, x, y, z) => node.setPosition(x, y, z),
+        setScale: (node, x, y, z) => node.setScale(x, y, z),
+        setRotation: (node, x, y, z, radians) => node.setRotationAxisAngle(x, y, z, radians),
+        /* Normalised on the way out rather than stored that way: `WindState` carries a velocity, and
+           a direction is what a behaviour asks for. Zero speed has no direction, and zero is the
+           honest answer rather than a NaN from dividing by it. */
+        windDirectionX: (wind) => f(wind.speed > 1e-5 ? wind.velocityX / wind.speed : 0),
+        windDirectionZ: (wind) => f(wind.speed > 1e-5 ? wind.velocityZ / wind.speed : 0),
+        windSpeed: (wind) => f(wind.speed),
+        windGust: (wind) => f(wind.gust),
+        distance: (a, b) => {
+            const dx = a.position[0] - b.position[0];
+            const dy = a.position[1] - b.position[1];
+            const dz = a.position[2] - b.position[2];
+            return f(Math.sqrt(dx * dx + dy * dy + dz * dz));
+        },
+    };
+}
+export function physicsImplementation() {
+    /* One scratch buffer, reused. `query` writes indices into an out-parameter and returns how many
+       it wrote, so a fresh array per call would allocate on a path a script runs every frame — which
+       is the rule the whole engine is built on. Sized generously; a broad-phase answer only needs to
+       know whether the count was non-zero. */
+    const hits = new Int32Array(256);
+    /*
+     * The last raycast, per world, held **here rather than on the engine**.
+     *
+     * A script cannot receive a record, so a hit is read back through accessors — and putting the
+     * state in the binding keeps `PhysicsWorld` free of a field that exists only because of a
+     * language limitation. A `WeakMap` rather than one shared slot, because two worlds are two
+     * questions and a shared slot would let one answer the other's.
+     */
+    const lastHit = new WeakMap();
+    const hitOf = (world) => {
+        let hit = lastHit.get(world);
+        if (!hit) {
+            hit = createRayHit();
+            lastHit.set(world, hit);
+        }
+        return hit;
+    };
+    const filter = { mask: 0xffffffff };
+    /*
+     * The last `nearestWithin`, per collider set, in the same shape and for the same reasons.
+     *
+     * A consumer reported the gap this closes: `anyWithin` answered *whether* something was near and
+     * never *what*, so a script could find the nearest person through `drift/ecs` and could not find
+     * the nearest wall at all — and the rule for what is in reach moved into TypeScript, which is
+     * exactly the rule somebody wants to edit with the game running.
+     *
+     * **The answer is a search plus accessors rather than a value**, which is the third time this
+     * file has drawn that conclusion — `raycast` with its `hit` functions, `findNearest` with
+     * `nearest`, and now this. A script cannot receive a record, and returning an option would
+     * allocate one object per call on a path an agent runs every frame.
+     */
+    const lastNear = new WeakMap();
+    const nearOf = (colliders) => {
+        let near = lastNear.get(colliders);
+        if (!near) {
+            near = { collider: -1, distance: 0, x: 0, y: 0, z: 0 };
+            lastNear.set(colliders, near);
+        }
+        return near;
+    };
+    /* One reused box for the scan, because `bounds` writes into a caller's object and a fresh one
+       per candidate is the per-frame allocation the engine forbids. */
+    const box = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+    /*
+     * The boxes of a group being built, per set. A `WeakMap` for the same reason `nearOf` uses one:
+     * two sets are two builders, and a shared slot would let one set's region land in the other.
+     */
+    const pending = new WeakMap();
+    return {
+        colliderCount: (colliders) => colliders.count,
+        colliderCapacity: (colliders) => colliders.capacity,
+        colliderBytes: (colliders) => colliders.bytes().total,
+        beginColliderGroup(colliders) {
+            if (pending.has(colliders)) {
+                throw new Error('beginColliderGroup: a group is already open on this set. Close it with ' +
+                    '`endColliderGroup` before opening another.');
+            }
+            pending.set(colliders, []);
+        },
+        addColliderBox(colliders, cx, cy, cz, hx, hy, hz) {
+            const open = pending.get(colliders);
+            if (open === undefined) {
+                throw new Error('addColliderBox: no group is open on this set. Call `beginColliderGroup` first.');
+            }
+            open.push(boxCollider(cx, cy, cz, hx, hy, hz));
+        },
+        endColliderGroup(colliders) {
+            const open = pending.get(colliders);
+            if (open === undefined) {
+                throw new Error('endColliderGroup: no group is open on this set.');
+            }
+            pending.delete(colliders);
+            return colliders.add(open);
+        },
+        removeColliderGroup(colliders, group) {
+            colliders.remove(group);
+        },
+        anyWithin(colliders, x, y, z, radius) {
+            const found = colliders.query(x - radius, y - radius, z - radius, x + radius, y + radius, z + radius, hits);
+            return found > 0;
+        },
+        nearestWithin(colliders, x, y, z, radius) {
+            const near = nearOf(colliders);
+            near.collider = -1;
+            near.distance = 0;
+            near.x = 0;
+            near.y = 0;
+            near.z = 0;
+            const found = colliders.query(x - radius, y - radius, z - radius, x + radius, y + radius, z + radius, hits);
+            let best = radius * radius;
+            for (let i = 0; i < found; i += 1) {
+                const index = hits[i];
+                colliders.bounds(index, box);
+                /* The closest point on the box, which is the clamp and nothing more. Inside it, the clamp
+                   is the query point itself and the distance is zero — which is the right answer for a
+                   character standing in a wall and the one a square root would also give. */
+                const px = x < box.minX ? box.minX : x > box.maxX ? box.maxX : x;
+                const py = y < box.minY ? box.minY : y > box.maxY ? box.maxY : y;
+                const pz = z < box.minZ ? box.minZ : z > box.maxZ ? box.maxZ : z;
+                const dx = px - x;
+                const dy = py - y;
+                const dz = pz - z;
+                const squared = dx * dx + dy * dy + dz * dz;
+                /* Squared throughout the scan and rooted once at the end: the comparison is the same and
+                   this runs over every candidate the hash returned, every frame an agent looks around. */
+                if (squared > best)
+                    continue;
+                best = squared;
+                near.collider = index;
+                near.distance = squared;
+                near.x = px;
+                near.y = py;
+                near.z = pz;
+            }
+            if (near.collider < 0)
+                return false;
+            near.distance = Math.sqrt(near.distance);
+            return true;
+        },
+        nearCollider: (colliders) => nearOf(colliders).collider,
+        nearX: (colliders) => f(nearOf(colliders).x),
+        nearY: (colliders) => f(nearOf(colliders).y),
+        nearZ: (colliders) => f(nearOf(colliders).z),
+        nearDistance: (colliders) => f(nearOf(colliders).distance),
+        bodyCount: (world) => world.bodies.count,
+        bodyX: (world, body) => f(world.bodies.posX[body] ?? 0),
+        bodyY: (world, body) => f(world.bodies.posY[body] ?? 0),
+        bodyZ: (world, body) => f(world.bodies.posZ[body] ?? 0),
+        bodyVelX: (world, body) => f(world.bodies.velX[body] ?? 0),
+        bodyVelY: (world, body) => f(world.bodies.velY[body] ?? 0),
+        bodyVelZ: (world, body) => f(world.bodies.velZ[body] ?? 0),
+        bodyMass: (world, body) => f(world.bodyMass(body)),
+        sleeping: (world, body) => world.sleeping(body),
+        raycast(world, x, y, z, dx, dy, dz, maxDistance, mask) {
+            filter.mask = mask;
+            return world.raycast(x, y, z, dx, dy, dz, maxDistance, hitOf(world), filter);
+        },
+        hitBody: (world) => hitOf(world).body,
+        hitX: (world) => f(hitOf(world).x),
+        hitY: (world) => f(hitOf(world).y),
+        hitZ: (world) => f(hitOf(world).z),
+        hitNormalX: (world) => f(hitOf(world).nx),
+        hitNormalY: (world) => f(hitOf(world).ny),
+        hitNormalZ: (world) => f(hitOf(world).nz),
+        hitFraction: (world) => f(hitOf(world).fraction),
+        contactCount: (world) => world.events.count,
+        contactKind: (world, index) => world.events.data[index * 3] ?? 0,
+        contactA: (world, index) => world.events.data[index * 3 + 1] ?? 0,
+        contactB: (world, index) => world.events.data[index * 3 + 2] ?? 0,
+        applyImpulse: (world, body, px, py, pz, atX, atY, atZ) => world.applyImpulse(body, px, py, pz, atX, atY, atZ),
+        applyForce: (world, body, fx, fy, fz, dt, atX, atY, atZ) => world.applyForce(body, fx, fy, fz, dt, atX, atY, atZ),
+        setVelocity: (world, body, vx, vy, vz) => world.setVelocity(body, vx, vy, vz),
+        setPosition: (world, body, x, y, z) => world.setPosition(body, x, y, z),
+        wake: (world, body) => world.wakeIsland(body),
+        setGravity(world, x, y, z) {
+            world.gravityX = x;
+            world.gravityY = y;
+            world.gravityZ = z;
+        },
+    };
+}
+export function inputImplementation() {
+    const scratch = { x: 0, y: 0 };
+    return {
+        down: (actions, action) => actions.down(action),
+        pressed: (actions, action) => actions.pressed(action),
+        axisX(actions, action) {
+            /* One scratch object reused, because `vector` writes into an out-parameter and a fresh
+               literal per call would allocate on a path a script runs every frame. */
+            actions.vector(action, scratch);
+            return f(scratch.x);
+        },
+        axisY(actions, action) {
+            actions.vector(action, scratch);
+            return f(scratch.y);
+        },
+        /* No scratch: `axis` returns the number rather than filling an out-parameter, because one axis
+           is one value and there was nothing to write into. */
+        rawAxisX: (actions, action) => f(actions.axis(action, 'x')),
+        rawAxisY: (actions, action) => f(actions.axis(action, 'y')),
+        canRumble: (actions) => actions.canRumble,
+        rumble: (actions, durationMs, strong, weak) => actions.rumble(durationMs, strong, weak),
+        stopRumble: (actions) => actions.stopRumble(),
+    };
+}
+export function cameraImplementation() {
+    /* Called directly, with no optional-call cast anywhere. A cast that tolerates a missing method is
+       a binding that cannot fail when the engine renames one — which is how the first version of this
+       described two methods the class does not have. */
+    return {
+        snap: (camera) => camera.snap(),
+        shotAge: (camera) => f(camera.shotAgeSec),
+    };
+}
+/* Referenced so the imports that document what this binds are not dropped as unused. `mulberry32`,
+   `angleDelta` and `wrapAngle` are the engine's, named here because a reader looking for what a
+   binding dispatches to should find it in one place. */
+void mulberry32;
+void angleDelta;
+void wrapAngle;