@typeonce/ritmo 0.7.0 → 0.8.0

package/dist/Runtime.js

@@ -59,8 +59,10 @@ import * as HostClockModule from "./HostClock.js";
 import * as Command from "./Command.js";
 import * as DescriptorModule from "./Descriptor.js";
 import * as Cells from "./internal/cells.js";
+import { sameValue } from "./internal/equal.js";
 import * as DebugInternal from "./internal/debug.js";
 import { makeQueryEngine } from "./internal/queries.js";
+import { requirementIndex } from "./internal/requirements.js";
 import * as Streams from "./internal/streams.js";
 import { ABSENT, makeWorld } from "./internal/world.js";
 import * as Query from "./Query.js";
@@ -240,8 +242,52 @@ const makeValidatedRuntime = (options) => {
     const providedMachines = (options.machines ?? machines());
     const machineEntries = (options.machines ?? machines())[runtimeMachinesEntries];
     const machineDefinitionOrder = new Map(options.machineDefinitions.map((machine, index) => [machine.key, index]));
+    /** Machines the runtime was given an initial value for. */
+    const providedMachineKeys = new Set();
     for (const provision of machineEntries) {
         currentMachines.set(provision.machine.key, provision.initial);
+        providedMachineKeys.add(provision.machine.key);
+    }
+    /**
+     * Sub-states by parent machine key, in definition order, and the value
+     * each enters whenever its parent enters the state it exists in (its
+     * runtime-provided value). A sub-state has no current value while its
+     * parent is elsewhere, and never one when the runtime does not provide it.
+     */
+    const subStates = new Map();
+    const subStateEntry = new Map();
+    for (const machine of options.machineDefinitions) {
+        if (machine.within === undefined)
+            continue;
+        const siblings = subStates.get(machine.within.machine.key);
+        if (siblings === undefined)
+            subStates.set(machine.within.machine.key, [machine]);
+        else
+            siblings.push(machine);
+        if (!currentMachines.has(machine.key))
+            continue;
+        subStateEntry.set(machine.key, currentMachines.get(machine.key));
+    }
+    // Definition order puts a parent before its sub-states, so a sub-state of
+    // an inactive sub-state is cleared too.
+    for (const machine of options.machineDefinitions) {
+        if (machine.within !== undefined && currentMachines.get(machine.within.machine.key) !== machine.within.state) {
+            currentMachines.delete(machine.key);
+        }
+    }
+    /**
+     * Scope despawn triggers by machine key, in scope definition order
+     * (`Game.EntityScope(name, { despawnOnExit, despawnOnEnter })`).
+     */
+    const scopeTriggers = new Map();
+    for (const scope of options.scopeDefinitions) {
+        for (const trigger of scope.despawnOn) {
+            const triggers = scopeTriggers.get(trigger.machine.key);
+            if (triggers === undefined)
+                scopeTriggers.set(trigger.machine.key, [{ trigger, scope }]);
+            else
+                triggers.push({ trigger, scope });
+        }
     }
     const appendRelationFailure = (relation, operation, sourceId, targetId, error) => {
         if (tracing) {
@@ -283,15 +329,57 @@ const makeValidatedRuntime = (options) => {
         }
         systems.add(commandOrigin);
     };
+    /**
+     * `Schema.requires`, checked when commands are applied. Types reject a
+     * breaking command when they can see it; this catches the rest: a query
+     * proof gone stale within one flush (another system's command applied in
+     * between), erased types, and raw ids. A breaking command is skipped
+     * whole, traced, and reported by the `requirement-violated` lint.
+     */
+    const requirements = requirementIndex(options.schema);
+    /** With `debug`, skipped commands by system, command, and requirement, for the lint. */
+    const requirementViolations = new Map();
+    const violateRequirement = (command, entity, [component, missing]) => {
+        if (tracing)
+            recordEffect({ kind: "requirementViolated", entity, command, component, missing });
+        if (debugEnabled) {
+            const key = `${commandOrigin}/${command}/${component}/${missing}`;
+            const seen = requirementViolations.get(key);
+            requirementViolations.set(key, { system: commandOrigin, command, component, missing, entity, count: (seen?.count ?? 0) + 1 });
+        }
+    };
+    const holds = (id) => {
+        const record = world.records.get(id);
+        return (descriptor) => record !== undefined && world.has(record, world.ordinalOf(descriptor));
+    };
+    /** The first requirement `components` break, as `[requirer, missing]`. */
+    const missingIn = (components, alsoHeld) => {
+        for (const [descriptor] of components) {
+            for (const required of requirements.requires.get(descriptor.name) ?? []) {
+                if (!alsoHeld(required) && !components.some(([staged]) => staged.name === required.name)) {
+                    return [descriptor.name, required.name];
+                }
+            }
+        }
+        return undefined;
+    };
     /**
      * World adapter used by deferred commands.
      */
     const commandWorld = {
         spawnEntity(id, components) {
+            if (!requirements.empty) {
+                const missing = missingIn(components, () => false);
+                if (missing !== undefined) {
+                    violateRequirement("spawn", id, missing);
+                    return false;
+                }
+            }
             if (debugEnabled)
                 for (const [descriptor] of components)
                     noteCommand("spawns", descriptor.name);
             world.spawnEntity(id, components);
+            return true;
         },
         destroyEntity(id) {
             if (debugEnabled) {
@@ -311,15 +399,37 @@ const makeValidatedRuntime = (options) => {
                 noteCommand("despawnsScope", scope.name);
             world.destroyEntityScope(scope.key);
         },
-        removeComponent(id, descriptor) {
-            if (debugEnabled)
-                noteCommand("removes", descriptor.name);
-            world.removeComponent(id, descriptor);
+        removeComponents(id, descriptors) {
+            if (!requirements.empty && world.records.has(id)) {
+                const held = holds(id);
+                for (const descriptor of descriptors) {
+                    for (const requirer of requirements.requiredBy.get(descriptor.name) ?? []) {
+                        if (held(requirer) && !descriptors.some((removed) => removed.name === requirer.name)) {
+                            violateRequirement("remove", id, [requirer.name, descriptor.name]);
+                            return;
+                        }
+                    }
+                }
+            }
+            for (const descriptor of descriptors) {
+                if (debugEnabled)
+                    noteCommand("removes", descriptor.name);
+                world.removeComponent(id, descriptor);
+            }
         },
-        writeComponent(id, descriptor, value) {
-            if (debugEnabled)
-                noteCommand("inserts", descriptor.name);
-            world.writeComponent(id, descriptor, value);
+        insertComponents(id, entries) {
+            if (!requirements.empty && world.records.has(id)) {
+                const missing = missingIn(entries, holds(id));
+                if (missing !== undefined) {
+                    violateRequirement("insert", id, missing);
+                    return;
+                }
+            }
+            for (const [descriptor, value] of entries) {
+                if (debugEnabled)
+                    noteCommand("inserts", descriptor.name);
+                world.writeComponent(id, descriptor, value);
+            }
         },
         tryRelate(id, relation, target) {
             if (debugEnabled) {
@@ -494,6 +604,14 @@ const makeValidatedRuntime = (options) => {
         store.set(key, value);
     };
     const writeResource = journalStoreWrite(resources, resourceOriginals);
+    /**
+     * Resource change ticks for `changedResource` readers. Only resources some
+     * system reads with `changedResource` are compared at commit; a reader's
+     * first run reports a change anyway, so writes before it registers are not
+     * needed.
+     */
+    const watchedResources = new Set();
+    const resourceChangedAt = new Map();
     const journalMachine = (key) => {
         if (!machineOriginals.has(key)) {
             machineOriginals.set(key, pendingMachines.get(key) ?? absentValue);
@@ -504,6 +622,15 @@ const makeValidatedRuntime = (options) => {
     };
     const commitSystemTransaction = () => {
         world.commitTransaction();
+        if (watchedResources.size > 0) {
+            for (const [key, before] of resourceOriginals) {
+                if (!watchedResources.has(key))
+                    continue;
+                if (before === absentValue || !sameValue(before, resources.get(key))) {
+                    resourceChangedAt.set(key, world.currentTick());
+                }
+            }
+        }
         if (emittedEvents.size > 0) {
             const published = world.advanceTick();
             for (const [key, values] of emittedEvents) {
@@ -540,6 +667,16 @@ const makeValidatedRuntime = (options) => {
         emittedEvents.clear();
     };
     const makeResourceWriteView = (descriptor, store, write) => Cells.storeWrite(store, descriptor.key, write, DescriptorModule.constructorOf(descriptor));
+    const makeResourceChangedView = (descriptor, reader) => {
+        const key = descriptor.key;
+        watchedResources.add(key);
+        const read = Cells.storeRead(resources, key);
+        return {
+            get: () => read.get(),
+            // `since` is the previous completed run; 0 before the first one.
+            changed: () => reader.since === 0 || (resourceChangedAt.get(key) ?? 0) > reader.since
+        };
+    };
     const makeEventReadView = (descriptorKey, reader) => ({
         all() {
             return events.since(descriptorKey, reader.streamSince);
@@ -598,15 +735,28 @@ const makeValidatedRuntime = (options) => {
         get: () => currentMachines.get(stateMachine.key),
         is: (value) => currentMachines.get(stateMachine.key) === value
     });
+    /** Queues a next value; a sub-state whose parent is in another state queues nothing and fails. */
+    const queueMachine = (stateMachine, value, skipIfSame) => {
+        const within = stateMachine.within;
+        if (within !== undefined && !currentMachines.has(stateMachine.key)) {
+            return Result.failure({
+                _tag: "SubStateInactive",
+                machine: stateMachine.name,
+                parent: within.machine.name,
+                requires: within.state
+            });
+        }
+        journalMachine(stateMachine.key);
+        pendingMachines.set(stateMachine.key, { value, skipIfSame });
+        return (within === undefined ? undefined : succeeded);
+    };
     const makeNextMachineWriteView = (stateMachine) => ({
         getPending: () => pendingMachines.get(stateMachine.key)?.value,
         set(value) {
-            journalMachine(stateMachine.key);
-            pendingMachines.set(stateMachine.key, { value, skipIfSame: false });
+            return queueMachine(stateMachine, value, false);
         },
         setIfChanged(value) {
-            journalMachine(stateMachine.key);
-            pendingMachines.set(stateMachine.key, { value, skipIfSame: true });
+            return queueMachine(stateMachine, value, true);
         },
         reset() {
             journalMachine(stateMachine.key);
@@ -660,7 +810,9 @@ const makeValidatedRuntime = (options) => {
             lookup,
             resources: mapRecord(spec.resources, (access) => access.mode === "read"
                 ? Cells.storeRead(resources, access.descriptor.key)
-                : makeResourceWriteView(access.descriptor, resources, writeResource)),
+                : access.mode === "changed"
+                    ? makeResourceChangedView(access.descriptor, reader)
+                    : makeResourceWriteView(access.descriptor, resources, writeResource)),
             events: mapRecord(spec.events, (access) => access.mode === "read"
                 ? makeEventReadView(access.descriptor.key, reader)
                 : makeEventWriteView(access.descriptor.key)),
@@ -971,6 +1123,39 @@ const makeValidatedRuntime = (options) => {
             activeTransitions.delete(schedule.transition.machine.key);
         }
     };
+    /**
+     * Despawns the scopes whose trigger matches a committed transition: leaving
+     * `snapshot.from` or entering `snapshot.to`. It runs right after the
+     * commit, so `onExit` systems still saw the members and entities spawned by
+     * `onEnter` survive. Members are the entities in the scope at that moment:
+     * commands queued by `onExit` systems and not yet applied are not.
+     */
+    const despawnTriggeredScopes = (machineKey, snapshot) => {
+        const triggers = scopeTriggers.get(machineKey);
+        if (triggers === undefined)
+            return;
+        const applied = [];
+        for (const { trigger, scope } of triggers) {
+            const matches = trigger.phase === "exit" ? trigger.state === snapshot.from : trigger.state === snapshot.to;
+            if (!matches)
+                continue;
+            const origin = `${trigger.phase === "exit" ? "onExit" : "onEnter"}(${trigger.machine.name}=${String(trigger.state)})`;
+            const effects = [];
+            commandEffects = tracing ? effects : undefined;
+            commandOrigin = origin;
+            try {
+                commandWorld.destroyEntityScope(scope);
+            }
+            finally {
+                commandEffects = undefined;
+            }
+            if (tracing)
+                applied.push({ tag: `despawnScope ${scope.name}`, system: origin, effects });
+        }
+        if (applied.length > 0) {
+            emit({ type: "deferred", frame: frameCount, tick: world.currentTick(), schedule: currentSchedule(), marker: "applyStateTransitions", commands: applied });
+        }
+    };
     /**
      * Applies queued commands, then queued machine transitions, running the
      * matching exit, transition, and enter schedules from the bundle.
@@ -983,6 +1168,10 @@ const makeValidatedRuntime = (options) => {
             - (machineDefinitionOrder.get(rightKey) ?? Number.MAX_SAFE_INTEGER));
         const schedules = bundle?.entries ?? [];
         for (const [machineKey, pending] of scheduledTransitions) {
+            if (pendingMachines.get(machineKey) !== pending) {
+                // Discarded earlier in this marker: its parent left the state it exists in.
+                continue;
+            }
             pendingMachines.delete(machineKey);
             const current = currentMachines.get(machineKey);
             if (current === undefined) {
@@ -993,11 +1182,24 @@ const makeValidatedRuntime = (options) => {
                     traceTransition(machineKey, { from: current, to: current }, "unchanged");
                 continue;
             }
-            previousMachines.set(machineKey, current);
             const snapshot = {
                 from: current,
                 to: pending.value
             };
+            // Sub-states that exist in the state being left exit first, deepest
+            // first: their exit schedules run before the parent's, while they
+            // still have their values, and they lose them at the parent's commit.
+            const leaving = activeSubStatesIn(machineKey, snapshot.from);
+            for (const sub of leaving) {
+                const value = currentMachines.get(sub.key);
+                const result = runPhase(sub.key, "exit", value, { from: value, to: undefined }, schedules);
+                if (!result.ok) {
+                    pendingMachines.set(machineKey, pending);
+                    if (tracing)
+                        traceTransition(machineKey, snapshot, "failed");
+                    return result;
+                }
+            }
             for (const schedule of schedules) {
                 const transition = schedule.transition;
                 if (transition.phase === "exit" && transition.machine.key === machineKey && transition.state === snapshot.from) {
@@ -1026,11 +1228,9 @@ const makeValidatedRuntime = (options) => {
                     }
                 }
             }
-            currentMachines.set(machineKey, pending.value);
-            changedMachines.add(machineKey);
-            transitionEvents.append(machineKey, world.advanceTick(), [snapshot]);
-            if (tracing)
-                traceTransition(machineKey, snapshot, "applied");
+            for (const sub of leaving)
+                commitMachine(sub.key, currentMachines.get(sub.key), undefined);
+            commitMachine(machineKey, current, pending.value);
             for (const schedule of schedules) {
                 const transition = schedule.transition;
                 if (transition.phase === "enter" && transition.machine.key === machineKey && transition.state === snapshot.to) {
@@ -1042,6 +1242,79 @@ const makeValidatedRuntime = (options) => {
                     }
                 }
             }
+            // Sub-states that exist in the entered state enter their value, parents first.
+            const entered = enterSubStates(machineKey, snapshot.to, schedules);
+            if (!entered.ok)
+                return entered;
+        }
+        return succeeded;
+    };
+    /**
+     * Commits one machine's value (`undefined` for a sub-state that stops
+     * existing): records the change and its transition event, traces it, and
+     * despawns the scopes it triggers.
+     */
+    const commitMachine = (machineKey, from, to) => {
+        const snapshot = { from, to };
+        if (from !== undefined)
+            previousMachines.set(machineKey, from);
+        if (to === undefined) {
+            currentMachines.delete(machineKey);
+            pendingMachines.delete(machineKey);
+        }
+        else {
+            currentMachines.set(machineKey, to);
+        }
+        changedMachines.add(machineKey);
+        transitionEvents.append(machineKey, world.advanceTick(), [snapshot]);
+        if (tracing)
+            traceTransition(machineKey, snapshot, "applied");
+        despawnTriggeredScopes(machineKey, snapshot);
+    };
+    /** Runs every schedule of `phase` for `machineKey` in `state`, in bundle order. */
+    const runPhase = (machineKey, phase, state, snapshot, schedules) => {
+        for (const schedule of schedules) {
+            const transition = schedule.transition;
+            if (transition.phase === phase && transition.machine.key === machineKey && transition.state === state) {
+                const result = runTransitionSchedule(schedule, snapshot);
+                if (!result.ok)
+                    return result;
+            }
+        }
+        return succeeded;
+    };
+    /** The sub-states with a value that exist in `state` of `parentKey`, and theirs, deepest first. */
+    const activeSubStatesIn = (parentKey, state) => {
+        const result = [];
+        for (const sub of subStates.get(parentKey) ?? []) {
+            const value = currentMachines.get(sub.key);
+            if (sub.within.state !== state || value === undefined)
+                continue;
+            result.push(...activeSubStatesIn(sub.key, value), sub);
+        }
+        return result;
+    };
+    /**
+     * Gives the sub-states of `parentKey` that exist in `state` their entry
+     * value, then runs their `onEnter` schedules and enters their own
+     * sub-states.
+     */
+    const enterSubStates = (parentKey, state, schedules) => {
+        for (const sub of subStates.get(parentKey) ?? []) {
+            if (sub.within.state !== state || currentMachines.has(sub.key) || !subStateEntry.has(sub.key))
+                continue;
+            const value = subStateEntry.get(sub.key);
+            commitMachine(sub.key, undefined, value);
+            const snapshot = { from: undefined, to: value };
+            const result = runPhase(sub.key, "enter", value, snapshot, schedules);
+            if (!result.ok) {
+                if (tracing)
+                    traceTransition(sub.key, snapshot, "enterFailed");
+                return result;
+            }
+            const nested = enterSubStates(sub.key, value, schedules);
+            if (!nested.ok)
+                return nested;
         }
         return succeeded;
     };
@@ -1213,7 +1486,8 @@ const makeValidatedRuntime = (options) => {
             case "resource":
                 return resources.has(requirement.key);
             case "stateMachine":
-                return currentMachines.has(requirement.key);
+                // An inactive sub-state has no value but is provided.
+                return providedMachineKeys.has(requirement.key) || currentMachines.has(requirement.key);
         }
     };
     const tryRunSchedule = (schedule) => {
@@ -1317,6 +1591,11 @@ const makeValidatedRuntime = (options) => {
                     return Result.failure({ _tag: "InvalidComponent", entityId: entity.id, name, error: value.error });
                 components.push([descriptor, value.value]);
             }
+            // Transient components are never saved, so a requirement on one is not checked here.
+            const missing = missingIn(components, DescriptorModule.isTransient);
+            if (missing !== undefined) {
+                return Result.failure({ _tag: "MissingRequiredComponent", entityId: entity.id, name: missing[1], requiredBy: missing[0] });
+            }
             entities.push({ id: entity.id, components });
         }
         const validatedResources = [];
@@ -1358,14 +1637,34 @@ const makeValidatedRuntime = (options) => {
                 }
             }
         }
-        const machineValues = [];
+        const restoredMachines = new Map(currentMachines);
         for (const [name, value] of Object.entries(saved.machines)) {
             const machine = machinesByName.get(name);
             if (!machine)
                 return Result.failure({ _tag: "UnknownMachine", name });
             if (!machine.values.includes(value))
                 return Result.failure({ _tag: "InvalidMachineState", name, value });
-            machineValues.push([machine.key, value]);
+            restoredMachines.set(machine.key, value);
+        }
+        // A save has no value for a sub-state whose parent is elsewhere; one that
+        // has a value must have its parent in the state it exists in. A sub-state
+        // missing while its parent is there enters its entry value.
+        for (const machine of options.machineDefinitions) {
+            const within = machine.within;
+            if (within === undefined)
+                continue;
+            const active = restoredMachines.get(within.machine.key) === within.state;
+            if (Object.hasOwn(saved.machines, machine.name)) {
+                if (!active) {
+                    return Result.failure({ _tag: "InactiveSubState", name: machine.name, parent: within.machine.name, requires: within.state });
+                }
+            }
+            else if (active && subStateEntry.has(machine.key)) {
+                restoredMachines.set(machine.key, subStateEntry.get(machine.key));
+            }
+            else {
+                restoredMachines.delete(machine.key);
+            }
         }
         const scoped = new Set();
         const memberships = [];
@@ -1397,9 +1696,12 @@ const makeValidatedRuntime = (options) => {
         }
         for (const [id, key] of memberships)
             world.assignEntityScope(id, key);
-        for (const [key, value] of validatedResources)
+        for (const [key, value] of validatedResources) {
             resources.set(key, value);
-        for (const [key, value] of machineValues)
+            resourceChangedAt.set(key, world.currentTick());
+        }
+        currentMachines.clear();
+        for (const [key, value] of restoredMachines)
             currentMachines.set(key, value);
         // Locals are not saved: each system starts over from its factory.
         localSlots.forEach(({ slot }, index) => { slot.context.local = rebuiltLocals[index]; });
@@ -1546,11 +1848,14 @@ const makeValidatedRuntime = (options) => {
             schema: options.schema,
             machines: [...new Set(machinesByName.values())],
             currentMachine: (machine) => currentMachines.get(machine.key),
+            providesMachine: (machine) => providedMachineKeys.has(machine.key),
+            scopes: options.scopeDefinitions,
             providedServices: Object.keys(providedServices),
             externallyWrittenEvents: new Set([...externallyWrittenEvents, ...hostEvents]),
             relationMutations,
             commandUses,
             ranSystems,
+            requirementViolations: [...requirementViolations.values()],
             hasResource: (descriptor) => resources.has(descriptor.key),
             schedules: [...scheduleNames].map(([schedule, name]) => [name, schedule])
         }),
@@ -1621,6 +1926,7 @@ export const make = (options) => {
         resources: validated.value,
         machines: options.machines,
         machineDefinitions: options.machineDefinitions ?? [],
+        scopeDefinitions: options.scopeDefinitions ?? [],
         debug: options.debug
     });
     return (fallible ? Result.success(runtime) : runtime);