@typeonce/ritmo 0.8.0 → 0.9.0

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,