@typeonce/ritmo 0.6.0 → 0.8.0

package/src/Schema.ts

@@ -13,8 +13,11 @@
  * 3. bind one `Game` with `Schema.bind(...)`
  * 4. build a runtime from that bound `Game`
  *
- * `Schema.Feature` composes fragments and their schedules before binding; see
- * the `feature` module.
+ * There is no plugin or feature object. A reusable slice of a game is a
+ * fragment (its descriptors) plus plain functions `(Game, options) => System |
+ * Schedule` that build its systems from the bound `Game`, like
+ * `RenderSync.system(Game, ...)` and `InputCapture.system(Game, ...)`. List
+ * every fragment in one `Schema.bind(...)` call.
  *
  * @module Schema
  * @docGroup core
@@ -65,8 +68,6 @@ import type * as Runtime from "./Runtime.ts"
 import type * as Schedule from "./Schedule.ts"
 import type * as System from "./System.ts"
 
-export { Feature } from "./Feature.ts"
-
 /**
  * A mapping from schema keys to nominal descriptors.
  */
@@ -74,20 +75,80 @@ export type Registry = Record<string, Descriptor.Any>
 
 /**
  * A closed schema: the components, resources, events, and relations a world
- * may contain.
+ * may contain, and the component requirements (`Schema.requires`) every
+ * entity of it keeps.
  */
 export interface SchemaDefinition<
   out Components extends Registry = {},
   out Resources extends Registry = {},
   out Events extends Registry = {},
-  out Relations extends Record<string, Relation.Relation.Any> = {}
+  out Relations extends Record<string, Relation.Relation.Any> = {},
+  out Requires extends RequirementPair = never
 > {
   readonly components: Components
   readonly resources: Resources
   readonly events: Events
   readonly relations: Relations
+  /** Component requirements declared with `Schema.requires(...)`. */
+  readonly requires: ReadonlyArray<ComponentRequirement<Requires>>
+}
+
+/**
+ * One requirement carried in a schema type, by component name:
+ * `[requirer, required]`. One pair per required component, so lookups by
+ * either end stay exact.
+ */
+export type RequirementPair = readonly [string, string]
+
+/**
+ * One `Schema.requires(...)` declaration: every entity holding `component`
+ * also holds each of `required`.
+ */
+export interface ComponentRequirement<out Pairs extends RequirementPair = RequirementPair> {
+  readonly kind: "requires"
+  readonly component: Descriptor<"component", string, any>
+  readonly required: ReadonlyArray<Descriptor<"component", string, any>>
+  readonly __pairs?: (_: never) => Pairs
 }
 
+type AnyComponentDescriptor = Descriptor<"component", string, any>
+
+/** One `[from, to]` pair per required name. */
+type RequirementPairs<From extends string, To extends string> = To extends string ? readonly [From, To] : never
+
+type PairsOf<R> = R extends ComponentRequirement<infer Pairs> ? Pairs : never
+
+/**
+ * Declares that every entity holding `component` also holds each of
+ * `required`. List it in a fragment's `requires`.
+ *
+ * The compiler then rejects every command that would break it:
+ * `commands.spawn` / `spawnIn` of a draft missing a required entry,
+ * `commands.insert` of `component` on an entity not proven to hold the
+ * rest, and `commands.remove` of a required component while a requirer may
+ * stay. `Game.System.spawns(component)` also allows spawning what it
+ * requires. Nothing is ever filled in with a default: the draft must carry
+ * every value.
+ *
+ * Requirements chain (`A` requires `B`, `B` requires `C`) and may name
+ * components of other fragments of the same `Schema.bind`.
+ *
+ * @example
+ * ```ts
+ * const Gameplay = Schema.fragment({
+ *   components: { Player, Position, Velocity },
+ *   requires: [Schema.requires(Player, Position, Velocity)]
+ * })
+ * ```
+ */
+export const requires = <
+  D extends AnyComponentDescriptor,
+  const Required extends readonly [AnyComponentDescriptor, ...Array<AnyComponentDescriptor>]
+>(
+  component: D,
+  ...required: Required
+): ComponentRequirement<RequirementPairs<D["name"], Required[number]["name"]>> => ({ kind: "requires", component, required })
+
 const schemaRootTypeId = "~ritmo/SchemaRoot" as const
 
 export type RootToken<Name extends string = string> = {
@@ -111,7 +172,8 @@ export type MergeSchemaDefinitions<
   Schema.Components<A> & Schema.Components<B>,
   Schema.Resources<A> & Schema.Resources<B>,
   Schema.Events<A> & Schema.Events<B>,
-  Schema.Relations<A> & Schema.Relations<B>
+  Schema.Relations<A> & Schema.Relations<B>,
+  Schema.Requires<A> | Schema.Requires<B>
 >
 
 /**
@@ -185,6 +247,24 @@ export type ValidateFragments<Fragments extends ReadonlyArray<Schema.Any>> =
         readonly __schemaConflicts__: FragmentConflicts<Fragments>
       }
 
+type UnregisteredRequirements<S extends Schema.Any> =
+  Exclude<Schema.Requires<S>[0] | Schema.Requires<S>[1], Schema.ComponentDescriptor<S>["name"]>
+
+/**
+ * Rejects requirements naming a component the bound schema does not
+ * register. Checked at `bind`, so a fragment may require a component another
+ * fragment registers. Erased schemas (`Schema.Any`) are checked by `bind` at
+ * runtime instead.
+ */
+export type ValidateRequires<S extends Schema.Any> =
+  [UnregisteredRequirements<S>] extends [never]
+    ? unknown
+    : string extends Schema.Requires<S>[1]
+    ? unknown
+    : {
+        readonly __schemaRequires__: `${UnregisteredRequirements<S>} is named in Schema.requires(...) but no fragment registers it: add it to a fragment's components`
+      }
+
 /**
  * Creates one explicit root token for schema-bound long-lived references.
  *
@@ -223,8 +303,9 @@ export const empty = (): SchemaDefinition => emptySchema()
  * @example
  * ```ts
  * const Combat = Schema.fragment({
- *   components: { Health, Damage },
- *   events: { Hit }
+ *   components: { Health, Damage, Enemy },
+ *   events: { Hit },
+ *   requires: [Schema.requires(Enemy, Health)]
  * })
  * ```
  */
@@ -232,33 +313,22 @@ export const fragment = <
   const Components extends Registry = {},
   const Resources extends Registry = {},
   const Events extends Registry = {},
-  const Relations extends Record<string, Relation.Relation.Any> = {}
+  const Relations extends Record<string, Relation.Relation.Any> = {},
+  const Requires extends ReadonlyArray<ComponentRequirement> = readonly []
 >(definition: {
   readonly components?: Components
   readonly resources?: Resources
   readonly events?: Events
   readonly relations?: Relations
-} & ValidateFragments<[SchemaDefinition<Components, Resources, Events, Relations>]>): SchemaDefinition<Components, Resources, Events, Relations> =>
+  readonly requires?: Requires
+} & ValidateFragments<[SchemaDefinition<Components, Resources, Events, Relations>]>): SchemaDefinition<Components, Resources, Events, Relations, PairsOf<Requires[number]>> =>
   mergeSchemas(emptySchema(), {
     components: definition.components ?? {},
     resources: definition.resources ?? {},
     events: definition.events ?? {},
-    relations: definition.relations ?? {}
-  }) as SchemaDefinition<Components, Resources, Events, Relations>
-
-/**
- * Merges two schema fragments into a larger closed schema.
- *
- * Duplicate keys and descriptor names are rejected at the type level and at
- * runtime.
- */
-export const merge = <
-  A extends Schema.Any,
-  B extends Schema.Any
->(
-  left: A,
-  right: B & ValidateFragments<[A, B]>
-): MergeSchemaDefinitions<A, B> => mergeSchemas(left, right) as MergeSchemaDefinitions<A, B>
+    relations: definition.relations ?? {},
+    requires: definition.requires ?? []
+  }) as SchemaDefinition<Components, Resources, Events, Relations, PairsOf<Requires[number]>>
 
 /**
  * Composes one or more fragments and returns one bound `Game` surface.
@@ -275,18 +345,18 @@ export const merge = <
  */
 export function bind<
   S extends Schema.Any
->(schema: S & ValidateFragments<[S]>): Schema.Game<S, S>
+>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>): Schema.Game<S, S>
 export function bind<
   S extends Schema.Any,
   const Name extends string
->(schema: S & ValidateFragments<[S]>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>
+>(schema: S & ValidateFragments<[S]> & ValidateRequires<S>, root: RootToken<Name>): Schema.Game<S, RootToken<Name>>
 export function bind<
   const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>]
->(...fragments: Fragments & ValidateFragments<Fragments>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>
+>(...fragments: Fragments & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, BuildFragments<Fragments>>
 export function bind<
   const Fragments extends readonly [Schema.Any, Schema.Any, ...Array<Schema.Any>],
   const Name extends string
->(...args: [...Fragments, RootToken<Name>] & ValidateFragments<Fragments>): Schema.Game<BuildFragments<Fragments>, RootToken<Name>>
+>(...args: [...Fragments, RootToken<Name>] & ValidateFragments<Fragments> & ValidateRequires<BuildFragments<Fragments>>): Schema.Game<BuildFragments<Fragments>, RootToken<Name>>
 export function bind(...args: ReadonlyArray<Schema.Any | RootToken>) {
   const maybeRoot = args[args.length - 1]
   const fragments = (isRootToken(maybeRoot) ? args.slice(0, -1) : args) as Array<Schema.Any>
@@ -311,7 +381,7 @@ type QuerySelectionAccess<S extends Schema.Any, Root> =
 
 interface BoundSystemAccess<S extends Schema.Any, Root> extends System.SystemAccessInput {
   readonly queries?: Record<string, Query.Any<Root>>
-  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
+  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
   readonly events?: Record<string, System.EventRead<EventDescriptor<S>> | System.EventWrite<EventDescriptor<S>>>
   readonly machines?: Record<string, Machine.MachineRead<Schema.BoundStateMachine<Root>>>
   readonly nextMachines?: Record<string, Machine.NextMachineWrite<Schema.BoundStateMachine<Root>>>
@@ -322,11 +392,12 @@ interface BoundSystemAccess<S extends Schema.Any, Root> extends System.SystemAcc
   readonly pauseWhen?: ReadonlyArray<Machine.Condition<Root>>
   readonly transitions?: Record<string, Machine.TransitionRead<Schema.BoundStateMachine<Root>>>
   readonly local?: () => unknown
+  readonly commands?: Command.CommandAccess<ComponentDescriptor<S>, ComponentDescriptor<S>, ComponentDescriptor<S>, ComponentDescriptor<S>, EntityScope.EntityScope<string, Root>, RelationDescriptor<S>>
 }
 
 interface BoundCheckAccess<S extends Schema.Any, Root> extends Condition.CheckAccessInput {
   readonly queries?: Record<string, Query.Any<Root>>
-  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>>>
+  readonly resources?: Record<string, System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | System.ResourceWrite<ResourceDescriptor<S>>>
   readonly machines?: Record<string, Machine.MachineRead<Schema.BoundStateMachine<Root>>>
 }
 
@@ -341,10 +412,10 @@ interface BoundInspectorAccess<S extends Schema.Any, Root> extends Inspector.Ins
 }
 
 type BoundScheduleEntry<S extends Schema.Any, Root> =
-  | Schema.BoundSystem<S, Root, any, any, any>
+  | Schema.BoundSystem<S, Root, any, any>
   | Schedule.ApplyDeferredStep
   | Schedule.ApplyStateTransitionsStep<any, Root>
-  | Schema.BoundSchedule<S, Root, any, any>
+  | Schedule.ScheduleDefinition<S, any, Root, any, any, Schedule.AnyScheduleOrder>
 
 type BoundTransitionEntry<S extends Schema.Any, Root> =
   Exclude<BoundScheduleEntry<S, Root>, Schedule.ApplyStateTransitionsStep<any, Root>>
@@ -359,7 +430,8 @@ type BoundTransitionScheduleResult<
   M,
   Schedule.CompositionExactRequirements<Entries>,
   Root,
-  Schedule.CompositionFailure<Entries>
+  Schedule.CompositionFailure<Entries>,
+  Schedule.CompositionOrder<Entries>
 >
 
 type BoundTransitionBundleInput<S extends Schema.Any, Root> =
@@ -376,7 +448,8 @@ type BoundTransitionBundleResult<
   Schedule.TransitionBundleRequirements<Schedule.FlattenTransitionEntries<Entries>>,
   Root,
   Schedule.TransitionBundleRequirements<Schedule.FlattenTransitionEntries<Entries>>,
-  Schedule.TransitionBundleFailure<Schedule.FlattenTransitionEntries<Entries>>
+  Schedule.TransitionBundleFailure<Schedule.FlattenTransitionEntries<Entries>>,
+  Schedule.CompositionOrder<Entries>
 >
 
 /**
@@ -386,12 +459,14 @@ export namespace Schema {
   /**
    * Any complete schema definition.
    */
-  export type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>>
+  export type Any = SchemaDefinition<Registry, Registry, Registry, Record<string, Relation.Relation.Any>, RequirementPair>
 
   export type Components<T extends Any> = T["components"]
   export type Resources<T extends Any> = T["resources"]
   export type Events<T extends Any> = T["events"]
   export type Relations<T extends Any> = T["relations"]
+  /** The component requirements of a schema, as `[requirer, required]` name pairs (`Schema.requires`). */
+  export type Requires<T extends Any> = T extends SchemaDefinition<any, any, any, any, infer Pairs> ? Pairs : never
 
   export type ComponentValue<T extends Any, K extends keyof Components<T>> = Descriptor.Value<Components<T>[K]>
   export type ResourceValue<T extends Any, K extends keyof Resources<T>> = Descriptor.Value<Resources<T>[K]>
@@ -413,11 +488,10 @@ export namespace Schema {
     S extends Any,
     Root,
     Spec extends System.AnySystemSpec = System.AnySystemSpec,
-    A = void,
     E = never,
     Name extends string = string,
     Needs extends Requirement.Requirement = Requirement.Requirement
-  > = System.SystemDefinition<Spec & { readonly schema: S }, A, E, Root, Name, Needs>
+  > = System.SystemDefinition<Spec & { readonly schema: S }, E, Root, Name, Needs>
 
   /** A schema-bound read-only world projection. */
   export type BoundInspector<
@@ -437,7 +511,7 @@ export namespace Schema {
     Root,
     Needs extends Requirement.Requirement = Requirement.Requirement,
     Failure extends System.SystemFailure = never
-  > = Schedule.ScheduleDefinition<S, Needs, Root, Needs, Failure>
+  > = Schedule.ScheduleDefinition<S, Needs, Root, Needs, Failure, Schedule.ScheduleOrder>
 
   /**
    * A schema-bound finite-state machine.
@@ -445,24 +519,27 @@ export namespace Schema {
   export type BoundStateMachine<
     Root,
     Name extends string = string,
-    Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]]
-  > = Machine.StateMachineDefinition<Name, Values, Root>
+    Values extends readonly [Machine.StateValue, ...Machine.StateValue[]] = readonly [Machine.StateValue, ...Machine.StateValue[]],
+    Parent = unknown
+  > = Machine.StateMachineDefinition<Name, Values, Root, Parent>
 
   export type BoundTransitionSchedule<
     S extends Any,
     Root,
     M extends BoundStateMachine<Root> = BoundStateMachine<Root>,
     Needs extends Requirement.Requirement = Requirement.Requirement,
-    Failure extends System.SystemFailure = never
-  > = Machine.TransitionScheduleDefinition<S, M, Needs, Root, Failure>
+    Failure extends System.SystemFailure = never,
+    Order extends Schedule.AnyScheduleOrder = Schedule.AnyScheduleOrder
+  > = Machine.TransitionScheduleDefinition<S, M, Needs, Root, Failure, Order>
 
   export type BoundTransitionBundle<
     S extends Any,
     Root,
     Entries extends ReadonlyArray<BoundTransitionSchedule<S, Root, any, any, any>> = ReadonlyArray<BoundTransitionSchedule<S, Root, any, any, any>>,
     Needs extends Requirement.Requirement = Requirement.Requirement,
-    Failure extends System.SystemFailure = never
-  > = Schedule.TransitionBundleDefinition<S, Entries, Needs, Root, Needs, Failure>
+    Failure extends System.SystemFailure = never,
+    Order extends Schedule.AnyScheduleOrder = Schedule.AnyScheduleOrder
+  > = Schedule.TransitionBundleDefinition<S, Entries, Needs, Root, Needs, Failure, Order>
 
   /**
    * A schema-bound runtime branded to one bound schema root.
@@ -480,8 +557,40 @@ export namespace Schema {
    */
   export interface Game<S extends Any, Root = S> {
     readonly schema: S
-    /** Creates a typed ownership scope for scene or level entities. */
-    readonly EntityScope: <const Name extends string>(name: Name) => EntityScope.EntityScope<Name, Root>
+    /**
+     * Creates a typed ownership scope for scene or level entities: a flat
+     * group whose members are spawned with `commands.spawnIn(...)` and
+     * despawned together. Use `Descriptor.Hierarchy` instead for a
+     * parent-child tree with ordered children, traversal, and recursive
+     * despawn.
+     *
+     * When the group lives exactly as long as a state, name the state change
+     * that ends it: `despawnOnExit: [Flow, "Playing"]` despawns every member
+     * when `applyStateTransitions(...)` commits leaving `Playing` (after its
+     * `onExit` schedules, which still see the members), and
+     * `despawnOnEnter: [Flow, "Playing"]` when it commits entering it (before
+     * its `onEnter` schedules, so what they spawn survives). Use
+     * `commands.despawnScope(...)` instead when the wipe is not tied to a
+     * state change. Scope names are unique per game.
+     *
+     * @example
+     * ```ts
+     * const RunScope = Game.EntityScope("Shooter/Run", { despawnOnExit: [Flow, "Playing"] })
+     * ```
+     */
+    readonly EntityScope: <
+      const Name extends string,
+      Enter extends Machine.StateMachine.Any = never,
+      Exit extends Machine.StateMachine.Any = never
+    >(
+      name: Name,
+      options?: {
+        /** Despawns every member when the machine enters this state, before its `onEnter` schedules run. */
+        readonly despawnOnEnter?: readonly [Enter & Machine.SameGame<Enter, Root>, Machine.StateMachine.Value<Enter>]
+        /** Despawns every member when the machine leaves this state, after its `onExit` schedules run. */
+        readonly despawnOnExit?: readonly [Exit & Machine.SameGame<Exit, Root>, Machine.StateMachine.Value<Exit>]
+      }
+    ) => EntityScope.EntityScope<Name, Root>
     /** Declares a reusable, requirement-checked read-only world projection. */
     readonly Inspector: <
       const Name extends string,
@@ -521,12 +630,20 @@ export namespace Schema {
         readonly withoutRelations?: WithoutRelations
         readonly withRelated?: WithRelated
         readonly withoutRelated?: WithoutRelated
-      }): QueryModule.QuerySpec<Selection, With, Without, Filters, WithRelations, WithoutRelations, WithRelated, WithoutRelated, Root>
+        // Uninferred: an omitted list is `[]`, never inferred from the spec it is written in (`queries: { ... }`).
+      }): QueryModule.QuerySpec<Selection, QueryModule.Uninferred<With, ReadonlyArray<ComponentDescriptor<S>>>, QueryModule.Uninferred<Without, ReadonlyArray<ComponentDescriptor<S>>>, QueryModule.Uninferred<Filters, ReadonlyArray<QueryModule.Filter<ComponentDescriptor<S>>>>, QueryModule.Uninferred<WithRelations, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithoutRelations, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithRelated, ReadonlyArray<Relation.Relation.Any>>, QueryModule.Uninferred<WithoutRelated, ReadonlyArray<Relation.Relation.Any>>, Root>
       read: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.ReadAccess<D>
-      write: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.WriteAccess<D>
+      write: <D extends ComponentDescriptor<S>>(descriptor: D & QueryModule.Writable<D>) => QueryModule.WriteAccess<D>
       optional: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.OptionalReadAccess<D>
       added: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.AddedFilter<D>
       changed: <D extends ComponentDescriptor<S>>(descriptor: D) => QueryModule.ChangedFilter<D>
+      anyOf: <
+        const Filters extends readonly [
+          QueryModule.LifecycleFilter<ComponentDescriptor<S>>,
+          QueryModule.LifecycleFilter<ComponentDescriptor<S>>,
+          ...ReadonlyArray<QueryModule.LifecycleFilter<ComponentDescriptor<S>>>
+        ]
+      >(...filters: Filters) => QueryModule.AnyOfFilter<Filters[number]["descriptor"]>
       readRelation: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.RelationReadAccess<R, S, Root>
       optionalRelation: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.OptionalRelationReadAccess<R, S, Root>
       readRelated: <R extends RelationDescriptor<S>>(descriptor: R) => Relation.RelatedReadAccess<R, S, Root>
@@ -537,16 +654,15 @@ export namespace Schema {
       spawn: <const Entries extends ReadonlyArray<Command.SpawnEntry<S>> = readonly []>(
         ...entries: Entries
       ) => Command.DraftFor<S, Entries, {}, Root>
-      /** Adds entries to a draft. */
-      insert: <P extends Entity.ComponentProof, const Entries extends ReadonlyArray<Command.SpawnEntry<S>>>(
+      /**
+       * Adds entries to a draft (a value not yet spawned). Use
+       * `commands.insert` for an entity that already exists.
+       */
+      extend: <P extends Entity.ComponentProof, const Entries extends ReadonlyArray<Command.SpawnEntry<S>>>(
         draft: Entity.EntityDraft<S, P, Root>,
         ...entries: Entries
       ) => Command.DraftFor<S, Entries, P, Root>
       entry: <D extends ComponentDescriptor<S>>(descriptor: D, value: Descriptor.Value<D>) => Command.Entry<D>
-      entryResult: <D extends ComponentDescriptor<S>, E>(
-        descriptor: D,
-        result: Result.Result<Descriptor.Value<D>, E>
-      ) => Result.Result<Command.Entry<D>, E>
       entryRaw: <D extends Extract<ComponentDescriptor<S>, ConstructedDescriptor<"component", string, any, any, any>>>(
         descriptor: D,
         raw: Descriptor.Raw<D>
@@ -557,15 +673,57 @@ export namespace Schema {
         target: Entity.EntityId<S, Root>
       ) => Entity.EntityDraft<S, P, Root>
     }
+    /**
+     * Declares one game-wide mode (menu, playing, paused): queued with
+     * `nextState`, committed at `applyStateTransitions(...)`, gating systems
+     * with `Game.Condition.inState(...)`. Use `Descriptor.EntityState(...)`
+     * instead for a state each entity has on its own.
+     */
     readonly StateMachine: {
       <
         const Name extends string,
         const Values extends readonly [Machine.StateValue, ...Machine.StateValue[]]
       >(name: Name, values: Values): Schema.BoundStateMachine<Root, Name, Values>
+      /**
+       * Declares a sub-state: a machine that exists only while `within[0]` is
+       * in state `within[1]` (a battle phase that only means something while
+       * playing). Whenever the parent enters that state, the sub-state enters
+       * the value given to `Game.Runtime.machine(...)`; when the parent leaves
+       * it, the sub-state exits and has no value: `get()` is `undefined`,
+       * `Game.Condition.inState(Sub, x)` is false, and `nextMachines.sub.set(...)`
+       * returns a `SubStateInactive` failure. So `inState(Sub, x)` alone
+       * implies the parent's state.
+       *
+       * Use a second top-level machine instead when the two modes are
+       * independent (each keeps its value whatever the other does).
+       *
+       * @example
+       * ```ts
+       * const Phase = Game.StateMachine("Phase", ["Setup", "Battle"], { within: [Session, "Playing"] })
+       * ```
+       */
+      <
+        const Name extends string,
+        const Values extends readonly [Machine.StateValue, ...Machine.StateValue[]],
+        Parent extends Machine.StateMachine.Any
+      >(
+        name: Name,
+        values: Values,
+        options: { readonly within: readonly [Parent & Machine.SameGame<Parent, Root>, Machine.StateMachine.Value<Parent>] }
+      ): Schema.BoundStateMachine<Root, Name, Values, Parent>
     }
     readonly Condition: {
-      inState: typeof Machine.inState
-      stateChanged: typeof Machine.stateChanged
+      /**
+       * Passes while the machine's committed value is `value`. For a
+       * sub-state it fails while the parent is in another state. A machine
+       * of another game fails to compile with a message naming the fix.
+       */
+      inState: <M extends Machine.StateMachine.Any>(
+        machine: M & Machine.SameGame<M, Root>,
+        value: Machine.StateMachine.Value<M>
+      ) => Machine.InStateCondition<M>
+      /** Passes in the schedule run where `applyStateTransitions(...)` changed the machine. */
+      stateChanged: <M extends Machine.StateMachine.Any>(machine: M & Machine.SameGame<M, Root>) => Machine.StateChangedCondition<M>
       not: typeof Machine.not
       and: typeof Machine.and
       or: typeof Machine.or
@@ -584,17 +742,25 @@ export namespace Schema {
       <
         const Name extends string,
         const Access extends BoundSystemAccess<S, Root>,
-        A = void,
         E = never
       >(
         name: Name,
         spec: System.ExactAccess<Access>,
-        run: System.SystemRun<System.SystemSpec<S, Access, Root>, A, E>
-      ): BoundSystem<S, Root, System.SystemSpec<S, Access, Root>, A, E, Name, System.SystemAccessNeeds<Access>>
+        run: System.SystemRun<System.SystemSpec<S, Access, Root>, E>
+      ): BoundSystem<S, Root, System.SystemSpec<S, Access, Root>, E, Name, System.SystemAccessNeeds<Access>>
       readResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceRead<D>
       writeResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceWrite<D>
+      changedResource: <D extends ResourceDescriptor<S>>(descriptor: D) => System.ResourceChanged<D>
       readEvent: <D extends EventDescriptor<S>>(descriptor: D) => System.EventRead<D>
       writeEvent: <D extends EventDescriptor<S>>(descriptor: D) => System.EventWrite<D>
+      /**
+       * Requires every writer of this event or resource to run earlier in the
+       * same `runtime.tick(...)` call; checked at compile time by `tick`.
+       * Accepts `readEvent(...)`, `readResource(...)`, or a query.
+       */
+      thisTick: <Read extends System.EventRead<EventDescriptor<S>> | System.ResourceRead<ResourceDescriptor<S>> | System.ResourceChanged<ResourceDescriptor<S>> | Query.Any<Root>>(
+        read: Read
+      ) => Read & System.ThisTick
       service: typeof System.service
       machine: <M extends BoundStateMachine<Root>>(machine: M) => Machine.MachineRead<M>
       nextState: <M extends BoundStateMachine<Root>>(machine: M) => Machine.NextMachineWrite<M>
@@ -603,6 +769,23 @@ export namespace Schema {
       readRemoved: <D extends ComponentDescriptor<S>>(descriptor: D) => System.RemovedRead<D>
       readDespawned: () => System.DespawnedRead
       readRelationFailures: <R extends RelationDescriptor<S>>(relation: R) => System.RelationFailureRead<R>
+      /**
+       * Declares the commands a system may queue, for its spec's `commands`:
+       * `Game.System.commands(Game.System.spawns(Enemy, Position), Game.System.despawns(Enemy))`.
+       */
+      commands: typeof Command.commands
+      /** Allows spawning drafts whose components are all among these and what they require (`Schema.requires`); see `Command.spawns`. */
+      spawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"spawns", Components[number] | Command.RequiredDescriptors<S, Components[number]["name"]>>
+      /** Allows `insert` (add or replace at the next `applyDeferred()`) of these; see `Command.inserts`. */
+      inserts: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"inserts", Components[number]>
+      /** Allows `remove` of these. */
+      removes: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"removes", Components[number]>
+      /** Allows `despawn` of entities a query proves have one of these; see `Command.despawns`. */
+      despawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"despawns", Components[number]>
+      /** Allows `despawnScope` of this scope. */
+      despawnsScope: <const Scope extends EntityScope.EntityScope<string, Root>>(scope: Scope) => Command.Permission<"despawnsScope", Scope>
+      /** Allows `relate`, `unrelate`, and `reorderChildren` of these relations. */
+      relates: <const Relations extends ReadonlyArray<RelationDescriptor<S>>>(...relations: Relations) => Command.Permission<"relates", Relations[number]>
     }
     readonly Schedule: {
       /**
@@ -633,7 +816,9 @@ export namespace Schema {
       /**
        * Builds a schedule whose systems run only while every condition
        * passes (in addition to their own `when`). Nested schedules are
-       * gated too; marker steps still run.
+       * gated too; marker steps still run. Gated systems drop the events
+       * published while gated; use `pauseWhen` to keep them. For one system,
+       * use `when` in its spec.
        */
       when: <
         const Conditions extends readonly [Machine.Condition<Root>, ...Array<Machine.Condition<Root>>],
@@ -647,6 +832,7 @@ export namespace Schema {
        * fails: unlike `when`, a paused system keeps its place in the event
        * streams it reads and sees everything published meanwhile once it
        * runs again. For freezes whose events stay valid (hit-stop, pause).
+       * For one system, use `pauseWhen` in its spec.
        */
       pauseWhen: <
         const Conditions extends readonly [Machine.Condition<Root>, ...Array<Machine.Condition<Root>>],

package/src/Snapshot.ts

@@ -115,12 +115,16 @@ export type RestoreError =
   | { readonly _tag: "UnsupportedVersion"; readonly version: unknown }
   | { readonly _tag: "UnknownComponent"; readonly entityId: number; readonly name: string }
   | { readonly _tag: "InvalidComponent"; readonly entityId: number; readonly name: string; readonly error: unknown }
+  /** A saved entity holds `requiredBy` but lacks `name`, which `Schema.requires` says it needs. */
+  | { readonly _tag: "MissingRequiredComponent"; readonly entityId: number; readonly name: string; readonly requiredBy: string }
   | { readonly _tag: "UnknownResource"; readonly name: string }
   | { readonly _tag: "InvalidResource"; readonly name: string; readonly error: unknown }
   | { readonly _tag: "UnknownRelation"; readonly name: string }
   | { readonly _tag: "InvalidRelation"; readonly name: string; readonly sourceId: number; readonly targetId: number }
   | { readonly _tag: "UnknownMachine"; readonly name: string }
   | { readonly _tag: "InvalidMachineState"; readonly name: string; readonly value: unknown }
+  /** A saved sub-state value while its parent machine is not in the state the sub-state exists in. */
+  | { readonly _tag: "InactiveSubState"; readonly name: string; readonly parent: string; readonly requires: unknown }
   | { readonly _tag: "DuplicateEntity"; readonly entityId: number }
   /** A scope member that is not a saved entity, or is already in another scope. */
   | { readonly _tag: "InvalidScope"; readonly name: string; readonly entityId: number }