@typeonce/ritmo 0.7.0 → 0.9.0

package/src/internal/queries.ts

@@ -14,6 +14,7 @@
  * Matches are always returned in ascending entity id order, which is spawn
  * order, so iteration is deterministic.
  */
+import type { Descriptor } from "../Descriptor.ts"
 import * as DescriptorModule from "../Descriptor.ts"
 import type * as Entity from "../Entity.ts"
 import * as Query from "../Query.ts"
@@ -46,6 +47,9 @@ interface LifecycleFilterPlan {
   readonly ordinal: number
 }
 
+/** A query filter: one lifecycle filter, or `anyOf` several (passes when one does). */
+type FilterPlan = ReadonlyArray<LifecycleFilterPlan>
+
 interface QueryState {
   readonly ordinal: number
   readonly required: ReadonlyArray<number>
@@ -54,7 +58,7 @@ interface QueryState {
   readonly withoutRelations: ReadonlyArray<Relation.Relation.Any>
   readonly withRelated: ReadonlyArray<Relation.Relation.Any>
   readonly withoutRelated: ReadonlyArray<Relation.Relation.Any>
-  readonly filters: ReadonlyArray<LifecycleFilterPlan>
+  readonly filters: ReadonlyArray<FilterPlan>
   readonly slots: ReadonlyArray<SlotPlan>
   readonly proofSlots: ReadonlyArray<readonly [string, number]>
   readonly writeSlots: ReadonlyArray<readonly [string, number]>
@@ -121,6 +125,31 @@ export const makeQueryEngine = (world: World) => {
   const states = new WeakMap<AnyQuery, QueryState>()
   let nextOrdinal = 0
 
+  /**
+   * The ordinal of a selected component, checking that the descriptor the
+   * query names behaves like the one the schema registers under that name:
+   * identity is (kind, name), so a look-alike built elsewhere must not add
+   * or drop behaviour (entity-state transitions, a constructor, immutability,
+   * transience) the schema does not declare.
+   */
+  const registeredOrdinal = (descriptor: Descriptor.Any): number => {
+    const ordinal = world.ordinalOf(descriptor as never)
+    const registered = world.descriptorAt(ordinal) as Descriptor.Any
+    if (registered === descriptor) return ordinal
+    const traits = (candidate: Descriptor.Any) => [
+      DescriptorModule.isEntityState(candidate as never) ? "an entity state" : undefined,
+      DescriptorModule.hasConstructor(candidate) ? "constructed" : undefined,
+      DescriptorModule.isImmutable(candidate) ? "immutable" : undefined,
+      DescriptorModule.isTransient(candidate) ? "transient" : undefined
+    ].filter((trait) => trait !== undefined).join(", ") || "plain"
+    const expected = traits(registered)
+    const actual = traits(descriptor)
+    if (expected !== actual) {
+      throw new Error(`${descriptor.name} is ${expected} in this schema, but this query names a descriptor that is ${actual}: use the descriptor the schema registers`)
+    }
+    return ordinal
+  }
+
   const compile = (query: AnyQuery): QueryState => {
     const required: Array<number> = query.with.map((descriptor) => world.ordinalOf(descriptor))
     const withRelations: Array<Relation.Relation.Any> = [...query.withRelations]
@@ -133,7 +162,7 @@ export const makeQueryEngine = (world: World) => {
       switch (access.mode) {
         case "read":
         case "write": {
-          const ordinal = world.ordinalOf(access.descriptor)
+          const ordinal = registeredOrdinal(access.descriptor)
           required.push(ordinal)
           proofSlots.push([slot, ordinal])
           if (access.mode === "write") {
@@ -151,7 +180,7 @@ export const makeQueryEngine = (world: World) => {
           break
         }
         case "optional":
-          slots.push({ slot, mode: "optional", ordinal: world.ordinalOf(access.descriptor) })
+          slots.push({ slot, mode: "optional", ordinal: registeredOrdinal(access.descriptor) })
           break
         case "readRelation":
           withRelations.push(access.descriptor)
@@ -185,11 +214,13 @@ export const makeQueryEngine = (world: World) => {
       withoutRelations: query.withoutRelations,
       withRelated: unique(withRelated),
       withoutRelated: query.withoutRelated,
-      filters: query.filters.map((filter) => {
-        const ordinal = world.ordinalOf(filter.descriptor)
-        world.trackChanges(ordinal)
-        return { kind: filter.kind, ordinal }
-      }),
+      filters: query.filters.map((filter) =>
+        (filter.kind === "anyOf" ? filter.filters : [filter]).map((member) => {
+          const ordinal = world.ordinalOf(member.descriptor)
+          world.trackChanges(ordinal)
+          return { kind: member.kind, ordinal }
+        })
+      ),
       slots,
       proofSlots,
       writeSlots,
@@ -239,14 +270,33 @@ export const makeQueryEngine = (world: World) => {
 
   const matchesFilters = (state: QueryState, record: EntityRecord, since: number): boolean => {
     for (const filter of state.filters) {
-      const matched = filter.kind === "added"
-        ? world.addedSince(record, filter.ordinal, since)
-        : world.changedSince(record, filter.ordinal, since)
+      let matched = false
+      for (const member of filter) {
+        matched = member.kind === "added"
+          ? world.addedSince(record, member.ordinal, since)
+          : world.changedSince(record, member.ordinal, since)
+        if (matched) break
+      }
       if (!matched) return false
     }
     return true
   }
 
+  /**
+   * Ids that may pass one filter (may repeat), or `undefined` when a change
+   * log no longer covers `since`. An `anyOf` is the union of its members' logs.
+   */
+  const filterCandidates = (filter: FilterPlan, since: number): ReadonlyArray<number> | undefined => {
+    if (filter.length === 1) return world.changedCandidates(filter[0]!.ordinal, since)
+    const union: Array<number> = []
+    for (const member of filter) {
+      const logged = world.changedCandidates(member.ordinal, since)
+      if (logged === undefined) return undefined
+      for (const id of logged) union.push(id)
+    }
+    return union
+  }
+
   const relatedIds = (relation: Relation.Relation.Any, id: number): ReadonlyArray<Entity.EntityId<any, any>> =>
     world.relatedSourceIds(relation, id).map(world.entityIdOf)
 
@@ -426,7 +476,7 @@ export const makeQueryEngine = (world: World) => {
     // bounds the candidates for either filter.
     let candidates: ReadonlyArray<number> | undefined
     for (const filter of state.filters) {
-      const logged = world.changedCandidates(filter.ordinal, since)
+      const logged = filterCandidates(filter, since)
       if (logged === undefined) continue
       if (logged.length === 0) return []
       if (candidates === undefined || logged.length < candidates.length) candidates = logged

package/src/internal/relations.ts

@@ -0,0 +1,52 @@
+/**
+ * Builds relation pairs for `Descriptor.Hierarchy` and `Descriptor.Relation`,
+ * the one public way to define a relation.
+ */
+import type { PairBrand, RelatedDefinition, RelationDefinition, RelationKind } from "../Relation.ts"
+
+const relationTypeId = "~ritmo/Relation"
+
+export const makePair = <
+  const Name extends string,
+  const RelatedName extends string,
+  const Kind extends RelationKind
+>(
+  kind: Kind,
+  name: Name,
+  relatedName: RelatedName
+): {
+  readonly relation: RelationDefinition<Name, RelatedName, Kind, PairBrand<Name, RelatedName, Kind>>
+  readonly related: RelatedDefinition<RelatedName, Name, Kind, PairBrand<Name, RelatedName, Kind>>
+} => {
+  type Pair = PairBrand<Name, RelatedName, Kind>
+  const related = {
+    kind: "related",
+    relatedName,
+    relationName: name,
+    key: Symbol.for(`ritmo/related/${name}`),
+    relationKind: kind,
+    [relationTypeId]: {
+      _Pair: (_: never) => undefined as unknown as Pair
+    }
+  } as RelatedDefinition<RelatedName, Name, Kind, Pair>
+
+  const relation = {
+    kind: "relation",
+    name,
+    relatedName,
+    key: Symbol.for(`ritmo/relation/${name}`),
+    relationKind: kind,
+    linkedDespawn: kind === "hierarchy",
+    allowSelf: false,
+    ordered: kind === "hierarchy",
+    related,
+    [relationTypeId]: {
+      _Pair: (_: never) => undefined as unknown as Pair
+    }
+  } as RelationDefinition<Name, RelatedName, Kind, Pair>
+
+  return {
+    relation,
+    related
+  }
+}

package/src/internal/requirements.ts

@@ -0,0 +1,71 @@
+/**
+ * Runtime side of `Schema.requires`: the requirement index built once per
+ * bound schema, used to expand `Game.System.spawns(...)`, to check commands
+ * when they are applied, and to check restored entities.
+ *
+ * The compile-time counterpart lives in `Command.ts` (spawn, insert, remove)
+ * and `Schema.ts` (`ValidateRequires`).
+ */
+import type { Descriptor } from "../Descriptor.ts"
+import type { Schema } from "../Schema.ts"
+
+type ComponentDescriptor = Descriptor<"component", string, any>
+
+export interface RequirementIndex {
+  /** Whether the schema declares any requirement. */
+  readonly empty: boolean
+  /** Component name to the components it directly requires. */
+  readonly requires: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+  /** Component name to the components that directly require it. */
+  readonly requiredBy: ReadonlyMap<string, ReadonlyArray<ComponentDescriptor>>
+}
+
+const push = (map: Map<string, Array<ComponentDescriptor>>, key: string, value: ComponentDescriptor): void => {
+  const list = map.get(key)
+  if (list === undefined) map.set(key, [value])
+  else if (!list.some((entry) => entry.name === value.name)) list.push(value)
+}
+
+export const requirementIndex = (schema: Schema.Any): RequirementIndex => {
+  const requires = new Map<string, Array<ComponentDescriptor>>()
+  const requiredBy = new Map<string, Array<ComponentDescriptor>>()
+  for (const requirement of schema.requires) {
+    for (const required of requirement.required) {
+      push(requires, requirement.component.name, required)
+      push(requiredBy, required.name, requirement.component)
+    }
+  }
+  return { empty: requires.size === 0, requires, requiredBy }
+}
+
+/** `components` and everything they require, transitively, without duplicates. */
+export const withRequired = (
+  index: RequirementIndex,
+  components: ReadonlyArray<ComponentDescriptor>
+): ReadonlyArray<ComponentDescriptor> => {
+  if (index.empty) return components
+  const result: Array<ComponentDescriptor> = []
+  const seen = new Set<string>()
+  const visit = (descriptor: ComponentDescriptor): void => {
+    if (seen.has(descriptor.name)) return
+    seen.add(descriptor.name)
+    result.push(descriptor)
+    for (const required of index.requires.get(descriptor.name) ?? []) visit(required)
+  }
+  components.forEach(visit)
+  return result
+}
+
+/** The first requirement `held` breaks, as `[requirer, missing]`, or `undefined`. */
+export const firstMissing = (
+  index: RequirementIndex,
+  held: (name: string) => boolean,
+  names: Iterable<string>
+): readonly [string, string] | undefined => {
+  for (const name of names) {
+    for (const required of index.requires.get(name) ?? []) {
+      if (!held(required.name)) return [name, required.name]
+    }
+  }
+  return undefined
+}

package/src/internal/streams.ts

@@ -59,6 +59,8 @@ export interface Streams<T> {
    * reader has read, then enforces the capacity.
    */
   trim(windowBoundary: number): void
+  /** Drops every batch stamped after `tick` (what a rolled-back phase published). */
+  retract(tick: number): void
   /** Clears simulation messages; unread host messages survive world restore. */
   clear(): void
   /** Every key with retained entries or registered readers. */
@@ -151,6 +153,15 @@ export const make = <T>(capacity: number): Streams<T> => {
         dropFront(log, overflow)
       }
     },
+    retract(tick) {
+      for (const log of logs.values()) {
+        const start = firstAfter(log.ticks, tick)
+        for (let index = start; index < log.batches.length; index++) log.size -= log.batches[index]!.length
+        log.ticks.length = start
+        log.batches.length = start
+        log.surviveRestore.length = start
+      }
+    },
     clear() {
       for (const [key, log] of logs) {
         const ticks: Array<number> = []

package/src/internal/world.ts

@@ -48,6 +48,8 @@ export interface EntityRecord {
    * Cached query matches by query ordinal, reused while the entity matches.
    */
   readonly matches: Array<unknown>
+  /** The name of the component at an ordinal, for error messages (shared by the world's records). */
+  readonly nameAt: (ordinal: number) => string
   alive: boolean
 }
 
@@ -227,6 +229,16 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
   const journalRecords: Array<EntityRecord> = []
   const journalOrdinals: Array<number> = []
   const journalValues: Array<unknown> = []
+  /**
+   * Journal of a phase: several system transactions undone together (a
+   * transition's exit schedules). Each committed write keeps its value and
+   * change tick from before it, so rollback restores both, newest first.
+   */
+  let inPhase = false
+  const phaseRecords: Array<EntityRecord> = []
+  const phaseOrdinals: Array<number> = []
+  const phaseValues: Array<unknown> = []
+  const phaseChanged: Array<number> = []
 
   /**
    * Entity ownership used by scene and level lifetime scopes.
@@ -238,6 +250,8 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
   /** Suppresses per-component and relation hooks inside spawns and despawns. */
   let hookDepth = 0
 
+  const nameAt = (ordinal: number): string => descriptors[ordinal]?.name ?? `component #${ordinal}`
+
   const ordinalOf = (descriptor: ComponentDescriptor): number => {
     const known = ordinals.get(descriptor.key)
     if (known !== undefined) {
@@ -337,6 +351,7 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
         values,
         marks,
         matches: [],
+        nameAt,
         alive: true
       }
       records.set(record.id, record)
@@ -363,14 +378,19 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
   /**
    * Writes an existing component value in place and records the change.
    */
-  const setComponentValue = (record: EntityRecord, ordinal: number, value: unknown): void => {
-    if (!record.alive) {
-      return
+  /**
+   * Writes a component the entity holds. Returns `false`, writing nothing,
+   * when it does not (despawned records hold nothing): only a stale query
+   * cell gets here, and it reports the misuse.
+   */
+  const setComponentValue = (record: EntityRecord, ordinal: number, value: unknown): boolean => {
+    if (record.values[ordinal] === ABSENT) {
+      return false
     }
     if (!inTransaction) {
       record.values[ordinal] = value
       markChanged(record, ordinal)
-      return
+      return true
     }
     const slot = ordinal * MARK_STRIDE + JOURNALED
     if (record.marks[slot] !== transaction) {
@@ -380,6 +400,7 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
       journalValues.push(record.values[ordinal])
     }
     record.values[ordinal] = value
+    return true
   }
 
   const clearJournal = (): void => {
@@ -403,6 +424,13 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
     inTransaction = false
     for (let index = 0; index < journalRecords.length; index++) {
       const record = journalRecords[index]!
+      if (inPhase) {
+        const ordinal = journalOrdinals[index]!
+        phaseRecords.push(record)
+        phaseOrdinals.push(ordinal)
+        phaseValues.push(journalValues[index])
+        phaseChanged.push(record.marks[ordinal * MARK_STRIDE + CHANGED]!)
+      }
       if (record.alive) {
         markChanged(record, journalOrdinals[index]!)
       }
@@ -421,6 +449,30 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
     clearJournal()
   }
 
+  const clearPhase = (): void => {
+    inPhase = false
+    phaseRecords.length = 0
+    phaseOrdinals.length = 0
+    phaseValues.length = 0
+    phaseChanged.length = 0
+  }
+
+  /** Starts a phase: the transactions committed until it ends can be undone together. */
+  const beginPhase = (): void => {
+    inPhase = true
+  }
+
+  /** Restores every write committed in the phase, with its change tick. */
+  const rollbackPhase = (): void => {
+    for (let index = phaseRecords.length - 1; index >= 0; index--) {
+      const record = phaseRecords[index]!
+      const ordinal = phaseOrdinals[index]!
+      record.values[ordinal] = phaseValues[index]
+      record.marks[ordinal * MARK_STRIDE + CHANGED] = phaseChanged[index]!
+    }
+    clearPhase()
+  }
+
   const clearEntityScope = (id: number): void => {
     const scopeKey = scopeByEntity.get(id)
     if (scopeKey === undefined) {
@@ -779,6 +831,7 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
     records,
     relationDefinitions,
     ordinalOf,
+    nameAt,
     has,
     entityIdOf,
     allocateEntity,
@@ -792,6 +845,9 @@ export const makeWorld = <S extends Schema.Any>(schema: S, lifecycleCapacity: nu
     beginTransaction,
     commitTransaction,
     rollbackTransaction,
+    beginPhase,
+    commitPhase: clearPhase,
+    rollbackPhase,
     tryRelate,
     unrelate,
     reorderChildren,