Blame for unify/README.md

# UNIFY

UNIFY is a 2D game engine runtime written in C++17, with Lua gameplay, a CUDA-like kernel compiler that
targets its own WASM runtime, and interchangeable platform backends. `game/` holds a small platformer
built on it, which proves the runtime end to end.

```
UNIFY                          where
├── renderer                   engine/render      RenderDevice, Renderer2D (sort + batch), camera, atlas, QOI/PNG, bitmap font
├── physics                    engine/physics     rigid bodies, SAP broadphase, SAT/clip manifolds, sequential impulses, CCD, islands
├── audio                      engine/audio       mixer, buses, voices, WAV decoder, streaming ring buffer, device thread
├── input                      engine/input       timestamped event queue → per-tick InputFrame, actions/axes, buffering
├── animation                  engine/animation   sprite clips, keyframe tracks, loop/once/ping-pong, crossfade blending
├── scene                      engine/runtime     scene stack with per-scene resource ownership, prefabs, transitions
├── ECS                        engine/ecs         generational entities, sparse-set component pools
├── Lua                        engine/script      Lua 5.4 VM: own allocator + budget, engine-scheduled GC, sandbox
├── memory / GC                engine/memory      Frame/Pool/Object/Asset/Buffer allocators, pool-backed STL allocator
├── assets                     engine/assets      registry, ref-counted handles, cache, loaders
├── serialization              engine/serialization  tagged, versioned binary sections
├── save states                engine/runtime     save_state / load_state / snapshot / restore / state_hash
├── networking-ready state     engine/net         rollback buffer: snapshots + input log, rewind & resimulate
├── WASM runtime               engine/wasm        binary decoder, interpreter, shared linear memory, buffers
├── kernel compiler            engine/kernel      CUDA-like source → AST → IR → constant folding → WASM
└── Unreal backend             backends/unreal    UE5 plugin implementing unify::Backend (not compiled here, see Status)
```

## Build and run

Requires CMake ≥ 3.16, a C++17 compiler, and optionally SDL2 (`libsdl2-dev`) for the windowed backend.

```bash
cmake -S . -B build -G Ninja
cmake --build build          # also generates the game's sprites, SFX and music (unify_assetgen)
ctest --test-dir build       # 58 unit/integration tests + the definition-of-done playtest
./build/unify_game           # SDL2 window: arrows/AD move, Space jump, F5 save, F9 load, Esc menu
./build/unify_game --headless --frames 600 --screenshot out.png
./build/unify_playtest game/assets out/   # scripted playthrough with verification + screenshots
```

## The engine loop

Every real-time frame runs these stages. The playtest prints this order from the engine's own trace.

```
INPUT → INPUT BUFFER → FIXED SIMULATION → PHYSICS → GAMEPLAY / LUA → ANIMATION → AUDIO → RENDER PREPARATION → RENDER → PRESENT
        └─────────────────── zero or more fixed 60 Hz ticks ──────────────────┘
```

There are five separate clocks:

| Clock | Where | Used for |
|---|---|---|
| Wall / input clock | `Backend::now_ns()` | timestamping OS events, deciding when ticks are due |
| Simulation | `SimClock` (integer ticks) | all gameplay, physics and animation. Seconds are derived from ticks, never accumulated |
| Render | `RenderClock` | interpolation factor between the last two sim states |
| Audio | `Mixer::frames_rendered()` | advanced by the audio device thread, independent of frame rate |
| Input | event timestamps | an event is consumed by the tick whose window contains it |

A tick is due when `origin + (tick+1)·1e9/rate ≤ now`. After `max_ticks_per_frame`, a stall drops time
rather than spiralling. Rendering interpolates transforms, so 30, 60 and 144 FPS all run the same
60 ticks per second (tested).

**Input buffering.** OS events are queued with timestamps. Each tick drains the events stamped before
its end and folds them into an `InputFrame`: `pressed`, `released`, `repeated`, `held`, axes and pointer.
A press and release that both land between two ticks still reads as *pressed* in the next tick; the
playtest checks this with a 3 ms tap. `input:buffered("jump", n)` gives gameplay a press window.

## Determinism, save states, networking

- One seeded RNG (xoshiro128**) is the only random source. Lua's `math.random` is rebound to it.
  Lua has no `os` or `io`, so no wall-clock reads.
- The build uses `-ffp-contract=off -fno-fast-math`, and every container that affects the simulation
  iterates in a deterministic order.
- **Save state** = tagged binary sections: `HEAD` (magic, version, engine, tick rate), `TIME` (tick,
  timers), `RNG`, `SCEN` (scene stack, owned assets by name, buffers, kernels), `ECS` (entity pool and
  component pools in dense order), `PHYS` (bodies, *and contact impulses for warm starting*), `ANIM`,
  `INPT`, `CAMR`, `COMP` (live WASM buffers and kernel sources), `LUA` (the `game` table plus each scene's
  `state`), and `AUDI` (voices by asset name and position). There are no raw pointers; handles and names
  only. Unknown sections are skippable, and newer versions are refused.
- `save_state()` / `load_state()` from Lua are applied at the tick boundary. `snapshot()` / `restore()`
  are the in-memory forms, and `save_to_file()` writes atomically.
- **Round trip:** restore reproduces the saved `state_hash()` exactly, in the same engine or a fresh one.
  Replaying the recorded input from a restored state reproduces the original continuation bit for bit.
- `engine/net/rollback.h` keeps periodic snapshots plus the input log. `correct(tick, frame)` rewinds and
  re-simulates. A test proves that a late-corrected timeline equals the true one.

## Lua API

Scenes are Lua files returning a table with `init`, `load`, `update(dt)`, `render`, `on_contact(a, b,
kind, nx, ny, impulse)`, `on_timer(name)`, `on_saved`, `on_loaded` and `unload`. UNIFY owns the lifecycle.

```lua
entity:set_position(x, y)        entity:set_velocity(x, y)     entity:set_animation("run", blend)
physics:apply_force(entity, x, y)  physics:raycast(x1, y1, x2, y2, mask, ignore)  physics:add_static_box(...)
audio:play("audio/jump")         audio:stream("music/theme")   audio:stop(id, fade)   audio:set_bus_volume("music", v)
input:is_pressed("jump")         input:is_held("left")         input:buffered("jump", ticks)   input:axis("move")
world:spawn("prefabs/player", x, y)   world:find(name)         camera:set(x, y, zoom)   ui:text(...)  -- ui only in render()
timer.after(sec, name)   scene.transition("level")   animation.define{...}   map.load("maps/level1")
buffer.create(n)  buffer.upload(b, t)  buffer.download(b)      kernel.compile(src)  kernel.load(k)  kernel.dispatch(k, grid, block, ...)
save_state([slot])  load_state([slot])   gc_step() gc_budget(kb) gc_pause() gc_resume() gc_collect()
```

Lua only ever holds handles: entities, buffers and kernels are userdata that wrap a generational handle,
checked on every call. A destroyed entity raises `stale entity handle` instead of touching freed memory.
Lua memory comes from its own allocator with a hard cap (the default is 64 MB). The collector is stopped,
and the engine runs one budgeted incremental step per tick, plus a full collection only on scene loads.

## Kernel compiler and WASM runtime

```c
__global__ void vadd(const float* A, const float* B, float* C, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    if (i < n) C[i] = A[i] + B[i];
}
```

**Source → AST.** A lexer and recursive-descent parser handle `int`/`float`, pointers, `if`/`for`/`while`,
`break`/`continue`, casts, `sqrtf`/`fabsf`/`fminf`/`fmaxf`/`min`/`max`, and `threadIdx`/`blockIdx`/`blockDim`/`gridDim`.

**AST → IR.** A typed, name-resolved, structured IR with explicit conversions, printed by `print_ir`.
Constant folding and dead-branch elimination run on it.

**IR → WASM.** Each module imports `env.memory` and exports the kernel plus `<name>__dispatch(grid, block, ...)`,
which loops over the whole grid inside WASM.

**Runtime.** It decodes and validates the binary, builds block side tables, and interprets i32/i64/f32/f64.
Out-of-bounds access, divide by zero, stack overflow and fuel exhaustion are *traps*, returned as errors.
All kernels share one linear memory, and buffers are ranges handed out by `BufferAllocator`.

The demo runs `vadd` on the title screen and integrates the sparkle particles with a second kernel.

## Backends

| Backend | Render | Audio | Input | Status |
|---|---|---|---|---|
| Headless | software device, offscreen | null device thread (real time) | programmatic / replay | built and tested |
| SDL2 (native) | software device → SDL texture, integer scaling | SDL audio callback | keyboard, mouse, game controller, touch | built; smoke-tested with SDL's dummy drivers |
| Unreal | `FCanvasTriangleItem` per batch, transient `UTexture2D` | `USynthComponent` | `AnyKey` bindings | **source only, not compiled** (no UE toolchain in CI) |

The renderer is a `RenderDevice` interface. The engine ships a software rasterizer as its reference
device, and a GPU device would plug in at the same interface.

## Verification

- `unify_tests`: 58 tests covering every physics edge case in the spec (tunneling, bullets, resting
  contacts, stacking, penetration, zero and infinite mass, tiny and huge bodies, coincident centres,
  parallel edges, corner, edge and multi contacts, triggers, sleep and wake, filtering, NaN containment,
  exact save/restore). They also cover input buffering, the mixer, streaming and loop points, the audio
  device thread, renderer batching, blending, scissor and rotation, animation modes and blending, the
  allocators, handles, RNG, the kernel pipeline, WASM traps, scene-transition leak checks, determinism
  across engines, fresh-engine restore, Lua sandboxing, the handle and memory caps, GC scheduling,
  **zero heap allocations per steady-state tick**, stage order, frame-rate independence, and rollback.
- `unify_playtest`: the definition of done, from BOOT to CONTINUE PLAYING, on the real game with
  scripted input. Each stage is verified from engine state (hashes, counts, clips, voices) and
  screenshots are written.
- The whole suite and the playtest are clean under AddressSanitizer and UndefinedBehaviorSanitizer.

## Not included / known limits

- The **WASM *platform* backend** (compiling UNIFY itself to WebAssembly for browsers) is not built. It
  needs Emscripten, which isn't available here. The engine core has no platform dependencies, so it is
  a backend-sized job. UNIFY's WASM *runtime* for kernels is fully built.
- **Unreal backend**: see the table above.
- **Compilers**: builds with GCC and Clang, and with MinGW-w64 GCC on Windows (runtime linked statically).
  MSVC is not supported: the code uses `__builtin_clz` and `__uint128_t`.
- Audio decodes PCM16 WAV only. Physics has no joints. Scissor rectangles are not applied on the Unreal
  backend. The software renderer is the only render device.