2D worlds you can replay
LudoWeave Engine
A Python engine for small 2D worlds with verified replay, pause and single-step controls, seek/resume, and a tick-aware playback status panel.
Experimental alpha. Repeating world state does not guarantee identical graphics or sound across devices.
Latest verified change · M244 / PR #262 ↗ · Merged
Verified replay gains controls and visible status
M242 through M244 add pause/step, seek/resume and current/final tick with PLAYING, PAUSED and COMPLETE states. Full-artifact verification remains mandatory; presentation controls never supply world input.
Source checked . Documentation and retained evidence review, not a new runtime test.
Read change evidence ↗Captured output / 9 September 2026
Watch a small world change, then check the record.
These are two actual offscreen frames from Clockwork Arena. Compare the early and later state, then open the capture record to inspect the world and pixel hashes.
What changed between the two saved runs?
A repeated 180-tick run matched both hashes in the recorded environment. The image and the state can be checked together.
Captured on 9 September 2026 with Null audio and no interactive window. These saved frames are not live gameplay, a new run or proof of cross-device determinism.
In plain terms
Record a small game session, then replay it to check whether the same inputs produce the same world.
Why it matters
When a simulation behaves unexpectedly, replay helps trace what happened. People, tests and AI tools use the same rules to change the world.
Follow the example, step by step
Record a session
Save the inputs and world changes from the Clockwork Arena example.
Replay the record
Run the recording again without needing a display or audio device.
Compare the result
Check the recorded world state before optionally displaying the replay.
Keep device pacing outside canonical state
Documented approach
The optional audio adapter is explicitly pumped by its owning application. It uses blocking output without Python stream or completion callbacks, while Null remains the default.
Alternative and scope
The earlier provider restriction admitted only Null audio. This decision adds optional device output without introducing a worker or a process-global mixer; background mixing and richer formats remain deferred.
Cost of the choice
Writes may block or underrun, and there is no hard real-time guarantee. Device latency and completion do not control canonical state or replay.
What the evidence establishes
ADR-0034 records local qualification with hosted qualification pending at this snapshot. The captured example below uses Null audio and therefore adds no listening or device-audio evidence.
Read the decision source (opens in a new tab)Consumed input becomes replay-owned evidence
The play loop records consumed snapshots and receipted transactions. A fresh headless process verifies the artifact; optional rendering and audio remain presentation layers.
Inspect playback without changing the recording
With controls enabled, Space pauses or resumes and Right Arrow advances one tick while paused. Paused Left Arrow rewinds one tick; Home returns to the initial tick. Held keys do not repeat. Controlled playback requires a window and one tick per recorded batch.
Seeking first verifies the entire artifact, then reconstructs a fresh world from the initial snapshot to the selected boundary. Resume starts fresh presentation deadlines, so paused or skipped time does not create a catch-up burst. Reconstruction is synchronous within the 3,600-tick/batch viewer bound; no seek-latency guarantee is made.
M244 displays the current/final tick, playback state and contextual hints using built-in diagnostic glyphs. The panel can be hidden without changing replay hashes or summaries. Very small windows reduce legibility, the panel overlays the game view, and playback still exits at completion. The portfolio's older captured frames are not evidence of the new panel.
One canonical world for humans and agents
LudoWeave gives its application runner, command line, tests, rendering adapters, and agent interface the same authoritative world and command contracts. Deterministic clocks, stable entity identity, immutable schemas, and explicit ownership make state changes inspectable rather than implicit.
- Atomic command transactions with dry-run, optimistic hashes, semantic diffs, and receipts
- Snapshots, checkpoints, replay-owned input history, and parent-referenced timeline branches
- Backend-neutral rendering with an optional pinned wgpu adapter and offscreen capture
- Clockwork Arena recording, headless verification and hash-checked presentation
Agent control is a capability boundary
The typed agent service declares capabilities, quotas, redaction, and serialized mutation. Its local MCP adapter uses standard input and output, opens no network listener, and remains read-only unless the trusted composition root explicitly enables writes.
The Agent World Builder example closes the loop from typed creation and validation through capture, query, adjustment, diff, telemetry, tests, and replay evidence.
Experimental by explicit contract
The repository records the current baseline as a community-alpha release candidate and marks every Python API and wire format experimental. Packaging, CI, checksums, an SPDX SBOM, installed-artifact smoke tests, and a pinned provenance workflow support evaluation without implying production stability.
Optional sample audio is available with blocking presentation pacing and explicit resource ownership. This does not imply general production audio support: the current README keeps network transports, a visual editor, 3D, executable plugins and native acceleration deferred. Device playback is optional presentation, not a stable production-audio guarantee.
Clockwork Arena: a captured local run
Two unretouched offscreen frames from the pinned example, captured at 60 and 180 ticks with Null audio. A second 180-tick run matched both the canonical state hash and captured pixel hash in this environment.
Windows · Python 3.12.13 · wgpu 0.32.0 · AMD Radeon(TM) Graphics · Vulkan · 960 × 540
- Original frame at 60 ticks · Recorded score: 200
- Original frame at 180 ticks · Recorded score: 300
This verifies a bounded local example, not device-audio playback, interactive input, performance, cross-device determinism or production readiness.
Read commands, environment and hash results
Captured from the Apache-2.0 LudoWeave example. Read the source license and attribution notice.
Inspect a replay boundary
An illustrative one-dimensional world: each consumed input moves a position by −1, 0 or +1. Step through the saved inputs, then change one input to see the first checkpoint disagreement. This is a teaching model, not LudoWeave execution or a captured game recording.
Inspect the saved example
Initial position: 0. Inputs: 1, 1, 0, -1, 1, 0. Checkpoints: 1, 2, 2, 1, 2, 2.
Replay applies the same inputs to the same starting state and compares each position. This model uses integer positions, not the engine’s world hashes.
Tick 0 of 6 · Position 0. Ready to inspect.
Matching state does not establish who supplied an input, identical pixels or device-audio behavior.
Read the pinned replay contract ↗ (opens in a new tab)Related writing
Related updates
Inspect the checked source
Evidence reviewed . Individual decisions and captured examples retain their own source revisions and limitations.
Read the checked README (opens in a new tab)