gizgame/simulation
import * as Simulation from "gizgame/simulation";Types
Input
type Input = { tick: i64; sequence: i64; payload: bytes; }Inputs belonging to one fixed tick. Payloads are the application's versioned input contract.
tick:i64sequence:i64payload:bytes
Frame
type Frame = { steps: i64; alpha: f64; dropped: f64; tick: i64; }The fixed steps taken and fraction toward the next step; DROPPED is time refused by bounded catch-up.
steps:i64alpha:f64dropped:f64tick:i64
Clock
class Clock { private step: f64; private maximum: i64; private previous: f64 = -1.0; private pending: f64 = 0.0; private number: i64 = 0; constructor(hz: f64 = 60.0, maximum: i64 = 5) { assert(Math.isFinite(hz) && hz> 0.0 && hz <= 1000.0 && maximum> 0 && maximum <= 1000); this.step = 1.0 / hz; this.maximum = maximum; } tick(): i64 { return this.number; } seconds(): f64 { return this.step; } pause(): void { this.previous = -1.0; this.pending = 0.0; } seek(tick: i64): void { assert(tick> = 0); this.number = tick; this.pause(); } advance(now: f64, run: (tick: i64, seconds: f64) => void throws string): Frame throws string { if (!Math.isFinite(now) || now <0.0) { throw "Invalid monotonic frame time"; } if (this.previous <0.0) { this.previous = now; return { steps: 0, alpha: 0.0, dropped: 0.0, tick: this.number }; } if (now <this.previous) { throw "Frame clock moved backwards"; } const elapsed = (now - this.previous) / 1000.0; this.previous = now; const cap = this.step * f64(this.maximum); const accepted = Math.min(elapsed, cap); const dropped = elapsed - accepted; this.pending + = accepted; let steps: i64 = 0; while (this.pending> = this.step && steps <this.maximum) { run(this.number, this.step); this.pending - = this.step; this.number + = 1; steps + = 1; } return { steps, alpha: this.pending / this.step, dropped, tick: this.number }; } }A fixed clock. NOW is supplied by the host's monotonic clock; simulation never reads a wall clock.
step:f64maximum:i64previous:f64pending:f64number:i64
System
type System = { name: string; reads: Vec<i64>; writes: Vec<i64>; after: Vec<string>; incremental: bool; structural?: bool; run: (world: World, tick: i64, seconds: f64, inputs: Vec<Input>) => void throws string; }An ordinary function with explicit component accesses. AFTER declares non-component dependencies.
name:stringreads:Vec<i64>writes:Vec<i64>after:Vec<string>incremental:boolstructural:_gizlang_sdk_core.Option<bool>run:(arg0: Ref<M186.World>, arg1: i64, arg2: f64, arg3: Vec<M184.Input>) => void throws string
Schedule
class Schedule { private systems: Vec<System>; private stages: Vec<Vec<i64>> = []; private observed: Vec<i64> = []; private epoch: i64 = -1; constructor(systems: Vec<System>) throws string { this.systems = systems; let names = new Set<string>(); for (const system of systems) { if (system.name === "" || names.has(system.name)) { throw "Empty or duplicate system name"; } names.add(system.name); this.observed.push(-1); if (system.reads.some(id => id <0) || system.writes.some(id => id <0)) { throw "Invalid component access"; } } for (const system of systems) { if (system.after.some(name => !names.has(name) || name === system.name)) { throw "Invalid system dependency"; } } const after = systems.map(system => system.after.map(name => systems.findIndex(other => other.name === name))); this.stages = dependencyBatches(after, (left: i64, right: i64): bool => conflict(systems[left], systems[right])); } batches(): Vec<Vec<string>> { let out: Vec<Vec<string>> = []; for (const stage of this.stages) { out.push(stage.map(index => this.systems[index].name)); } return out; } reset(): void { for (const i of range(0, this.observed.length)) { this.observed[i] = -1; } } run(world: World, tick: i64, seconds: f64, inputs: Vec<Input>): void throws string { if (this.epoch !== world.epoch()) { this.reset(); this.epoch = world.epoch(); } for (const stage of this.stages) { for (const index of stage) { const system = this.systems[index]; const revision = world.componentRevision([...system.reads, ...system.writes]); if (!system.incremental || inputs.length> 0 || this.observed[index] !== revision) { world.system(system.reads, system.writes, system.structural ?? false, (): void throws string => system.run(world, tick, seconds, inputs)); this.observed[index] = world.componentRevision([...system.reads, ...system.writes]); } } } } }Deterministic dependency batches. Execution starts serially; independent batches are explicit for future workers.
systems:Vec<M184.System>stages:Vec<Vec<i64>>observed:Vec<i64>epoch:i64
Inputs
class Inputs { private pending: Vec<Input> = []; private lastTick: i64 = -1; private sequences = new Set<i64>(); private used: i64 = 0; private maximum: i64; constructor(maximum: i64 = 16777216) { assert(maximum> 0); this.maximum = maximum; } push(input: Input): void throws string { if (input.tick <= this.lastTick || input.sequence <0 || this.sequences.has(input.sequence)) { throw "Late or duplicate input"; } if (this.pending.length> = 65536) { throw "Pending input budget exceeded"; } if (input.payload.length> this.maximum-this.used-24) { throw "Pending input byte budget exceeded"; } this.pending.push(input); this.sequences.add(input.sequence); this.used+ = input.payload.length+24; } take(tick: i64): Vec<Input> throws string { if (tick !== this.lastTick + 1) { throw "Inputs must be consumed one tick at a time"; } const result = this.pending.filter(input => input.tick === tick).toSorted((a, b) => a.sequence <b.sequence); for (const input of result) { this.sequences.delete(input.sequence); this.used- = input.payload.length+24; } this.pending = this.pending.filter(input => input.tick !== tick); this.lastTick = tick; return result; } seek(tick: i64): void { assert(tick> = 0); this.pending = []; this.sequences = new Set<i64>(); this.used = 0; this.lastTick = tick - 1; } entries(): Vec<Input> { return this.pending.toSorted((a, b) => a.tick <b.tick || a.tick === b.tick && a.sequence <b.sequence); } }Inputs in tick/sequence order. Late inputs fail explicitly so a caller chooses rollback or rejection.
pending:Vec<M184.Input>lastTick:i64sequences:_gizlang_sdk_collections.Set<i64>used:i64maximum:i64
Simulation
class Simulation { world: World; clock: Clock; schedule: Schedule; private inputs: Inputs; private recording: Vec<Input> = []; private limit: i64; private recordedBytes: i64 = 0; private recordingOn: bool = false; private sequence: i64 = 0; constructor(world: World, systems: Vec<System>, hz: f64 = 60.0, maximum: i64 = 5, memory: i64 = 16777216) throws string { if (memory <1) { throw "Invalid replay budget"; } this.world = world; this.clock = new Clock(hz, maximum); this.schedule = new Schedule(systems); this.inputs = new Inputs(memory); this.limit = memory; } record(enabled: bool): void { this.recordingOn = enabled; } recorded(): Vec<Input> { return this.recording; } clearRecording(): void { this.recording = []; this.recordedBytes = 0; } nextSequence(): i64 { return this.sequence; } input(input: Input): void throws string { const bytes = input.payload.length+24; if (input.sequence === 9223372036854775807) { throw "Input sequence exhausted"; } if (this.recordingOn && bytes> this.limit-this.recordedBytes) { throw "Replay input budget exceeded"; } this.inputs.push(input); this.sequence = Math.maxI64(this.sequence, input.sequence+1); if (this.recordingOn) { this.recording.push(input); this.recordedBytes+ = bytes; } } private step(tick: i64, seconds: f64): void throws string { const inputs = this.inputs.take(tick); this.schedule.run(this.world, tick, seconds, inputs); } pause(): void { this.clock.pause(); this.inputs.seek(this.clock.tick()); } frame(now: f64, resumed: bool = false): Frame throws string { if (resumed) { this.clock.pause(); } return this.clock.advance(now, (tick: i64, seconds: f64): void throws string => this.step(tick, seconds)); } snapshot(): bytes { let out = b"GIZSIM01"; writeF64LE(out, this.clock.seconds()); writeU64LE(out, u64(this.clock.tick())); writeU64LE(out, u64(this.sequence)); const pending = this.inputs.entries(); writeU64LE(out, u64(pending.length)); for (const input of pending) { writeU64LE(out, u64(input.tick)); writeU64LE(out, u64(input.sequence)); writeU64LE(out, u64(input.payload.length)); out+ = input.payload; } out+ = this.world.snapshot(); return out; } restore(state: bytes): void throws string { if (state.length <40 || state.slice(0, 8) !== b"GIZSIM01" || state.readF64LE(8) !== this.clock.seconds()) { throw "Simulation snapshot version or tick rate differs"; } const tick = state.readU64LE(16); if (tick> 9223372036854775807u) { throw "Invalid snapshot tick"; } const sequence = state.readU64LE(24); if (sequence> 9223372036854775807u) { throw "Invalid snapshot input sequence"; } const count = state.readU64LE(32); if (count> 65536u) { throw "Too many snapshot inputs"; } const pending = new Inputs(this.limit); pending.seek(i64(tick)); let at: i64 = 40; for (const index of range(0, i64(count))) { if (state.length-at <24) { throw "Truncated snapshot input"; } const inputTick = state.readU64LE(at); const inputSequence = state.readU64LE(at+8); const size = state.readU64LE(at+16); at+ = 24; if (inputTick> 9223372036854775807u || inputSequence> = sequence || size> u64(state.length-at)) { throw "Invalid snapshot input"; } pending.push({ tick: i64(inputTick), sequence: i64(inputSequence), payload: state.slice(at, at+i64(size)) }); at+ = i64(size); } this.world.restore(state.slice(at)); this.clock.seek(i64(tick)); this.inputs = pending; this.sequence = i64(sequence); this.schedule.reset(); } replay(state: bytes, inputs: Vec<Input>, until: i64): string throws string { this.restore(state); if (until <this.clock.tick()) { throw "Replay ends before its snapshot"; } for (const input of inputs) { if (input.sequence === 9223372036854775807) { throw "Input sequence exhausted"; } this.inputs.push(input); this.sequence = Math.maxI64(this.sequence, input.sequence+1); } while (this.clock.tick() <until) { const tick = this.clock.tick(); this.step(tick, this.clock.seconds()); this.clock.seek(tick+1); } return fingerprint(this.snapshot()); } }One simulation loop and its input queue. All host frame callbacks and recorded replays use this same tick path.
world:Ref<M186.World>clock:Ref<M184.Clock>schedule:Ref<M184.Schedule>inputs:Ref<M184.Inputs>recording:Vec<M184.Input>limit:i64recordedBytes:i64recordingOn:boolsequence:i64
Functions
constructor
constructor(hz: f64 = 60.0, maximum: i64 = 5)HZ fixed ticks per second and at most MAXIMUM ticks during one host frame.
Effects: fail, read, write, alloc.
constructor
constructor(systems: Vec<System>) throws stringValidates references and orders systems, refusing an explicit cycle instead of breaking it silently.
Effects: fail, read, write, console, io, alloc.
constructor
constructor(maximum: i64 = 16777216)Bounds queued payload bytes independently of the number of events.
Effects: fail, read, write, alloc.
constructor
constructor(world: World, systems: Vec<System>, hz: f64 = 60.0, maximum: i64 = 5, memory: i64 = 16777216) throws stringMEMORY bounds queued inputs and the retained recording separately, not the World's component memory.
Effects: fail, read, write, console, io, alloc.
Methods
Clock.tick
tick(): i64The next tick to run.
Effects: fail, read.
Clock.seconds
seconds(): f64Seconds in one tick.
Effects: fail, read.
Clock.pause
pause(): voidClears the wall-time accumulator on hide/resume, keeping simulation time.
Effects: fail, read, write.
Clock.seek
seek(tick: i64): voidRestores simulation time at a frame boundary.
Effects: fail, read, write.
Clock.advance
advance(now: f64, run: (tick: i64, seconds: f64) => void throws string): Frame throws stringRuns complete ticks and returns interpolation for presentation. RUN finishes before the tick is committed.
Effects: fail, read, write, console, io, alloc.
Schedule.batches
batches(): Vec<Vec<string>>The stable independent batches, as system names for diagnostics.
Effects: fail, read, alloc.
Schedule.reset
reset(): voidInvalidates extraction after restoring a World. No cached observation crosses a state replacement.
Effects: fail, read, write, alloc.
Schedule.run
run(world: World, tick: i64, seconds: f64, inputs: Vec<Input>): void throws stringRuns a fixed tick. Time-dependent systems set incremental false. Inputs always invalidate incremental work.
Effects: fail, read, write, console, io, alloc.
Inputs.push
push(input: Input): void throws stringEnqueues an input once, before its tick has run.
Effects: fail, read, write, alloc.
Inputs.take
take(tick: i64): Vec<Input> throws stringThe tick's inputs. Consuming a skipped or older tick is refused.
Effects: fail, read, write, alloc.
Inputs.seek
seek(tick: i64): voidResets the queue before restoring a saved tick or replaying a recording.
Effects: fail, read, write, alloc.
Inputs.entries
entries(): Vec<Input>Canonical queued inputs retained by a snapshot, including events whose next tick has not run yet.
Effects: fail, read, alloc.
Simulation.record
record(enabled: bool): voidStarts or stops input recording. Existing recordings stay owned by this instance until clearRecording.
Effects: fail, read, write.
Simulation.recorded
recorded(): Vec<Input>The recorded inputs, with exact tick and sequence.
Effects: fail, read.
Simulation.clearRecording
clearRecording(): voidDrops only the input history, retaining the current simulation.
Effects: fail, read, write, alloc.
Simulation.nextSequence
nextSequence(): i64Next application input identity, preserved across reloads and independent of a browser's local frame counter.
Effects: fail, read.
Simulation.input
input(input: Input): void throws stringEnqueues a host input for a future tick, enforcing the recording budget before accepting it.
Effects: fail, read, write, alloc.
Simulation.pause
pause(): voidPauses wall time and discards host events queued before an editor or scene transition. Tick identity stays stable.
Effects: fail, read, write, alloc.
Simulation.frame
frame(now: f64, resumed: bool = false): Frame throws stringAdvances at the host's monotonic time. RESUMED discards hidden-tab elapsed time.
Effects: fail, read, write, console, io, alloc.
Simulation.snapshot
snapshot(): bytesState transfer at a tick boundary; includes rate, next tick, pending inputs and authoritative World data.
Effects: fail, read, alloc.
Simulation.restore
restore(state: bytes): void throws stringRestores only the exact schema and tick rate; queues and derived observations are invalidated.
Effects: fail, read, write, alloc.
Simulation.replay
replay(state: bytes, inputs: Vec<Input>, until: i64): string throws stringReplays complete ticks from STATE through the same systems and input ordering as frame().
Effects: fail, read, write, console, io, alloc.