@driftengine/script 3.61.0

package/dist/bindings/xr.js

@@ -0,0 +1,155 @@
+/**
+ * `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 { defineCapability } from 'driftscript';
+import { JOINT_INDEX } from '@driftengine/xr';
+export const XR_MODULE = 'drift/xr';
+export const XR_TYPES = [];
+const define = (name, params, returns, effects, doc, implementation) => 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 = [
+    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'),
+];
+/** 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';
+}
+export function xrImplementation(runtime) {
+    const at = new Float32Array(3);
+    const other = new Float32Array(3);
+    const head = (axis) => runtime.headPosition?.[axis] ?? 0;
+    const joint = (hand, name, axis) => {
+        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: () => runtime.headPosition !== null,
+        supported: () => runtime.support?.immersiveVr === true || runtime.support?.immersiveAr === true,
+        headX: () => head(0),
+        headY: () => head(1),
+        headZ: () => head(2),
+        trigger: (hand) => runtime.controller(handOf(hand))?.buttons[0] ?? 0,
+        squeeze: (hand) => runtime.controller(handOf(hand))?.buttons[1] ?? 0,
+        holding: (hand) => runtime.controller(handOf(hand))?.tracked ?? false,
+        jointX: (hand, name) => joint(hand, name, 0),
+        jointY: (hand, name) => joint(hand, name, 1),
+        jointZ: (hand, name) => joint(hand, name, 2),
+        pinching: (hand) => {
+            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] - other[0];
+            const dy = at[1] - other[1];
+            const dz = at[2] - other[2];
+            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) {
+    return JOINT_INDEX[name] ?? -1;
+}

package/dist/entityHost.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 } 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 declare function assertHostShapes(module: DriftModule, registry: ComponentRegistry): void;
+/**
+ * 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 declare function registerEntityModule(module: DriftModule, registry: ComponentRegistry, resources?: ResourceRegistry): RegisteredModule;

package/dist/entityHost.js

@@ -0,0 +1,159 @@
+/**
+ * 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 { defineComponent, definePrefab, } from '@driftengine/entities';
+/**
+ * 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, registry) {
+    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, registry, resources = new Map()) {
+    assertHostShapes(module, registry);
+    const components = [];
+    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];
+    })));
+    const systems = (module.info.systems ?? []).map((declared) => {
+        const resolve = (names) => 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 = {};
+        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) {
+                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(view, lent);
+            },
+        };
+    });
+    return { components, prefabs, systems };
+}

package/dist/host.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The engine as a DriftScript host: a registry describing what it provides, and the map that binds
+ * a compiled module to the real implementations.
+ *
+ * **This package is the only place the language and the engine are coupled**, and this file is the
+ * only place in it that knows about both at once. `driftscript` imports no `@driftengine/*` at all,
+ * asserted three ways; everything the engine contributes arrives through here.
+ *
+ * ---
+ *
+ * ## Adding a binding when a track lands
+ *
+ * **A capability that exists and is not bound is a capability DriftScript cannot reach**, and
+ * nothing fails when one is missed — a script author simply finds the module refused and assumes
+ * the track has not shipped. That silence is why this note exists rather than a checklist somewhere
+ * else.
+ *
+ * When a track lands, or a package grows a public function a script would want:
+ *
+ * 1. **Describe it.** A `defineCapability` entry in `bindings/`: its parameters and return as type
+ *    names, its effects, whether a `@deterministic` function may call it, and a sentence of
+ *    documentation that hover will show.
+ * 2. **Implement it.** One entry in the module's implementation map. A binding is a *lookup*; if it
+ *    needs the engine to grow a function, that function belongs in the package that owns the
+ *    subsystem.
+ * 3. **Provide it.** Add the module to `ENGINE_MODULES`, or a target cannot link it.
+ * 4. **Check the trap.** If the TypeScript signature has an optional parameter whose absence
+ *    produces a *wrong result* rather than an error, make it required here and say why — a script
+ *    author is further from the subsystem than a TypeScript caller and meets it first.
+ *    `bindings/animation.ts` is the worked example.
+ * 5. **Correct the table.** `docs/CAPABILITIES.md` names which modules DriftScript reaches, and
+ *    `driftscript`'s own linker names which do not, and refuses them by name.
+ *    Those two lists must agree; a test asserts it.
+ *
+ * A binding is cheap — a table entry and a lookup — and is the difference between a subsystem
+ * a consumer can script and one they can only call from TypeScript.
+ */
+import type { AudioGraph, SoundRegistry } from '@driftengine/audio';
+import { type BehaviorServices } from './bindings/behavior.ts';
+import { type NavigationServices } from './bindings/navigation.ts';
+import { type CapabilityRegistry, type DriftModule, type TargetManifest } from 'driftscript';
+import { type AiServices } from './bindings/ai.ts';
+import { type XrRuntime } from './bindings/xr.ts';
+import type { CoreServices } from './bindings/core.ts';
+import { type EntityServices } from './bindings/entities.ts';
+import { type ChemistryServices } from './bindings/chemistry.ts';
+/**
+ * What the engine can provide. Everything wired; nothing that is not.
+ *
+ * `drift/core` is deliberately absent: §11 gives its provider as `startLoop` and `LoopHooks`, which
+ * are what *drives* a script rather than what a script calls. A module with nothing to call is not
+ * registered rather than registered empty.
+ */
+export declare const ENGINE_MODULES: readonly string[];
+/**
+ * A registry describing this engine's capabilities.
+ *
+ * Built rather than exported as a constant, because a registry refuses a duplicate registration —
+ * two consumers sharing one module-level instance would be one consumer's startup failing on
+ * another's import. Cheap: a few dozen object literals.
+ */
+export declare function engineRegistry(): CapabilityRegistry;
+/**
+ * A target providing everything this engine has wired.
+ *
+ * A consumer that wants less passes its own list. **A consumer that wants more cannot** — the
+ * manifest may only name modules something provides, so a target claiming `drift/ecs` is refused
+ * at the manifest rather than at every call site.
+ */
+export declare function engineTarget(name?: string): TargetManifest;
+export interface HostServices extends CoreServices {
+    /**
+     * The agents a script may name, and what the two bridges answer for them.
+     *
+     * `agents` alone is a supported configuration: a host with no navigation graph and no session
+     * still gets `wake`, `consider`, `intentId` and `degraded`. The bridge sub-services are what
+     * `reachable`, `navigate`, `path` and `deciding` need, and a capability whose service is absent
+     * fails at the call saying which one to provide rather than answering falsely.
+     */
+    readonly ai?: AiServices;
+    /**
+     * The live session, if a host has one.
+     *
+     * Absent means `drift/xr` calls fail at the call naming the namespace, which is the bargain every
+     * optional service here makes. A stub would be worse than usual: a script asking where a head is
+     * and getting the origin cannot tell a headset at the world origin from no headset at all, and
+     * one of those is a scene that draws and the other is a scene nobody is in.
+     */
+    readonly xr?: XrRuntime;
+    readonly audio?: {
+        readonly graph: AudioGraph;
+        readonly registry: SoundRegistry;
+    };
+    /**
+     * The component types, and any prefabs, a script may name.
+     *
+     * Absent means a script's `drift/ecs` calls fail at the call with the namespace's own name in the
+     * error — the same bargain every other optional service makes, and the reason none of them is
+     * stubbed.
+     */
+    readonly entities?: EntityServices;
+    /**
+     * The chemistry world a script reads and writes.
+     *
+     * Absent means `drift/chemistry` calls fail at the call naming the namespace — the same bargain
+     * every other optional service makes, and the reason none of them is stubbed. A stub would make a
+     * script whose fire never lights indistinguishable from one whose chemistry is not connected.
+     */
+    readonly chemistry?: ChemistryServices;
+    /**
+     * The network scripts path over: a graph, and one search reused across every agent.
+     *
+     * Absent means `drift/navigation` calls fail at the call naming the namespace, like every other
+     * optional service. A stub would be worse here than elsewhere: an agent given a route of no nodes
+     * behaves exactly like one that arrived, so a world whose navigation was never connected would
+     * look like a world where every agent is already where it wants to be.
+     */
+    readonly navigation?: NavigationServices;
+    /**
+     * What a behaviour tick is handed.
+     *
+     * Absent means `drift/behavior` calls fail at the call naming the namespace. A stub is
+     * particularly bad here for the reason `doing` exists: an agent whose routine never runs looks
+     * exactly like one that is standing about because it has nothing to do.
+     */
+    readonly behavior?: BehaviorServices;
+}
+/**
+ * The implementation map a generated module's `__bind` receives.
+ *
+ * Keyed by logical module name, because that is what generated code looks up: `audio` in a `.drs`
+ * file is `$host['drift/audio']` in the output.
+ *
+ * **A service the consumer did not supply is absent rather than stubbed.** A module that binds it
+ * and then calls it fails at the call with the namespace's own name in the error, which is what the
+ * rule against silent no-ops asks for — a stub that quietly did nothing would make a script that
+ * plays no sound indistinguishable from one whose audio is not connected.
+ */
+export declare function engineImplementations(services: HostServices): Record<string, unknown>;
+export type BindResult = {
+    readonly bound: true;
+} | {
+    readonly bound: false;
+    readonly reason: string;
+};
+/**
+ * Give a loaded module its host, and refuse in words when the host cannot satisfy it.
+ *
+ * Checked against `__drift.requires` before anything is called, so a missing service is reported at
+ * bind time naming the module — rather than at the first capability call, deep in a frame, as an
+ * undefined property.
+ */
+export declare function bindModule(module: DriftModule, services: HostServices): BindResult;