@driftengine/script 3.61.0

package/src/bindings/sprites.ts

@@ -0,0 +1,310 @@
+import type { SpriteBatch, SpriteSheet, Tilemap } from '@driftengine/ui2d';
+import {
+  createSpriteFrame,
+  drawSprite,
+  drawTilemap,
+  frameOf,
+  setTile,
+  sheetFrame,
+  tileAt,
+} from '@driftengine/ui2d';
+import type { CapabilityDefinition, Effect, OpaqueType } from 'driftscript';
+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: readonly OpaqueType[] = [
+  {
+    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: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: readonly Effect[],
+  doc: string,
+): CapabilityDefinition =>
+  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' },
+] as const;
+
+export const SPRITES_CAPABILITIES: readonly CapabilityDefinition[] = [
+  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(): Record<string, unknown> {
+  /* 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: number, y: number, w: number, h: number): typeof place => {
+    place.x = x;
+    place.y = y;
+    place.w = w;
+    place.h = h;
+    return place;
+  };
+
+  return {
+    sprite: (batch: SpriteBatch, texture: number, x: number, y: number, w: number, h: number) => {
+      drawSprite(batch, texture, at(x, y, w, h), null, null);
+    },
+    tinted: (
+      batch: SpriteBatch,
+      texture: number,
+      x: number,
+      y: number,
+      w: number,
+      h: number,
+      r: number,
+      g: number,
+      b: number,
+      a: number,
+    ) => {
+      tint[0] = r;
+      tint[1] = g;
+      tint[2] = b;
+      tint[3] = a;
+      drawSprite(batch, texture, at(x, y, w, h), null, tint);
+    },
+    frame: (
+      batch: SpriteBatch,
+      sheet: SpriteSheet,
+      frame: number,
+      x: number,
+      y: number,
+      w: number,
+      h: number,
+    ) => {
+      drawSprite(batch, sheet.texture, at(x, y, w, h), sheetFrame(sheet, frame, scratch), null);
+    },
+    named: (sheet: SpriteSheet, name: string) => frameOf(sheet, name),
+    frames: (sheet: SpriteSheet) => sheet.count,
+    tilemap: (
+      batch: SpriteBatch,
+      map: Tilemap,
+      sheet: SpriteSheet,
+      x: number,
+      y: number,
+      w: number,
+      h: number,
+    ) => {
+      view.x = x;
+      view.y = y;
+      view.w = w;
+      view.h = h;
+      return drawTilemap(batch, map, sheet, view, null);
+    },
+    tile: (map: Tilemap, column: number, row: number) => tileAt(map, column, row),
+    setTile: (map: Tilemap, column: number, row: number, tile: number) => {
+      setTile(map, column, row, tile);
+    },
+    columns: (map: Tilemap) => map.columns,
+    rows: (map: Tilemap) => map.rows,
+    count: (batch: SpriteBatch) => batch.count,
+    dropped: (batch: SpriteBatch) => batch.dropped,
+  };
+}

package/src/bindings/terrain.ts

@@ -0,0 +1,180 @@
+import { exactAcos } from '@driftengine/core';
+import type { Terrain } from '@driftengine/terrain';
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+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: readonly OpaqueType[] = [
+  {
+    module: TERRAIN_MODULE,
+    name: 'Terrain',
+    doc: 'A heightfield: ask it how high the ground is and which way it faces.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  doc: string,
+): CapabilityDefinition =>
+  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' },
+] as const;
+
+export const TERRAIN_CAPABILITIES: readonly CapabilityDefinition[] = [
+  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(): Record<string, unknown> {
+  /* 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: Terrain, x: number, z: number): Float32Array =>
+    terrain.normalAt(x, z, normal);
+
+  return {
+    heightAt: (terrain: Terrain, x: number, z: number) => terrain.heightAt(x, z),
+    normalX: (terrain: Terrain, x: number, z: number) => at(terrain, x, z)[0] ?? 0,
+    normalY: (terrain: Terrain, x: number, z: number) => at(terrain, x, z)[1] ?? 1,
+    normalZ: (terrain: Terrain, x: number, z: number) => at(terrain, x, z)[2] ?? 0,
+    slopeAt: (terrain: Terrain, x: number, z: number) => {
+      /*
+       * `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: Terrain, x: number, z: number) => {
+      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) => terrain.extentX,
+    extentZ: (terrain: Terrain) => terrain.extentZ,
+  };
+}