@driftengine/script 3.61.0

package/dist/bindings/rollback.d.ts

@@ -0,0 +1,41 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const ROLLBACK_MODULE = "drift/rollback";
+/**
+ * `drift/rollback` — what a script can ask about the rewind it is running inside.
+ *
+ * **Every capability here is `nondeterministic`, and that is the whole design.** The obvious reading
+ * is that these are reads and reads are cheap, so they should be as permissive as possible. The
+ * opposite is true, and the reason is the thing being read: *whether this tick is a replay*, *how
+ * far back the loop can still reach*, *which ticks are settled*. All of them move with packet
+ * timing, and a `@deterministic` system that branched on one would take a different path live than
+ * on replay — producing a world that differs from the world it is replaying, for a reason that
+ * looks nothing like a networking bug.
+ *
+ * That is the same call `bindings/ui.ts` made for `hovered` and `pressed`, and `bindings/network.ts`
+ * makes for the confirmed watermark. Stated once more here because this is the module where getting
+ * it wrong would be most tempting and least visible.
+ *
+ * ## `isReplaying` is the one worth being explicit about
+ *
+ * A script asking "am I being replayed" is almost always about to do something that should not
+ * happen twice — play a sound, spawn a particle, send a message. **That is a legitimate use and it
+ * is precisely why the effect is what it is**: the function doing it is not a simulation function,
+ * it is a presentation function that happens to run beside one, and the annotation should say so.
+ *
+ * A script using it to change *simulation* state is writing a bug, and nothing here can stop that.
+ * What it can do is make the deterministic annotation refuse to compile over it, which is the
+ * difference between a bug that is found by the checker and one that is found by two players
+ * disagreeing about who won.
+ *
+ * ## There is no `rollback.read` effect and this does not add one
+ *
+ * The language named `behavior.read` and `behavior.write` ahead of their provider precisely so a
+ * track would not need a release first, and it named `network.read` and `network.write` the same
+ * way — but nothing for rollback. `nondeterministic` is honest for every capability here, so no
+ * release is needed. *Reversed by* a consumer who wants a `@deterministic` function to read
+ * something in this module, at which point the question is which capability and why, and the answer
+ * is a one-line change to the `Effect` union.
+ */
+export declare const ROLLBACK_TYPES: readonly OpaqueType[];
+export declare const ROLLBACK_CAPABILITIES: readonly CapabilityDefinition[];
+export declare function rollbackImplementation(): Record<string, unknown>;

package/dist/bindings/rollback.js

@@ -0,0 +1,74 @@
+import { defineCapability } from 'driftscript';
+export const ROLLBACK_MODULE = 'drift/rollback';
+/**
+ * `drift/rollback` — what a script can ask about the rewind it is running inside.
+ *
+ * **Every capability here is `nondeterministic`, and that is the whole design.** The obvious reading
+ * is that these are reads and reads are cheap, so they should be as permissive as possible. The
+ * opposite is true, and the reason is the thing being read: *whether this tick is a replay*, *how
+ * far back the loop can still reach*, *which ticks are settled*. All of them move with packet
+ * timing, and a `@deterministic` system that branched on one would take a different path live than
+ * on replay — producing a world that differs from the world it is replaying, for a reason that
+ * looks nothing like a networking bug.
+ *
+ * That is the same call `bindings/ui.ts` made for `hovered` and `pressed`, and `bindings/network.ts`
+ * makes for the confirmed watermark. Stated once more here because this is the module where getting
+ * it wrong would be most tempting and least visible.
+ *
+ * ## `isReplaying` is the one worth being explicit about
+ *
+ * A script asking "am I being replayed" is almost always about to do something that should not
+ * happen twice — play a sound, spawn a particle, send a message. **That is a legitimate use and it
+ * is precisely why the effect is what it is**: the function doing it is not a simulation function,
+ * it is a presentation function that happens to run beside one, and the annotation should say so.
+ *
+ * A script using it to change *simulation* state is writing a bug, and nothing here can stop that.
+ * What it can do is make the deterministic annotation refuse to compile over it, which is the
+ * difference between a bug that is found by the checker and one that is found by two players
+ * disagreeing about who won.
+ *
+ * ## There is no `rollback.read` effect and this does not add one
+ *
+ * The language named `behavior.read` and `behavior.write` ahead of their provider precisely so a
+ * track would not need a release first, and it named `network.read` and `network.write` the same
+ * way — but nothing for rollback. `nondeterministic` is honest for every capability here, so no
+ * release is needed. *Reversed by* a consumer who wants a `@deterministic` function to read
+ * something in this module, at which point the question is which capability and why, and the answer
+ * is a one-line change to the `Effect` union.
+ */
+export const ROLLBACK_TYPES = [
+    {
+        module: ROLLBACK_MODULE,
+        name: 'Rewind',
+        doc: 'The rewind loop: which tick is running, whether this is a replay, and how far back it can reach.',
+    },
+];
+const define = (name, returns, doc) => defineCapability({
+    module: ROLLBACK_MODULE,
+    name,
+    signature: `fn(rewind: Rewind) -> ${returns}`,
+    params: [{ name: 'rewind', type: 'Rewind' }],
+    returns,
+    effects: ['nondeterministic'],
+    deterministic: false,
+    doc,
+    implementation: `${ROLLBACK_MODULE}.${name}`,
+});
+export const ROLLBACK_CAPABILITIES = [
+    define('tick', 'i32', 'The last tick that was stepped, or -1 before the first.'),
+    define('isReplaying', 'bool', 'Whether this tick is being re-run to correct a mispredicted one. Anything that should not happen twice — a sound, a particle, a message — asks this first.'),
+    define('depth', 'i32', 'How many ticks back a rewind can reach. Eight at 60 Hz is 133 milliseconds of correction.'),
+    define('earliest', 'i32', 'The oldest tick still retained, or -1. An input older than this cannot be applied and the session cannot be made correct.'),
+    define('replays', 'i32', 'How many rewinds have happened. A session correcting constantly has a link problem.'),
+    define('replayedTicks', 'i32', 'How many ticks those rewinds re-ran in total. Divided by `replays`, the average depth of a correction.'),
+];
+export function rollbackImplementation() {
+    return {
+        tick: (rewind) => rewind.tick,
+        isReplaying: (rewind) => rewind.isReplaying,
+        depth: (rewind) => rewind.depth,
+        earliest: (rewind) => rewind.earliest,
+        replays: (rewind) => rewind.stats.replays,
+        replayedTicks: (rewind) => rewind.stats.replayedTicks,
+    };
+}

package/dist/bindings/sprites.d.ts

@@ -0,0 +1,53 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const SPRITES_MODULE = "drift/2d";
+/**
+ * `drift/2d` — quads with a picture on them, and the grids of them.
+ *
+ * ```drs
+ * import { sprite, tilemap } from "drift/2d" as sprites
+ *
+ * fn hud(batch: SpriteBatch) {
+ *     sprites.sprite(batch, 0, 10, 10, 32, 32)
+ * }
+ * ```
+ *
+ * **The `as` is not decoration and this module is why the language has it.** A capability is reached
+ * through a namespace and the namespace was the last segment of the path, so a call here would have
+ * been `2d.sprite(...)` — a number followed by an identifier, refused by the lexer before the
+ * checker saw it. This binding was written on 2026-09-03, wired, found uncallable, and **withdrawn
+ * rather than shipped**, because a capability nobody can spell is the silent no-op this repository
+ * forbids wearing a feature's clothes. DriftScript 1.11.0 answered it at the import, and the
+ * language's own changelog carries the five spellings that were tried and failed.
+ *
+ * So a script naming this module must name the namespace too, and `DS0139` says so at the import
+ * with the line to write rather than leaving an author at `DS0003` inside their own call.
+ *
+ * ## The effects, and why this one needed nothing from the language
+ *
+ * Unlike `drift/terrain`, this module met no wall on effects. **A sprite is a thing that draws**,
+ * and `scene.write` is exactly what the language reserves for that — its own comment says a
+ * `SceneNode` "is what *draws*", and that writing one is a change to the view rather than to the
+ * simulation. Everything here that puts a quad in a batch is declared that way, and it is outside
+ * `DETERMINISTIC_EFFECTS` for the right reason: a `@deterministic` system decides where things
+ * *are*, and something else draws them.
+ *
+ * **Reading a sheet or a tile is `scene.read`**, which is inside the boundary, so a deterministic
+ * system may ask what frame a name is or what is in a cell. That asymmetry is the honest one:
+ * looking at the view is a read of state the simulation already produced.
+ *
+ * **`setTile` is a write to the view and is outside**, which is worth being explicit about because
+ * it reads as a limitation and is not one. A `Tilemap` here is *drawing* data — its cells are frame
+ * indices into a sheet, and `tilemap.ts` says so in its first line. A game's collision grid is the
+ * game's own array and is not this. A deterministic system that wants to dig a hole changes its own
+ * grid and lets a drawing system follow.
+ */
+export declare const SPRITES_TYPES: readonly OpaqueType[];
+export declare const SPRITES_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * **No services, and that is the shape rather than an omission.**
+ *
+ * Every capability takes the batch, sheet or map it acts on, so the module needs nothing from the
+ * host to answer — they reach a script through `uses`, the way a `Terrain` and a `NavGraph` do. So
+ * this is registered unconditionally, and a script that never receives a batch never calls it.
+ */
+export declare function spritesImplementation(): Record<string, unknown>;

package/dist/bindings/sprites.js

@@ -0,0 +1,186 @@
+import { createSpriteFrame, drawSprite, drawTilemap, frameOf, setTile, sheetFrame, tileAt, } from '@driftengine/ui2d';
+import { defineCapability } from 'driftscript';
+export const SPRITES_MODULE = 'drift/2d';
+/**
+ * `drift/2d` — quads with a picture on them, and the grids of them.
+ *
+ * ```drs
+ * import { sprite, tilemap } from "drift/2d" as sprites
+ *
+ * fn hud(batch: SpriteBatch) {
+ *     sprites.sprite(batch, 0, 10, 10, 32, 32)
+ * }
+ * ```
+ *
+ * **The `as` is not decoration and this module is why the language has it.** A capability is reached
+ * through a namespace and the namespace was the last segment of the path, so a call here would have
+ * been `2d.sprite(...)` — a number followed by an identifier, refused by the lexer before the
+ * checker saw it. This binding was written on 2026-09-03, wired, found uncallable, and **withdrawn
+ * rather than shipped**, because a capability nobody can spell is the silent no-op this repository
+ * forbids wearing a feature's clothes. DriftScript 1.11.0 answered it at the import, and the
+ * language's own changelog carries the five spellings that were tried and failed.
+ *
+ * So a script naming this module must name the namespace too, and `DS0139` says so at the import
+ * with the line to write rather than leaving an author at `DS0003` inside their own call.
+ *
+ * ## The effects, and why this one needed nothing from the language
+ *
+ * Unlike `drift/terrain`, this module met no wall on effects. **A sprite is a thing that draws**,
+ * and `scene.write` is exactly what the language reserves for that — its own comment says a
+ * `SceneNode` "is what *draws*", and that writing one is a change to the view rather than to the
+ * simulation. Everything here that puts a quad in a batch is declared that way, and it is outside
+ * `DETERMINISTIC_EFFECTS` for the right reason: a `@deterministic` system decides where things
+ * *are*, and something else draws them.
+ *
+ * **Reading a sheet or a tile is `scene.read`**, which is inside the boundary, so a deterministic
+ * system may ask what frame a name is or what is in a cell. That asymmetry is the honest one:
+ * looking at the view is a read of state the simulation already produced.
+ *
+ * **`setTile` is a write to the view and is outside**, which is worth being explicit about because
+ * it reads as a limitation and is not one. A `Tilemap` here is *drawing* data — its cells are frame
+ * indices into a sheet, and `tilemap.ts` says so in its first line. A game's collision grid is the
+ * game's own array and is not this. A deterministic system that wants to dig a hole changes its own
+ * grid and lets a drawing system follow.
+ */
+export const SPRITES_TYPES = [
+    {
+        module: SPRITES_MODULE,
+        name: 'SpriteBatch',
+        doc: 'One frame of quads, in the order they were put in. Reset it, fill it, draw it.',
+    },
+    {
+        module: SPRITES_MODULE,
+        name: 'SpriteSheet',
+        doc: 'The rectangles of one texture that each hold a picture, addressed by index or by name.',
+    },
+    {
+        module: SPRITES_MODULE,
+        name: 'Tilemap',
+        doc: 'A grid of sheet frames. Drawing one costs the view rather than the map.',
+    },
+];
+const define = (name, params, returns, effects, doc) => defineCapability({
+    module: SPRITES_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: [...effects],
+    /*
+     * Every float here is `f32` and none is `float`. `float` is width-polymorphic and takes its
+     * width from another `float`, so a capability returning one must take one — a rule Track L paid
+     * for. Nothing here returns a float at all, and a batch stores its instances as `Float32Array`,
+     * so `f32` is what the number actually is rather than a width chosen to satisfy a checker.
+     */
+    deterministic: !effects.includes('scene.write'),
+    doc,
+    implementation: `${SPRITES_MODULE}.${name}`,
+});
+const AT = [
+    { name: 'x', type: 'f32' },
+    { name: 'y', type: 'f32' },
+    { name: 'w', type: 'f32' },
+    { name: 'h', type: 'f32' },
+];
+export const SPRITES_CAPABILITIES = [
+    define('sprite', [{ name: 'batch', type: 'SpriteBatch' }, { name: 'texture', type: 'i32' }, ...AT], 'void', ['scene.write'], 'Put one quad in the batch, covering the whole of a texture.'),
+    define('tinted', [
+        { name: 'batch', type: 'SpriteBatch' },
+        { name: 'texture', type: 'i32' },
+        ...AT,
+        { name: 'r', type: 'f32' },
+        { name: 'g', type: 'f32' },
+        { name: 'b', type: 'f32' },
+        { name: 'a', type: 'f32' },
+    ], 'void', ['scene.write'], 'The same, multiplied by a colour. White is the identity, so a white texture draws exactly this colour — which is how a solid rectangle is drawn.'),
+    define('frame', [
+        { name: 'batch', type: 'SpriteBatch' },
+        { name: 'sheet', type: 'SpriteSheet' },
+        { name: 'frame', type: 'i32' },
+        ...AT,
+    ], 'void', ['scene.write'], 'Put one frame of a sheet in the batch. A frame the sheet does not have draws the whole sheet, which is unmistakable.'),
+    define('named', [
+        { name: 'sheet', type: 'SpriteSheet' },
+        { name: 'name', type: 'String' },
+    ], 'i32', ['scene.read'], 'The index a name has in a sheet, or -1. Ask once and keep the number: a name lookup is a hash and a frame is an array read.'),
+    define('frames', [{ name: 'sheet', type: 'SpriteSheet' }], 'i32', ['scene.read'], 'How many frames the sheet was cut into.'),
+    define('tilemap', [
+        { name: 'batch', type: 'SpriteBatch' },
+        { name: 'map', type: 'Tilemap' },
+        { name: 'sheet', type: 'SpriteSheet' },
+        ...AT,
+    ], 'i32', ['scene.write'], 'Draw the tiles a view rectangle can see, and answer how many that was. The cost is the view rather than the map.'),
+    define('tile', [
+        { name: 'map', type: 'Tilemap' },
+        { name: 'column', type: 'i32' },
+        { name: 'row', type: 'i32' },
+    ], 'i32', ['scene.read'], 'The frame in a cell, or -1 for an empty one — including for a cell outside the map, which answers empty rather than another row.'),
+    define('setTile', [
+        { name: 'map', type: 'Tilemap' },
+        { name: 'column', type: 'i32' },
+        { name: 'row', type: 'i32' },
+        { name: 'tile', type: 'i32' },
+    ], 'void', ['scene.write'], 'Put a frame in a cell. A cell outside the map is ignored rather than wrapping into another row.'),
+    define('columns', [{ name: 'map', type: 'Tilemap' }], 'i32', ['scene.read'], 'How wide the map is, in cells.'),
+    define('rows', [{ name: 'map', type: 'Tilemap' }], 'i32', ['scene.read'], 'How tall the map is, in cells.'),
+    define('count', [{ name: 'batch', type: 'SpriteBatch' }], 'i32', ['scene.read'], 'How many quads are in the batch this frame.'),
+    /*
+     * **A script can see the batch overflow, which is the whole reason this is exposed.** The batch
+     * does not grow: past its capacity a draw is counted and dropped, and a caller with no way to
+     * read that count finds out by noticing something missing from a corner of the screen.
+     */
+    define('dropped', [{ name: 'batch', type: 'SpriteBatch' }], 'i32', ['scene.read'], 'How many quads did not fit this frame. Zero is the only good value; anything else is a batch that wants a bigger capacity.'),
+];
+/**
+ * **No services, and that is the shape rather than an omission.**
+ *
+ * Every capability takes the batch, sheet or map it acts on, so the module needs nothing from the
+ * host to answer — they reach a script through `uses`, the way a `Terrain` and a `NavGraph` do. So
+ * this is registered unconditionally, and a script that never receives a batch never calls it.
+ */
+export function spritesImplementation() {
+    /* One frame rectangle for every `frame` call. These run per draw and may not allocate. */
+    const scratch = createSpriteFrame();
+    const place = { x: 0, y: 0, w: 0, h: 0 };
+    const tint = new Float32Array(4);
+    const view = { x: 0, y: 0, w: 0, h: 0 };
+    const at = (x, y, w, h) => {
+        place.x = x;
+        place.y = y;
+        place.w = w;
+        place.h = h;
+        return place;
+    };
+    return {
+        sprite: (batch, texture, x, y, w, h) => {
+            drawSprite(batch, texture, at(x, y, w, h), null, null);
+        },
+        tinted: (batch, texture, x, y, w, h, r, g, b, a) => {
+            tint[0] = r;
+            tint[1] = g;
+            tint[2] = b;
+            tint[3] = a;
+            drawSprite(batch, texture, at(x, y, w, h), null, tint);
+        },
+        frame: (batch, sheet, frame, x, y, w, h) => {
+            drawSprite(batch, sheet.texture, at(x, y, w, h), sheetFrame(sheet, frame, scratch), null);
+        },
+        named: (sheet, name) => frameOf(sheet, name),
+        frames: (sheet) => sheet.count,
+        tilemap: (batch, map, sheet, x, y, w, h) => {
+            view.x = x;
+            view.y = y;
+            view.w = w;
+            view.h = h;
+            return drawTilemap(batch, map, sheet, view, null);
+        },
+        tile: (map, column, row) => tileAt(map, column, row),
+        setTile: (map, column, row, tile) => {
+            setTile(map, column, row, tile);
+        },
+        columns: (map) => map.columns,
+        rows: (map) => map.rows,
+        count: (batch) => batch.count,
+        dropped: (batch) => batch.dropped,
+    };
+}

package/dist/bindings/terrain.d.ts

@@ -0,0 +1,54 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+export declare const TERRAIN_MODULE = "drift/terrain";
+/**
+ * `drift/terrain` — where the ground is, and which way it faces.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track L. It does not any more: `@driftengine/terrain` ships a heightfield whose query answers the
+ * surface that is *drawn*, which is the one property a script needs to be able to trust. A script
+ * placing a tree, deciding whether a slope is walkable, or dropping a dead body on the ground is
+ * asking this module and nothing else.
+ *
+ * **Every capability here is a read of static data**, so all of them are deterministic and a
+ * `@deterministic` system may ask where the ground is. That is the point — deciding where to stand
+ * belongs inside the fixed step.
+ *
+ * ## The effect these are declared under, and why it is not `terrain.read`
+ *
+ * **The language names no terrain effect.** `Effect` in `driftscript`'s registry runs from `pure`
+ * through `network.write`, and there is no `terrain.*` in it — `drift/terrain` is in
+ * `SPECIFIED_MODULES` and was missed when the effects were named. `drift/behavior` was in exactly
+ * this position and the language fixed it the other way round, naming `behavior.read` and
+ * `behavior.write` in 2026-08-28 *ahead of any provider*, with a comment saying it was so the track
+ * that built it would not need a language release first. Terrain did not get that.
+ *
+ * **This engine does not move the language's version**, which the navigation binding states where it
+ * meets the same wall. So the choice was between shipping under an effect that exists and not
+ * shipping.
+ *
+ * **`physics.read` is the one it ships under, and it is a description rather than a borrowing.**
+ * The terrain package's own tests assert that the surface a query answers, the surface that is
+ * drawn and the surface a body collides with are one surface — a ray cast against the mesh built
+ * from a patch lands where `heightAt` says the ground is. So "ask the terrain how high the ground
+ * is" and "cast a ray down and see what you hit" are the same question about the same surface, and
+ * the second is `physics.read` already. It is also in `DETERMINISTIC_EFFECTS`, which is what a
+ * script needs.
+ *
+ * **What would change it**: the language naming `terrain.read`. `docs/IMPROVEMENTS.md` carries that
+ * as a one-line change on the language's side and a one-word change here.
+ */
+export declare const TERRAIN_TYPES: readonly OpaqueType[];
+export declare const TERRAIN_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * **No services, and that is the shape rather than an omission.**
+ *
+ * Every capability here takes the field it is asking about, so the module needs nothing from the
+ * host to answer — the terrain reaches a script the way a `NavGraph` does, as a resource handed in
+ * through `uses`. `drift/animation` made the same move on 2026-08-28 when `blendTree` was replaced
+ * by `blendSet` and `blendAt`: drive a thing the host built, rather than offering to build one out
+ * of values the language has no shape for.
+ *
+ * So this is registered unconditionally, and a script that never receives a `Terrain` simply never
+ * calls it.
+ */
+export declare function terrainImplementation(): Record<string, unknown>;

package/dist/bindings/terrain.js

@@ -0,0 +1,138 @@
+import { exactAcos } from '@driftengine/core';
+import { defineCapability } from 'driftscript';
+export const TERRAIN_MODULE = 'drift/terrain';
+/**
+ * `drift/terrain` — where the ground is, and which way it faces.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track L. It does not any more: `@driftengine/terrain` ships a heightfield whose query answers the
+ * surface that is *drawn*, which is the one property a script needs to be able to trust. A script
+ * placing a tree, deciding whether a slope is walkable, or dropping a dead body on the ground is
+ * asking this module and nothing else.
+ *
+ * **Every capability here is a read of static data**, so all of them are deterministic and a
+ * `@deterministic` system may ask where the ground is. That is the point — deciding where to stand
+ * belongs inside the fixed step.
+ *
+ * ## The effect these are declared under, and why it is not `terrain.read`
+ *
+ * **The language names no terrain effect.** `Effect` in `driftscript`'s registry runs from `pure`
+ * through `network.write`, and there is no `terrain.*` in it — `drift/terrain` is in
+ * `SPECIFIED_MODULES` and was missed when the effects were named. `drift/behavior` was in exactly
+ * this position and the language fixed it the other way round, naming `behavior.read` and
+ * `behavior.write` in 2026-08-28 *ahead of any provider*, with a comment saying it was so the track
+ * that built it would not need a language release first. Terrain did not get that.
+ *
+ * **This engine does not move the language's version**, which the navigation binding states where it
+ * meets the same wall. So the choice was between shipping under an effect that exists and not
+ * shipping.
+ *
+ * **`physics.read` is the one it ships under, and it is a description rather than a borrowing.**
+ * The terrain package's own tests assert that the surface a query answers, the surface that is
+ * drawn and the surface a body collides with are one surface — a ray cast against the mesh built
+ * from a patch lands where `heightAt` says the ground is. So "ask the terrain how high the ground
+ * is" and "cast a ray down and see what you hit" are the same question about the same surface, and
+ * the second is `physics.read` already. It is also in `DETERMINISTIC_EFFECTS`, which is what a
+ * script needs.
+ *
+ * **What would change it**: the language naming `terrain.read`. `docs/IMPROVEMENTS.md` carries that
+ * as a one-line change on the language's side and a one-word change here.
+ */
+export const TERRAIN_TYPES = [
+    {
+        module: TERRAIN_MODULE,
+        name: 'Terrain',
+        doc: 'A heightfield: ask it how high the ground is and which way it faces.',
+    },
+];
+const define = (name, params, returns, doc) => defineCapability({
+    module: TERRAIN_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: ['physics.read'],
+    deterministic: true,
+    doc,
+    implementation: `${TERRAIN_MODULE}.${name}`,
+});
+const AT = [
+    { name: 'terrain', type: 'Terrain' },
+    { name: 'x', type: 'float' },
+    { name: 'z', type: 'float' },
+];
+export const TERRAIN_CAPABILITIES = [
+    define('heightAt', AT, 'float', 'How high the ground is at a place, in metres. The surface that is drawn, not an approximation of it, so a thing put here stands on what you can see.'),
+    /*
+     * **Three calls rather than one that returns a vector**, which is the shape `drift/physics`
+     * already uses for a body's position and `drift/navigation` for a steer point: the language
+     * returns one value, and the alternative is a search-then-read pair with state between the two.
+     * A normal is cheap enough that three independent reads beat a hidden cursor.
+     */
+    define('normalX', AT, 'float', 'Which way the ground faces at a place, along x.'),
+    define('normalY', AT, 'float', 'The same, along y. One on the flat and smaller on a slope.'),
+    define('normalZ', AT, 'float', 'The same, along z.'),
+    /*
+     * **The slope as an angle, because that is what a script actually asks.** Every use of a terrain
+     * normal in a script is "is this too steep" — for a footpath, for a building, for whether a cart
+     * rolls — and each of those written from three components is an `acos` of a dot product a script
+     * author has to get right. Radians from vertical: zero on the flat.
+     */
+    define('slopeAt', AT, 'float', 'How steep the ground is at a place, in radians from flat. Zero on the level; a quarter turn on a wall.'),
+    define('covers', AT, 'bool', 'Whether a place is over the field at all. A query outside it answers the nearest edge rather than nothing, so ask this first where it matters.'),
+    /*
+     * **`f32` rather than `float`, and the language is right to insist.** `float` is width-polymorphic
+     * and takes its width from a `float` parameter; these take none, so nothing would fix it. A field
+     * is stored as `Float32Array`, so `f32` is what the number actually is rather than a width chosen
+     * to satisfy a checker.
+     */
+    define('extentX', [{ name: 'terrain', type: 'Terrain' }], 'f32', 'How far the field reaches along x, in metres.'),
+    define('extentZ', [{ name: 'terrain', type: 'Terrain' }], 'f32', 'How far the field reaches along z, in metres.'),
+];
+/**
+ * **No services, and that is the shape rather than an omission.**
+ *
+ * Every capability here takes the field it is asking about, so the module needs nothing from the
+ * host to answer — the terrain reaches a script the way a `NavGraph` does, as a resource handed in
+ * through `uses`. `drift/animation` made the same move on 2026-08-28 when `blendTree` was replaced
+ * by `blendSet` and `blendAt`: drive a thing the host built, rather than offering to build one out
+ * of values the language has no shape for.
+ *
+ * So this is registered unconditionally, and a script that never receives a `Terrain` simply never
+ * calls it.
+ */
+export function terrainImplementation() {
+    /* One scratch for every normal read, because these run inside the fixed step and the frame rules
+       forbid allocating there. Reused rather than returned: each capability answers one number. */
+    const normal = new Float32Array(3);
+    const at = (terrain, x, z) => terrain.normalAt(x, z, normal);
+    return {
+        heightAt: (terrain, x, z) => terrain.heightAt(x, z),
+        normalX: (terrain, x, z) => at(terrain, x, z)[0] ?? 0,
+        normalY: (terrain, x, z) => at(terrain, x, z)[1] ?? 1,
+        normalZ: (terrain, x, z) => at(terrain, x, z)[2] ?? 0,
+        slopeAt: (terrain, x, z) => {
+            /*
+             * `exactAcos` of the upward component, clamped: a normal is a unit vector in exact arithmetic
+             * and a hair outside the domain in float, where `acos` answers NaN rather than zero.
+             *
+             * **`Math.acos` until 2026-09-03, and that was a defect rather than a tidiness point.**
+             * `drift/terrain` ships under `physics.read`, which is inside the language's
+             * `DETERMINISTIC_EFFECTS`, so a `@deterministic` system asking a hillside how steep it is was
+             * receiving a number ECMAScript does not specify — two engines may answer an ulp apart, and
+             * the annotation promising the system replays identically was false for anything that
+             * branched on the answer. Found by widening `scripts/determinism.mjs` past the one package it
+             * had scanned since Track B.
+             */
+            const up = Math.min(1, Math.max(-1, at(terrain, x, z)[1] ?? 1));
+            return exactAcos(up);
+        },
+        covers: (terrain, x, z) => {
+            const u = x - (terrain.origin[0] ?? 0);
+            const v = z - (terrain.origin[2] ?? 0);
+            return u >= 0 && v >= 0 && u <= terrain.extentX && v <= terrain.extentZ;
+        },
+        extentX: (terrain) => terrain.extentX,
+        extentZ: (terrain) => terrain.extentZ,
+    };
+}

package/dist/bindings/xr.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `drift/xr` — what a script may ask about a headset, and what it may not.
+ *
+ * **The last surface the linker refused, and it refused it since 1.0.** `drift/xr` has been in the
+ * language's `SPECIFIED_MODULES` the whole time with nothing here describing it, which is exactly
+ * the arrangement the language exists to make possible: a file naming it parsed, type-checked and
+ * declined only at link time, and the same file links now without a character changing.
+ *
+ * ## Nothing here is deterministic, and that is the property
+ *
+ * A head moves because somebody moved their head. A controller reports where it is because a camera
+ * saw it. None of that is a function of the simulation, so none of it may be read from inside the
+ * fixed step: a `@deterministic` system branching on where a hand is would take the other branch on
+ * replay, and a stored run would stop meaning anything.
+ *
+ * `drift/ui` settled the same question for a pointer, and the reasoning transfers unchanged: its
+ * `hovered` and `pressed` are fields on a tree that `scene.read` would have type-checked and would
+ * have been a lie about what they carry, so they were declared `input.read` and left outside
+ * `DETERMINISTIC_EFFECTS`. A head and a hand are the same kind of fact arriving through the same
+ * door.
+ *
+ * ## No matrices, and the argument is `drift/render`'s
+ *
+ * There is no `xr.projection` and no `xr.viewMatrix`. An eye's projection is a fact about somebody's
+ * optics, and its view is a fact about where their head is in a room the script has never seen;
+ * handing either to a script would be `drift/render`'s refused dial read in a different costume, a
+ * machine-dependent number registered where a script could compare two runs with it.
+ *
+ * What a script gets is where the head is, whether a session is running, and what the hands are
+ * doing. Drawing the two eyes is the host's, because the host owns the renderer and the loop.
+ *
+ * ## `presenting` is `scene.read` and the rest is `input.read`
+ *
+ * Whether a session is running is a fact about the view: it decides what is drawn and where, and it
+ * changes when somebody puts a headset on. `scene.read` sits outside `DETERMINISTIC_EFFECTS` for
+ * that reason, which is the one this needs.
+ */
+import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
+import type { ControllerState, HandSkeleton, Handedness, XrSupport } from '@driftengine/xr';
+export declare const XR_MODULE = "drift/xr";
+export declare const XR_TYPES: readonly OpaqueType[];
+export declare const XR_CAPABILITIES: readonly CapabilityDefinition[];
+/**
+ * What the host keeps up to date, and what a script reads through.
+ *
+ * The consumer's, exactly as `AgentRegistry` and `SoundRegistry` are. This package owns neither the
+ * session nor the frame, and which of them is current is not something a binding can know.
+ */
+export interface XrRuntime {
+    readonly support: XrSupport | null;
+    /** Null outside a session. */
+    readonly headPosition: Float32Array | null;
+    controller(hand: Handedness): ControllerState | null;
+    hand(hand: Handedness): HandSkeleton | null;
+}
+export declare function xrImplementation(runtime: XrRuntime): Readonly<Record<string, unknown>>;