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>
59 lines
4.4 KiB
Markdown
59 lines
4.4 KiB
Markdown
---
|
|
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]`.
|