GizStack
View .mdOpen in ChatGPTOpen in Claude

gizgame/simulation

gizlang
import * as Simulation from "gizgame/simulation";

Types

Input

gizlang
type Input = { tick: i64; sequence: i64; payload: bytes; }

Inputs belonging to one fixed tick. Payloads are the application's versioned input contract.

  • tick: i64
  • sequence: i64
  • payload: bytes

Frame

gizlang
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: i64
  • alpha: f64
  • dropped: f64
  • tick: i64

Clock

gizlang
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: f64
  • maximum: i64
  • previous: f64
  • pending: f64
  • number: i64

System

gizlang
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: string
  • reads: Vec<i64>
  • writes: Vec<i64>
  • after: Vec<string>
  • incremental: bool
  • structural: _gizlang_sdk_core.Option<bool>
  • run: (arg0: Ref<M186.World>, arg1: i64, arg2: f64, arg3: Vec<M184.Input>) => void throws string

Schedule

gizlang
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

gizlang
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: i64
  • sequences: _gizlang_sdk_collections.Set<i64>
  • used: i64
  • maximum: i64

Simulation

gizlang
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: i64
  • recordedBytes: i64
  • recordingOn: bool
  • sequence: i64

Functions

constructor

gizlang
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

gizlang
constructor(systems: Vec<System>) throws string

Validates references and orders systems, refusing an explicit cycle instead of breaking it silently.

Effects: fail, read, write, console, io, alloc.

constructor

gizlang
constructor(maximum: i64 = 16777216)

Bounds queued payload bytes independently of the number of events.

Effects: fail, read, write, alloc.

constructor

gizlang
constructor(world: World, systems: Vec<System>, hz: f64 = 60.0, maximum: i64 = 5, memory: i64 = 16777216) throws string

MEMORY bounds queued inputs and the retained recording separately, not the World's component memory.

Effects: fail, read, write, console, io, alloc.

Methods

Clock.tick

gizlang
tick(): i64

The next tick to run.

Effects: fail, read.

Clock.seconds

gizlang
seconds(): f64

Seconds in one tick.

Effects: fail, read.

Clock.pause

gizlang
pause(): void

Clears the wall-time accumulator on hide/resume, keeping simulation time.

Effects: fail, read, write.

Clock.seek

gizlang
seek(tick: i64): void

Restores simulation time at a frame boundary.

Effects: fail, read, write.

Clock.advance

gizlang
advance(now: f64, run: (tick: i64, seconds: f64) => void throws string): Frame throws string

Runs complete ticks and returns interpolation for presentation. RUN finishes before the tick is committed.

Effects: fail, read, write, console, io, alloc.

Schedule.batches

gizlang
batches(): Vec<Vec<string>>

The stable independent batches, as system names for diagnostics.

Effects: fail, read, alloc.

Schedule.reset

gizlang
reset(): void

Invalidates extraction after restoring a World. No cached observation crosses a state replacement.

Effects: fail, read, write, alloc.

Schedule.run

gizlang
run(world: World, tick: i64, seconds: f64, inputs: Vec<Input>): void throws string

Runs a fixed tick. Time-dependent systems set incremental false. Inputs always invalidate incremental work.

Effects: fail, read, write, console, io, alloc.

Inputs.push

gizlang
push(input: Input): void throws string

Enqueues an input once, before its tick has run.

Effects: fail, read, write, alloc.

Inputs.take

gizlang
take(tick: i64): Vec<Input> throws string

The tick's inputs. Consuming a skipped or older tick is refused.

Effects: fail, read, write, alloc.

Inputs.seek

gizlang
seek(tick: i64): void

Resets the queue before restoring a saved tick or replaying a recording.

Effects: fail, read, write, alloc.

Inputs.entries

gizlang
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

gizlang
record(enabled: bool): void

Starts or stops input recording. Existing recordings stay owned by this instance until clearRecording.

Effects: fail, read, write.

Simulation.recorded

gizlang
recorded(): Vec<Input>

The recorded inputs, with exact tick and sequence.

Effects: fail, read.

Simulation.clearRecording

gizlang
clearRecording(): void

Drops only the input history, retaining the current simulation.

Effects: fail, read, write, alloc.

Simulation.nextSequence

gizlang
nextSequence(): i64

Next application input identity, preserved across reloads and independent of a browser's local frame counter.

Effects: fail, read.

Simulation.input

gizlang
input(input: Input): void throws string

Enqueues a host input for a future tick, enforcing the recording budget before accepting it.

Effects: fail, read, write, alloc.

Simulation.pause

gizlang
pause(): void

Pauses wall time and discards host events queued before an editor or scene transition. Tick identity stays stable.

Effects: fail, read, write, alloc.

Simulation.frame

gizlang
frame(now: f64, resumed: bool = false): Frame throws string

Advances at the host's monotonic time. RESUMED discards hidden-tab elapsed time.

Effects: fail, read, write, console, io, alloc.

Simulation.snapshot

gizlang
snapshot(): bytes

State transfer at a tick boundary; includes rate, next tick, pending inputs and authoritative World data.

Effects: fail, read, alloc.

Simulation.restore

gizlang
restore(state: bytes): void throws string

Restores only the exact schema and tick rate; queues and derived observations are invalidated.

Effects: fail, read, write, alloc.

Simulation.replay

gizlang
replay(state: bytes, inputs: Vec<Input>, until: i64): string throws string

Replays complete ticks from STATE through the same systems and input ordering as frame().

Effects: fail, read, write, console, io, alloc.