@driftengine/script 4.7.4 → 4.8.0

package/dist/bindings/chemistry.d.ts

@@ -40,6 +40,10 @@ import { AtmosphereField, ChemistryWorld, ParcelStore, SpeciesRegistry, Substanc
 import { type ComponentType } from '@driftengine/entities';
 import { type CapabilityDefinition, type OpaqueType } from 'driftscript';
 export declare const CHEMISTRY_MODULE = "drift/chemistry";
+/** A parcel's phase, in the package's order: `PHASE_SOLID`, `_LIQUID`, `_GAS`, then `PHASE_MIXED`. */
+export declare const MATTER_PHASE: import("./variants.ts").HostEnum;
+/** What happened to a parcel this tick, in the order of the package's `EVENT_*` constants. */
+export declare const CHEMISTRY_EVENT: import("./variants.ts").HostEnum;
 /**
  * The three opaque types `§20.2` names.
  *

package/dist/bindings/chemistry.js

@@ -39,6 +39,7 @@
 import { AtmosphereField, ChemistryWorld, ParcelStore, SpeciesRegistry, SubstanceRegistry, } from '@driftengine/chemistry';
 import { defineComponent } from '@driftengine/entities';
 import { defineCapability } from 'driftscript';
+import { hostEnum } from './variants.js';
 export const CHEMISTRY_MODULE = 'drift/chemistry';
 const define = (name, params, returns, effects, doc) => defineCapability({
     module: CHEMISTRY_MODULE,
@@ -52,6 +53,32 @@ const define = (name, params, returns, effects, doc) => defineCapability({
     doc,
     implementation: `${CHEMISTRY_MODULE}.${name}`,
 });
+/** A parcel's phase, in the package's order: `PHASE_SOLID`, `_LIQUID`, `_GAS`, then `PHASE_MIXED`. */
+export const MATTER_PHASE = hostEnum(CHEMISTRY_MODULE, 'MatterPhase', ['Solid', 'Liquid', 'Gas', 'Mixed'], 'What a parcel is made of now. Mixed is a real answer: wet wood is a solid and a liquid at once.');
+/** What happened to a parcel this tick, in the order of the package's `EVENT_*` constants. */
+export const CHEMISTRY_EVENT = hostEnum(CHEMISTRY_MODULE, 'ChemistryEvent', [
+    'Ignited',
+    'Extinguished',
+    'SmoulderStart',
+    'SmoulderEnd',
+    'Consumed',
+    'Charred',
+    'StructuralFail',
+    'Frozen',
+    'Melted',
+    'Boiled',
+    'Condensed',
+    'Sublimed',
+    'Corroded',
+    'Calcined',
+    'Dissolved',
+    'Denatured',
+    'Browned',
+    'Caramelised',
+    'Fermented',
+    'Decayed',
+    'Exploded',
+], 'What happened to a parcel this tick: it caught, went out, melted, boiled and the rest.');
 /**
  * The three opaque types `§20.2` names.
  *
@@ -75,6 +102,8 @@ export const CHEMISTRY_TYPES = [
         name: 'Species',
         doc: 'A registered chemical species, such as `O2` or `cellulose`.',
     },
+    MATTER_PHASE.type,
+    CHEMISTRY_EVENT.type,
 ];
 const READ = ['chemistry.read'];
 const WRITE = ['chemistry.write'];
@@ -104,7 +133,7 @@ export const CHEMISTRY_CAPABILITIES = [
     define('charDepth', [P, PARCEL], 'f32', READ, 'Metres of char measured inward from the surface.'),
     define('wetness', [P, PARCEL], 'f32', READ, 'kg of liquid water on the surface, per square metre of it.'),
     define('wettable', [P, PARCEL], 'bool', READ, 'Whether this material can hold liquid water, which is what `wet` asks. Rain over everything asks first, since `wet` refuses an iron nail.'),
-    define('phase', [P, PARCEL], 'i32', READ, '0 solid, 1 liquid, 2 gas, 3 mixed. Mixed is a real answer: wet wood is a solid and a liquid at once.'),
+    define('phase', [P, PARCEL], 'MatterPhase', READ, 'Whether the parcel is solid, liquid, gas or mixed. Mixed is a real answer: wet wood is a solid and a liquid at once.'),
     define('burning', [P, PARCEL], 'bool', READ, 'Whether a flame stands over it.'),
     define('smouldering', [P, PARCEL], 'bool', READ, 'Whether it is glowing with no flame. A smoulder survives air a flame cannot, which is why smothering leaves embers.'),
     define('heatRelease', [P, PARCEL], 'f32', READ, "kW the reactions released last tick. A fire's size is its heat release rate, not its temperature. Negative while a surface is gasifying, which is correct."),
@@ -153,7 +182,7 @@ export const CHEMISTRY_CAPABILITIES = [
     define('addAirHeat', [P, { name: 'joules', type: 'f32' }, ...XYZ], 'void', WRITE, 'Joules into a cell of air, which is what a heater does and what a fire does to the room.'),
     /* The event buffer, §20.5, in the shape `drift/physics`'s contact buffer established. */
     define('eventCount', [P], 'i32', READ, 'Events this tick. Cleared at the top of every one.'),
-    define('eventKind', [P, { name: 'index', type: 'i32' }], 'i32', READ, '0 ignited, 1 extinguished, 2 smoulderStart, 3 smoulderEnd, 4 consumed, 5 charred, 6 structuralFail, 7 frozen, 8 melted, 9 boiled, 10 condensed, 11 sublimed, 12 corroded, 13 calcined, 14 dissolved, 15 denatured, 16 browned, 17 caramelised, 18 fermented, 19 decayed, 20 exploded.'),
+    define('eventKind', [P, { name: 'index', type: 'i32' }], 'ChemistryEvent', READ, 'What happened in one of this tick’s events. An index outside `eventCount` is refused, naming both.'),
     define('eventParcel', [P, { name: 'index', type: 'i32' }], 'i32', READ, 'Which parcel it happened to.'),
     define('eventSpecies', [P, { name: 'index', type: 'i32' }], 'i32', READ, 'Which species, or -1 where the kind does not name one.'),
     define('eventValue', [P, { name: 'index', type: 'i32' }], 'f32', READ, "The kind's own quantity."),
@@ -213,7 +242,7 @@ export function chemistryImplementation(services) {
         charDepth: (_, parcel) => parcels.charDepthOf(parcel),
         wetness: (_, parcel) => parcels.wetnessOf(parcel),
         wettable: (_, parcel) => parcels.wettable(parcel),
-        phase: (_, parcel) => parcels.parcelPhaseOf(parcel),
+        phase: (_, parcel) => MATTER_PHASE.of[parcels.parcelPhaseOf(parcel)],
         burning: (_, parcel) => parcels.burning(parcel),
         smouldering: (_, parcel) => parcels.smouldering(parcel),
         /* Watts inside, kilowatts out: a fire is quoted in kW everywhere a person reads one. */
@@ -247,7 +276,14 @@ export function chemistryImplementation(services) {
         release: (_, s, kilograms, x, y, z) => air.addSpecies(x, y, z, s, kilograms),
         addAirHeat: (_, joules, x, y, z) => air.addHeat(x, y, z, joules),
         eventCount: () => world.events.count,
-        eventKind: (_, index) => world.events.kindOf(index),
+        eventKind(_, index) {
+            /* The buffer is read unchecked, and past `count` it holds the last tick's events or nothing:
+               a kind that did not happen this tick, or no variant at all. */
+            if (!(index >= 0 && index < world.events.count)) {
+                throw new RangeError(`event ${index} is outside this tick's ${world.events.count}`);
+            }
+            return CHEMISTRY_EVENT.of[world.events.kindOf(index)];
+        },
         eventParcel: (_, index) => world.events.parcelOf(index),
         eventSpecies: (_, index) => world.events.speciesOf(index),
         eventValue: (_, index) => world.events.valueOf(index),

package/dist/bindings/core.js

@@ -20,6 +20,7 @@
  */
 import { ActionMap, CinematicCamera, ColliderSet, RemoteSaveStore, MessageQueue, PhysicsWorld, SceneNode, angleDelta, boxCollider, createRayHit, hashToUnit, mulberry32, wrapAngle, } from '@driftengine/core';
 import { defineCapability } from 'driftscript';
+import { hostEnum } from './variants.js';
 export const TIME_MODULE = 'drift/time';
 export const RANDOM_MODULE = 'drift/random';
 export const EVENTS_MODULE = 'drift/events';
@@ -39,6 +40,16 @@ const define = (module, name, params, returns, effects, deterministic, doc) => d
     doc,
     implementation: `${module}.${name}`,
 });
+/** A contact event's kind, in `@driftengine/physics`'s order: `EVENT_ENTER`, `_STAY`, `_EXIT`. */
+const CONTACT_KIND = hostEnum('drift/physics', 'ContactKind', ['Enter', 'Stay', 'Exit'], 'Whether two bodies began touching this step, are still touching, or have parted.');
+/** A remote store's `SaveStatus`, one variant per string the store answers with. */
+const SAVE_STATUS = hostEnum('drift/persistence', 'SaveStatus', ['Idle', 'Pending', 'Saving', 'Failed'], 'Whether a store’s writes have landed: idle, waiting to send, sending, or failed.');
+const SAVE_STATUS_OF = {
+    idle: SAVE_STATUS.of[0],
+    pending: SAVE_STATUS.of[1],
+    saving: SAVE_STATUS.of[2],
+    failed: SAVE_STATUS.of[3],
+};
 /**
  * Handles a script holds and passes back, never reads into.
  *
@@ -86,6 +97,8 @@ export const CORE_TYPES = [
         doc: 'A priority message queue with dedupe and a ceiling.',
     },
     { module: PERSISTENCE_MODULE, name: 'Store', doc: 'A key-value store the consumer supplied.' },
+    CONTACT_KIND.type,
+    SAVE_STATUS.type,
 ];
 /**
  * `drift/time` — the loop's three clocks, and the one that is deterministic is not here.
@@ -161,7 +174,7 @@ export const PERSISTENCE_CAPABILITIES = [
      * 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, 'saveStatus', [{ name: 'store', type: 'Store' }], 'SaveStatus', ['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.'),
 ];
 /**
@@ -381,7 +394,7 @@ export const PHYSICS_CAPABILITIES = [
     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."),
+    ], 'ContactKind', ['physics.read'], true, "An event's kind: the two bodies began touching, are still touching, or have parted."),
     define(PHYSICS_MODULE, 'contactA', [
         { name: 'world', type: 'PhysicsWorld' },
         { name: 'index', type: 'i32' },
@@ -599,7 +612,7 @@ export function persistenceImplementation() {
         },
         /* `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',
+        saveStatus: (store) => SAVE_STATUS_OF[store instanceof RemoteSaveStore ? store.status : 'idle'],
         pendingSaves: (store) => (store instanceof RemoteSaveStore ? store.pending : 0),
     };
 }
@@ -778,7 +791,13 @@ export function physicsImplementation() {
         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,
+        contactKind(world, index) {
+            /* Past `count` the buffer holds an older step's events or nothing, so neither is answered. */
+            if (!(index >= 0 && index < world.events.count)) {
+                throw new RangeError(`contact ${index} is outside this step's ${world.events.count}`);
+            }
+            return CONTACT_KIND.of[world.events.data[index * 3]];
+        },
         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),

package/dist/bindings/editor.d.ts

@@ -32,13 +32,16 @@ export declare const EDITOR_MODULE = "drift/editor";
  *
  * ## Three capabilities where an argument would have done, deliberately
  *
- * `translateMode`, `rotateMode` and `scaleMode` rather than `setMode(gizmo, mode)`. The language has
- * no enum, so the argument would be a string or a number, and an unrecognised one leaves exactly two
- * options — change nothing, the silent no-op `host.ts` rules out, or throw inside a frame, which
- * `AGENTS.md` rules out. Three names make the invalid call impossible to write, and the checker
- * rather than a runtime branch is what refuses it. `space` is the same argument again.
- *
- * The *readers* are strings because a reader is total: there is no invalid value to answer.
+ * `translateMode`, `rotateMode` and `scaleMode` rather than `setMode(gizmo, mode)`. When these were
+ * written a host could not declare an enum, so the argument would have been a string or a number,
+ * and an unrecognised one leaves exactly two options — change nothing, the silent no-op `host.ts`
+ * rules out, or throw inside a frame, which `AGENTS.md` rules out. Three names make the invalid call
+ * impossible to write, and the checker rather than a runtime branch is what refuses it. A
+ * `GizmoMode` argument would do the same now; the three stay because scripts call them. `space` is
+ * the same argument again.
+ *
+ * The *readers* answer variants, a `GizmoMode`, a `GizmoSpace` and a `GizmoHandle`, so a script
+ * that matches on one is told when a mode or a handle is added.
  */
 export declare const EDITOR_TYPES: readonly OpaqueType[];
 export declare const EDITOR_CAPABILITIES: readonly CapabilityDefinition[];

package/dist/bindings/editor.js

@@ -1,5 +1,43 @@
 import { defineCapability } from 'driftscript';
+import { hostEnum } from './variants.js';
 export const EDITOR_MODULE = 'drift/editor';
+/** Which tool the gizmo is, one variant per `Gizmo.mode`. */
+const GIZMO_MODE = hostEnum(EDITOR_MODULE, 'GizmoMode', ['Translate', 'Rotate', 'Scale'], 'Which tool a gizmo is: it moves, turns or scales.');
+/** Which axes the handles follow, one variant per `Gizmo.space`. */
+const GIZMO_SPACE = hostEnum(EDITOR_MODULE, 'GizmoSpace', ['World', 'Local'], 'Which axes a gizmo’s handles point along: the world’s or the object’s own.');
+/**
+ * The handle under the pointer, in the order of `Gizmo`'s integer constants, `None` first.
+ *
+ * A variant per handle where this used to answer a name such as `"translate.yz"`, which a script
+ * compared as a string: a misspelt name compared false forever and nothing said so. A handle added
+ * in the middle now changes this list, and every script `match` over it that misses it stops
+ * compiling.
+ */
+const GIZMO_HANDLE = hostEnum(EDITOR_MODULE, 'GizmoHandle', [
+    'None',
+    'TranslateX',
+    'TranslateY',
+    'TranslateZ',
+    'TranslateYZ',
+    'TranslateZX',
+    'TranslateXY',
+    'RotateX',
+    'RotateY',
+    'RotateZ',
+    'ScaleX',
+    'ScaleY',
+    'ScaleZ',
+    'ScaleUniform',
+], 'Which handle the pointer is over, or `None`.');
+/** What the editor is doing, one variant per `EditorMode`. */
+const EDITOR_MODE = hostEnum(EDITOR_MODULE, 'EditorMode', ['Edit', 'Play', 'Paused'], 'Whether the editor is editing, playing the world, or paused part way through playing it.');
+/** How the inspector shows a field, one variant per `FieldKind`. */
+const FIELD_KIND = hostEnum(EDITOR_MODULE, 'FieldKind', ['Number', 'Integer', 'Boolean', 'Text', 'Entity', 'Enum'], 'How an inspector field is shown, taken from the type it was declared with.');
+const byName = (names, of) => new Map(names.map((name, index) => [name, of[index]]));
+const GIZMO_MODE_OF = byName(['translate', 'rotate', 'scale'], GIZMO_MODE.of);
+const GIZMO_SPACE_OF = byName(['world', 'local'], GIZMO_SPACE.of);
+const EDITOR_MODE_OF = byName(['edit', 'play', 'paused'], EDITOR_MODE.of);
+const FIELD_KIND_OF = byName(['number', 'integer', 'boolean', 'text', 'entity', 'enum'], FIELD_KIND.of);
 /**
  * `drift/editor` — the transform tool, driven from a script that never ships.
  *
@@ -32,13 +70,16 @@ export const EDITOR_MODULE = 'drift/editor';
  *
  * ## Three capabilities where an argument would have done, deliberately
  *
- * `translateMode`, `rotateMode` and `scaleMode` rather than `setMode(gizmo, mode)`. The language has
- * no enum, so the argument would be a string or a number, and an unrecognised one leaves exactly two
- * options — change nothing, the silent no-op `host.ts` rules out, or throw inside a frame, which
- * `AGENTS.md` rules out. Three names make the invalid call impossible to write, and the checker
- * rather than a runtime branch is what refuses it. `space` is the same argument again.
+ * `translateMode`, `rotateMode` and `scaleMode` rather than `setMode(gizmo, mode)`. When these were
+ * written a host could not declare an enum, so the argument would have been a string or a number,
+ * and an unrecognised one leaves exactly two options — change nothing, the silent no-op `host.ts`
+ * rules out, or throw inside a frame, which `AGENTS.md` rules out. Three names make the invalid call
+ * impossible to write, and the checker rather than a runtime branch is what refuses it. A
+ * `GizmoMode` argument would do the same now; the three stay because scripts call them. `space` is
+ * the same argument again.
  *
- * The *readers* are strings because a reader is total: there is no invalid value to answer.
+ * The *readers* answer variants, a `GizmoMode`, a `GizmoSpace` and a `GizmoHandle`, so a script
+ * that matches on one is told when a mode or a handle is added.
  */
 export const EDITOR_TYPES = [
     {
@@ -51,6 +92,11 @@ export const EDITOR_TYPES = [
         name: 'Editor',
         doc: 'An editing session: what is selected, the tree of what exists, and whether the world is playing.',
     },
+    GIZMO_MODE.type,
+    GIZMO_SPACE.type,
+    GIZMO_HANDLE.type,
+    EDITOR_MODE.type,
+    FIELD_KIND.type,
 ];
 const define = (name, params, returns, doc) => defineCapability({
     module: EDITOR_MODULE,
@@ -81,18 +127,19 @@ export const EDITOR_CAPABILITIES = [
     define('translateMode', OF, 'void', 'Make this an arrow gizmo, which moves what it is on.'),
     define('rotateMode', OF, 'void', 'Make this a ring gizmo, which turns what it is on.'),
     define('scaleMode', OF, 'void', 'Make this a scale gizmo. Scale is always in the object’s own axes, whatever the space says, because a non-uniform scale along a world axis would shear it.'),
-    define('gizmoMode', OF, 'String', 'Which of the three the gizmo is: "translate", "rotate" or "scale".'),
+    define('gizmoMode', OF, 'GizmoMode', 'Which of the three the gizmo is: translate, rotate or scale.'),
     define('worldSpace', OF, 'void', 'Point the handles along the world axes.'),
     define('localSpace', OF, 'void', 'Point the handles along the object’s own axes.'),
-    define('space', OF, 'String', 'Which the handles are pointing along: "world" or "local".'),
+    define('space', OF, 'GizmoSpace', 'Which the handles are pointing along: the world or the object.'),
     define('size', OF, 'f32', 'How big the gizmo is in metres. The host keeps this the same on screen as the camera moves.'),
     define('setSize', [...OF, { name: 'metres', type: 'f32' }], 'void', 'Set how big the gizmo is in metres. Non-positive draws nothing and picks nothing rather than failing.'),
     /*
-     * **A name rather than a number, and total.** The handles are integer constants in TypeScript, and
-     * a script comparing against a magic number is a script that breaks silently the day a handle is
-     * added in the middle. `"none"` is a real answer rather than a missing one.
+     * **A variant, and total.** The handles are integer constants in TypeScript, and a script comparing
+     * against a magic number breaks silently the day a handle is added in the middle; a script
+     * comparing against a name breaks silently the day it misspells one. `None` is a real answer
+     * rather than a missing one.
      */
-    define('hovered', OF, 'String', 'What the pointer is over, as a name: "none", or one of "translate.x", "translate.yz", "rotate.y", "scale.uniform" and their siblings.'),
+    define('hovered', OF, 'GizmoHandle', 'What the pointer is over: `None`, or a handle such as `TranslateX`, `TranslateYZ`, `RotateY` or `ScaleUniform`.'),
     define('dragging', OF, 'bool', 'Whether a drag is running.'),
     define('dragAngle', OF, 'f32', 'How far a rotation drag has turned, in radians, signed and past a full turn if it went that far. Zero when the drag is not a rotation. This is what to snap or clamp; the rotation itself cannot tell a three-quarter turn from a quarter turn back.'),
     define('positionX', OF, 'f32', 'Where the thing being edited is, along x.'),
@@ -116,7 +163,7 @@ export const EDITOR_CAPABILITIES = [
      * **The session, from `@driftengine/editor`.** Everything above drives one tool; everything below
      * drives the editor around it — which is what an `@editor` script is actually for.
      */
-    define('mode', ON, 'String', 'What the editor is doing: "edit", "play" or "paused".'),
+    define('mode', ON, 'EditorMode', 'What the editor is doing: editing, playing or paused.'),
     define('playing', ON, 'bool', 'Whether the world is advancing. False while paused and while editing.'),
     define('play', ON, 'bool', 'Start playing, taking a snapshot of the world first so `stop` can put it back. Resuming from paused does not re-snapshot. False when no world is bound to snapshot.'),
     define('pause', ON, 'void', 'Hold the world where it is. The frame keeps drawing.'),
@@ -133,31 +180,10 @@ export const EDITOR_CAPABILITIES = [
     define('fieldCount', ON, 'i32', 'How many fields the inspector is showing.'),
     define('fieldLabel', [...ON, { name: 'field', type: 'i32' }], 'String', 'A field\u2019s name as it was declared, or "" for a field that does not exist.'),
     define('fieldGroup', [...ON, { name: 'field', type: 'i32' }], 'String', 'What a field belongs to: a component\u2019s name, or "transform" for a node.'),
-    define('fieldKind', [...ON, { name: 'field', type: 'i32' }], 'String', 'How to show a field: "number", "integer", "boolean", "text", "entity" or "enum". Taken from the declared type, because a read cannot tell them apart.'),
+    define('fieldKind', [...ON, { name: 'field', type: 'i32' }], 'FieldKind', 'How to show a field: a number, an integer, a boolean, text, an entity or an enum. Taken from the declared type, because a read cannot tell them apart. A field outside `fieldCount` is refused, naming both.'),
     define('fieldNumber', [...ON, { name: 'field', type: 'i32' }], 'f32', 'A field\u2019s value as a number. Zero for a field that is not one, and for one that does not exist.'),
     define('setFieldNumber', [...ON, { name: 'field', type: 'i32' }, { name: 'value', type: 'f32' }], 'bool', 'Write a number into a field. False where the field does not exist or will not take one.'),
 ];
-/**
- * Handle constants as the names a script reads, in the order the constants run.
- *
- * A table rather than a `switch`, so adding a handle is one line here and the reader stays total.
- */
-const HANDLE_NAMES = [
-    'none',
-    'translate.x',
-    'translate.y',
-    'translate.z',
-    'translate.yz',
-    'translate.zx',
-    'translate.xy',
-    'rotate.x',
-    'rotate.y',
-    'rotate.z',
-    'scale.x',
-    'scale.y',
-    'scale.z',
-    'scale.uniform',
-];
 /**
  * **No services, and that is the shape rather than an omission.**
  *
@@ -177,19 +203,19 @@ export function editorImplementation() {
         scaleMode: (gizmo) => {
             gizmo.mode = 'scale';
         },
-        gizmoMode: (gizmo) => gizmo.mode,
+        gizmoMode: (gizmo) => GIZMO_MODE_OF.get(gizmo.mode),
         worldSpace: (gizmo) => {
             gizmo.space = 'world';
         },
         localSpace: (gizmo) => {
             gizmo.space = 'local';
         },
-        space: (gizmo) => gizmo.space,
+        space: (gizmo) => GIZMO_SPACE_OF.get(gizmo.space),
         size: (gizmo) => gizmo.size,
         setSize: (gizmo, metres) => {
             gizmo.size = metres;
         },
-        hovered: (gizmo) => HANDLE_NAMES[gizmo.hovered] ?? 'none',
+        hovered: (gizmo) => GIZMO_HANDLE.of[gizmo.hovered] ?? GIZMO_HANDLE.of[0],
         dragging: (gizmo) => gizmo.dragging,
         dragAngle: (gizmo) => gizmo.dragAngle,
         positionX: (gizmo) => gizmo.position[0] ?? 0,
@@ -207,7 +233,7 @@ export function editorImplementation() {
         rotationY: (gizmo) => gizmo.rotation[1] ?? 0,
         rotationZ: (gizmo) => gizmo.rotation[2] ?? 0,
         rotationW: (gizmo) => gizmo.rotation[3] ?? 1,
-        mode: (editor) => editor.mode,
+        mode: (editor) => EDITOR_MODE_OF.get(editor.mode),
         playing: (editor) => editor.mode === 'play',
         play: (editor) => editor.play(),
         pause: (editor) => {
@@ -238,7 +264,13 @@ export function editorImplementation() {
         fieldCount: (editor) => editor.inspector.fields.length,
         fieldLabel: (editor, field) => editor.inspector.fields[field]?.label ?? '',
         fieldGroup: (editor, field) => editor.inspector.fields[field]?.group ?? '',
-        fieldKind: (editor, field) => editor.inspector.fields[field]?.kind ?? '',
+        fieldKind(editor, field) {
+            const found = editor.inspector.fields[field];
+            if (found === undefined) {
+                throw new RangeError(`field ${field} is outside the ${editor.inspector.fields.length} shown`);
+            }
+            return FIELD_KIND_OF.get(found.kind);
+        },
         fieldNumber: (editor, field) => {
             const value = editor.inspector.fields[field]?.value;
             return typeof value === 'number' ? value : 0;

package/dist/bindings/entities.js

@@ -221,10 +221,18 @@ export function entitiesImplementation(services) {
         attach: (w, entity, component) => w.add(entity, resolve(component)),
         detach: (w, entity, component) => w.remove(entity, resolve(component)),
         read: (w, entity, component, field) => {
-            const value = w.read(entity, resolve(component), field);
-            /* An entity without the component reads `undefined`, and a script's `f64` may not hold one:
-               the language has no null, so the honest zero is what a missing value is. */
-            return typeof value === 'number' ? value : 0;
+            const type = resolve(component);
+            const value = w.read(entity, type, field);
+            if (value !== undefined)
+                return value;
+            /*
+             * Nothing to read: an absent optional field, or an entity without the component. An optional
+             * field answers `undefined`, which the generated code turns into `none`; the compiler wraps
+             * every read of one. Any other field answers zero, since a script's `f64` cannot hold
+             * nothing. Answering zero for an optional field too was what made it unreadable: `none` and
+             * a stored zero were the same answer.
+             */
+            return optionalField(type, field) ? undefined : 0;
         },
         write: (w, entity, component, field, value) => w.write(entity, resolve(component), field, value),
         /*
@@ -342,3 +350,7 @@ export function entitiesImplementation(services) {
         },
     };
 }
+/** Whether a component declared this field as an option, `option:<inner>` in its schema. */
+function optionalField(type, field) {
+    return type.schema.fields.some((f) => f.name === field && f.type.startsWith('option:'));
+}

package/dist/bindings/variants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A host enum's variants, as the values a script holds and hands back.
+ *
+ * An engine answer that is one of a few things is an enum on the script's side: DriftScript lets a
+ * host declare one (`OpaqueType.variants`), a script names its variants and a `match` over it has
+ * to cover them all. The engine keeps its own numbering, and this is the one place a number becomes
+ * a variant and back. Before it, each such capability answered with the number and a sentence
+ * saying what each number meant, and every script restated that sentence as constants.
+ *
+ * One frozen object per variant, made once, so answering allocates nothing. A script compares a
+ * variant by its tag, so a script's own copy of `{ tag: 'Solid' }` equals this one.
+ */
+import type { OpaqueType } from 'driftscript';
+export interface Variant {
+    readonly tag: string;
+}
+export interface HostEnum {
+    /** The type to register, so a script can name it. */
+    readonly type: OpaqueType;
+    /** The variant for an engine code, in the order the engine numbers them. */
+    readonly of: readonly Variant[];
+    /** The engine's code for a variant a script handed back, or -1 for anything else. */
+    code(variant: Variant): number;
+}
+export declare function hostEnum(module: string, name: string, variants: readonly string[], doc: string): HostEnum;

package/dist/bindings/variants.js

@@ -0,0 +1,9 @@
+export function hostEnum(module, name, variants, doc) {
+    const of = variants.map((tag) => Object.freeze({ tag }));
+    const codes = new Map(variants.map((tag, index) => [tag, index]));
+    return {
+        type: { module, name, doc, variants },
+        of,
+        code: (variant) => codes.get(variant.tag) ?? -1,
+    };
+}

package/dist/bindings/xr.js

@@ -36,9 +36,22 @@
  * that reason, which is the one this needs.
  */
 import { defineCapability } from 'driftscript';
-import { JOINT_INDEX } from '@driftengine/xr';
+import { hostEnum } from './variants.js';
+import { HAND_JOINTS, JOINT_INDEX } from '@driftengine/xr';
 export const XR_MODULE = 'drift/xr';
-export const XR_TYPES = [];
+/** Which hand, one variant per `Handedness`; `None` is the source a runtime gives no side. */
+const HAND = hostEnum(XR_MODULE, 'Hand', ['Left', 'Right', 'None'], 'Which hand: left, right, or the input source with no side.');
+const HANDEDNESS = ['left', 'right', 'none'];
+/**
+ * A hand joint, one variant per name in `@driftengine/xr`'s `HAND_JOINTS`, in its order:
+ * `index-finger-tip` is `IndexFingerTip`. Derived from that list, so a joint the package adds is a
+ * variant here with nothing else to change, and a script cannot ask for one it misspelt.
+ */
+const HAND_JOINT = hostEnum(XR_MODULE, 'HandJoint', HAND_JOINTS.map((name) => name
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')), 'One of the twenty-five joints WebXR tracks on a hand, from the wrist to each fingertip.');
+export const XR_TYPES = [HAND.type, HAND_JOINT.type];
 const define = (name, params, returns, effects, doc, implementation) => defineCapability({
     module: XR_MODULE,
     name,
@@ -54,8 +67,8 @@ const define = (name, params, returns, effects, doc, implementation) => defineCa
     doc,
     implementation,
 });
-/** `left`, `right`, or anything else for the source with no handedness. */
-const HAND = { name: 'hand', type: 'String' };
+const HAND_PARAM = { name: 'hand', type: 'Hand' };
+const JOINT_PARAM = { name: 'joint', type: 'HandJoint' };
 export const XR_CAPABILITIES = [
     define('presenting', [], 'bool', ['scene.read'], 'Whether a session is running. False before one starts and after the user takes the headset off.', 'XrRuntime.presenting'),
     define('supported', [], 'bool', ['scene.read'], 'Whether this device could present at all. False on a machine with no headset attached.', 'XrRuntime.supported'),
@@ -76,9 +89,9 @@ export const XR_CAPABILITIES = [
     define('headX', [], 'f32', ['input.read'], 'Where the viewer’s head is, in metres. Zero outside a session.', 'XrRuntime.headX'),
     define('headY', [], 'f32', ['input.read'], 'Where the viewer’s head is, in metres. Zero outside a session.', 'XrRuntime.headY'),
     define('headZ', [], 'f32', ['input.read'], 'Where the viewer’s head is, in metres. Zero outside a session.', 'XrRuntime.headZ'),
-    define('trigger', [HAND], 'f32', ['input.read'], 'How far a hand’s trigger is pulled, 0 to 1. Zero for a hand that is not there.', 'XrRuntime.trigger'),
-    define('squeeze', [HAND], 'f32', ['input.read'], 'How far a hand’s grip is squeezed, 0 to 1. Zero for a hand that is not there.', 'XrRuntime.squeeze'),
-    define('holding', [HAND], 'bool', ['input.read'], 'Whether a hand is tracked this frame. False while a controller is set down or out of view.', 'XrRuntime.holding'),
+    define('trigger', [HAND_PARAM], 'f32', ['input.read'], 'How far a hand’s trigger is pulled, 0 to 1. Zero for a hand that is not there.', 'XrRuntime.trigger'),
+    define('squeeze', [HAND_PARAM], 'f32', ['input.read'], 'How far a hand’s grip is squeezed, 0 to 1. Zero for a hand that is not there.', 'XrRuntime.squeeze'),
+    define('holding', [HAND_PARAM], 'bool', ['input.read'], 'Whether a hand is tracked this frame. False while a controller is set down or out of view.', 'XrRuntime.holding'),
     /*
      * A joint by name and not by index.
      *
@@ -86,15 +99,15 @@ export const XR_CAPABILITIES = [
      * number a script would have to keep its own copy of and watch drift against a specification.
      * A name is checked at the call and answers false for one nobody has heard of.
      */
-    define('jointX', [HAND, { name: 'joint', type: 'String' }], 'f32', ['input.read'], 'Where a named hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointX'),
-    define('jointY', [HAND, { name: 'joint', type: 'String' }], 'f32', ['input.read'], 'Where a named hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointY'),
-    define('jointZ', [HAND, { name: 'joint', type: 'String' }], 'f32', ['input.read'], 'Where a named hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointZ'),
-    define('pinching', [HAND], 'bool', ['input.read'], 'Whether a hand’s thumb and index tips are close enough to count as a pinch.', 'XrRuntime.pinching'),
+    define('jointX', [HAND_PARAM, JOINT_PARAM], 'f32', ['input.read'], 'Where a hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointX'),
+    define('jointY', [HAND_PARAM, JOINT_PARAM], 'f32', ['input.read'], 'Where a hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointY'),
+    define('jointZ', [HAND_PARAM, JOINT_PARAM], 'f32', ['input.read'], 'Where a hand joint is, in metres. Zero for a joint that is not tracked.', 'XrRuntime.jointZ'),
+    define('pinching', [HAND_PARAM], 'bool', ['input.read'], 'Whether a hand’s thumb and index tips are close enough to count as a pinch.', 'XrRuntime.pinching'),
 ];
 /** How close two fingertips count as a pinch, in metres. */
 const PINCH_METRES = 0.025;
-function handOf(value) {
-    return value === 'left' ? 'left' : value === 'right' ? 'right' : 'none';
+function handOf(hand) {
+    return HANDEDNESS[HAND.code(hand)] ?? 'none';
 }
 export function xrImplementation(runtime) {
     const at = new Float32Array(3);
@@ -107,7 +120,7 @@ export function xrImplementation(runtime) {
         /* The flat arrays the package already fills are read directly. `jointPosition` would answer the
            same question through a `Float32Array` this would then have to unpack, three times per joint
            per frame. */
-        const index = jointIndexOf(name);
+        const index = HAND_JOINT.code(name);
         if (index < 0 || skeleton.tracked[index] !== 1)
             return 0;
         return skeleton.matrices[index * 16 + 12 + axis] ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/script",
-  "version": "4.7.4",
+  "version": "4.8.0",
   "description": "The drift/* capability bindings: what this engine provides to DriftScript, and the only place the two are coupled",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,20 +28,20 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "driftscript": "1.14.0"
+    "driftscript": "1.16.0"
   },
   "peerDependencies": {
-    "@driftengine/ai": "4.7.4",
-    "@driftengine/animation": "4.7.4",
-    "@driftengine/audio": "4.7.4",
-    "@driftengine/chemistry": "4.7.4",
-    "@driftengine/core": "4.7.4",
-    "@driftengine/editor": "4.7.4",
-    "@driftengine/entities": "4.7.4",
-    "@driftengine/network": "4.7.4",
-    "@driftengine/terrain": "4.7.4",
-    "@driftengine/ui2d": "4.7.4",
-    "@driftengine/xr": "4.7.4"
+    "@driftengine/ai": "4.8.0",
+    "@driftengine/animation": "4.8.0",
+    "@driftengine/audio": "4.8.0",
+    "@driftengine/chemistry": "4.8.0",
+    "@driftengine/core": "4.8.0",
+    "@driftengine/editor": "4.8.0",
+    "@driftengine/entities": "4.8.0",
+    "@driftengine/network": "4.8.0",
+    "@driftengine/terrain": "4.8.0",
+    "@driftengine/ui2d": "4.8.0",
+    "@driftengine/xr": "4.8.0"
   },
   "author": "Drift Technologies",
   "repository": {