@driftengine/script 3.61.0

package/src/bindings/xr.ts

@@ -0,0 +1,272 @@
+/**
+ * `drift/xr` — what a script may ask about a headset, and what it may not.
+ *
+ * **The last surface the linker refused, and it refused it since 1.0.** `drift/xr` has been in the
+ * language's `SPECIFIED_MODULES` the whole time with nothing here describing it, which is exactly
+ * the arrangement the language exists to make possible: a file naming it parsed, type-checked and
+ * declined only at link time, and the same file links now without a character changing.
+ *
+ * ## Nothing here is deterministic, and that is the property
+ *
+ * A head moves because somebody moved their head. A controller reports where it is because a camera
+ * saw it. None of that is a function of the simulation, so none of it may be read from inside the
+ * fixed step: a `@deterministic` system branching on where a hand is would take the other branch on
+ * replay, and a stored run would stop meaning anything.
+ *
+ * `drift/ui` settled the same question for a pointer, and the reasoning transfers unchanged: its
+ * `hovered` and `pressed` are fields on a tree that `scene.read` would have type-checked and would
+ * have been a lie about what they carry, so they were declared `input.read` and left outside
+ * `DETERMINISTIC_EFFECTS`. A head and a hand are the same kind of fact arriving through the same
+ * door.
+ *
+ * ## No matrices, and the argument is `drift/render`'s
+ *
+ * There is no `xr.projection` and no `xr.viewMatrix`. An eye's projection is a fact about somebody's
+ * optics, and its view is a fact about where their head is in a room the script has never seen;
+ * handing either to a script would be `drift/render`'s refused dial read in a different costume, a
+ * machine-dependent number registered where a script could compare two runs with it.
+ *
+ * What a script gets is where the head is, whether a session is running, and what the hands are
+ * doing. Drawing the two eyes is the host's, because the host owns the renderer and the loop.
+ *
+ * ## `presenting` is `scene.read` and the rest is `input.read`
+ *
+ * Whether a session is running is a fact about the view: it decides what is drawn and where, and it
+ * changes when somebody puts a headset on. `scene.read` sits outside `DETERMINISTIC_EFFECTS` for
+ * that reason, which is the one this needs.
+ */
+
+import { type CapabilityDefinition, type OpaqueType, defineCapability } from 'driftscript';
+import { JOINT_INDEX } from '@driftengine/xr';
+import type { ControllerState, HandSkeleton, Handedness, XrSupport } from '@driftengine/xr';
+
+export const XR_MODULE = 'drift/xr';
+
+export const XR_TYPES: readonly OpaqueType[] = [];
+
+const define = (
+  name: string,
+  params: readonly { name: string; type: string }[],
+  returns: string,
+  effects: CapabilityDefinition['effects'],
+  doc: string,
+  implementation: string,
+): CapabilityDefinition =>
+  defineCapability({
+    module: XR_MODULE,
+    name,
+    signature: `fn(${params.map((p) => `${p.name}: ${p.type}`).join(', ')}) -> ${returns}`,
+    params: [...params],
+    returns,
+    effects,
+    /*
+     * Never deterministic, on every capability here. See the header: a head moves because a person
+     * moved, and a `@deterministic` system reading one would take a different branch on replay.
+     */
+    deterministic: false,
+    doc,
+    implementation,
+  });
+
+/** `left`, `right`, or anything else for the source with no handedness. */
+const HAND = { name: 'hand', type: 'String' };
+
+export const XR_CAPABILITIES: readonly CapabilityDefinition[] = [
+  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',
+  ),
+  /*
+   * The head, as three reads rather than one call returning a triple.
+   *
+   * The language has no tuple and no out parameter, and a `data` record would be a value the host
+   * allocates per call inside a frame loop. Three floats is the shape every other position on this
+   * surface takes, and `drift/navigation`'s `steerX`/`steerY`/`steerZ` set the precedent.
+   */
+  /*
+   * `f32` and not `float`. The language refuses a width-polymorphic return with no `float`
+   * parameter to fix it against, which `drift/navigation.steerX` never meets because it takes the
+   * position it steers from. These take a hand or nothing, so the width is stated: every position
+   * this engine stores is a `Float32Array`, and answering `f64` would widen a number that was
+   * never that precise.
+   */
+  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',
+  ),
+  /*
+   * A joint by name and not by index.
+   *
+   * `HAND_JOINTS` fixes an order and a script could be handed it, and should not be: an index is a
+   * 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',
+  ),
+];
+
+/**
+ * What the host keeps up to date, and what a script reads through.
+ *
+ * The consumer's, exactly as `AgentRegistry` and `SoundRegistry` are. This package owns neither the
+ * session nor the frame, and which of them is current is not something a binding can know.
+ */
+export interface XrRuntime {
+  readonly support: XrSupport | null;
+  /** Null outside a session. */
+  readonly headPosition: Float32Array | null;
+  controller(hand: Handedness): ControllerState | null;
+  hand(hand: Handedness): HandSkeleton | null;
+}
+
+/** How close two fingertips count as a pinch, in metres. */
+const PINCH_METRES = 0.025;
+
+function handOf(value: string): Handedness {
+  return value === 'left' ? 'left' : value === 'right' ? 'right' : 'none';
+}
+
+export function xrImplementation(runtime: XrRuntime): Readonly<Record<string, unknown>> {
+  const at = new Float32Array(3);
+  const other = new Float32Array(3);
+
+  const head = (axis: number): number => runtime.headPosition?.[axis] ?? 0;
+
+  const joint = (hand: string, name: string, axis: number): number => {
+    const skeleton = runtime.hand(handOf(hand));
+    if (skeleton === null) return 0;
+    /* 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);
+    if (index < 0 || skeleton.tracked[index] !== 1) return 0;
+    return skeleton.matrices[index * 16 + 12 + axis] ?? 0;
+  };
+
+  return {
+    presenting: (): boolean => runtime.headPosition !== null,
+    supported: (): boolean =>
+      runtime.support?.immersiveVr === true || runtime.support?.immersiveAr === true,
+    headX: (): number => head(0),
+    headY: (): number => head(1),
+    headZ: (): number => head(2),
+    trigger: (hand: string): number => runtime.controller(handOf(hand))?.buttons[0] ?? 0,
+    squeeze: (hand: string): number => runtime.controller(handOf(hand))?.buttons[1] ?? 0,
+    holding: (hand: string): boolean => runtime.controller(handOf(hand))?.tracked ?? false,
+    jointX: (hand: string, name: string): number => joint(hand, name, 0),
+    jointY: (hand: string, name: string): number => joint(hand, name, 1),
+    jointZ: (hand: string, name: string): number => joint(hand, name, 2),
+    pinching: (hand: string): boolean => {
+      const skeleton = runtime.hand(handOf(hand));
+      if (skeleton === null) return false;
+      const thumb = jointIndexOf('thumb-tip');
+      const index = jointIndexOf('index-finger-tip');
+      if (skeleton.tracked[thumb] !== 1 || skeleton.tracked[index] !== 1) return false;
+      for (let i = 0; i < 3; i++) {
+        at[i] = skeleton.matrices[thumb * 16 + 12 + i] ?? 0;
+        other[i] = skeleton.matrices[index * 16 + 12 + i] ?? 0;
+      }
+      const dx = (at[0] as number) - (other[0] as number);
+      const dy = (at[1] as number) - (other[1] as number);
+      const dz = (at[2] as number) - (other[2] as number);
+      return Math.sqrt(dx * dx + dy * dy + dz * dz) <= PINCH_METRES;
+    },
+  };
+}
+
+/**
+ * A joint's index by name.
+ *
+ * **Read from `@driftengine/xr` rather than written again here.** That package owns the order, an
+ * index is written into recordings, and a second copy of the list would be a second answer to what
+ * a stored hand means the first time somebody added a joint to one of them.
+ */
+function jointIndexOf(name: string): number {
+  return JOINT_INDEX[name] ?? -1;
+}

package/src/entityHost.ts

@@ -0,0 +1,219 @@
+/**
+ * Building a world from what a module declares.
+ *
+ * A compiled `.drs` file carries its components, entities, systems and prefabs as **description**
+ * rather than code. This turns that description into the engine's own objects: a `ComponentType`
+ * per component, a `Prefab` per prefab, and a `SystemDefinition` per system.
+ *
+ * ## A system definition calls through `exports`, and that is what makes it hot-reloadable
+ *
+ * `runSchedule` caches one `BoundSystem` per world and definition, and calls `definition.run(view)`.
+ * A definition holding the generated function *directly* would pin the pre-patch body in the
+ * schedule forever — and the symptom is an edit that compiles, reloads, reports success and changes
+ * nothing, which is the one failure hot reload exists to prevent.
+ *
+ * So `run` reaches the function through `module.exports` on every tick. That is one property lookup
+ * per system per tick, which is the same bargain `runtime/module.ts` documents at its own
+ * declaration and the reason that indirection exists at all.
+ *
+ * ## A host-declared component is asserted, never created
+ *
+ * `component Transform from host { … }` says the host registered one and this is its shape. The
+ * module creates nothing for it; it is checked when the module binds, and a mismatch is refused
+ * naming the field and both types. **The refusal is the whole value of the declaration** — without
+ * it the two descriptions drift, and the first thing anybody notices is a field reading zeroes.
+ *
+ * ## A system's resources are resolved here, once, and `@driftengine/entities` never learns about them
+ *
+ * `system Walk { uses graph: NavGraph … }` asks to be handed a value this host owns. Without it a
+ * handle reaches a script only as a *function* parameter, and every per-entity walk has to be
+ * driven from TypeScript. The generated function takes a second parameter: a table keyed by **type
+ * name**, so a host supplies "the `NavGraph` this world has" and never learns what any script
+ * called its binding.
+ *
+ * The table is built at registration and captured, rather than assembled per tick. A resource does
+ * not change between ticks, and an object per system per tick is the allocation this package refuses
+ * everywhere else.
+ *
+ * **A missing resource is refused at registration, not left as `undefined`.** Passing nothing would
+ * reach a capability as an absent argument and produce a wrong *result* rather than an error, which
+ * is the trap `host.ts` step four is about. Init is where a person is watching.
+ *
+ * `SystemDefinition` gains nothing for this. A resource is a host's object, and the ECS has no
+ * business knowing one exists — so the table lives in the closure that already reaches through
+ * `module.exports`.
+ */
+import {
+  type ComponentType,
+  type Prefab,
+  type SystemDefinition,
+  type SystemView,
+  defineComponent,
+  definePrefab,
+} from '@driftengine/entities';
+import type { DriftModule } from 'driftscript';
+
+/** Components a host already registered, by the name a script writes. */
+export type ComponentRegistry = Map<string, ComponentType>;
+
+/**
+ * Values a host lends to systems, by the **type name** a script writes in a `uses` clause.
+ *
+ * By type rather than by binding name, which is the language's own rule: a resource is one per type,
+ * so two systems asking for a `NavGraph` are handed the same object whatever each file calls it, and
+ * a script renaming its binding changes nothing here.
+ */
+export type ResourceRegistry = ReadonlyMap<string, unknown>;
+
+export interface RegisteredModule {
+  /** Component types this module declared, in declaration order. Host-asserted ones are absent. */
+  readonly components: readonly ComponentType[];
+  readonly prefabs: readonly Prefab[];
+  /** Ready for `buildSchedule`, in declaration order. */
+  readonly systems: readonly SystemDefinition[];
+}
+
+/**
+ * Check every `from host` declaration against what the host registered.
+ *
+ * Throws on the first mismatch rather than collecting: a shape disagreement means the module was
+ * compiled against a different world than the one it is being loaded into, and the second error
+ * would be a consequence of the first.
+ */
+export function assertHostShapes(module: DriftModule, registry: ComponentRegistry): void {
+  for (const declared of module.info.components ?? []) {
+    if (!declared.fromHost) continue;
+
+    const registered = registry.get(declared.name);
+    if (registered === undefined) {
+      throw new Error(
+        `\`${module.info.module}\` declares \`component ${declared.name} from host\`, and this host ` +
+          `registered no component of that name. It has ` +
+          `${[...registry.keys()].map((k) => `\`${k}\``).join(', ')}. A \`from host\` declaration ` +
+          'asserts a shape rather than creating one, so there is nothing to fall back to.',
+      );
+    }
+
+    const actual = new Map(registered.schema.fields.map((field) => [field.name, field.type]));
+    for (const field of declared.schema.fields) {
+      const found = actual.get(field.name);
+      if (found === undefined) {
+        throw new Error(
+          `\`${declared.name}.${field.name}\` is declared in \`${module.info.module}\` and the ` +
+            `registered component has no such field. It has ` +
+            `${[...actual.keys()].map((k) => `\`${k}\``).join(', ')}.`,
+        );
+      }
+      if (found !== field.type) {
+        throw new Error(
+          `\`${declared.name}.${field.name}\` is \`${field.type}\` in \`${module.info.module}\` and ` +
+            `\`${found}\` in the component this host registered. A script reading it would get a ` +
+            'value of a type it was not compiled against.',
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Build every component, prefab and system a module declares.
+ *
+ * Components are registered into `registry` as they are made, so a prefab or a system later in the
+ * same module finds them — and so a second module loaded against the same registry shares them
+ * rather than making a second store for one name.
+ */
+export function registerEntityModule(
+  module: DriftModule,
+  registry: ComponentRegistry,
+  resources: ResourceRegistry = new Map(),
+): RegisteredModule {
+  assertHostShapes(module, registry);
+
+  const components: ComponentType[] = [];
+  for (const declared of module.info.components ?? []) {
+    /* A host-declared component is already registered; asserting its shape is all this does. */
+    if (declared.fromHost) continue;
+    const existing = registry.get(declared.name);
+    /* A module reloaded keeps the store it already made: replacing the type would orphan every
+       entity holding one, which is a world that silently loses its components on an edit. */
+    const type = existing ?? defineComponent(declared.schema);
+    registry.set(declared.name, type);
+    components.push(type);
+  }
+
+  const prefabs = (module.info.prefabs ?? []).map((declared) =>
+    definePrefab(
+      declared.name,
+      declared.components.map((component) => {
+        const type = registry.get(component.name);
+        if (type === undefined) {
+          throw new Error(
+            `prefab \`${declared.name}\` names the component \`${component.name}\`, which nothing ` +
+              'has registered. The compiler refuses this, so a module reaching here was built ' +
+              'against a different set of declarations than it is being loaded with.',
+          );
+        }
+        return [type, component.values] as const;
+      }),
+    ),
+  );
+
+  const systems = (module.info.systems ?? []).map((declared): SystemDefinition => {
+    const resolve = (names: readonly string[]): ComponentType[] =>
+      names.map((name) => {
+        const type = registry.get(name);
+        if (type === undefined) {
+          throw new Error(
+            `system \`${declared.name}\` declares \`${name}\`, which nothing has registered.`,
+          );
+        }
+        return type;
+      });
+
+    /*
+     * Built once and frozen, so a system cannot acquire a resource by writing into the table it was
+     * handed — which would be state shared between ticks that nothing declares.
+     */
+    const lent: Record<string, unknown> = {};
+    for (const resource of declared.uses ?? []) {
+      if (!resources.has(resource.type)) {
+        throw new Error(
+          `system \`${declared.name}\` uses \`${resource.name}: ${resource.type}\`, and no ` +
+            `\`${resource.type}\` was supplied. Pass one in the third argument to ` +
+            '`registerEntityModule`, keyed by the type name. Refused here rather than passed as ' +
+            'nothing, because an absent argument reaches a capability as a wrong answer.',
+        );
+      }
+      lent[resource.type] = resources.get(resource.type);
+    }
+    Object.freeze(lent);
+
+    return {
+      name: declared.name,
+      reads: resolve(declared.reads),
+      writes: resolve(declared.writes),
+      after: declared.after,
+      everyTicks: declared.everyTicks,
+      /*
+       * Through `exports` on every tick, never captured here. See the header: a captured function
+       * is pinned in the schedule across a hot patch, and the symptom is an edit that reports
+       * success and changes nothing.
+       */
+      run(view: SystemView): void {
+        const fn = module.exports[declared.name];
+        if (typeof fn !== 'function') {
+          throw new Error(
+            `\`${declared.name}\` is not exported by \`${module.info.module}\` any more. A disposed ` +
+              'module left in a schedule fails here rather than silently doing nothing.',
+          );
+        }
+        /* The second argument is passed whether or not this system asked for anything. A generated
+           function without `uses` clauses declares one parameter and ignores it, which is what makes
+           the quiet form quiet in the compiler and costs nothing here. */
+        (fn as (v: SystemView, r: Record<string, unknown>) => void)(view, lent);
+      },
+    };
+  });
+
+  return { components, prefabs, systems };
+}