feat: engine skeleton (Build Order step 1) and siege_tests

Engine:
- SdlContext and Window: RAII, throwing constructors, non-movable
- FrameClock (real time, clamped dt) and SimClock (fixed 1/60 s steps,
  speed 0 = planning phase, backlog capped per frame)
- Application owns them in lifetime order, exposes EngineContext, and
  runs the fixed-timestep loop; AppConfig::FromArgs parses --frames,
  --seed and --fullscreen
- Temporary window-surface fill so Wayland maps the window until
  RenderDevice lands in step 2

Build:
- Split into the siege_engine static lib and the siege_deck exe
- check_engine_deps fails the build if Engine/ includes Game/
- ctest smoke test: siege_deck --frames 30 on the offscreen driver
- siege_tests on Catch2 v3.15.3 (nixpkgs + CPM pin), with SimClock,
  FrameClock and AppConfig tests

Docs:
- Decision Log: error handling split, Catch2 for unit tests
- Build Order step 1 done; Engine Overview, Main Loop and Time and
  README updated to match
- AGENTS.md with build, conventions and gotchas for coding agents
- .gitignore: .mcp.json (local CLion MCP port) and Obsidian's
  workspace.json (tab/pane state), now untracked

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-25 00:27:36 +02:00
co-authored by Claude Opus 5.5
parent 45b246c1d7
commit 384f1ed1f2
26 changed files with 1072 additions and 271 deletions
+7
View File
@@ -49,3 +49,10 @@ Newest at the bottom. Status is one of: **accepted**, **proposed**, **rejected**
- `std::expected` for failures the caller really handles on the spot: loading assets, compiling scripts, parsing definitions. The caller falls back and keeps running, which hot reload depends on.
- Exceptions (`std::runtime_error` for now) for failures with nothing to fall back to: SDL/window/GPU startup, broken invariants. Thrown from constructors and caught once in `main`, which logs and exits with 1.
- **Consequences:** platform types are plain RAII classes: a constructor that throws, non-movable when they mean "exactly one" (`SdlContext`, `Window`), and no empty state. The STL throws anyway, so `-fno-exceptions` was never an option. Exceptions must not cross C callbacks (SDL, the script VM): script bindings need a catch boundary.
## Catch2 v3 for unit tests
- **Date:** 2026-09-25 · **Status:** accepted
- **Context:** we needed a framework for `siege_tests`; the candidates were doctest and Catch2 v3.
- **Decision:** Catch2 v3, pinned to the nixpkgs version like every other dependency. Tests live in `Tests/`, mirroring `Source/`.
- **Reason:** doctest's main advantage (tests inline in production `.cpp` files) doesn't work well with `siege_engine` being a static library: the linker drops test-only object files unless the whole archive is force-linked. Catch2's generators suit the RNG and property tests we'll need, its floating-point matchers suit the clocks and simulation, it has built-in benchmarks, and it's actively maintained. Compile time is a non-issue at this size, with the PCH.
- **Consequences:** `catch_discover_tests` registers each `TEST_CASE` with ctest. Slow tests are tagged `[slow]`.