@driftengine/script 4.7.4 → 4.8.1

package/src/bindings/behavior.ts

@@ -1,8 +1,17 @@
 import { BehaviorRunner } from '@driftengine/core';
 import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import { hostEnum } from './variants.ts';
 
 export const BEHAVIOR_MODULE = 'drift/behavior';
 
+/** What a tick answered, in the engine's own order: `FAILURE`, `SUCCESS`, `RUNNING`. */
+const TREE_STATUS = hostEnum(
+  BEHAVIOR_MODULE,
+  'TreeStatus',
+  ['Failure', 'Success', 'Running'],
+  'What a behaviour tree answered: it failed, it finished, or it is still going.',
+);
+
 /**
  * `drift/behavior` — driving and watching a behaviour tree from a script.
  *
@@ -29,6 +38,7 @@ export const BEHAVIOR_TYPES: readonly OpaqueType[] = [
     name: 'Behavior',
     doc: 'One agent running one behaviour tree: where it is in its routine.',
   },
+  TREE_STATUS.type,
 ];
 
 const define = (
@@ -55,15 +65,15 @@ export const BEHAVIOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     'tick',
     [{ name: 'behavior', type: 'Behavior' }],
-    'i32',
+    'TreeStatus',
     ['behavior.write'],
-    'Advance the routine one tick. Answers 0 failed, 1 finished, 2 still going. Does nothing while paused.',
+    'Advance the routine one tick, and answer whether it failed, finished or is still going. Does nothing while paused.',
     false,
   ),
   define(
     'step',
     [{ name: 'behavior', type: 'Behavior' }],
-    'i32',
+    'TreeStatus',
     ['behavior.write'],
     'Advance one tick even while paused, which is what a step button is.',
     false,
@@ -97,7 +107,7 @@ export const BEHAVIOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     'status',
     [{ name: 'behavior', type: 'Behavior' }],
-    'i32',
+    'TreeStatus',
     ['behavior.read'],
     'What the last tick answered, without ticking again.',
   ),
@@ -142,14 +152,16 @@ export function behaviorImplementation(services: BehaviorServices): Record<strin
   let scratch: Uint32Array<ArrayBuffer> = new Uint32Array(32);
 
   return {
-    tick: (character: BehaviorRunner<unknown>) => character.tick(services.context(character)),
-    step: (character: BehaviorRunner<unknown>) => character.stepOnce(services.context(character)),
+    tick: (character: BehaviorRunner<unknown>) =>
+      TREE_STATUS.of[character.tick(services.context(character))],
+    step: (character: BehaviorRunner<unknown>) =>
+      TREE_STATUS.of[character.stepOnce(services.context(character))],
     restart: (character: BehaviorRunner<unknown>) => character.reset(),
     setPaused: (character: BehaviorRunner<unknown>, paused: boolean) => {
       character.paused = paused;
     },
     paused: (character: BehaviorRunner<unknown>) => character.paused,
-    status: (character: BehaviorRunner<unknown>) => character.status,
+    status: (character: BehaviorRunner<unknown>) => TREE_STATUS.of[character.status],
     depth(character: BehaviorRunner<unknown>): number {
       scratch = fit(scratch, character);
       return character.activePath(scratch);

package/src/bindings/chemistry.ts

@@ -45,6 +45,7 @@ import {
 } from '@driftengine/chemistry';
 import { type ComponentType, defineComponent } from '@driftengine/entities';
 import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import { hostEnum } from './variants.ts';
 
 export const CHEMISTRY_MODULE = 'drift/chemistry';
 
@@ -68,6 +69,44 @@ const define = (
     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.
  *
@@ -91,6 +130,8 @@ export const CHEMISTRY_TYPES: readonly OpaqueType[] = [
     name: 'Species',
     doc: 'A registered chemical species, such as `O2` or `cellulose`.',
   },
+  MATTER_PHASE.type,
+  CHEMISTRY_EVENT.type,
 ];
 
 const READ = ['chemistry.read'] as const;
@@ -199,9 +240,9 @@ export const CHEMISTRY_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     'phase',
     [P, PARCEL],
-    'i32',
+    'MatterPhase',
     READ,
-    '0 solid, 1 liquid, 2 gas, 3 mixed. Mixed is a real answer: wet wood is a solid and a liquid at once.',
+    '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(
@@ -401,9 +442,9 @@ export const CHEMISTRY_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     'eventKind',
     [P, { name: 'index', type: 'i32' }],
-    'i32',
+    'ChemistryEvent',
     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.',
+    'What happened in one of this tick’s events. An index outside `eventCount` is refused, naming both.',
   ),
   define(
     'eventParcel',
@@ -496,7 +537,7 @@ export function chemistryImplementation(services: ChemistryServices): Record<str
     charDepth: (_: unknown, parcel: number) => parcels.charDepthOf(parcel),
     wetness: (_: unknown, parcel: number) => parcels.wetnessOf(parcel),
     wettable: (_: unknown, parcel: number) => parcels.wettable(parcel),
-    phase: (_: unknown, parcel: number) => parcels.parcelPhaseOf(parcel),
+    phase: (_: unknown, parcel: number) => MATTER_PHASE.of[parcels.parcelPhaseOf(parcel)],
     burning: (_: unknown, parcel: number) => parcels.burning(parcel),
     smouldering: (_: unknown, parcel: number) => parcels.smouldering(parcel),
     /* Watts inside, kilowatts out: a fire is quoted in kW everywhere a person reads one. */
@@ -548,7 +589,14 @@ export function chemistryImplementation(services: ChemistryServices): Record<str
       air.addHeat(x, y, z, joules),
 
     eventCount: () => world.events.count,
-    eventKind: (_: unknown, index: number) => world.events.kindOf(index),
+    eventKind(_: unknown, index: number) {
+      /* 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: (_: unknown, index: number) => world.events.parcelOf(index),
     eventSpecies: (_: unknown, index: number) => world.events.speciesOf(index),
     eventValue: (_: unknown, index: number) => world.events.valueOf(index),

package/src/bindings/core.ts

@@ -25,6 +25,7 @@ import {
   type Collider,
   ColliderSet,
   type KeyValueStore,
+  type SaveStatus,
   RemoteSaveStore,
   MessageQueue,
   PhysicsWorld,
@@ -41,6 +42,7 @@ import {
   wrapAngle,
 } from '@driftengine/core';
 import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import { type Variant, hostEnum } from './variants.ts';
 
 export const TIME_MODULE = 'drift/time';
 export const RANDOM_MODULE = 'drift/random';
@@ -72,6 +74,28 @@ const define = (
     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: Readonly<Record<SaveStatus, Variant>> = {
+  idle: SAVE_STATUS.of[0] as Variant,
+  pending: SAVE_STATUS.of[1] as Variant,
+  saving: SAVE_STATUS.of[2] as Variant,
+  failed: SAVE_STATUS.of[3] as Variant,
+};
+
 /**
  * Handles a script holds and passes back, never reads into.
  *
@@ -119,6 +143,8 @@ export const CORE_TYPES: readonly OpaqueType[] = [
     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,
 ];
 
 /**
@@ -306,10 +332,10 @@ export const PERSISTENCE_CAPABILITIES: readonly CapabilityDefinition[] = [
     PERSISTENCE_MODULE,
     'saveStatus',
     [{ name: 'store', type: 'Store' }],
-    'String',
+    '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.',
+    '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,
@@ -899,10 +925,10 @@ export const PHYSICS_CAPABILITIES: readonly CapabilityDefinition[] = [
       { name: 'world', type: 'PhysicsWorld' },
       { name: 'index', type: 'i32' },
     ],
-    'i32',
+    'ContactKind',
     ['physics.read'],
     true,
-    "An event's kind: 0 entered, 1 still touching, 2 left.",
+    "An event's kind: the two bodies began touching, are still touching, or have parted.",
   ),
   define(
     PHYSICS_MODULE,
@@ -1341,7 +1367,7 @@ export function persistenceImplementation(): Record<string, unknown> {
     /* `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: KeyValueStore) =>
-      store instanceof RemoteSaveStore ? store.status : 'idle',
+      SAVE_STATUS_OF[store instanceof RemoteSaveStore ? store.status : 'idle'],
     pendingSaves: (store: KeyValueStore) => (store instanceof RemoteSaveStore ? store.pending : 0),
   };
 }
@@ -1583,7 +1609,13 @@ export function physicsImplementation(): Record<string, unknown> {
     hitFraction: (world: PhysicsWorld) => f(hitOf(world).fraction),
 
     contactCount: (world: PhysicsWorld) => world.events.count,
-    contactKind: (world: PhysicsWorld, index: number) => world.events.data[index * 3] ?? 0,
+    contactKind(world: PhysicsWorld, index: number) {
+      /* 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] as number];
+    },
     contactA: (world: PhysicsWorld, index: number) => world.events.data[index * 3 + 1] ?? 0,
     contactB: (world: PhysicsWorld, index: number) => world.events.data[index * 3 + 2] ?? 0,
 

package/src/bindings/editor.ts

@@ -1,10 +1,84 @@
 import type { Gizmo, SceneNode } from '@driftengine/core';
 import type { EditorHost } from '@driftengine/editor';
+import type { EditorMode, FieldKind } from '@driftengine/editor';
 import type { CapabilityDefinition, OpaqueType } from 'driftscript';
 import { defineCapability } from 'driftscript';
+import { type Variant, hostEnum } from './variants.ts';
 
 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: readonly string[], of: readonly Variant[]): ReadonlyMap<string, Variant> =>
+  new Map(names.map((name, index) => [name, of[index] as Variant]));
+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'] satisfies EditorMode[], EDITOR_MODE.of);
+const FIELD_KIND_OF = byName(
+  ['number', 'integer', 'boolean', 'text', 'entity', 'enum'] satisfies FieldKind[],
+  FIELD_KIND.of,
+);
+
 /**
  * `drift/editor` — the transform tool, driven from a script that never ships.
  *
@@ -37,13 +111,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: readonly OpaqueType[] = [
   {
@@ -56,6 +133,11 @@ export const EDITOR_TYPES: readonly OpaqueType[] = [
     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 = (
@@ -103,13 +185,18 @@ export const EDITOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   define(
     'gizmoMode',
     OF,
-    'String',
-    'Which of the three the gizmo is: "translate", "rotate" or "scale".',
+    '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',
@@ -125,15 +212,16 @@ export const EDITOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   ),
 
   /*
-   * **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.',
+    '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(
@@ -172,7 +260,7 @@ export const EDITOR_CAPABILITIES: readonly CapabilityDefinition[] = [
    * **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,
@@ -254,8 +342,8 @@ export const EDITOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   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.',
+    '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',
@@ -271,28 +359,6 @@ export const EDITOR_CAPABILITIES: readonly CapabilityDefinition[] = [
   ),
 ];
 
-/**
- * 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: readonly string[] = [
-  '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.**
  *
@@ -312,7 +378,7 @@ export function editorImplementation(): Record<string, unknown> {
     scaleMode: (gizmo: Gizmo) => {
       gizmo.mode = 'scale';
     },
-    gizmoMode: (gizmo: Gizmo) => gizmo.mode,
+    gizmoMode: (gizmo: Gizmo) => GIZMO_MODE_OF.get(gizmo.mode),
 
     worldSpace: (gizmo: Gizmo) => {
       gizmo.space = 'world';
@@ -320,14 +386,14 @@ export function editorImplementation(): Record<string, unknown> {
     localSpace: (gizmo: Gizmo) => {
       gizmo.space = 'local';
     },
-    space: (gizmo: Gizmo) => gizmo.space,
+    space: (gizmo: Gizmo) => GIZMO_SPACE_OF.get(gizmo.space),
 
     size: (gizmo: Gizmo) => gizmo.size,
     setSize: (gizmo: Gizmo, metres: number) => {
       gizmo.size = metres;
     },
 
-    hovered: (gizmo: Gizmo) => HANDLE_NAMES[gizmo.hovered] ?? 'none',
+    hovered: (gizmo: Gizmo) => GIZMO_HANDLE.of[gizmo.hovered] ?? GIZMO_HANDLE.of[0],
     dragging: (gizmo: Gizmo) => gizmo.dragging,
     dragAngle: (gizmo: Gizmo) => gizmo.dragAngle,
 
@@ -349,7 +415,7 @@ export function editorImplementation(): Record<string, unknown> {
     rotationZ: (gizmo: Gizmo) => gizmo.rotation[2] ?? 0,
     rotationW: (gizmo: Gizmo) => gizmo.rotation[3] ?? 1,
 
-    mode: (editor: EditorHost) => editor.mode,
+    mode: (editor: EditorHost) => EDITOR_MODE_OF.get(editor.mode),
     playing: (editor: EditorHost) => editor.mode === 'play',
     play: (editor: EditorHost) => editor.play(),
     pause: (editor: EditorHost) => {
@@ -382,7 +448,15 @@ export function editorImplementation(): Record<string, unknown> {
     fieldCount: (editor: EditorHost) => editor.inspector.fields.length,
     fieldLabel: (editor: EditorHost, field: number) => editor.inspector.fields[field]?.label ?? '',
     fieldGroup: (editor: EditorHost, field: number) => editor.inspector.fields[field]?.group ?? '',
-    fieldKind: (editor: EditorHost, field: number) => editor.inspector.fields[field]?.kind ?? '',
+    fieldKind(editor: EditorHost, field: number) {
+      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: EditorHost, field: number) => {
       const value = editor.inspector.fields[field]?.value;
       return typeof value === 'number' ? value : 0;

package/src/bindings/entities.ts

@@ -399,10 +399,17 @@ export function entitiesImplementation(services: EntityServices): Record<string,
     attach: (w: World, entity: Entity, component: string) => w.add(entity, resolve(component)),
     detach: (w: World, entity: Entity, component: string) => w.remove(entity, resolve(component)),
     read: (w: World, entity: Entity, component: string, field: string) => {
-      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: World, entity: Entity, component: string, field: string, value: number) =>
       w.write(entity, resolve(component), field, value),
@@ -551,3 +558,8 @@ interface QuerySource {
   query(a: ComponentType, b?: ComponentType, c?: ComponentType, d?: ComponentType): QueryCursor;
   view(type: ComponentType, forWriting: boolean): ComponentView;
 }
+
+/** Whether a component declared this field as an option, `option:<inner>` in its schema. */
+function optionalField(type: ComponentType, field: string): boolean {
+  return type.schema.fields.some((f) => f.name === field && f.type.startsWith('option:'));
+}

package/src/bindings/variants.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 function hostEnum(
+  module: string,
+  name: string,
+  variants: readonly string[],
+  doc: string,
+): HostEnum {
+  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,
+  };
+}