Files
darmanandClaude Opus 5.5 384f1ed1f2 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>
2026-09-25 00:27:36 +02:00

4.4 KiB

tags
tags
decisions

Decision Log

Newest at the bottom. Status is one of: accepted, proposed, rejected, superseded.

Phased time model with a fixed-step simulation

  • Date: 2026-09-23 · Status: accepted
  • Context: rounds are a paused planning phase followed by a real-time wave (Game Constraints).
  • Decision: a fixed 60 Hz SimClock (pausable, speed via extra steps) and a separate real-time FrameClock for UI; interpolated rendering.
  • Consequences: planning is just speed 0; combat stays stable at every speed. See Main Loop and Time.

Seeded run generation, non-deterministic combat

  • Date: 2026-09-23 · Status: accepted
  • Decision: named RNG streams with our own distributions; no requirement for combat to replay bit-exactly.
  • Consequences: floats are allowed in the simulation, and there's no lockstep constraint. See Randomness.

Grid with fixed lanes

  • Date: 2026-09-23 · Status: accepted
  • Decision: enemies follow predefined lanes; towers are placed on buildable tiles and never block paths.
  • Consequences: no pathfinding system; lane following is a waypoint or spline walk.

Rigid-part 3D on SDL_GPU

  • Date: 2026-09-23 · Status: accepted
  • Context: we want 3D presentation without the engine and art cost of skeletal animation.
  • Decision: render with SDL_GPU (not SDL_Renderer); models are rigid node hierarchies animated by glTF node clips plus procedural overrides; a Renderer2D overlay for the UI.
  • Consequences: a shader build step (SPIR-V, Vulkan on Linux and Windows); instancing from the start; skinning deferred. See Rendering, Rigid-Part Animation.

The simulation stays 2D

  • Date: 2026-09-23 · Status: accepted
  • Decision: gameplay positions are 2D on the ground plane; height is visual only.
  • Consequences: gameplay code and scripts are unaffected by the 3D presentation.

C# not used for scripting

  • Date: 2026-09-23 · Status: rejected
  • Reason: CoreCLR hosting, an interop layer, fragile hot reload and runtime distribution cost too much for event-only content hooks. It would only fit as the main game language, which isn't the goal.

Scripting language shortlist

  • Date: 2026-09-23 · Status: proposed
  • Decision: the candidates are Lua (5.4 or Luau) and AngelScript, to be decided by a spike. See Scripting.

Error handling split

  • Date: 2026-09-24 · Status: accepted
  • Context: principle 6 of the Engine Overview ("errors as values") was written for loaders, then stretched to platform startup. There, it forced static Create() factories, private constructors, and move constructors with a "moved-from" flag, just to return non-movable things like the SDL context through std::expected.
  • Decision: errors you can recover from are values; fatal errors are exceptions.
    • 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].