@typeonce/ritmo 0.7.0 → 0.8.0

package/src/Schema.ts

@@ -75,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> = {
@@ -112,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>
 >
 
 /**
@@ -186,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.
  *
@@ -224,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)]
  * })
  * ```
  */
@@ -233,19 +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>
+    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.
@@ -262,18 +345,18 @@ export const fragment = <
  */
 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>
@@ -298,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>>>
@@ -314,7 +397,7 @@ interface BoundSystemAccess<S extends Schema.Any, Root> extends System.SystemAcc
 
 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>>>
 }
 
@@ -376,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]>
@@ -434,8 +519,9 @@ 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,
@@ -473,11 +559,38 @@ export namespace Schema {
     readonly schema: S
     /**
      * Creates a typed ownership scope for scene or level entities: a flat
-     * group despawned together with `commands.despawnScope(...)`. Use
-     * `Descriptor.Hierarchy` instead for a parent-child tree with ordered
-     * children, traversal, and recursive despawn.
+     * 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>(name: Name) => EntityScope.EntityScope<Name, Root>
+    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,
@@ -520,10 +633,17 @@ export namespace Schema {
         // 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>
@@ -564,10 +684,46 @@ export namespace Schema {
         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
@@ -594,6 +750,7 @@ export namespace Schema {
       ): 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>
       /**
@@ -601,7 +758,7 @@ export namespace Schema {
        * 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>> | Query.Any<Root>>(
+      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
@@ -617,8 +774,8 @@ export namespace Schema {
        * `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; see `Command.spawns`. */
-      spawns: <const Components extends ReadonlyArray<ComponentDescriptor<S>>>(...components: Components) => Command.Permission<"spawns", Components[number]>
+      /** 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. */

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 }

package/src/System.ts

@@ -193,6 +193,50 @@ export const writeResource = <D extends Descriptor<"resource", string, any>>(
   descriptor
 })
 
+/**
+ * Declares read access to a resource plus whether it changed since this
+ * system's previous completed run.
+ */
+export type ResourceChanged<D extends Descriptor<"resource", string, any>> = {
+  readonly mode: "changed"
+  readonly descriptor: D
+}
+
+/**
+ * Creates a resource read that also reports `changed()`: whether a committed
+ * write left a different value since this system's previous completed run.
+ *
+ * Use it for work worth doing only when a value moved: rewriting a HUD label,
+ * rebuilding a cache from settings. Use `readResource` when the system needs
+ * the value every run anyway.
+ *
+ * A write that leaves an equal value is not a change: primitives compare
+ * with `Object.is`, plain objects and arrays by their entries, other objects
+ * by reference. This differs from `Game.Query.changed`, where every write
+ * through a component write cell counts. The first run reports `true`; a
+ * failed run (rolled back) is not a change, and a failed reader sees the same
+ * change again next run. Its own writes are not reported to the writer.
+ *
+ * Conditions (`Game.Condition.check`) cannot declare it: they own no cursor.
+ *
+ * @example
+ * ```ts
+ * const SyncHud = Game.System("SyncHud", {
+ *   resources: { score: Game.System.changedResource(Score) },
+ *   services: { hud: Game.System.service(Hud) }
+ * }, ({ resources, services }) => {
+ *   if (!resources.score.changed()) return
+ *   services.hud.score.textContent = `${resources.score.get()}`
+ * })
+ * ```
+ */
+export const changedResource = <D extends Descriptor<"resource", string, any>>(
+  descriptor: D
+): ResourceChanged<D> => ({
+  mode: "changed",
+  descriptor
+})
+
 /**
  * Declares read-only access to an event stream.
  */
@@ -314,7 +358,7 @@ export interface ThisTick {
  * ```
  */
 export const thisTick = <
-  Read extends EventRead<Descriptor<"event", string, any>> | ResourceRead<Descriptor<"resource", string, any>> | Query.Any<any>
+  Read extends EventRead<Descriptor<"event", string, any>> | ResourceRead<Descriptor<"resource", string, any>> | ResourceChanged<Descriptor<"resource", string, any>> | Query.Any<any>
 >(read: Read): Read & ThisTick => ({ ...read, thisTick: true })
 
 /**
@@ -367,7 +411,10 @@ export const readTransitionEvent = <M extends Machine.StateMachine.Any>(
 /**
  * Internal union for all supported resource access declarations.
  */
-type ResourceAccess = ResourceRead<Descriptor<"resource", string, any>> | ResourceWrite<Descriptor<"resource", string, any>>
+type ResourceAccess =
+  | ResourceRead<Descriptor<"resource", string, any>>
+  | ResourceChanged<Descriptor<"resource", string, any>>
+  | ResourceWrite<Descriptor<"resource", string, any>>
 /**
  * Internal union for all supported event access declarations.
  */
@@ -378,6 +425,15 @@ type EventAccess = EventRead<Descriptor<"event", string, any>> | EventWrite<Desc
  */
 export interface ResourceReadView<T> extends ReadCell<T> {}
 
+/**
+ * A read-only view over a resource value that also reports whether it
+ * changed since this system's previous completed run (`changedResource`).
+ */
+export interface ResourceChangedView<T> extends ReadCell<T> {
+  /** Whether a committed write left a different value since this system's previous completed run. `true` on the first run. */
+  changed(): boolean
+}
+
 /**
  * A mutable view over a resource value.
  */
@@ -412,7 +468,8 @@ export interface EventWriteView<T> {
  * A read-only view over one committed finite-state-machine value.
  */
 export interface MachineReadView<M extends Machine.StateMachine.Any = Machine.StateMachine.Any> {
-  get(): Machine.StateMachine.Value<M>
+  /** The committed value; `undefined` only for a sub-state whose parent is in another state. */
+  get(): Machine.CurrentValue<M>
   is(value: Machine.StateMachine.Value<M>): boolean
 }
 
@@ -421,20 +478,31 @@ export interface MachineReadView<M extends Machine.StateMachine.Any = Machine.St
  */
 export interface NextMachineWriteView<M extends Machine.StateMachine.Any = Machine.StateMachine.Any> {
   getPending(): Machine.StateMachine.Value<M> | undefined
-  set(value: Machine.StateMachine.Value<M>): void
-  setIfChanged(value: Machine.StateMachine.Value<M>): void
+  /**
+   * Queues `value`, committed at the next `applyStateTransitions(...)`. For a
+   * sub-state it returns a `Result` that fails with `SubStateInactive` (and
+   * queues nothing) while the parent is in another state.
+   */
+  set(value: Machine.StateMachine.Value<M>): Machine.SetResult<M>
+  /** Like `set`, but committing the current value again is skipped (no exit or enter schedules). */
+  setIfChanged(value: Machine.StateMachine.Value<M>): Machine.SetResult<M>
   reset(): void
 }
 
 /**
  * A read-only view over the last applied transition payload for one machine.
+ *
+ * Only meaningful inside transition schedules, so it is only given to
+ * systems that declare `transitions: { x: Game.System.transition(M) }`.
  */
 export interface TransitionReadView<M extends Machine.StateMachine.Any = Machine.StateMachine.Any> {
   get(): Machine.TransitionSnapshot<M>
 }
 
 /**
- * A read-only event stream of committed machine transitions.
+ * A read-only event stream of committed machine transitions, published by
+ * `applyStateTransitions(...)`. Like events, each reader sees the
+ * transitions published since its own previous run.
  */
 export interface TransitionEventReadView<M extends Machine.StateMachine.Any = Machine.StateMachine.Any> {
   all(): ReadonlyArray<Machine.TransitionSnapshot<M>>
@@ -847,6 +915,7 @@ export type AnySystemSpec = SystemSpec<any, any, any>
 type ResourceContext<Spec extends AnySystemSpec> = {
   readonly [K in keyof Spec["resources"]]:
     Spec["resources"][K] extends ResourceRead<infer D> ? ResourceReadView<Descriptor.Value<D>>
+    : Spec["resources"][K] extends ResourceChanged<infer D> ? ResourceChangedView<Descriptor.Value<D>>
     : Spec["resources"][K] extends ResourceWrite<infer D> ? ResourceWriteView<D>
     : never
 }