@driftengine/script 3.61.0

package/src/bindings/network.ts

@@ -0,0 +1,178 @@
+import type { ScriptSession } from '@driftengine/network';
+import type { CapabilityDefinition, Effect, OpaqueType } from 'driftscript';
+import { defineCapability } from 'driftscript';
+
+export const NETWORK_MODULE = 'drift/network';
+
+/**
+ * `drift/network` — what a script can see of a session, and the scalars it can publish.
+ *
+ * **The linker has refused this module by name since the language shipped**, saying it waits on
+ * Track J. The corpus carries `NetworkReplicatedActor.drs`, written *before* any provider existed
+ * so that "the networking semantics are written down before networking couples itself to the state
+ * and task design". Its names are honoured here — `replicate` and `authority` are both capabilities
+ * — and its one illustrative call is not: it reads `network.replicate(character.x, character.y)`, with no
+ * session, because when it was written there was no handle to take. Every capability takes the
+ * thing it is about, the way every other binding in this directory does.
+ *
+ * ---
+ *
+ * ## The effect split, which the language asked this track to make
+ *
+ * `capability.ts` puts `network.read` **inside** `DETERMINISTIC_EFFECTS` and leaves `network.write`
+ * outside, with a note that the exclusion is *"a deferral rather than a judgement: each belongs to a
+ * track that has not shipped, and the track that builds one is the one that can say whether its
+ * writes are the simulation or a consequence of it."* This is that track, so here is the answer.
+ *
+ * **`network.write` stays outside, and the rollback loop is the reason.** The tempting argument for
+ * admitting it is that publishing a value changes no simulation state, so a replay would publish
+ * the same thing and nothing would drift. That argument is exactly backwards once a rewind exists:
+ * **a `@deterministic` function is precisely the kind that gets re-run**, several times, over ticks
+ * that have already happened. A send is not idempotent — the replay would publish the same value
+ * again for a tick a peer already has, and a correction that replayed twelve ticks would put twelve
+ * duplicate messages on the wire. Deferring the effect was right and the deferral now has a reason
+ * behind it rather than an absence.
+ *
+ * **`network.read` is kept for the two things that genuinely do not vary**: which participant this
+ * is, and whether this peer is the authority. Both are fixed when the session is created, so a
+ * `@deterministic` system may branch on them and replay identically.
+ *
+ * **Everything else a session knows is `nondeterministic`, and that is not pedantry.** The confirmed
+ * watermark, the participant count and whether the session has halted all move with packet timing:
+ * a system that branched on "is tick 400 confirmed" would take one path live and the other on
+ * replay, which is the class of bug rollback netcode is famous for. `bindings/ui.ts` made the same
+ * call for `hovered` and `pressed`, and this file's version of that sentence is: an effect that
+ * type-checks can still be a lie.
+ *
+ * ## Slots rather than field names
+ *
+ * `replicate(session, slot, value)` writes into a numbered table. A name would need a string map on
+ * a per-tick path and a miss would need an optional to answer with, which the language does not
+ * have. A slot out of range does nothing on write and answers zero on read, so both are total.
+ */
+export const NETWORK_TYPES: readonly OpaqueType[] = [
+  {
+    module: NETWORK_MODULE,
+    name: 'Session',
+    doc: 'A networking session: who this peer is, what it can see of the others, and the scalars it publishes.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: readonly Effect[],
+  deterministic: boolean,
+  doc: string,
+): CapabilityDefinition =>
+  defineCapability({
+    module: NETWORK_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects: [...effects],
+    deterministic,
+    doc,
+    implementation: `${NETWORK_MODULE}.${name}`,
+  });
+
+const ON = [{ name: 'session', type: 'Session' }] as const;
+
+export const NETWORK_CAPABILITIES: readonly CapabilityDefinition[] = [
+  /* The two that do not move. See the header for why only these two. */
+  define(
+    'self',
+    ON,
+    'i32',
+    ['network.read'],
+    true,
+    'Which participant this peer is. Fixed for the life of the session, which is why a deterministic system may read it.',
+  ),
+  define(
+    'authority',
+    ON,
+    'bool',
+    ['network.read'],
+    true,
+    'Whether this peer’s world is the authoritative one. Fixed when the session is created.',
+  ),
+
+  /* Everything that moves with packet timing. */
+  define(
+    'participants',
+    ON,
+    'i32',
+    ['nondeterministic'],
+    false,
+    'How many participants the session holds. Nondeterministic because somebody may join or leave between two runs of the same recording.',
+  ),
+  define(
+    'confirmed',
+    ON,
+    'i32',
+    ['nondeterministic'],
+    false,
+    'The highest tick every participant’s input has arrived for, or -1. Moves with packet timing, so a deterministic system may not branch on it.',
+  ),
+  define(
+    'halted',
+    ON,
+    'bool',
+    ['nondeterministic'],
+    false,
+    'Whether the session has stopped, because an input arrived too late to apply or two peers computed different worlds.',
+  ),
+  define(
+    'haltReason',
+    ON,
+    'String',
+    ['nondeterministic'],
+    false,
+    'Why it halted, as a sentence, or an empty string. Names the tick a divergence began at.',
+  ),
+  define(
+    'slots',
+    ON,
+    'i32',
+    ['nondeterministic'],
+    false,
+    'How many replicated scalars each participant has. A consumer sizes this when the session is made.',
+  ),
+  define(
+    'replicated',
+    [...ON, { name: 'participant', type: 'i32' }, { name: 'slot', type: 'i32' }],
+    'f32',
+    ['nondeterministic'],
+    false,
+    'Read a participant’s published scalar. An index out of range answers zero rather than failing, because a frame loop has nothing to do with a refusal.',
+  ),
+
+  /* And the one write. */
+  define(
+    'replicate',
+    [...ON, { name: 'slot', type: 'i32' }, { name: 'value', type: 'f32' }],
+    'void',
+    ['network.write'],
+    false,
+    'Publish a value in one of this peer’s slots. Not callable from a deterministic system: a replay re-runs one and a send is not idempotent.',
+  ),
+];
+
+export function networkImplementation(): Record<string, unknown> {
+  return {
+    self: (session: ScriptSession) => session.self,
+    authority: (session: ScriptSession) => session.authority,
+    participants: (session: ScriptSession) => session.participants,
+    confirmed: (session: ScriptSession) => session.confirmed,
+    halted: (session: ScriptSession) => session.halted,
+    haltReason: (session: ScriptSession) => session.haltReason,
+    slots: (session: ScriptSession) => session.slots,
+    replicated: (session: ScriptSession, participant: number, slot: number) =>
+      session.replicated(participant, slot),
+    replicate: (session: ScriptSession, slot: number, value: number) => {
+      session.replicate(slot, value);
+    },
+  };
+}

package/src/bindings/render.ts

@@ -0,0 +1,191 @@
+import type { RendererApi } from '@driftengine/core';
+import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+
+export const RENDER_MODULE = 'drift/render';
+
+/**
+ * `drift/render` — how the finished image is presented, for the frame about to be drawn.
+ *
+ * **The linker refused this module by name from the day the language shipped until now**, and the
+ * roadmap slot it was waiting on was Track D. Track D completed on 2026-09-03 with refraction, so
+ * the wait ended five releases before anything noticed — `docs/CAPABILITIES.md` still mapped this
+ * module to a track that had closed, while `host.test.ts` had already been corrected to say it
+ * waits on a row of its own. Two documents, one right.
+ *
+ * ## What this module is, which is a smaller thing than "the renderer"
+ *
+ * `RenderQuality` has fifty fields and **none of them are here.** The engine already draws
+ * the line this module needs, in `renderQuality.ts`'s own words about depth of field:
+ *
+ * > A ceiling rather than the effect [...] this says how far a defocused point may spread and
+ * > therefore what the pass may cost, and `setDepthOfField` says where this frame's lens is focused
+ * > and how much of the ceiling it takes. A camera focuses on a subject; a quality profile decides
+ * > how expensive that is allowed to be.
+ *
+ * **A quality profile is the application's and a dial is the game's.** A profile is chosen once,
+ * from what the device can afford, and is clamped by `capabilityClamp` against what the adapter
+ * actually reports; a script that wrote to one would be overruling a decision made about hardware
+ * it cannot see, and two machines running the same script would draw different pictures for
+ * reasons the script did not choose. So this module binds the seven dials and none of the ceilings.
+ *
+ * ## Writes only, and the reason is the same one
+ *
+ * There is no `render.bloomOf` here, and nothing reads a dial back. Every one of these is **clamped
+ * against the ceiling the host set** — `setBloom` does nothing at all when `bloom` is 0, because
+ * the chain is never built — so what a read would answer is a fact about the machine wearing the
+ * costume of a fact about the frame. The language wrote this argument once already, for
+ * `network.read` and a confirmed-input watermark: a host registering a machine-dependent number
+ * under a deterministic effect hands a `@deterministic` system a value that differs between a run
+ * and its replay. A script sets a dial; what the device did with it is the device's business.
+ *
+ * ## The effect, which needed no language release
+ *
+ * **`scene.write`, and it is a description rather than a borrowing.** `capability.ts` puts
+ * `scene.write` outside `DETERMINISTIC_EFFECTS` and says exactly why: *"a `SceneNode` is what
+ * draws, and `ARCHITECTURE.md` forbids render code mutating simulation state, so moving a node is
+ * a change to the view."* Every capability here is a change to the view and nothing else — the
+ * renderers' own comments call these *"a renderer parameter rather than a scene one: it describes
+ * how the finished image is presented, not anything in the world, which is why nothing about the
+ * world has to know it exists."* Two files arriving at the same sentence from opposite ends is the
+ * argument.
+ *
+ * So no capability here is deterministic, and that is the property rather than a limitation: a
+ * `@deterministic` system may not dim the screen. Presentation belongs outside the fixed step,
+ * where the frame is.
+ */
+export const RENDER_TYPES: readonly OpaqueType[] = [
+  {
+    module: RENDER_MODULE,
+    name: 'Renderer',
+    doc: 'The renderer drawing this frame. Reaches a script through `uses`.',
+  },
+];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  doc: string,
+): CapabilityDefinition =>
+  defineCapability({
+    module: RENDER_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> void`,
+    params: [...params],
+    returns: 'void',
+    effects: ['scene.write'],
+    deterministic: false,
+    doc,
+    implementation: `${RENDER_MODULE}.${name}`,
+  });
+
+const R = { name: 'renderer', type: 'Renderer' } as const;
+
+export const RENDER_CAPABILITIES: readonly CapabilityDefinition[] = [
+  define(
+    'bloom',
+    [R, { name: 'scale', type: 'f32' }],
+    "How much of the frame's bloom ceiling to take, 0 to 1. Held until changed. Does nothing " +
+      "when the quality profile's `bloom` is 0, because the chain is never built.",
+  ),
+  define(
+    'exposure',
+    [R, { name: 'stops', type: 'f32' }],
+    "How far this frame is scaled into the tone curve, above 0. Replaces the profile's " +
+      '`outputExposure` for this frame onward. Adaptation is yours: a game knows it walked into a ' +
+      'cave, and the renderer could only find out a frame late. Ignored unless the output ' +
+      'transform is `aces`, since otherwise there is no curve to be exposed into.',
+  ),
+  define(
+    'motionBlur',
+    [R, { name: 'scale', type: 'f32' }],
+    'How much of the camera motion blur ceiling this frame takes, 0 to 1. Held until changed. ' +
+      'Ramp it with whatever "fast" means here: blur that is always on stops being a speed cue ' +
+      'within seconds and costs eight taps a moving pixel while doing so.',
+  ),
+  define(
+    'speedBlur',
+    [R, { name: 'strength', type: 'f32' }],
+    'How much speed blur the frame resolves with, 0 to 1. Held until changed, and ignored when ' +
+      'screen effects are off.',
+  ),
+  define(
+    'focus',
+    [
+      R,
+      { name: 'distance', type: 'f32' },
+      { name: 'range', type: 'f32' },
+      { name: 'scale', type: 'f32' },
+    ],
+    "Where this frame's lens is focused and how deep the sharp zone is, in metres, and how much " +
+      'of the depth-of-field ceiling to take, 0 to 1. Held until changed. `scale` is required ' +
+      'here though the engine defaults it to 1, because taking the whole ceiling is the expensive ' +
+      'answer and a script author is further from that cost than a TypeScript caller.',
+  ),
+  define(
+    'medium',
+    [
+      R,
+      { name: 'density', type: 'f32' },
+      { name: 'albedo', type: 'f32' },
+      { name: 'anisotropy', type: 'f32' },
+      { name: 'maxDistance', type: 'f32' },
+    ],
+    'How thick the air is: a medium filling the whole frustum, rather than a beam inside a hull. ' +
+      '`density` is extinction per metre and 0 is off — nothing is allocated and nothing is drawn, ' +
+      'so a script that never raises it costs nothing. `albedo` is how much of what the air takes ' +
+      'out comes back as light rather than heat, 0 to 1; `anisotropy` is -1 back to 1 forward, and ' +
+      'is what makes haze glow toward a low sun; `maxDistance` is where the search for light to ' +
+      'scatter stops, in metres, which is not where the fog stops. Held until changed. Does ' +
+      "nothing when the quality profile's `globalMediumSteps` is 0, because no march is built.",
+  ),
+  define(
+    'veil',
+    [
+      R,
+      { name: 'red', type: 'f32' },
+      { name: 'green', type: 'f32' },
+      { name: 'blue', type: 'f32' },
+      { name: 'alpha', type: 'f32' },
+    ],
+    'Composite a flat colour over the finished frame, for a cut dipping to white or to black. ' +
+      '**Once per frame: a frame that does not call this draws with no veil at all**, unlike the ' +
+      'dials above, because a transition that forgets to turn itself off is worse than one that ' +
+      'forgets to turn on.',
+  ),
+];
+
+/**
+ * Unconditional, like `drift/terrain` and `drift/editor`: every capability takes the renderer it
+ * acts on, which reaches a script through `uses`, so there is nothing for an absent service to
+ * make fail.
+ *
+ * **`medium` takes every argument the engine defaults**, unlike `setGlobalMedium`, and for the
+ * reason `focus` gives about its own `scale`: a script author is further from the cost than a
+ * TypeScript caller, and a defaulted albedo is a number somebody has to go and look up before they
+ * can tell what their fog will look like. Four numbers is one line either way.
+ *
+ *  * **`speedBlur` is the one name here that is not the engine's own.** The method is `setSpeedRush`,
+ * and a rush is a thing that happens in somebody's game rather than a description of an image
+ * operation — binding that spelling would have written one consumer's noun into the language's
+ * surface, where it could not later be taken back. A binding is a lookup and this is what a lookup
+ * is for.
+ */
+export function renderImplementation(): Record<string, unknown> {
+  return {
+    bloom: (renderer: RendererApi, scale: number) => renderer.setBloom(scale),
+    exposure: (renderer: RendererApi, stops: number) => renderer.setOutputExposure(stops),
+    motionBlur: (renderer: RendererApi, scale: number) => renderer.setCameraMotionBlur(scale),
+    speedBlur: (renderer: RendererApi, strength: number) => renderer.setSpeedRush(strength),
+    focus: (renderer: RendererApi, distance: number, range: number, scale: number) =>
+      renderer.setDepthOfField(distance, range, scale),
+    medium: (
+      renderer: RendererApi,
+      density: number,
+      albedo: number,
+      anisotropy: number,
+      maxDistance: number,
+    ) => renderer.setGlobalMedium(density, albedo, anisotropy, maxDistance),
+    veil: (renderer: RendererApi, red: number, green: number, blue: number, alpha: number) =>
+      renderer.setFrameVeil(red, green, blue, alpha),
+  };
+}

package/src/bindings/rollback.ts

@@ -0,0 +1,110 @@
+import type { CapabilityDefinition, OpaqueType } from 'driftscript';
+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: readonly OpaqueType[] = [
+  {
+    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.',
+  },
+];
+
+/** What the binding needs of a `RewindLoop`, declared rather than imported. */
+interface RewindLike {
+  readonly tick: number;
+  readonly depth: number;
+  readonly earliest: number;
+  readonly isReplaying: boolean;
+  readonly stats: { readonly replays: number; readonly replayedTicks: number };
+}
+
+const define = (name: string, returns: string, doc: string): CapabilityDefinition =>
+  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: readonly CapabilityDefinition[] = [
+  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(): Record<string, unknown> {
+  return {
+    tick: (rewind: RewindLike) => rewind.tick,
+    isReplaying: (rewind: RewindLike) => rewind.isReplaying,
+    depth: (rewind: RewindLike) => rewind.depth,
+    earliest: (rewind: RewindLike) => rewind.earliest,
+    replays: (rewind: RewindLike) => rewind.stats.replays,
+    replayedTicks: (rewind: RewindLike) => rewind.stats.replayedTicks,
+  };
+}