@typeonce/ritmo 0.7.0 → 0.9.0

package/src/Debug.ts

@@ -35,7 +35,7 @@
  *
  * @example
  * ```ts
- * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } })
+ * const runtime = Game.Runtime.make({ services, resources, debug: { hostClock: HostClock.standard } }).value
  * runtime.debug.nameSchedules({ setup: setupSchedule, update: updateSchedule })
  *
  * const stop = runtime.debug.observe((event) => {
@@ -116,6 +116,10 @@ export type Storage = "constructed" | "transient" | "plain"
 export interface ComponentDescription {
   readonly name: string
   readonly storage: Storage
+  /** Declared `immutable: true`: queries only read it, `commands.insert` replaces it. */
+  readonly immutable: boolean
+  /** The components it directly requires (`Schema.requires`). */
+  readonly requires: ReadonlyArray<string>
 }
 
 export interface ResourceDescription {
@@ -136,8 +140,22 @@ export interface RelationDescription {
 export interface MachineDescription {
   readonly name: string
   readonly states: ReadonlyArray<Machine.StateValue>
-  /** The committed value, or `undefined` when the runtime does not provide the machine. */
+  /**
+   * The committed value, or `undefined` when the runtime does not provide the
+   * machine, or when it is a sub-state whose parent is in another state.
+   */
   readonly current: Machine.StateValue | undefined
+  /** Whether the runtime was given an initial value for the machine. */
+  readonly provided: boolean
+  /** For a sub-state, where it exists, as `Parent=state`. */
+  readonly within: string | undefined
+}
+
+/** An entity scope and the state changes that despawn it (`Game.EntityScope(name, { despawnOnExit, despawnOnEnter })`). */
+export interface ScopeDescription {
+  readonly name: string
+  /** Triggers as `onExit(Flow=Playing)` / `onEnter(Flow=Menu)`; empty when only `commands.despawnScope` ends it. */
+  readonly despawnOn: ReadonlyArray<string>
 }
 
 export interface ServiceDescription {
@@ -155,6 +173,8 @@ export interface QueryDescription {
   readonly without: ReadonlyArray<string>
   readonly added: ReadonlyArray<string>
   readonly changed: ReadonlyArray<string>
+  /** One entry per `anyOf` filter: the components of its `added` and `changed` members. */
+  readonly anyOf: ReadonlyArray<{ readonly added: ReadonlyArray<string>; readonly changed: ReadonlyArray<string> }>
   /** Relation filters and reads, for example `with ChildOf` or `read Children`. */
   readonly relations: ReadonlyArray<string>
 }
@@ -165,7 +185,8 @@ export interface SystemDescription {
   /** Where the system runs, as `schedule#step`. */
   readonly placements: ReadonlyArray<string>
   readonly queries: ReadonlyArray<QueryDescription>
-  readonly resources: { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
+  /** Resource reads and writes. `changed` lists the reads declared with `changedResource` (also in `reads`). */
+  readonly resources: { readonly reads: ReadonlyArray<string>; readonly changed: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
   readonly events: { readonly reads: ReadonlyArray<string>; readonly writes: ReadonlyArray<string> }
   readonly machines: {
     readonly reads: ReadonlyArray<string>
@@ -185,7 +206,11 @@ export interface SystemDescription {
    * names for despawnsScope, relation names for relates.
    */
   readonly commands: CommandPermissions
-  /** Run conditions, rendered, for example `stateChanged(Game/Flow)`. */
+  /**
+   * Run conditions, rendered, for example `stateChanged(Game/Flow)`. A system
+   * placed under several `Schedule.when` / `pauseWhen` groups is described
+   * once, with the conditions of every placement.
+   */
   readonly when: ReadonlyArray<string>
   /** Pause conditions, rendered: while one fails the system waits and holds its stream entries. */
   readonly pauseWhen: ReadonlyArray<string>
@@ -217,11 +242,19 @@ export interface ScheduleDescription {
  * A finding about the described schedules. `warning` is almost certainly a
  * bug; `info` is worth a look but can be intentional.
  *
- * Most lints read declarations only. Two also use what the runtime has seen
- * so far: events sent with `runtime.send(...)` count as written, and
+ * Most lints read declarations only. Some also use what the runtime has seen
+ * so far: events sent with `runtime.send(...)` count as written,
  * `relation-failure-never-read` fires for a relation that applied commands
  * have tried to relate or reorder (which can fail) while no described system
- * reads its failures, so describe after the game has run for a while.
+ * reads its failures, and `requirement-violated` lists commands skipped
+ * because they would have broken a `Schema.requires` requirement,
+ * `next-state-replaced` lists next states one system queued and another
+ * replaced with a different value before the marker (the last wins),
+ * `stale-target` lists `despawn` / `remove` commands given a `SpawnedId`
+ * kept from an earlier run (skipped), `stream-loss-unread` lists stream
+ * readers that never check `lagged()` and lost entries (or are paused), so
+ * describe after the game has run for a while. `scope-trigger-never-applied`
+ * also reads which machines the runtime provides.
  */
 export interface Lint {
   readonly severity: "warning" | "info"
@@ -230,10 +263,16 @@ export interface Lint {
     | "relation-failure-never-read"
     | "event-never-written"
     | "next-state-never-applied"
+    | "resource-changed-never-written"
     | "component-never-read"
     | "read-before-write"
     | "this-tick-order"
     | "command-permission-unused"
+    | "requirement-violated"
+    | "next-state-replaced"
+    | "stale-target"
+    | "stream-loss-unread"
+    | "scope-trigger-never-applied"
   readonly message: string
   readonly subject: string
   /** What to change to resolve it (or, for `info`, when it is fine as it is). */
@@ -254,6 +293,8 @@ export interface Description {
   readonly events: ReadonlyArray<{ readonly name: string }>
   readonly relations: ReadonlyArray<RelationDescription>
   readonly machines: ReadonlyArray<MachineDescription>
+  /** Scopes defined through the game, in definition order. */
+  readonly scopes: ReadonlyArray<ScopeDescription>
   readonly services: ReadonlyArray<ServiceDescription>
   readonly schedules: ReadonlyArray<ScheduleDescription>
   readonly systems: ReadonlyArray<SystemDescription>
@@ -393,6 +434,78 @@ export type Effect =
   | { readonly kind: "relate"; readonly entity: number; readonly relation: string; readonly target: number }
   | { readonly kind: "unrelate"; readonly entity: number; readonly relation: string }
   | { readonly kind: "relationFailure"; readonly entity: number; readonly relation: string; readonly error: string }
+  /** A command skipped because it would leave `component` without `missing` (`Schema.requires`). */
+  | {
+      readonly kind: "requirementViolated"
+      readonly entity: number
+      readonly command: RequirementViolation["command"]
+      readonly component: string
+      readonly missing: string
+    }
+  /** A `despawn` / `remove` skipped because it was given a `SpawnedId` from an earlier run. */
+  | { readonly kind: "staleTarget"; readonly entity: number; readonly command: StaleTarget["command"] }
+
+/**
+ * A next state one system queued and another replaced with a different value
+ * before the same `applyStateTransitions(...)`: the `next-state-replaced`
+ * lint. Only the last value is committed.
+ */
+export interface NextStateReplacement {
+  readonly machine: string
+  readonly replaced: { readonly system: string; readonly value: Machine.StateValue }
+  readonly by: { readonly system: string; readonly value: Machine.StateValue }
+  /** How many times it happened. */
+  readonly count: number
+}
+
+/**
+ * Commands of one system skipped because applying them would have left a
+ * component without one it requires (`Schema.requires`): the
+ * `requirement-violated` lint.
+ */
+export interface RequirementViolation {
+  readonly system: string
+  readonly command: "spawn" | "insert" | "remove"
+  /** The requirer. */
+  readonly component: string
+  /** The required component it would have lacked. */
+  readonly missing: string
+  /** The last entity it happened to. */
+  readonly entity: number
+  /** How many commands were skipped this way. */
+  readonly count: number
+}
+
+/**
+ * Commands of one system skipped because they were given a `SpawnedId` kept
+ * from an earlier run, whose entity may since have been despawned and its id
+ * reused: the `stale-target` lint.
+ */
+export interface StaleTarget {
+  readonly system: string
+  readonly command: "despawn" | "remove"
+  /** The last entity id it happened to. */
+  readonly entity: number
+  /** How many commands were skipped this way. */
+  readonly count: number
+}
+
+/**
+ * One system's reads of one stream (events, transition events, removed,
+ * despawned, relation failures) on a debug runtime: the
+ * `stream-loss-unread` lint.
+ */
+export interface StreamLoss {
+  readonly system: string
+  /** The stream, as `events Hit`, `removed Sprite`, `despawned`, ... */
+  readonly stream: string
+  /** Runs that read it after entries were dropped before they were read. */
+  readonly lostRuns: number
+  /** Whether the system called `lagged()` on it. */
+  readonly checksLagged: boolean
+  /** Whether the system has `pauseWhen` conditions (a long pause can drop entries). */
+  readonly paused: boolean
+}
 
 export interface AppliedCommand {
   readonly tag: string
@@ -486,8 +599,10 @@ export interface TransitionEvent {
   readonly tick: number
   readonly schedule: string
   readonly machine: string
-  readonly from: Machine.StateValue
-  readonly to: Machine.StateValue
+  /** `undefined` when a sub-state starts existing (its parent entered its state). */
+  readonly from: Machine.StateValue | undefined
+  /** `undefined` when a sub-state stops existing (its parent left its state). */
+  readonly to: Machine.StateValue | undefined
   /**
    * `applied` committed the new value; `unchanged` was a `setIfChanged` to the
    * current value; `failed` stopped in an exit or transition schedule and was
@@ -572,9 +687,3 @@ export interface Option {
 export interface Member<S extends Schema.Any, Root> {
   readonly debug: Handle<S, Root>
 }
-
-/** Resolves the extra runtime member for a `debug` option type. */
-export type MemberFor<Enabled, S extends Schema.Any, Root> =
-  [Enabled] extends [true] ? Member<S, Root>
-  : [Enabled] extends [false | undefined] ? {}
-  : Partial<Member<S, Root>>

package/src/Descriptor.ts

@@ -166,6 +166,44 @@ export interface TransientDescriptor<
   readonly transient: true
 }
 
+/**
+ * Marks a component that is never edited in place: `Game.Query.write(...)`
+ * rejects it, and the only way to change its value is to replace it with
+ * `commands.insert(...)` (applied at `applyDeferred()`, seen by
+ * `Game.Query.changed(...)`).
+ */
+export interface Immutable {
+  readonly immutable: true
+}
+
+/**
+ * Options of the component descriptor constructors (`Component`,
+ * `ConstructedComponent`, `TransientComponent`).
+ */
+export interface ComponentOptions {
+  /**
+   * `true` for data that says what an entity is (a kind, a team, a tile) and
+   * is replaced, never edited: queries can only read it, and
+   * `commands.insert(...)` replaces it. Leave it out for state that systems
+   * update every frame.
+   */
+  readonly immutable?: true
+}
+
+/** The descriptor a component constructor returns for `Options`: `D`, plus `Immutable` when `immutable: true`. */
+export type WithComponentOptions<D, Options extends ComponentOptions> =
+  Options extends { readonly immutable: true } ? D & Immutable : D
+
+const applyComponentOptions = <D extends object>(descriptor: D, options: ComponentOptions | undefined): D =>
+  options?.immutable === true ? { ...descriptor, immutable: true } : descriptor
+
+/**
+ * Whether a component descriptor was declared `immutable: true` (readable by
+ * queries, replaced only with `commands.insert(...)`).
+ */
+export const isImmutable = (descriptor: Descriptor.Any): descriptor is Descriptor.Any & Immutable =>
+  "immutable" in descriptor && descriptor.immutable === true
+
 /**
  * Type-level helpers for working with descriptors.
  */
@@ -242,6 +280,22 @@ const makeConstructedDescriptor = <
     [descriptorConstruction]: constructor
   }) as ConstructedDescriptor<Kind, Name, Value, Raw, Error>
 
+/**
+ * The message naming why `Value` cannot be the value of a descriptor of
+ * `Kind`, or `never` when it can. `any` turns off every check on the
+ * descriptor's reads and writes, and `never` erases the fragment it is listed in.
+ */
+type Article<Kind extends string> = Kind extends "event" ? "an" : "a"
+
+type ValueRejection<Kind extends string, Value> = 0 extends 1 & Value
+  ? `${Article<Kind>} ${Kind} value cannot be \`any\`: give it a type (use \`unknown\` for a value you never read)`
+  : [Value] extends [never] ? `${Article<Kind>} ${Kind} value cannot be \`never\`: give it a type (use \`{}\` for a marker)`
+  : never
+
+/** `Make`, or, when `Value` is rejected, a function whose only parameter is the message. */
+type CheckedValue<Kind extends string, Value, Make> = [ValueRejection<Kind, Value>] extends [never] ? Make
+  : (name: ValueRejection<Kind, Value>) => never
+
 /**
  * Defines a component descriptor.
  *
@@ -251,14 +305,22 @@ const makeConstructedDescriptor = <
  * Components are the only descriptor kind that can be queried directly with
  * `Game.Query.read(...)`, `write(...)`, or `optional(...)`.
  *
+ * The value is a real type: `any` and `never` do not compile (here and in
+ * every other descriptor constructor). Use `unknown` for a value no system
+ * reads, and `Descriptor.Tag` for a marker.
+ *
  * @example
  * ```ts
  * const Position = Descriptor.Component<{ x: number; y: number }>()("Position")
+ * // What an entity is, replaced with commands.insert and never written by a query:
+ * const EnemyKind = Descriptor.Component<"grunt" | "boss">()("EnemyKind", { immutable: true })
  * ```
  */
-export const Component = <Value>() => <const Name extends string>(
-  name: Name
-): Descriptor<"component", Name, Value> => makeDescriptor("component", name)
+export const Component = <Value>(): CheckedValue<"component", Value, <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+) => WithComponentOptions<Descriptor<"component", Name, Value>, Options>> =>
+  ((name: string, options?: ComponentOptions) => applyComponentOptions(makeDescriptor("component", name), options)) as never
 
 /**
  * Defines a component descriptor that also knows how to validate raw values.
@@ -275,10 +337,11 @@ export const Component = <Value>() => <const Name extends string>(
  */
 export const ConstructedComponent = <Value, Raw, Error, Constructor extends {} = {}>(
   constructor: ResultConstructor<Value, Raw, Error> & Constructor
-) => <const Name extends string>(
-  name: Name
-): ConstructedFor<"component", Name, Value, Raw, Error, Constructor> =>
-  makeConstructedDescriptor("component", name, constructor) as ConstructedFor<"component", Name, Value, Raw, Error, Constructor>
+) => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<ConstructedFor<"component", Name, Value, Raw, Error, Constructor>, Options> =>
+  applyComponentOptions(makeConstructedDescriptor("component", name, constructor), options) as WithComponentOptions<ConstructedFor<"component", Name, Value, Raw, Error, Constructor>, Options>
 
 /**
  * Defines a component descriptor that snapshots skip.
@@ -291,9 +354,11 @@ export const ConstructedComponent = <Value, Raw, Error, Constructor extends {} =
  * const SpriteRef = Descriptor.TransientComponent<{ frame: number }>()("SpriteRef")
  * ```
  */
-export const TransientComponent = <Value>() => <const Name extends string>(
-  name: Name
-): TransientDescriptor<"component", Name, Value> => makeTransientDescriptor("component", name)
+export const TransientComponent = <Value>(): CheckedValue<"component", Value, <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+) => WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options>> =>
+  ((name: string, options?: ComponentOptions) => applyComponentOptions(makeTransientDescriptor("component", name), options)) as never
 
 /**
  * Defines a marker component: no data, only presence (`[Player, {}]`).
@@ -401,9 +466,9 @@ export const isEntityState = (
  * const Score = Descriptor.Resource<number>()("Score")
  * ```
  */
-export const Resource = <Value>() => <const Name extends string>(
+export const Resource = <Value>(): CheckedValue<"resource", Value, <const Name extends string>(
   name: Name
-): Descriptor<"resource", Name, Value> => makeDescriptor("resource", name)
+) => Descriptor<"resource", Name, Value>> => ((name: string) => makeDescriptor("resource", name)) as never
 
 /**
  * Defines a resource descriptor that also knows how to validate raw values.
@@ -424,9 +489,9 @@ export const ConstructedResource = <Value, Raw, Error, Constructor extends {} =
  * const DeltaTime = Descriptor.TransientResource<number>()("DeltaTime")
  * ```
  */
-export const TransientResource = <Value>() => <const Name extends string>(
+export const TransientResource = <Value>(): CheckedValue<"resource", Value, <const Name extends string>(
   name: Name
-): TransientDescriptor<"resource", Name, Value> => makeTransientDescriptor("resource", name)
+) => TransientDescriptor<"resource", Name, Value>> => ((name: string) => makeTransientDescriptor("resource", name)) as never
 
 /**
  * Defines an event descriptor.
@@ -446,9 +511,9 @@ export const TransientResource = <Value>() => <const Name extends string>(
  * const Hit = Descriptor.Event<{ target: number; amount: number }>()("Hit")
  * ```
  */
-export const Event = <Value>() => <const Name extends string>(
+export const Event = <Value>(): CheckedValue<"event", Value, <const Name extends string>(
   name: Name
-): Descriptor<"event", Name, Value> => makeDescriptor("event", name)
+) => Descriptor<"event", Name, Value>> => ((name: string) => makeDescriptor("event", name)) as never
 
 /**
  * Defines a service descriptor.
@@ -467,9 +532,9 @@ export const Event = <Value>() => <const Name extends string>(
  * const Logger = Descriptor.Service<{ log: (message: string) => void }>()("Logger")
  * ```
  */
-export const Service = <Value>() => <const Name extends string>(
+export const Service = <Value>(): CheckedValue<"service", Value, <const Name extends string>(
   name: Name
-): Descriptor<"service", Name, Value> => makeDescriptor("service", name)
+) => Descriptor<"service", Name, Value>> => ((name: string) => makeDescriptor("service", name)) as never
 
 /**
  * Checks whether one descriptor is transient (skipped by snapshots).
@@ -580,7 +645,10 @@ export function constructorOf<D extends Descriptor.Any>(
  * `Game.EntityScope(...)` instead when entities only share a lifetime (a
  * level, a menu) and need no tree, order, or traversal.
  */
-export const Hierarchy = RelationModule.Hierarchy
+export const Hierarchy = <const Name extends string, const RelatedName extends string>(
+  name: Name,
+  relatedName: RelatedName
+) => makePair("hierarchy", name, relatedName)
 
 /**
  * Defines a general relationship pair with direct edges and reverse lookups.
@@ -589,7 +657,10 @@ export const Hierarchy = RelationModule.Hierarchy
  * reverse lookup, but not hierarchy-only behavior such as tree traversal or
  * child reordering.
  */
-export const Relation = RelationModule.Relation
+export const Relation = <const Name extends string, const RelatedName extends string>(
+  name: Name,
+  relatedName: RelatedName
+) => makePair("relation", name, relatedName)
 import * as DecodeModule from "./Decode.ts"
-import * as RelationModule from "./Relation.ts"
+import { makePair } from "./internal/relations.ts"
 import * as ResultModule from "./Result.ts"

package/src/Entity.ts

@@ -131,7 +131,7 @@ export namespace Handle {
  * Drafts exist before the command queue is flushed. This is the place where the
  * API can safely carry exact structural information.
  */
-export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof, Root = unknown> {
+export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof, Root = unknown, out Relates = never> {
   /**
    * Runtime tag for debugging and pattern matching.
    */
@@ -156,6 +156,11 @@ export interface EntityDraft<S extends Schema.Any, out P extends ComponentProof,
    * Staged relationship edges attached to the entity before spawn.
    */
   readonly relations: ReadonlyArray<StagedRelation<S, Root>>
+  /**
+   * The relations `Game.Command.relate(...)` staged on this draft: spawning
+   * it needs them in the system's `Game.System.relates(...)`. Type-level only.
+   */
+  readonly __relates?: (_: never) => Relates
 }
 
 /**
@@ -168,17 +173,25 @@ export type StagedComponent = readonly [Descriptor<"component", string, any>, un
  *
  * Query execution is the main source of `EntityRef` values.
  */
-export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown, out Proves = unknown> {
+export interface EntityRef<S extends Schema.Any, out P extends ComponentProof, Root = unknown, in Proves = never, in Lacks = never> {
   /**
    * Runtime tag for debugging and pattern matching.
    */
   readonly kind: "EntityRef"
   /**
    * The component descriptors the query that produced this ref proves (its
-   * required slots and `with`): what `commands.despawn` checks against the
-   * system's `despawns` permission. Type-level only.
+   * required slots and `with`): what `commands.despawn`, `insert`, and
+   * `remove` check. Type-level only. Contravariant on purpose: a ref proving
+   * more is a subtype, so a union of refs (`cond ? a.entity : b.entity`)
+   * keeps only what both prove.
+   */
+  readonly __proves?: (_: Proves) => void
+  /**
+   * The component descriptors the producing query proves absent (its
+   * `without`): what `commands.remove` checks against `Schema.requires`.
+   * Type-level only.
    */
-  readonly __proves?: (_: never) => Proves
+  readonly __lacks?: (_: Lacks) => void
   /**
    * The schema-bound entity identity.
    */
@@ -201,14 +214,17 @@ export interface EntityMut<
   out P extends ComponentProof,
   out W extends ComponentProof,
   Root = unknown,
-  out Proves = unknown
+  in Proves = never,
+  in Lacks = never
 > {
   /**
    * Runtime tag for debugging and pattern matching.
    */
   readonly kind: "EntityMut"
   /** The component descriptors the producing query proves; see `EntityRef`. */
-  readonly __proves?: (_: never) => Proves
+  readonly __proves?: (_: Proves) => void
+  /** The component descriptors the producing query proves absent; see `EntityRef`. */
+  readonly __lacks?: (_: Lacks) => void
   /**
    * The schema-bound entity identity.
    */

package/src/EntityScope.ts

@@ -13,6 +13,11 @@
  * parent-child tree: ordered children, `lookup.parent` / `descendants`
  * traversal, and children despawned with their parent.
  *
+ * A scope whose lifetime is a game state declares it:
+ * `Game.EntityScope(name, { despawnOnExit: [Flow, "Playing"] })` despawns
+ * every member when `applyStateTransitions(...)` commits that state change,
+ * with no system, permission, or marker to place.
+ *
  * @module EntityScope
  * @docGroup core
  */
@@ -25,9 +30,21 @@ export interface EntityScope<
   readonly kind: "entityScope"
   readonly name: Name
   readonly key: symbol
+  /** State changes that despawn every member, applied by `applyStateTransitions(...)`. */
+  readonly despawnOn: ReadonlyArray<Trigger>
   readonly __schemaRoot?: Root | undefined
 }
 
+/**
+ * One state change that despawns a scope: leaving (`exit`) or entering
+ * (`enter`) `state` of `machine`.
+ */
+export interface Trigger {
+  readonly phase: "enter" | "exit"
+  readonly machine: { readonly key: symbol; readonly name: string }
+  readonly state: string | number
+}
+
 /** Type-level helpers for entity scopes. */
 export namespace EntityScope {
   export type Any = EntityScope<string, any>
@@ -42,11 +59,13 @@ export namespace EntityScope {
  * branded to that game's root.
  */
 export const make = <const Name extends string, Root = unknown>(
-  name: Name
+  name: Name,
+  despawnOn: ReadonlyArray<Trigger> = []
 ): EntityScope<Name, Root> => ({
   kind: "entityScope",
   name,
-  key: keyOf(name)
+  key: keyOf(name),
+  despawnOn
 })
 
 const keyPrefix = "ritmo/entityScope/"