@typeonce/ritmo 0.6.0 → 0.8.0

package/src/internal/cells.ts

@@ -18,7 +18,8 @@ abstract class WriteCellBase<T> {
   abstract get(): T
   abstract set(value: T): void
 
-  setResult<E>(result: Result.Result<T, E>): Result.Result<void, E> {
+  /** Writes a validated candidate only on success. Backs `setRaw` / `updateRaw`. */
+  writeResult<E>(result: Result.Result<T, E>): Result.Result<void, E> {
     if (!result.ok) {
       return Result.failure(result.error)
     }
@@ -30,9 +31,6 @@ abstract class WriteCellBase<T> {
     this.set(f(this.get()))
   }
 
-  updateResult<E>(f: (current: T) => Result.Result<T, E>): Result.Result<void, E> {
-    return this.setResult(f(this.get()))
-  }
 }
 
 /**
@@ -43,22 +41,22 @@ const withConstructor = <T, Raw, Error>(
   constructor: ResultConstructor<T, Raw, Error>
 ) => Object.assign(cell, {
   setRaw(raw: Raw): Result.Result<void, Error> {
-    return cell.setResult(constructor.result(raw))
+    return cell.writeResult(constructor.result(raw))
   },
   updateRaw(f: (current: T) => Raw): Result.Result<void, Error> {
-    return cell.setResult(constructor.result(f(cell.get())))
+    return cell.writeResult(constructor.result(f(cell.get())))
   }
 })
 
 /**
- * Adds `transition` to the write cell of a state component: a compare-and-set
+ * Adds `transition` to the write cell of an entity state component: a compare-and-set
  * that writes `to` only while the current state is still `from`.
  */
-const withTransition = (cell: WriteCellBase<unknown>, state: string) => Object.assign(cell, {
-  transition(from: unknown, to: unknown): Result.Result<void, { readonly _tag: "StateMismatch"; readonly state: string; readonly expected: unknown; readonly actual: unknown }> {
+const withTransition = (cell: WriteCellBase<unknown>, component: string) => Object.assign(cell, {
+  transition(from: unknown, to: unknown): Result.Result<void, { readonly _tag: "EntityStateMismatch"; readonly component: string; readonly expected: unknown; readonly actual: unknown }> {
     const actual = cell.get()
     if (actual !== from) {
-      return Result.failure({ _tag: "StateMismatch", state, expected: from, actual })
+      return Result.failure({ _tag: "EntityStateMismatch", component, expected: from, actual })
     }
     cell.set(to)
     return Result.success(undefined)
@@ -162,11 +160,11 @@ export const componentWrite = (
   ordinal: number,
   world: World,
   constructor: ResultConstructor<unknown, unknown, unknown> | undefined,
-  state: string | undefined
+  entityState: string | undefined
 ): WriteCellBase<unknown> => {
   const cell = new ComponentWriteCell(record, ordinal, world)
   const constructed = constructor === undefined ? cell : withConstructor(cell, constructor)
-  return state === undefined ? constructed : withTransition(constructed, state)
+  return entityState === undefined ? constructed : withTransition(constructed, entityState)
 }
 
 export const componentOptional = (record: EntityRecord, ordinal: number): { readonly present: boolean; get(): unknown } =>

package/src/internal/debug.ts

@@ -6,11 +6,13 @@
 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"
 import type * as Relation from "../Relation.ts"
 import * as Schedule from "../Schedule.ts"
+import * as OrderInternal from "./order.ts"
 import type { Schema } from "../Schema.ts"
 import type { SystemDefinition } from "../System.ts"
 
@@ -71,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> = []
@@ -101,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"),
@@ -113,11 +121,35 @@ 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 => {
+  const of = (kind: keyof Debug.CommandPermissions) =>
+    [...new Set((access?.permissions ?? []).filter((p) => p.permission === kind).flatMap((p) => p.values.map((value) => value.name)))]
+  return {
+    spawns: of("spawns"),
+    inserts: of("inserts"),
+    removes: of("removes"),
+    despawns: of("despawns"),
+    despawnsScope: of("despawnsScope"),
+    relates: of("relates")
+  }
+}
+
+const permissionVerb: Record<keyof Debug.CommandPermissions, string> = {
+  spawns: "spawn",
+  inserts: "insert",
+  removes: "remove",
+  despawns: "despawn",
+  despawnsScope: "despawn the scope",
+  relates: "relate"
+}
+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.
@@ -135,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") },
@@ -148,7 +181,16 @@ export const describeSystem = (system: AnySystem, placements: ReadonlyArray<stri
     removed: names(spec.removed as Record<string, { readonly descriptor: Descriptor.Any }>, (access) => access.descriptor.name),
     despawned: Object.keys(spec.despawned).length > 0,
     relationFailures: names(spec.relationFailures as Record<string, { readonly relation: Relation.Relation.Any }>, (access) => access.relation.name),
+    thisTick: [
+      ...[...Object.values(spec.events as Record<string, ThisTickAccess>), ...Object.values(spec.resources as Record<string, ThisTickAccess>)]
+        .filter((access) => access.thisTick === true)
+        .map((access) => access.descriptor.name),
+      ...Object.entries(spec.queries as Record<string, { readonly thisTick?: true }>)
+        .filter(([, query]) => query.thisTick === true)
+        .map(([slot]) => `queries.${slot}`)
+    ],
     services: names(spec.services as Record<string, { readonly descriptor: Descriptor.Any }>, (access) => access.descriptor.name),
+    commands: permissionsOf(spec.commands as CommandAccess | undefined),
     when: (spec.when as ReadonlyArray<Machine.Condition>).map(renderCondition),
     pauseWhen: (spec.pauseWhen as ReadonlyArray<Machine.Condition>).map(renderCondition),
     local: spec.local !== undefined
@@ -226,8 +268,20 @@ 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. */
+  readonly relationMutations: ReadonlyMap<string, ReadonlySet<string>>
+  /** What each system's applied commands did, as `kind:name`; see `Runtime`. */
+  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]>
 }
@@ -269,6 +323,7 @@ export const describe = (input: DescribeInput): Debug.Description => {
       }
     }
     for (const name of system.removed) components.read(name, system.name)
+    for (const name of [...system.commands.spawns, ...system.commands.inserts, ...system.commands.removes]) components.write(name, system.name)
     for (const name of system.resources.reads) resources.read(name, system.name)
     for (const name of system.resources.writes) resources.write(name, system.name)
     for (const name of system.events.reads) events.read(name, system.name)
@@ -283,7 +338,21 @@ export const describe = (input: DescribeInput): Debug.Description => {
   const appliesTransitions = schedules.some(([, schedule]) =>
     schedule.steps.some((step) => !Schedule.isSystemStep(step) && step.kind === "applyStateTransitions"))
 
-  const lints: Array<Debug.Lint> = []
+  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) {
@@ -313,7 +382,85 @@ 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>>()
+    for (const system of systems) {
+      for (const name of system.commands.relates) relaters.set(name, new Set([...(relaters.get(name) ?? []), system.name]))
+    }
+    for (const [name, queuers] of input.relationMutations) relaters.set(name, new Set([...(relaters.get(name) ?? []), ...queuers]))
+    for (const [name, queuers] of relaters) {
+      if (failureReaders.has(name)) continue
+      lints.push({
+        severity: "warning",
+        code: "relation-failure-never-read",
+        subject: name,
+        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) {
+      for (const issue of OrderInternal.tickOrderIssues(schedule.steps)) {
+        lints.push({ severity: "warning", code: "this-tick-order", subject: issue.data, message: `in ${name}, ${issue.message}` })
+      }
+    }
+    // Observed with debug: only systems that ran, so an unplayed session reports nothing.
+    for (const system of systems) {
+      if (!input.ranSystems.has(system.name)) continue
+      const uses = input.commandUses.get(system.name) ?? new Set<string>()
+      for (const kind of Object.keys(permissionVerb) as Array<keyof Debug.CommandPermissions>) {
+        const unused = system.commands[kind].filter((name) => !uses.has(`${kind}:${name}`))
+        if (unused.length === 0) continue
+        lints.push({
+          severity: "info",
+          code: "command-permission-unused",
+          subject: system.name,
+          message: `${system.name} may ${permissionVerb[kind]} ${unused.join(", ")} but never did in this session`
+        })
+      }
+    }
+    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({
@@ -328,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),
@@ -345,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,
@@ -355,7 +512,46 @@ export const describe = (input: DescribeInput): Debug.Description => {
       resources: resources.list(),
       events: events.list()
     },
-    lints
+    lints: lints.map((lint) => ({ ...lint, fix: fixFor(lint.code, lint.subject) }))
+  }
+}
+
+/**
+ * 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) {
+    case "event-never-read":
+      return `read ${subject} in a system with Game.System.readEvent, or stop emitting it; if only a render schedule reads it, pass that schedule as describe-only`
+    case "event-never-written":
+      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":
+      return "fine when a one-run lag is intended (input before movement); otherwise move the reader after the writer, or read with Game.System.thisTick to make it an error"
   }
 }
 
@@ -367,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
 })
 
@@ -380,8 +576,8 @@ const readBeforeWriteLints = (
   schedules: ReadonlyArray<readonly [string, AnySchedule]>,
   described: ReadonlyMap<AnySystem, Debug.SystemDescription>,
   externallyWrittenEvents: ReadonlySet<string>
-): Array<Debug.Lint> => {
-  const lints: Array<Debug.Lint> = []
+): Array<Omit<Debug.Lint, "fix">> => {
+  const lints: Array<Omit<Debug.Lint, "fix">> = []
   for (const [name, schedule] of schedules) {
     const steps = schedule.steps.flatMap((step) =>
       Schedule.isSystemStep(step) ? [{ system: described.get(step as AnySystem)!, accesses: accessesOf(described.get(step as AnySystem)!) }] : [])

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

@@ -5,6 +5,8 @@
  * module functions; the precise public types live on `Schema.Game`.
  */
 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"
@@ -16,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>
@@ -38,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: {
@@ -50,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,
@@ -57,9 +101,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
     }),
     Command: {
       spawn: Command.spawn,
-      insert: Command.insert,
+      extend: Command.extend,
       entry: Command.entry,
-      entryResult: Command.entryResult,
       entryRaw: Command.entryRaw,
       relate: Command.relate
     },
@@ -79,8 +122,19 @@ 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(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,
+        despawnsScope: Command.despawnsScope,
+        relates: Command.relates,
         service: System.service,
         machine: System.machine,
         nextState: System.nextState,
@@ -117,8 +171,8 @@ export const makeGame = <S extends Schema.Any, Root>(schema: S, _root: Root): Sc
         readonly services: Runtime.RuntimeServices<any>
         readonly resources?: object
         readonly machines?: Runtime.RuntimeMachines<any>
-        readonly debug?: true
-      }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines } as never),
+        readonly debug?: Debug.Option
+      }) => Runtime.make({ schema, ...options, machineDefinitions: definedMachines, scopeDefinitions: definedScopes } as never),
       service: Runtime.service,
       services: Runtime.services,
       machine: Runtime.machine,