@typeonce/ritmo 0.7.0 → 0.9.0

package/src/Snapshot.ts

@@ -24,10 +24,17 @@
  *
  * Restoring despawns every current entity and spawns the saved ones with their
  * original ids, so change detection and renderer sync see a restore as normal
- * despawns and spawns. Pending commands and events are dropped. Transient
+ * despawns and spawns. Pending commands and events emitted by systems are
+ * dropped; events the host sent with `runtime.send` and no system has read
+ * yet are kept, since they are input that has not been handled. Transient
  * components are absent from restored entities; transient resources keep their
  * current value.
  *
+ * When the game's save format changes, give the runtime its migrations
+ * (`Game.Runtime.make({ saves: Snapshot.migrations(...) })`): saves carry a
+ * `gameVersion`, and `restore` upgrades older ones step by step before
+ * validating them.
+ *
  * @module Snapshot
  * @docGroup runtime
  *
@@ -90,6 +97,12 @@ export const version = 2
 
 export interface WorldSnapshot {
   readonly version: typeof version
+  /**
+   * The game's own save version: the last `Snapshot.migration` the runtime
+   * that wrote it was given (0 without migrations, and for saves written
+   * before game versions existed).
+   */
+  readonly gameVersion: number
   /** The next id the runtime will allocate. */
   readonly nextEntity: number
   readonly entities: ReadonlyArray<EntitySnapshot>
@@ -113,15 +126,23 @@ export interface WorldSnapshot {
 export type RestoreError =
   | { readonly _tag: "InvalidSnapshot"; readonly path: string }
   | { readonly _tag: "UnsupportedVersion"; readonly version: unknown }
+  /** A save written by a newer game than this runtime's migrations reach. */
+  | { readonly _tag: "NewerGameVersion"; readonly gameVersion: number; readonly latest: number }
   | { 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 name that no `Game.EntityScope(...)` of this game defines. */
+  | { readonly _tag: "UnknownScope"; readonly name: string }
   /** A scope member that is not a saved entity, or is already in another scope. */
   | { readonly _tag: "InvalidScope"; readonly name: string; readonly entityId: number }
   | { readonly _tag: "UnvalidatedDescriptor"; readonly name: string }
@@ -141,6 +162,8 @@ const invalid = (path: string) => Result.failure<RestoreError>({ _tag: "InvalidS
 export const parse = (data: unknown): Result.Result<WorldSnapshot, RestoreError> => {
   if (!isRecord(data)) return invalid("$")
   if (data["version"] !== version) return Result.failure({ _tag: "UnsupportedVersion", version: data["version"] })
+  const gameVersion = data["gameVersion"] ?? 0
+  if (typeof gameVersion !== "number" || !Number.isSafeInteger(gameVersion) || gameVersion < 0) return invalid("$.gameVersion")
   if (!isEntityId(data["nextEntity"])) return invalid("$.nextEntity")
   const entities = data["entities"]
   if (!Array.isArray(entities)) return invalid("$.entities")
@@ -172,5 +195,74 @@ export const parse = (data: unknown): Result.Result<WorldSnapshot, RestoreError>
   for (const [name, members] of Object.entries(scopes)) {
     if (!Array.isArray(members) || !members.every(isEntityId)) return invalid(`$.scopes.${name}`)
   }
-  return Result.success(data as unknown as WorldSnapshot)
+  return Result.success({ ...data, gameVersion } as unknown as WorldSnapshot)
+}
+
+/**
+ * One step of a game's save format: turns a save of version `to - 1` into
+ * version `to`. A pure function on the save's plain data, tested like one.
+ */
+export interface Migration<To extends number = number> {
+  readonly to: To
+  readonly migrate: (save: WorldSnapshot) => WorldSnapshot
+}
+
+/** A game's save migrations, given to `Game.Runtime.make({ saves })`. Built with {@link migrations}. */
+export interface Migrations<Latest extends number = number> {
+  readonly kind: "SnapshotMigrations"
+  /** The game version `snapshot()` writes. */
+  readonly latest: Latest
+  readonly steps: ReadonlyArray<Migration>
+}
+
+/**
+ * Declares the step that upgrades saves to game version `to` (from `to - 1`).
+ *
+ * @example
+ * ```ts
+ * Snapshot.migration(2, (save) => ({ ...save, resources: { ...save.resources, "Town/Gold": 0 } }))
+ * ```
+ */
+export const migration = <const To extends number>(to: To, migrate: (save: WorldSnapshot) => WorldSnapshot): Migration<To> => ({ to, migrate })
+
+type Last<Steps> = Steps extends readonly [...Array<unknown>, infer L extends Migration] ? L["to"] : number
+
+/** `unknown` when the steps are numbered 1, 2, 3, ... in order; otherwise the message naming the misplaced one. */
+type Consecutive<Steps, Count extends Array<0> = []> =
+  Steps extends readonly [infer Head extends Migration, ...infer Tail]
+    ? number extends Head["to"] ? unknown
+    : Head["to"] extends [...Count, 0]["length"] ? Consecutive<Tail, [...Count, 0]>
+    : { readonly __fixMigrations__: `migration ${Head["to"]} is listed where migration ${[...Count, 0]["length"]} belongs: number migrations 1, 2, 3, ... in order` }
+    : unknown
+
+/**
+ * A game's save migrations, numbered 1, 2, 3, ... in order (checked at
+ * compile time for literal numbers, and at runtime). Pass them to
+ * `Game.Runtime.make({ saves })`: `snapshot()` then writes the last number as
+ * the save's `gameVersion`, and `restore(data)` runs every step after the
+ * save's version, in order, before validating it as usual. A save newer than
+ * the last step fails with `NewerGameVersion`. Use it instead of editing raw
+ * save data before `restore`.
+ *
+ * @example
+ * ```ts
+ * const runtime = Game.Runtime.make({
+ *   services,
+ *   saves: Snapshot.migrations(
+ *     Snapshot.migration(1, (save) => ({ ...save, scopes: {} })),
+ *     Snapshot.migration(2, renameGold)
+ *   )
+ * }).value
+ * runtime.restore(raw)
+ * ```
+ */
+export const migrations = <const Steps extends readonly [Migration, ...Array<Migration>]>(
+  ...steps: Steps & Consecutive<Steps>
+): Migrations<Last<Steps>> => {
+  steps.forEach((step, index) => {
+    if (step.to !== index + 1) {
+      throw new Error(`migration ${step.to} is listed where migration ${index + 1} belongs: number migrations 1, 2, 3, ... in order`)
+    }
+  })
+  return { kind: "SnapshotMigrations", latest: steps.length as Last<Steps>, steps }
 }

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.
  */
@@ -405,14 +461,16 @@ export interface EventReadView<T> {
  * A writable event stream view.
  */
 export interface EventWriteView<T> {
-  emit(value: T): void
+  /** Publishes one event. Takes the readonly shape reads return, so a read event can be emitted again. */
+  emit(value: import("./Query.ts").ReadonlyValue<T>): void
 }
 
 /**
  * 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 +479,38 @@ 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.
+   *
+   * One value is queued per machine: a later `set` before the marker
+   * replaces an earlier one. A `set` from a transition schedule (`onEnter`,
+   * `onExit`, `onTransition`) is committed at the following marker, while a
+   * value queued before the current marker still commits at it. A sub-state
+   * value set while its parent is still in its state but leaves it at the
+   * same marker returns ok and is dropped with the sub-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>>
@@ -593,10 +669,47 @@ export interface RelationFailureReadView<
  * A runtime query handle exposed to system implementations.
  *
  * The handle is already typed from the query spec, so iterating it returns
- * strongly typed entity proofs and cells.
+ * strongly typed entity proofs and cells. A query with `added` / `changed`
+ * filters only iterates (`each`, `singleOptional`): its lookups would fail
+ * for every entity that did not change since this system's previous run, so
+ * declare a second query without filters to resolve entities.
  */
-export interface QueryHandle<S extends Schema.Any, Q extends Query.Any> {
+export type QueryHandle<S extends Schema.Any, Q extends Query.Any> =
+  & QueryIteration<S, Q>
+  & (Q["filters"] extends readonly [] ? QueryLookups<S, Q> : FilteredQueryLookups)
+
+/** What every query handle has: iteration over its current matches. */
+export interface QueryIteration<S extends Schema.Any, Q extends Query.Any> {
   each(): ReadonlyArray<QueryMatch<S, Q>>
+  /**
+   * Returns a single match when zero or one entity satisfies the query.
+   *
+   * Use this when absence is acceptable but multiplicity is still a bug. Zero
+   * matches return `ok: true` with `value: undefined`; multiple matches remain
+   * an explicit `MultipleEntities` failure.
+   *
+   * @example
+   * ```ts
+   * const player = queries.player.singleOptional()
+   * if (!player.ok || !player.value) {
+   *   return
+   * }
+   *
+   * player.value.data.position.set({ x: 0, y: 0 })
+   * ```
+   */
+  singleOptional(): Result.Result<QueryMatch<S, Q> | undefined, Query.MultipleEntitiesError>
+}
+
+type FilteredLookupMessage = "lookups need a query without added/changed filters: declare a second query for resolving entities"
+
+/** The lookups of a query with filters, each replaced by the message naming the fix. */
+export type FilteredQueryLookups = {
+  readonly [K in keyof QueryLookups<Schema.Any, Query.Any>]: (this: FilteredLookupMessage, ...args: ReadonlyArray<unknown>) => never
+}
+
+/** Lookups of one entity or one hierarchy through a query without `added` / `changed` filters. */
+export interface QueryLookups<S extends Schema.Any, Q extends Query.Any> {
   /**
    * Retrieves the match for one specific entity id when it satisfies the query.
    *
@@ -643,24 +756,6 @@ export interface QueryHandle<S extends Schema.Any, Q extends Query.Any> {
    * Returns a single match when exactly one entity satisfies the query.
    */
   single(): Result.Result<QueryMatch<S, Q>, Query.SingleError>
-  /**
-   * Returns a single match when zero or one entity satisfies the query.
-   *
-   * Use this when absence is acceptable but multiplicity is still a bug. Zero
-   * matches return `ok: true` with `value: undefined`; multiple matches remain
-   * an explicit `MultipleEntities` failure.
-   *
-   * @example
-   * ```ts
-   * const player = queries.player.singleOptional()
-   * if (!player.ok || !player.value) {
-   *   return
-   * }
-   *
-   * player.value.data.position.set({ x: 0, y: 0 })
-   * ```
-   */
-  singleOptional(): Result.Result<QueryMatch<S, Q> | undefined, Query.MultipleEntitiesError>
 }
 
 /**
@@ -791,10 +886,36 @@ export interface SystemAccessInput {
  */
 export type SystemAccessSpec = SystemAccessInput
 
-/** Rejects unknown system access categories at a bound constructor. */
+/** Rejects unknown system access categories, and redundant resource and event slots, at a bound constructor. */
 export type ExactAccess<Access extends SystemAccessInput> = Access & {
   readonly [Key in Exclude<keyof Access, keyof SystemAccessInput>]: never
-}
+} & RedundantSlotsFix<Access, "resources", "read"> & RedundantSlotsFix<Access, "events", never>
+
+type SlotOf<A> = A extends { readonly mode: infer Mode extends string; readonly descriptor: { readonly name: infer Name extends string } } ? readonly [Mode, Name] : never
+
+/**
+ * Slots of `Record` that repeat another slot: the same descriptor in the same
+ * mode, or in `ReadMode` next to any other slot of it (a write or changed
+ * view already reads).
+ */
+type RedundantSlots<Record, ReadMode extends string> = {
+  readonly [K in keyof Record]: SlotOf<Record[K]> extends readonly [infer Mode, infer Name]
+    ? [Extract<SlotOf<Omit<Record, K>[keyof Omit<Record, K>]>, readonly [Mode extends ReadMode ? string : Mode, Name]>] extends [never] ? never : K
+    : never
+}[keyof Record]
+
+type RedundantSlotsFix<Access, Category extends "resources" | "events", ReadMode extends string> =
+  Access extends { readonly [C in Category]?: infer Record }
+    ? [RedundantSlots<Record, ReadMode>] extends [never]
+      ? unknown
+      : {
+        readonly [C in Category]: {
+          readonly [K in RedundantSlots<Record, ReadMode>]: {
+            readonly __fixSystem__: `${K & string} repeats ${Category extends "resources" ? "a resource" : "an event"} another slot of this system declares: keep one slot (a write or changed view reads too)`
+          }
+        }
+      }
+    : unknown
 
 type AccessField<
   Access,
@@ -847,6 +968,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
 }

package/src/index.ts

@@ -33,6 +33,10 @@ export * as Entity from "./Entity.ts"
  * Entity lifetime scopes used by scene and level ownership patterns.
  */
 export * as EntityScope from "./EntityScope.ts"
+/**
+ * Fixed-step timing for any host: clamping, catch-up limits, interpolation.
+ */
+export * as FixedLoop from "./FixedLoop.ts"
 /**
  * The host's wall clock as an injected contract (`standard`, `test()`).
  */

package/src/internal/cells.ts

@@ -63,38 +63,64 @@ const withTransition = (cell: WriteCellBase<unknown>, component: string) => Obje
   }
 })
 
+/**
+ * A required slot is empty only when its match outlived the run that produced
+ * it: the entity was despawned, or lost the component. Reading would hand out
+ * the internal marker as a value, and writing would put the component back
+ * without the insert path, so both fail loudly instead.
+ */
+const staleMatch = (record: EntityRecord, ordinal: number): Error =>
+  new Error(
+    `${record.nameAt(ordinal)} was used through a query match after ${record.alive ? "its entity lost it" : "its entity was despawned"}: `
+    + "a match is valid during the system run that produced it; keep the entity id or a handle and resolve it again with queries.x.get(id) or queries.x.getHandle(handle)"
+  )
+
+
+/** Kept out of `get` so the hot read stays small enough to inline. */
+const staleRead = (record: EntityRecord, ordinal: number): never => {
+  throw staleMatch(record, ordinal)
+}
+
 class ComponentReadCell {
-  readonly record: EntityRecord
+  // The record's values array, held directly: one load per read instead of
+  // two pays for the stale check. Records never replace their array.
+  readonly values: Array<unknown>
   readonly ordinal: number
+  readonly record: EntityRecord
 
   constructor(record: EntityRecord, ordinal: number) {
-    this.record = record
+    this.values = record.values
     this.ordinal = ordinal
+    this.record = record
   }
 
   get(): unknown {
-    return this.record.values[this.ordinal]
+    const value = this.values[this.ordinal]
+    return value === ABSENT ? staleRead(this.record, this.ordinal) : value
   }
 }
 
 class ComponentWriteCell extends WriteCellBase<unknown> {
-  readonly record: EntityRecord
+  readonly values: Array<unknown>
   readonly ordinal: number
+  readonly record: EntityRecord
   readonly world: World
 
   constructor(record: EntityRecord, ordinal: number, world: World) {
     super()
-    this.record = record
+    this.values = record.values
     this.ordinal = ordinal
+    this.record = record
     this.world = world
   }
 
   get(): unknown {
-    return this.record.values[this.ordinal]
+    const value = this.values[this.ordinal]
+    return value === ABSENT ? staleRead(this.record, this.ordinal) : value
   }
 
   set(value: unknown): void {
-    this.world.setComponentValue(this.record, this.ordinal, value)
+    if (!this.world.setComponentValue(this.record, this.ordinal, value)) staleRead(this.record, this.ordinal)
   }
 }
 
@@ -115,6 +141,11 @@ class OptionalComponentCell {
   get(): unknown {
     return this.record.values[this.ordinal]
   }
+
+  value(): unknown {
+    const value = this.record.values[this.ordinal]
+    return value === ABSENT ? undefined : value
+  }
 }
 
 class StoreReadCell {
@@ -167,7 +198,7 @@ export const componentWrite = (
   return entityState === undefined ? constructed : withTransition(constructed, entityState)
 }
 
-export const componentOptional = (record: EntityRecord, ordinal: number): { readonly present: boolean; get(): unknown } =>
+export const componentOptional = (record: EntityRecord, ordinal: number): { readonly present: boolean; get(): unknown; value(): unknown } =>
   new OptionalComponentCell(record, ordinal)
 
 export const storeRead = (store: Map<symbol, unknown>, key: symbol): { get(): unknown } =>
@@ -198,9 +229,10 @@ export const derivedRead = <T>(read: () => T): { get(): T } => ({ get: read })
 export const derivedOptional = <T>(
   isPresent: () => boolean,
   read: () => T
-): { readonly present: boolean; get(): T } => ({
+): { readonly present: boolean; get(): T; value(): T | undefined } => ({
   get present() {
     return isPresent()
   },
-  get: read
+  get: read,
+  value: () => (isPresent() ? read() : undefined)
 })