@typeonce/ritmo 0.7.0 → 0.8.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,8 @@ 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 hasResource: (descriptor: Descriptor.Any) => boolean
   readonly schedules: ReadonlyArray<readonly [string, AnySchedule]>
 }
@@ -325,6 +339,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,6 +382,24 @@ 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).
     const relaters = new Map<string, Set<string>>()
@@ -370,6 +416,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) {
@@ -392,6 +452,15 @@ export const describe = (input: DescribeInput): Debug.Description => {
         })
       }
     }
+    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 entry of components.list()) {
       if (entry.writers.length > 0 && entry.readers.every((reader) => entry.writers.includes(reader))) {
         lints.push({
@@ -406,7 +475,14 @@ export const describe = (input: DescribeInput): Debug.Description => {
 
   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 +499,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 +516,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 +536,18 @@ 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 "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":
@@ -467,7 +563,7 @@ const accessesOf = (system: Debug.SystemDescription): Record<"component" | "reso
     reads: system.queries.flatMap((query) => [...query.reads, ...query.optional, ...query.added, ...query.changed]),
     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

@@ -14,7 +14,8 @@ export const emptySchema = (): SchemaDefinition => ({
   components: {},
   resources: {},
   events: {},
-  relations: {}
+  relations: {},
+  requires: []
 })
 
 /**
@@ -35,10 +36,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["requires"] = [...left.requires, ...right.requires]
   return merged as unknown as Schema.Any
 }
 
@@ -47,5 +49,13 @@ 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`)
+      }
+    }
+  }
   return current
 }

package/src/internal/game.ts

@@ -6,6 +6,7 @@
  */
 import * as Command from "../Command.ts"
 import type * as Debug from "../Debug.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"
@@ -17,21 +18,62 @@ import * as Runtime from "../Runtime.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"
 
 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>
@@ -39,7 +81,7 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
 
   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: {
@@ -51,6 +93,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 +122,14 @@ 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>>) =>
+          Command.spawns(...withRequired(requirements, components)),
         inserts: Command.inserts,
         removes: Command.removes,
         despawns: Command.despawns,
@@ -126,7 +172,7 @@ 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),
+      }) => 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

package/src/internal/queries.ts

@@ -46,6 +46,9 @@ interface LifecycleFilterPlan {
   readonly ordinal: number
 }
 
+/** A query filter: one lifecycle filter, or `anyOf` several (passes when one does). */
+type FilterPlan = ReadonlyArray<LifecycleFilterPlan>
+
 interface QueryState {
   readonly ordinal: number
   readonly required: ReadonlyArray<number>
@@ -54,7 +57,7 @@ interface QueryState {
   readonly withoutRelations: ReadonlyArray<Relation.Relation.Any>
   readonly withRelated: ReadonlyArray<Relation.Relation.Any>
   readonly withoutRelated: ReadonlyArray<Relation.Relation.Any>
-  readonly filters: ReadonlyArray<LifecycleFilterPlan>
+  readonly filters: ReadonlyArray<FilterPlan>
   readonly slots: ReadonlyArray<SlotPlan>
   readonly proofSlots: ReadonlyArray<readonly [string, number]>
   readonly writeSlots: ReadonlyArray<readonly [string, number]>
@@ -185,11 +188,13 @@ export const makeQueryEngine = (world: World) => {
       withoutRelations: query.withoutRelations,
       withRelated: unique(withRelated),
       withoutRelated: query.withoutRelated,
-      filters: query.filters.map((filter) => {
-        const ordinal = world.ordinalOf(filter.descriptor)
-        world.trackChanges(ordinal)
-        return { kind: filter.kind, ordinal }
-      }),
+      filters: query.filters.map((filter) =>
+        (filter.kind === "anyOf" ? filter.filters : [filter]).map((member) => {
+          const ordinal = world.ordinalOf(member.descriptor)
+          world.trackChanges(ordinal)
+          return { kind: member.kind, ordinal }
+        })
+      ),
       slots,
       proofSlots,
       writeSlots,
@@ -239,14 +244,33 @@ export const makeQueryEngine = (world: World) => {
 
   const matchesFilters = (state: QueryState, record: EntityRecord, since: number): boolean => {
     for (const filter of state.filters) {
-      const matched = filter.kind === "added"
-        ? world.addedSince(record, filter.ordinal, since)
-        : world.changedSince(record, filter.ordinal, since)
+      let matched = false
+      for (const member of filter) {
+        matched = member.kind === "added"
+          ? world.addedSince(record, member.ordinal, since)
+          : world.changedSince(record, member.ordinal, since)
+        if (matched) break
+      }
       if (!matched) return false
     }
     return true
   }
 
+  /**
+   * Ids that may pass one filter (may repeat), or `undefined` when a change
+   * log no longer covers `since`. An `anyOf` is the union of its members' logs.
+   */
+  const filterCandidates = (filter: FilterPlan, since: number): ReadonlyArray<number> | undefined => {
+    if (filter.length === 1) return world.changedCandidates(filter[0]!.ordinal, since)
+    const union: Array<number> = []
+    for (const member of filter) {
+      const logged = world.changedCandidates(member.ordinal, since)
+      if (logged === undefined) return undefined
+      for (const id of logged) union.push(id)
+    }
+    return union
+  }
+
   const relatedIds = (relation: Relation.Relation.Any, id: number): ReadonlyArray<Entity.EntityId<any, any>> =>
     world.relatedSourceIds(relation, id).map(world.entityIdOf)
 
@@ -426,7 +450,7 @@ export const makeQueryEngine = (world: World) => {
     // bounds the candidates for either filter.
     let candidates: ReadonlyArray<number> | undefined
     for (const filter of state.filters) {
-      const logged = world.changedCandidates(filter.ordinal, since)
+      const logged = filterCandidates(filter, since)
       if (logged === undefined) continue
       if (logged.length === 0) return []
       if (candidates === undefined || logged.length < candidates.length) candidates = logged

package/src/internal/requirements.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime side of `Schema.requires`: the requirement index built once per
+ * bound schema, used to expand `Game.System.spawns(...)`, to check commands
+ * when they are applied, and to check restored entities.
+ *
+ * The compile-time counterpart lives in `Command.ts` (spawn, insert, remove)
+ * and `Schema.ts` (`ValidateRequires`).
+ */
+import type { Descriptor } from "../Descriptor.ts"
+import type { Schema } from "../Schema.ts"
+
+type ComponentDescriptor = Descriptor<"component", string, any>
+
+export interface RequirementIndex {
+  /** Whether the schema declares any requirement. */
+  readonly empty: boolean
+  /** Component name to the components it directly requires. */
+  readonly requires: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+  /** Component name to the components that directly require it. */
+  readonly requiredBy: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+}
+
+const push = (map: Map<string, Array<ComponentDescriptor>>, key: string, value: ComponentDescriptor): void => {
+  const list = map.get(key)
+  if (list === undefined) map.set(key, [value])
+  else if (!list.some((entry) => entry.name === value.name)) list.push(value)
+}
+
+export const requirementIndex = (schema: Schema.Any): RequirementIndex => {
+  const requires = new Map<string, Array<ComponentDescriptor>>()
+  const requiredBy = new Map<string, Array<ComponentDescriptor>>()
+  for (const requirement of schema.requires) {
+    for (const required of requirement.required) {
+      push(requires, requirement.component.name, required)
+      push(requiredBy, required.name, requirement.component)
+    }
+  }
+  return { empty: requires.size === 0, requires, requiredBy }
+}
+
+/** `components` and everything they require, transitively, without duplicates. */
+export const withRequired = (
+  index: RequirementIndex,
+  components: ReadonlyArray<ComponentDescriptor>
+): ReadonlyArray<ComponentDescriptor> => {
+  if (index.empty) return components
+  const result: Array<ComponentDescriptor> = []
+  const seen = new Set<string>()
+  const visit = (descriptor: ComponentDescriptor): void => {
+    if (seen.has(descriptor.name)) return
+    seen.add(descriptor.name)
+    result.push(descriptor)
+    for (const required of index.requires.get(descriptor.name) ?? []) visit(required)
+  }
+  components.forEach(visit)
+  return result
+}
+
+/** The first requirement `held` breaks, as `[requirer, missing]`, or `undefined`. */
+export const firstMissing = (
+  index: RequirementIndex,
+  held: (name: string) => boolean,
+  names: Iterable<string>
+): readonly [string, string] | undefined => {
+  for (const name of names) {
+    for (const required of index.requires.get(name) ?? []) {
+      if (!held(required.name)) return [name, required.name]
+    }
+  }
+  return undefined
+}