@typeonce/ritmo 0.7.0 → 0.8.0

package/src/Debug.ts

@@ -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>
@@ -217,11 +238,14 @@ 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, 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 +254,13 @@ 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"
+    | "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 +281,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 +422,32 @@ 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
+    }
+
+/**
+ * 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
+}
 
 export interface AppliedCommand {
   readonly tag: string
@@ -486,8 +541,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

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.
  */
@@ -254,11 +292,15 @@ const makeConstructedDescriptor = <
  * @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>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<Descriptor<"component", Name, Value>, Options> =>
+  applyComponentOptions(makeDescriptor("component", name), options) as WithComponentOptions<Descriptor<"component", Name, Value>, Options>
 
 /**
  * Defines a component descriptor that also knows how to validate raw values.
@@ -275,10 +317,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 +334,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>() => <const Name extends string, const Options extends ComponentOptions = {}>(
+  name: Name,
+  options?: Options
+): WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options> =>
+  applyComponentOptions(makeTransientDescriptor("component", name), options) as WithComponentOptions<TransientDescriptor<"component", Name, Value>, Options>
 
 /**
  * Defines a marker component: no data, only presence (`[Player, {}]`).

package/src/Entity.ts

@@ -168,17 +168,23 @@ 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, out Proves = unknown, out 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.
    */
   readonly __proves?: (_: never) => Proves
+  /**
+   * The component descriptors the producing query proves absent (its
+   * `without`): what `commands.remove` checks against `Schema.requires`.
+   * Type-level only.
+   */
+  readonly __lacks?: (_: never) => Lacks
   /**
    * The schema-bound entity identity.
    */
@@ -201,7 +207,8 @@ export interface EntityMut<
   out P extends ComponentProof,
   out W extends ComponentProof,
   Root = unknown,
-  out Proves = unknown
+  out Proves = unknown,
+  out Lacks = never
 > {
   /**
    * Runtime tag for debugging and pattern matching.
@@ -209,6 +216,8 @@ export interface EntityMut<
   readonly kind: "EntityMut"
   /** The component descriptors the producing query proves; see `EntityRef`. */
   readonly __proves?: (_: never) => Proves
+  /** The component descriptors the producing query proves absent; see `EntityRef`. */
+  readonly __lacks?: (_: never) => Lacks
   /**
    * 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/"

package/src/Machine.ts

@@ -39,6 +39,7 @@
  */
 import type { AnyScheduleOrder, Schedule } from "./Schedule.ts"
 import * as Requirement from "./Requirement.ts"
+import type * as Result from "./Result.ts"
 import type { Schema } from "./Schema.ts"
 import type { SystemFailure } from "./System.ts"
 
@@ -56,60 +57,71 @@ export type StateValue = string | number
 export interface StateMachineDefinition<
   out Name extends string = string,
   out Values extends readonly [StateValue, ...StateValue[]] = readonly [StateValue, ...StateValue[]],
-  out Root = unknown
+  out Root = unknown,
+  out Parent = unknown
 > {
   readonly kind: "stateMachine"
   readonly name: Name
   readonly key: symbol
   readonly values: Values
+  /** For a sub-state: the machine and the state it exists in. */
+  readonly within?: SubStateParent | undefined
   readonly __schemaRoot?: Root | undefined
+  /** The machine a sub-state exists within; `unknown` for a top-level machine. */
+  readonly __parent?: (_: never) => Parent
+}
+
+/** Where a sub-state exists: while `machine` is in `state`. */
+export interface SubStateParent {
+  readonly machine: StateMachine.Any
+  readonly state: StateValue
 }
 
 /**
- * The runtime-visible transition payload for one machine.
+ * Whether `M` is a sub-state (declared with `within`): it has no value while
+ * its parent machine is in another state.
  */
-export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
-  readonly from: StateMachine.Value<M>
-  readonly to: StateMachine.Value<M>
-}
+export type IsSubState<M> =
+  M extends { readonly __parent?: (_: never) => infer Parent } ? unknown extends Parent ? false : true : false
 
 /**
- * A typed read-only view over the current committed state.
+ * The committed value of `M`. A sub-state has none (`undefined`) while its
+ * parent machine is not in the state it exists in; a top-level machine
+ * always has one.
  */
-export interface MachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-  get(): StateMachine.Value<M>
-  is(value: StateMachine.Value<M>): boolean
-}
+export type CurrentValue<M extends StateMachine.Any> =
+  IsSubState<M> extends true ? StateMachine.Value<M> | undefined : StateMachine.Value<M>
 
 /**
- * A typed queued-write view over the next state.
+ * Why queuing a sub-state's next value failed: its parent machine is not in
+ * the state the sub-state exists in, so there is nothing to change.
  */
-export interface NextMachineView<M extends StateMachineDefinition = StateMachineDefinition> {
-  getPending(): StateMachine.Value<M> | undefined
-  set(value: StateMachine.Value<M>): void
-  setIfChanged(value: StateMachine.Value<M>): void
-  reset(): void
+export interface SubStateInactive {
+  readonly _tag: "SubStateInactive"
+  /** The sub-state's name. */
+  readonly machine: string
+  /** The parent machine's name. */
+  readonly parent: string
+  /** The parent state the sub-state exists in. */
+  readonly requires: StateValue
 }
 
 /**
- * A typed read-only view over the last applied transition.
- *
- * This view is only meaningful inside transition schedules and is therefore
- * only exposed to systems that explicitly declare transition access.
+ * What `nextMachines.x.set(...)` returns: nothing for a top-level machine,
+ * and for a sub-state a `Result` that fails with `SubStateInactive` when its
+ * parent is in another state.
  */
-export interface TransitionView<M extends StateMachineDefinition = StateMachineDefinition> {
-  get(): TransitionSnapshot<M>
-}
+export type SetResult<M extends StateMachine.Any> =
+  IsSubState<M> extends true ? Result.Result<void, SubStateInactive> : void
 
 /**
- * A typed read-only stream of committed machine transition events.
- *
- * These snapshots are published by `applyStateTransitions(...)` when a
- * transition commits. Like events, each reader sees the transitions published
- * since its own previous run.
+ * The runtime-visible transition payload for one machine. For a sub-state,
+ * `from` is `undefined` when it starts existing (its parent entered its
+ * state) and `to` is `undefined` when it stops.
  */
-export interface TransitionEventView<M extends StateMachineDefinition = StateMachineDefinition> {
-  all(): ReadonlyArray<TransitionSnapshot<M>>
+export interface TransitionSnapshot<M extends StateMachineDefinition = StateMachineDefinition> {
+  readonly from: CurrentValue<M>
+  readonly to: CurrentValue<M>
 }
 
 /**
@@ -263,7 +275,7 @@ export interface TransitionScheduleDefinition<
  * Type-level and value-level helpers for finite-state machines.
  */
 export namespace StateMachine {
-  export type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown>
+  export type Any = StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], unknown, unknown>
   export type Value<M extends Any> = M["values"][number]
   export type Root<M extends Any> = M extends StateMachineDefinition<string, readonly [StateValue, ...StateValue[]], infer R> ? R : never
   export type AnyCondition<Root = unknown> = Condition<Root>
@@ -271,6 +283,23 @@ export namespace StateMachine {
     TransitionScheduleDefinition<S, Any, Requirement.Requirement, Root, SystemFailure>
 }
 
+/**
+ * `unknown` when `M` was defined by the game rooted at `Root`; otherwise a
+ * type naming the fix, so passing another game's machine fails with that
+ * message.
+ */
+export type SameGame<M, Root> =
+  M extends StateMachineDefinition<infer Name, readonly [StateValue, ...StateValue[]], infer MachineRoot>
+    ? [Root] extends [MachineRoot]
+      ? [MachineRoot] extends [Root]
+        ? unknown
+        : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`>
+      : ForeignMachine<`${Name} is a state machine of another game: use a machine defined with this game's Game.StateMachine(...)`>
+    : unknown
+
+/** The message type `SameGame` resolves to: a type error prints `Message`. */
+type ForeignMachine<Message extends string> = { readonly __foreignMachine__: Message }
+
 /** Extracts the machine token from one declared machine access slot. */
 type MachineFromAccess<Access> =
   Access extends { readonly machine: infer M extends StateMachine.Any } ? M : never
@@ -314,6 +343,9 @@ export type MachineNeedsFromConditions<C extends ReadonlyArray<Condition>> =
  *
  * Use `Descriptor.EntityState(...)` instead when every entity carries its own
  * state (per-entity, written immediately, no enter/exit schedules).
+ *
+ * Pass `within` for a sub-state: a machine that exists only while another
+ * machine is in one state (`Game.StateMachine(name, values, { within })`).
  */
 export const StateMachine = <
   const Name extends string,
@@ -321,12 +353,14 @@ export const StateMachine = <
   Root = unknown
 >(
   name: Name,
-  values: Values
+  values: Values,
+  within?: SubStateParent
 ): StateMachineDefinition<Name, Values, Root> => ({
   kind: "stateMachine",
   name,
   key: Symbol.for(`ritmo/stateMachine/${name}`),
-  values
+  values,
+  ...(within === undefined ? {} : { within })
 }) as StateMachineDefinition<Name, Values, Root>
 
 /**

package/src/Query.ts

@@ -69,6 +69,7 @@
  * Query authoring helpers for selecting components and declaring explicit filters.
  */
 import type { DecodeError } from "./Decode.ts"
+import * as DescriptorModule from "./Descriptor.ts"
 import type { Descriptor, EntityStateValue } from "./Descriptor.ts"
 import type { EntityId, EntityMut, EntityRef } from "./Entity.ts"
 import type * as Result from "./Result.ts"
@@ -179,10 +180,24 @@ export interface ChangedFilter<D extends ComponentDescriptor> {
   readonly descriptor: D
 }
 
-export type Filter<D extends ComponentDescriptor> =
+/** An `added` or `changed` filter: the filters `anyOf` combines. */
+export type LifecycleFilter<D extends ComponentDescriptor> =
   | AddedFilter<D>
   | ChangedFilter<D>
 
+/**
+ * A filter that matches entities passing at least one of its `added` /
+ * `changed` filters since the reading system's previous run.
+ */
+export interface AnyOfFilter<D extends ComponentDescriptor> {
+  readonly kind: "anyOf"
+  readonly filters: ReadonlyArray<LifecycleFilter<D>>
+}
+
+export type Filter<D extends ComponentDescriptor> =
+  | LifecycleFilter<D>
+  | AnyOfFilter<D>
+
 /**
  * Declares read-only access to a component in a query selection.
  *
@@ -203,11 +218,29 @@ export const read = <D extends ComponentDescriptor>(descriptor: D): ReadAccess<D
  * place. A write slot both requires component presence and exposes the slot as
  * a `WriteCell`, so mutation capability stays visible in the query spec rather
  * than appearing ad hoc in the loop body.
+ *
+ * Components declared `immutable: true` cannot be written: replace them with
+ * `commands.insert(...)` instead.
  */
-export const write = <D extends ComponentDescriptor>(descriptor: D): WriteAccess<D> => ({
-  mode: "write",
-  descriptor
-})
+export const write = <D extends ComponentDescriptor>(descriptor: D & Writable<D>): WriteAccess<D> => {
+  if (DescriptorModule.isImmutable(descriptor)) {
+    throw new Error(immutableMessage(descriptor.name))
+  }
+  return { mode: "write", descriptor }
+}
+
+const immutableMessage = (name: string) =>
+  `${name} is immutable: replace it with commands.insert(entity, Game.Command.entry(${name}, ...))`
+
+type NameOf<D> = D extends { readonly name: infer Name extends string } ? Name : never
+
+/**
+ * `unknown` for a component a query may write; for one declared
+ * `immutable: true`, an argument error naming the fix.
+ */
+export type Writable<D> = D extends DescriptorModule.Immutable
+  ? { readonly __immutable__: `${NameOf<D>} is immutable: replace it with commands.insert(entity, Game.Command.entry(${NameOf<D>}, ...))` }
+  : unknown
 
 /**
  * Declares maybe-present read-only access to a component in a query
@@ -282,6 +315,34 @@ export const changed = <D extends ComponentDescriptor>(descriptor: D): ChangedFi
   descriptor
 })
 
+/**
+ * Declares a filter that matches entities passing at least one of `filters`
+ * (`added` / `changed`) since the reading system's previous run. Each entity
+ * is matched once, however many of its filters pass.
+ *
+ * Filters listed side by side in `filters: [...]` must all pass; use `anyOf`
+ * when any one of them is enough, for example to redraw when either the
+ * position or the sprite changed.
+ *
+ * @example
+ * ```ts
+ * const RedrawQuery = Game.Query({
+ *   selection: { position: Game.Query.read(Position), sprite: Game.Query.read(Sprite) },
+ *   filters: [Game.Query.anyOf(Game.Query.changed(Position), Game.Query.changed(Sprite))]
+ * })
+ * ```
+ */
+export const anyOf = <
+  const Filters extends readonly [
+    LifecycleFilter<ComponentDescriptor>,
+    LifecycleFilter<ComponentDescriptor>,
+    ...ReadonlyArray<LifecycleFilter<ComponentDescriptor>>
+  ]
+>(...filters: Filters): AnyOfFilter<Filters[number]["descriptor"]> => ({
+  kind: "anyOf",
+  filters
+})
+
 /**
  * A fully explicit query specification.
  *
@@ -387,6 +448,9 @@ export namespace Query {
   /** The component descriptors a query proves its matches have: required selection slots and `with`. */
   export type Proven<T extends Any> = RequiredSelectionDescriptors<T> | T["with"][number]
 
+  /** The component descriptors a query proves its matches lack: its `without`. */
+  export type Excluded<T extends Any> = T["without"][number]
+
   /**
    * The readable proof produced by a query.
    */
@@ -621,11 +685,11 @@ export type OptionalReadCell<T> = PresentOptionalReadCell<T> | AbsentOptionalRea
 export type QueryMatch<S extends Schema.Any, Q extends Query.Any> =
   keyof Query.WriteProof<Q> extends never
     ? {
-        readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>, Query.Proven<Q>>
+        readonly entity: EntityRef<S, Query.ReadProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>
         readonly data: Query.Cells<Q>
       }
     : {
-        readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>, Query.Proven<Q>>
+        readonly entity: EntityMut<S, Query.ReadProof<Q>, Query.WriteProof<Q>, Query.Root<Q>, Query.Proven<Q>, Query.Excluded<Q>>
         readonly data: Query.Cells<Q>
       }