@typeonce/ritmo 0.7.0 → 0.9.0

package/src/internal/debug.ts

@@ -6,6 +6,7 @@
 import type * as Debug from "../Debug.ts"
 import * as DescriptorModule from "../Descriptor.ts"
 import type { Descriptor } from "../Descriptor.ts"
+import type * as EntityScope from "../EntityScope.ts"
 import type * as Inspector from "../Inspector.ts"
 import type * as Machine from "../Machine.ts"
 import type * as Query from "../Query.ts"
@@ -72,6 +73,9 @@ export const transitionScheduleName = (schedule: TransitionSchedule): string =>
 const names = <A>(record: Record<string, A>, name: (value: A) => string): Array<string> =>
   Object.values(record).map(name)
 
+const lifecycleNames = (filters: ReadonlyArray<Query.Filter<any>>, kind: "added" | "changed"): Array<string> =>
+  filters.flatMap((filter) => filter.kind === kind ? [filter.descriptor.name] : [])
+
 const describeQuery = (slot: string, query: Query.Query.Any<any>): Debug.QueryDescription => {
   const reads: Array<string> = []
   const writes: Array<string> = []
@@ -102,8 +106,11 @@ const describeQuery = (slot: string, query: Query.Query.Any<any>): Debug.QueryDe
     optional,
     with: query.with.map((descriptor) => descriptor.name),
     without: query.without.map((descriptor) => descriptor.name),
-    added: query.filters.filter((filter) => filter.kind === "added").map((filter) => filter.descriptor.name),
-    changed: query.filters.filter((filter) => filter.kind === "changed").map((filter) => filter.descriptor.name),
+    added: lifecycleNames(query.filters, "added"),
+    changed: lifecycleNames(query.filters, "changed"),
+    anyOf: query.filters.flatMap((filter) => filter.kind === "anyOf"
+      ? [{ added: lifecycleNames(filter.filters, "added"), changed: lifecycleNames(filter.filters, "changed") }]
+      : []),
     relations: [
       ...relations,
       ...relationNames(query.withRelations, "with"),
@@ -114,7 +121,7 @@ const describeQuery = (slot: string, query: Query.Query.Any<any>): Debug.QueryDe
   }
 }
 
-type Mode = { readonly mode: "read" | "write"; readonly descriptor: Descriptor.Any }
+type Mode = { readonly mode: "read" | "changed" | "write"; readonly descriptor: Descriptor.Any }
 type CommandAccess = { readonly permissions: ReadonlyArray<{ readonly permission: keyof Debug.CommandPermissions; readonly values: ReadonlyArray<{ readonly name: string }> }> }
 
 const permissionsOf = (access: CommandAccess | undefined): Debug.CommandPermissions => {
@@ -142,7 +149,7 @@ type ThisTickAccess = Mode & { readonly thisTick?: true }
 
 export const describeSystem = (system: AnySystem, placements: ReadonlyArray<string>): Debug.SystemDescription => {
   const spec = system.spec
-  const byMode = (record: Record<string, Mode>, mode: "read" | "write") =>
+  const byMode = (record: Record<string, Mode>, mode: Mode["mode"]) =>
     Object.values(record).filter((access) => access.mode === mode).map((access) => access.descriptor.name)
   const machineName = (access: { readonly machine: Machine.StateMachine.Any }) => access.machine.name
   // A system also reads whatever its `check` conditions read.
@@ -160,7 +167,8 @@ export const describeSystem = (system: AnySystem, placements: ReadonlyArray<stri
         Object.entries(check.spec.queries as Record<string, Query.Query.Any<any>>).map(([slot, query]) => describeQuery(`check(${check.name}).${slot}`, query)))
     ],
     resources: {
-      reads: unique([...byMode(spec.resources, "read"), ...checks.flatMap((check) => byMode(check.spec.resources, "read"))]),
+      reads: unique([...byMode(spec.resources, "read"), ...byMode(spec.resources, "changed"), ...checks.flatMap((check) => byMode(check.spec.resources, "read"))]),
+      changed: byMode(spec.resources, "changed"),
       writes: byMode(spec.resources, "write")
     },
     events: { reads: byMode(spec.events, "read"), writes: byMode(spec.events, "write") },
@@ -260,6 +268,10 @@ export interface DescribeInput {
   readonly schema: Schema.Any
   readonly machines: ReadonlyArray<Machine.StateMachine.Any>
   readonly currentMachine: (machine: Machine.StateMachine.Any) => Machine.StateValue | undefined
+  /** Whether the runtime was given an initial value for the machine. */
+  readonly providesMachine: (machine: Machine.StateMachine.Any) => boolean
+  /** Every scope defined through the game, with its despawn triggers. */
+  readonly scopes: ReadonlyArray<EntityScope.EntityScope.Any>
   readonly providedServices: ReadonlyArray<string>
   readonly externallyWrittenEvents: ReadonlySet<string>
   /** Relations commands have tried to relate or reorder, by the queuing systems. */
@@ -268,6 +280,11 @@ export interface DescribeInput {
   readonly commandUses: ReadonlyMap<string, ReadonlySet<string>>
   /** Systems that ran in this session. */
   readonly ranSystems: ReadonlySet<string>
+  /** Commands skipped because they would have broken a `Schema.requires` requirement. */
+  readonly requirementViolations: ReadonlyArray<Debug.RequirementViolation>
+  readonly nextStateReplacements: ReadonlyArray<Debug.NextStateReplacement>
+  readonly staleTargets: ReadonlyArray<Debug.StaleTarget>
+  readonly streamLosses: ReadonlyArray<Debug.StreamLoss>
   readonly hasResource: (descriptor: Descriptor.Any) => boolean
   readonly schedules: ReadonlyArray<readonly [string, AnySchedule]>
 }
@@ -279,19 +296,38 @@ export const describe = (input: DescribeInput): Debug.Description => {
   const relations = Object.values(input.schema.relations) as ReadonlyArray<Relation.Relation.Any>
 
   const schedules = collectSchedules(input.schedules)
+  // A system gated by Schedule.when / pauseWhen is a copy pointing at its
+  // base: both are one system, described once with every placement.
+  const baseOf = (system: AnySystem): AnySystem => (system as { readonly base?: AnySystem }).base ?? system
   const placements = new Map<AnySystem, Array<string>>()
+  const steps = new Set<AnySystem>()
   for (const [name, schedule] of schedules) {
     schedule.steps.forEach((step, index) => {
       if (!Schedule.isSystemStep(step)) return
-      const system = step as AnySystem
+      const system = baseOf(step as AnySystem)
+      steps.add(step as AnySystem)
       const list = placements.get(system)
       const placement = `${name}#${index}`
       if (list) list.push(placement)
       else placements.set(system, [placement])
     })
   }
-  const described = new Map([...placements].map(([system, where]) => [system, describeSystem(system, where)] as const))
-  const systems = [...described.values()]
+  // Gates differ per placement: the description lists the conditions of all of them.
+  const gatesOf = new Map<AnySystem, { when: Set<unknown>; pauseWhen: Set<unknown> }>()
+  for (const step of steps) {
+    const base = baseOf(step)
+    const gates = gatesOf.get(base) ?? { when: new Set(), pauseWhen: new Set() }
+    for (const condition of step.spec.when as ReadonlyArray<unknown>) gates.when.add(condition)
+    for (const condition of step.spec.pauseWhen as ReadonlyArray<unknown>) gates.pauseWhen.add(condition)
+    gatesOf.set(base, gates)
+  }
+  const byBase = new Map([...placements].map(([system, where]) => {
+    const gates = gatesOf.get(system)!
+    const merged = { ...system, spec: { ...system.spec, when: [...gates.when], pauseWhen: [...gates.pauseWhen] } } as AnySystem
+    return [system, describeSystem(merged, where)] as const
+  }))
+  const described = new Map<AnySystem, Debug.SystemDescription>([...steps].map((step) => [step, byBase.get(baseOf(step))!] as const))
+  const systems = [...byBase.values()]
 
   const components = new Index(componentDescriptors.map((descriptor) => descriptor.name))
   const resources = new Index(resourceDescriptors.map((descriptor) => descriptor.name))
@@ -300,7 +336,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
   for (const name of input.externallyWrittenEvents) events.write(name, "runtime.send")
   for (const system of systems) {
     for (const query of system.queries) {
-      for (const name of [...query.reads, ...query.optional, ...query.with, ...query.added, ...query.changed]) {
+      for (const name of [...query.reads, ...query.optional, ...query.with, ...query.added, ...query.changed, ...anyOfNames(query)]) {
         components.read(name, system.name)
       }
       for (const name of query.writes) {
@@ -325,6 +361,20 @@ export const describe = (input: DescribeInput): Debug.Description => {
     schedule.steps.some((step) => !Schedule.isSystemStep(step) && step.kind === "applyStateTransitions"))
 
   const lints: Array<Omit<Debug.Lint, "fix">> = []
+  const triggerName = (trigger: EntityScope.Trigger) =>
+    `${trigger.phase === "exit" ? "onExit" : "onEnter"}(${trigger.machine.name}=${String(trigger.state)})`
+  for (const scope of input.scopes) {
+    for (const trigger of scope.despawnOn) {
+      const machine = input.machines.find((candidate) => candidate.key === trigger.machine.key)
+      if (machine !== undefined && input.providesMachine(machine)) continue
+      lints.push({
+        severity: "warning",
+        code: "scope-trigger-never-applied",
+        subject: scope.name,
+        message: `${scope.name} is despawned on ${triggerName(trigger)}, but the runtime does not provide ${trigger.machine.name}, so its state never changes and the scope is never despawned`
+      })
+    }
+  }
   if (schedules.length > 0) {
     for (const entry of events.list()) {
       if (entry.writers.length > 0 && entry.readers.length === 0) {
@@ -354,8 +404,26 @@ export const describe = (input: DescribeInput): Debug.Description => {
         })
       }
     }
+    for (const scope of input.scopes) {
+      for (const trigger of scope.despawnOn) {
+        const machine = input.machines.find((candidate) => candidate.key === trigger.machine.key)
+        if (machine === undefined || !input.providesMachine(machine)) continue
+        const reason = !appliesTransitions
+          ? "no described schedule has an applyStateTransitions() marker"
+          : !queuedWithParents(machine, nextStates)
+            ? `no described system queues a next state of ${machine.name}`
+            : undefined
+        if (reason === undefined) continue
+        lints.push({
+          severity: "warning",
+          code: "scope-trigger-never-applied",
+          subject: scope.name,
+          message: `${scope.name} is despawned on ${triggerName(trigger)}, but ${reason}, so the scope is never despawned`
+        })
+      }
+    }
     const failureReaders = new Set(systems.flatMap((system) => system.relationFailures))
-    // Declared `relates` permissions, and relations that commands were seen to relate (drafts relate without one).
+    // Declared `relates` permissions, and relations that commands were seen to relate (erased types can relate without one).
     const relaters = new Map<string, Set<string>>()
     for (const system of systems) {
       for (const name of system.commands.relates) relaters.set(name, new Set([...(relaters.get(name) ?? []), system.name]))
@@ -370,6 +438,20 @@ export const describe = (input: DescribeInput): Debug.Description => {
         message: `${name} is related by commands from ${[...queuers].sort().join(", ")}, but no described system reads its failures (Game.System.readRelationFailures(${name})), so a failed relate or reorder is dropped silently`
       })
     }
+    const resourceWriters = new Set(systems.flatMap((system) => system.resources.writes))
+    const changedReaders = new Map<string, Array<string>>()
+    for (const system of systems) {
+      for (const name of system.resources.changed) changedReaders.set(name, [...(changedReaders.get(name) ?? []), system.name])
+    }
+    for (const [name, readers] of changedReaders) {
+      if (resourceWriters.has(name)) continue
+      lints.push({
+        severity: "warning",
+        code: "resource-changed-never-written",
+        subject: name,
+        message: `${name} is read with changedResource by ${readers.join(", ")}, but no described system writes it, so changed() is true only on the first run`
+      })
+    }
     lints.push(...readBeforeWriteLints(schedules, described, input.externallyWrittenEvents))
     // Each named schedule is checked as one tick; `tick` checks this at compile time.
     for (const [name, schedule] of input.schedules) {
@@ -403,10 +485,63 @@ export const describe = (input: DescribeInput): Debug.Description => {
       }
     }
   }
+  // Observed with debug, whether or not schedules are named.
+  for (const violation of input.requirementViolations) {
+    const times = violation.count === 1 ? "once" : `${violation.count} times`
+    lints.push({
+      severity: "warning",
+      code: "requirement-violated",
+      subject: violation.system,
+      message: `${violation.system} queued ${violation.command === "insert" ? "an" : "a"} ${violation.command} that would have left ${violation.component} without ${violation.missing} (last on entity ${violation.entity}), so it was skipped ${times}`
+    })
+  }
+  for (const replacement of input.nextStateReplacements) {
+    const times = replacement.count === 1 ? "" : `, ${replacement.count} times`
+    lints.push({
+      severity: "warning",
+      code: "next-state-replaced",
+      subject: replacement.machine,
+      message: `${replacement.by.system} queued ${replacement.machine}=${String(replacement.by.value)}, replacing ${String(replacement.replaced.value)} queued by ${replacement.replaced.system} before the same applyStateTransitions()${times}: the last value wins`
+    })
+  }
+  for (const stale of input.staleTargets) {
+    const times = stale.count === 1 ? "once" : `${stale.count} times`
+    lints.push({
+      severity: "warning",
+      code: "stale-target",
+      subject: stale.system,
+      message: `${stale.system} passed ${stale.command} an id spawned in an earlier run (last entity ${stale.entity}), so it was skipped ${times}`
+    })
+  }
+  for (const loss of input.streamLosses) {
+    if (loss.checksLagged) continue
+    if (loss.lostRuns > 0) {
+      lints.push({
+        severity: "warning",
+        code: "stream-loss-unread",
+        subject: loss.system,
+        message: `${loss.system} read ${loss.stream} after entries were dropped before it read them (${loss.lostRuns === 1 ? "once" : `${loss.lostRuns} runs`}), and never checks lagged()`
+      })
+    } else if (loss.paused) {
+      lints.push({
+        severity: "info",
+        code: "stream-loss-unread",
+        subject: loss.system,
+        message: `${loss.system} reads ${loss.stream} under pauseWhen and never checks lagged(): a long pause drops entries past the stream's capacity`
+      })
+    }
+  }
 
   return {
     version: 1,
-    components: componentDescriptors.map((descriptor) => ({ name: descriptor.name, storage: storageOf(descriptor) })),
+    components: componentDescriptors.map((descriptor) => ({
+      name: descriptor.name,
+      storage: storageOf(descriptor),
+      immutable: DescriptorModule.isImmutable(descriptor),
+      requires: [...new Set(input.schema.requires
+        .filter((requirement) => requirement.component.name === descriptor.name)
+        .flatMap((requirement) => requirement.required.map((required) => required.name)))]
+    })),
     resources: resourceDescriptors.map((descriptor) => ({
       name: descriptor.name,
       storage: storageOf(descriptor),
@@ -423,8 +558,11 @@ export const describe = (input: DescribeInput): Debug.Description => {
     machines: input.machines.map((machine) => ({
       name: machine.name,
       states: machine.values,
-      current: input.currentMachine(machine)
+      current: input.currentMachine(machine),
+      provided: input.providesMachine(machine),
+      within: machine.within === undefined ? undefined : `${machine.within.machine.name}=${String(machine.within.state)}`
     })),
+    scopes: input.scopes.map((scope) => ({ name: scope.name, despawnOn: scope.despawnOn.map(triggerName) })),
     services: describeServices(input.providedServices, systems),
     schedules: schedules.map(([name, schedule]) => ({ name, steps: schedule.steps.map(describeStep) })),
     systems,
@@ -437,6 +575,17 @@ export const describe = (input: DescribeInput): Debug.Description => {
   }
 }
 
+/**
+ * Whether a described system queues a next state of `machine`, or of a
+ * machine it exists within: a parent leaving its state changes a sub-state too.
+ */
+const queuedWithParents = (machine: Machine.StateMachine.Any, nextStates: ReadonlyMap<string, unknown>): boolean => {
+  for (let current: Machine.StateMachine.Any | undefined = machine; current !== undefined; current = current.within?.machine) {
+    if (nextStates.has(current.name)) return true
+  }
+  return false
+}
+
 /** The fix each lint names, by code. */
 const fixFor = (code: Debug.Lint["code"], subject: string): string => {
   switch (code) {
@@ -446,12 +595,24 @@ const fixFor = (code: Debug.Lint["code"], subject: string): string => {
       return `emit ${subject} from a system with Game.System.writeEvent, or stop reading it; if the host sends it with runtime.send, declare it (debug.declareHostEvents, or hostEvents in a Session or lint target)`
     case "next-state-never-applied":
       return `add Game.Schedule.applyStateTransitions(...) to a schedule that runs after the system that queues ${subject}`
+    case "resource-changed-never-written":
+      return `write ${subject} from a system with Game.System.writeResource, or read it with Game.System.readResource; if only a render schedule writes it, pass that schedule as describe-only`
+    case "scope-trigger-never-applied":
+      return `provide the machine of ${subject}'s trigger in Game.Runtime.make({ machines }), queue its next state from a system, and apply it with Game.Schedule.applyStateTransitions(...); or despawn ${subject} with commands.despawnScope(...) instead`
     case "relation-failure-never-read":
       return `read the failures with Game.System.readRelationFailures(${subject}) in a system and handle them`
     case "this-tick-order":
       return "move the writer before the reader in the schedule (the message names both), or read without Game.System.thisTick"
     case "component-never-read":
       return `fine if ${subject} is read outside the described schedules (rendering, inspectors); otherwise stop writing it`
+    case "requirement-violated":
+      return `keep what ${subject} spawns or inserts complete (every component its components require), and remove a required component only together with its requirers; a query proof can go stale when another system's command is applied first in the same applyDeferred()`
+    case "stream-loss-unread":
+      return `check lagged() in ${subject} where a missed entry matters (a node never destroyed, a count off), and rebuild from queries when it is true; fine if a missed entry is harmless`
+    case "stale-target":
+      return `an id spawn returns is valid only in the run that spawned it; in ${subject}, keep the entity id or a handle and resolve it again with a query (queries.x.get(id) / lookup.getHandle(handle, query)) and pass match.entity`
+    case "next-state-replaced":
+      return "decide between the values in one system, or check whether a next state is already queued (nextMachines.x.getPending()) before setting another"
     case "command-permission-unused":
       return `fine if the session did not reach the case where ${subject} uses it; otherwise drop the permission from its Game.System.commands(...)`
     case "read-before-write":
@@ -462,12 +623,16 @@ const fixFor = (code: Debug.Lint["code"], subject: string): string => {
 type Accesses = { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
 
 /** What a system reads and writes, per kind. `with`/`without` filters test presence and are not reads. */
+/** The components named by a query's `anyOf` filters. */
+const anyOfNames = (query: Debug.QueryDescription): ReadonlyArray<string> =>
+  query.anyOf.flatMap((filter) => [...filter.added, ...filter.changed])
+
 const accessesOf = (system: Debug.SystemDescription): Record<"component" | "resource" | "event", Accesses> => ({
   component: {
-    reads: system.queries.flatMap((query) => [...query.reads, ...query.optional, ...query.added, ...query.changed]),
+    reads: system.queries.flatMap((query) => [...query.reads, ...query.optional, ...query.added, ...query.changed, ...anyOfNames(query)]),
     writes: system.queries.flatMap((query) => query.writes)
   },
-  resource: system.resources,
+  resource: { reads: system.resources.reads, writes: system.resources.writes },
   event: system.events
 })
 

package/src/internal/equal.ts

@@ -0,0 +1,31 @@
+/**
+ * Structural equality for plain data: primitives by `Object.is`, arrays and
+ * plain objects by their entries. Other objects (class instances, maps,
+ * sets) compare by reference. Used to decide whether a resource write
+ * changed the value (`Game.System.changedResource`).
+ */
+export const sameValue = (left: unknown, right: unknown): boolean => {
+  if (Object.is(left, right)) return true
+  if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) return false
+  if (Array.isArray(left)) {
+    if (!Array.isArray(right) || left.length !== right.length) return false
+    for (let index = 0; index < left.length; index++) {
+      if (!sameValue(left[index], right[index])) return false
+    }
+    return true
+  }
+  if (Array.isArray(right) || !isPlain(left) || !isPlain(right)) return false
+  const leftKeys = Object.keys(left)
+  if (leftKeys.length !== Object.keys(right).length) return false
+  const leftRecord = left as Record<string, unknown>
+  const rightRecord = right as Record<string, unknown>
+  for (const key of leftKeys) {
+    if (!(key in rightRecord) || !sameValue(leftRecord[key], rightRecord[key])) return false
+  }
+  return true
+}
+
+const isPlain = (value: object): boolean => {
+  const prototype = Object.getPrototypeOf(value) as object | null
+  return prototype === null || prototype === Object.prototype
+}

package/src/internal/fragments.ts

@@ -4,9 +4,14 @@
  * The compile-time counterpart is `ValidateFragments` in `Schema.ts`; these
  * guards cover schemas assembled from erased types.
  */
+import { isTransient } from "../Descriptor.ts"
 import type { Schema, SchemaDefinition } from "../Schema.ts"
 
-type NamedRegistry = Record<string, { readonly name: string }>
+type NamedRegistry = Record<string, { readonly name: string; readonly kind?: string }>
+
+/** The descriptor kind each registry holds (relations carry their own shape). */
+const expectedKind: Partial<Record<(typeof kinds)[number], string>> = { components: "component", resources: "resource", events: "event" }
+const article = (kind: string) => kind === "event" ? "an" : "a"
 
 const kinds = ["components", "resources", "events", "relations"] as const
 
@@ -14,15 +19,22 @@ export const emptySchema = (): SchemaDefinition => ({
   components: {},
   resources: {},
   events: {},
-  relations: {}
+  relations: {},
+  requires: []
 })
 
 /**
  * Merges two registries after checking for duplicate keys and descriptor names.
  */
-const mergeRegistry = (left: NamedRegistry, right: NamedRegistry): NamedRegistry => {
+const mergeRegistry = (left: NamedRegistry, right: NamedRegistry, expected: string | undefined): NamedRegistry => {
   const names = new Set(Object.values(left).map((entry) => entry.name))
   for (const [key, entry] of Object.entries(right)) {
+    if (expected !== undefined && entry.kind !== expected) {
+      const actual = String(entry.kind)
+      throw new Error(actual === "service"
+        ? `${key} is a service, not ${article(expected)} ${expected}: provide services to Game.Runtime.make({ services }) instead of registering them`
+        : `${key} is ${article(actual)} ${actual}, not ${article(expected)} ${expected}: move it to ${actual}s: { ... }`)
+    }
     if (key in left) {
       throw new Error(`Duplicate schema key: ${key}`)
     }
@@ -35,10 +47,11 @@ const mergeRegistry = (left: NamedRegistry, right: NamedRegistry): NamedRegistry
 }
 
 export const mergeSchemas = (left: Schema.Any, right: Schema.Any): Schema.Any => {
-  const merged: Record<string, NamedRegistry> = {}
+  const merged: Record<string, unknown> = {}
   for (const kind of kinds) {
-    merged[kind] = mergeRegistry(left[kind], right[kind])
+    merged[kind] = mergeRegistry(left[kind], right[kind], expectedKind[kind])
   }
+  merged["requires"] = [...left.requires, ...right.requires]
   return merged as unknown as Schema.Any
 }
 
@@ -47,5 +60,22 @@ export const buildSchema = (fragments: ReadonlyArray<Schema.Any>): Schema.Any =>
   for (const fragment of fragments) {
     current = mergeSchemas(current, fragment)
   }
+  const registered = new Set(Object.values(current.components).map((descriptor) => descriptor.name))
+  for (const requirement of current.requires) {
+    for (const descriptor of [requirement.component, ...requirement.required]) {
+      if (!registered.has(descriptor.name)) {
+        throw new Error(`${descriptor.name} is named in Schema.requires(...) but no fragment registers it: add it to a fragment's components`)
+      }
+    }
+    for (const required of requirement.required) {
+      if (isTransient(required) && !isTransient(requirement.component)) {
+        throw new Error(transientRequirementMessage(requirement.component.name, required.name))
+      }
+    }
+  }
   return current
 }
+
+/** Why a saved component cannot require a transient one: a restore would bring it back without it. */
+export const transientRequirementMessage = (requirer: string, required: string): string =>
+  `${requirer} requires ${required}, which is transient and not saved: make ${requirer} transient too, or give ${required} a constructor`

package/src/internal/game.ts

@@ -6,6 +6,8 @@
  */
 import * as Command from "../Command.ts"
 import type * as Debug from "../Debug.ts"
+import type * as Snapshot from "../Snapshot.ts"
+import type { Descriptor } from "../Descriptor.ts"
 import * as Condition from "../Condition.ts"
 import * as Entity from "../Entity.ts"
 import * as EntityScope from "../EntityScope.ts"
@@ -14,36 +16,90 @@ import * as Machine from "../Machine.ts"
 import * as QueryModule from "../Query.ts"
 import * as Relation from "../Relation.ts"
 import * as Runtime from "../Runtime.ts"
+import * as Requirement from "../Requirement.ts"
 import * as Schedule from "../Schedule.ts"
 import type { Schema } from "../Schema.ts"
 import * as System from "../System.ts"
+import { requirementIndex, withRequired } from "./requirements.ts"
+
+/** Why an exit phase (`onExit`, `onTransition`) cannot contain `applyDeferred()`. */
+export const exitApplyDeferredMessage =
+  "onExit and onTransition schedules cannot contain applyDeferred(): the exit phase rolls back as one when a system in it fails, so its commands are applied at the next applyDeferred() after the marker" as const
 
 export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Schema.Game<S, Root> => {
+  const requirements = requirementIndex(schema)
   const definedMachines: Array<Machine.StateMachine.Any> = []
   const definedMachineNames = new Set<string>()
 
-  const defineMachine = (name: string, values: readonly [Machine.StateValue, ...Machine.StateValue[]]) => {
+  const defineMachine = (
+    name: string,
+    values: readonly [Machine.StateValue, ...Machine.StateValue[]],
+    options?: { readonly within: readonly [Machine.StateMachine.Any, Machine.StateValue] }
+  ) => {
     if (definedMachineNames.has(name)) {
       throw new Error(`Duplicate state machine name: ${name}`)
     }
-    const machine = Machine.StateMachine(name, values)
+    const machine = Machine.StateMachine(
+      name,
+      values,
+      options === undefined ? undefined : { machine: options.within[0], state: options.within[1] }
+    )
     definedMachines.push(machine)
     definedMachineNames.add(name)
     return machine
   }
 
+  /**
+   * Every scope defined through this game, in definition order. The runtime
+   * reads their triggers at `Runtime.make`, so a scope only ever used with
+   * `spawnIn` is still despawned by its state change.
+   */
+  const definedScopes: Array<EntityScope.EntityScope.Any> = []
+  const definedScopeNames = new Set<string>()
+
+  const defineScope = (
+    name: string,
+    options?: {
+      readonly despawnOnEnter?: readonly [Machine.StateMachine.Any, Machine.StateValue]
+      readonly despawnOnExit?: readonly [Machine.StateMachine.Any, Machine.StateValue]
+    }
+  ) => {
+    if (definedScopeNames.has(name)) {
+      throw new Error(`Duplicate entity scope name: ${name}`)
+    }
+    const triggers: Array<EntityScope.Trigger> = []
+    if (options?.despawnOnExit !== undefined) {
+      triggers.push({ phase: "exit", machine: options.despawnOnExit[0], state: options.despawnOnExit[1] })
+    }
+    if (options?.despawnOnEnter !== undefined) {
+      triggers.push({ phase: "enter", machine: options.despawnOnEnter[0], state: options.despawnOnEnter[1] })
+    }
+    const scope = EntityScope.make(name, triggers)
+    definedScopes.push(scope)
+    definedScopeNames.add(name)
+    return scope
+  }
+
   const transitionSchedule = (
     transition: Machine.TransitionScheduleDefinition["transition"],
     plan: ReadonlyArray<Schedule.ScheduleEntry>
-  ) => ({ ...Schedule.make(schema, plan), transition })
+  ) => {
+    const schedule = Schedule.make(schema, plan)
+    if (transition.phase !== "enter" && schedule.steps.some((step) => !Schedule.isSystemStep(step) && step.kind === "applyDeferred")) {
+      throw new Error(exitApplyDeferredMessage)
+    }
+    // The machine is a requirement: a runtime without it could never run the schedule.
+    return { ...schedule, requirements: Requirement.collect([...schedule.requirements, transition.machine]), transition }
+  }
 
   const game = {
     schema,
-    EntityScope: (name: string) => EntityScope.make(name),
+    EntityScope: defineScope,
     Inspector: (name: string, spec: object, read: (context: any) => unknown) =>
       Inspector.make(name, { schema, ...spec } as never, read),
     Entity: {
-      handle: Entity.handle
+      handle: Entity.handle,
+      id: (handle: number) => Entity.makeEntityId(handle)
     },
     Query: Object.assign((spec: never) => QueryModule.Query(spec), {
       read: QueryModule.read,
@@ -51,6 +107,7 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
       optional: QueryModule.optional,
       added: QueryModule.added,
       changed: QueryModule.changed,
+      anyOf: QueryModule.anyOf,
       readRelation: Relation.read,
       optionalRelation: Relation.optional,
       readRelated: Relation.readRelated,
@@ -79,11 +136,15 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
       {
         readResource: System.readResource,
         writeResource: System.writeResource,
+        changedResource: System.changedResource,
         readEvent: System.readEvent,
         writeEvent: System.writeEvent,
         thisTick: System.thisTick,
         commands: Command.commands,
-        spawns: Command.spawns,
+        // `spawns(Player)` also allows what `Player` requires (`Schema.requires`), matching its type.
+        spawns: (...components: ReadonlyArray<Descriptor<"component", string, any>>) =>
+          // Internally erased: the bound signature already requires at least one component.
+          Command.spawns(...(withRequired(requirements, components) as unknown as readonly [Descriptor<"component", string, any>])),
         inserts: Command.inserts,
         removes: Command.removes,
         despawns: Command.despawns,
@@ -126,7 +187,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         readonly resources?: object
         readonly machines?: Runtime.RuntimeMachines<any>
         readonly debug?: Debug.Option
-      }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines } as never),
+        readonly saves?: Snapshot.Migrations
+      }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines, scopeDefinitions: definedScopes } as never),
       service: Runtime.service,
       services: Runtime.services,
       machine: Runtime.machine,

package/src/internal/order.ts

@@ -4,19 +4,23 @@
  * `Schedule.ts` (`TickOrderErrors`) and produces the same messages.
  */
 import type { Descriptor } from "../Descriptor.ts"
+import type * as Query from "../Query.ts"
 import * as Schedule from "../Schedule.ts"
 import type { SystemDefinition } from "../System.ts"
 
 type AnySystem = SystemDefinition<any, any, any, any, any>
 type OrderIssue = Schedule.OrderIssue
-type Access = { readonly mode: "read" | "write"; readonly descriptor: Descriptor.Any; readonly thisTick?: true }
+type Access = { readonly mode: "read" | "changed" | "write"; readonly descriptor: Descriptor.Any; readonly thisTick?: true }
 type QueryAccess = {
   readonly thisTick?: true
   readonly selection: Record<string, { readonly mode?: string; readonly descriptor?: Descriptor.Any }>
   readonly with: ReadonlyArray<Descriptor.Any>
   readonly without: ReadonlyArray<Descriptor.Any>
-  readonly filters: ReadonlyArray<{ readonly descriptor?: Descriptor.Any }>
+  readonly filters: ReadonlyArray<Query.Filter<any>>
 }
+/** Every component a filter names: the one of `added` / `changed`, or each member of `anyOf`. */
+const filterNames = (filter: Query.Filter<any>): ReadonlyArray<string> =>
+  filter.kind === "anyOf" ? filter.filters.map((member) => member.descriptor.name) : [filter.descriptor.name]
 type Permission = { readonly permission: string; readonly values: ReadonlyArray<{ readonly name: string }> }
 
 /** One position of a tick: a system, or a point where queued commands are applied. */
@@ -65,7 +69,7 @@ const changesQuery = (system: AnySystem, query: QueryAccess): boolean => {
     ...slots.flatMap((slot) => slot.descriptor ? [slot.descriptor.name] : []),
     ...query.with.map((d) => d.name),
     ...query.without.map((d) => d.name),
-    ...query.filters.flatMap((filter) => filter.descriptor ? [filter.descriptor.name] : [])
+    ...query.filters.flatMap((filter) => filterNames(filter))
   ])
   const changes = [...permissionNames(system, "inserts"), ...permissionNames(system, "removes")]
   if (changes.some((name) => named.has(name))) return true
@@ -95,7 +99,7 @@ const computeIssues = (steps: ReadonlyArray<Schedule.ScheduleStep>): ReadonlyArr
   const systemsAt = items.flatMap((item, at) => item.kind === "system" ? [{ system: item.system, at }] : [])
   for (const { system: reader, at: index } of systemsAt) {
     for (const read of accesses(reader)) {
-      if (read.mode !== "read" || read.thisTick !== true) continue
+      if ((read.mode !== "read" && read.mode !== "changed") || read.thisTick !== true) continue
       const data = read.descriptor.name
       for (const { system, at } of systemsAt) {
         if (at <= index || sameSystem(system, reader)) continue