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:
-250
@@ -1,250 +0,0 @@
|
||||
{
|
||||
"main": {
|
||||
"id": "c6ad48c4d87faead",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "dd3e919d5adca5d6",
|
||||
"type": "tabs",
|
||||
"dimension": 75.6,
|
||||
"children": [
|
||||
{
|
||||
"id": "ca9ae29dd35549a6",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "markdown",
|
||||
"state": {
|
||||
"file": "Engine/Engine Overview.md",
|
||||
"mode": "source",
|
||||
"source": false
|
||||
},
|
||||
"icon": "lucide-file",
|
||||
"title": "Engine Overview"
|
||||
},
|
||||
"group": "994c0f9c38f6b8e7"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "81ff5c2ddea79443",
|
||||
"type": "tabs",
|
||||
"dimension": 24.4,
|
||||
"children": [
|
||||
{
|
||||
"id": "3ffd1b71ff5031fb",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "graph",
|
||||
"state": {},
|
||||
"icon": "lucide-git-fork",
|
||||
"title": "Graph view"
|
||||
},
|
||||
"group": "994c0f9c38f6b8e7"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "vertical"
|
||||
},
|
||||
"left": {
|
||||
"id": "c526f838c3013812",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "eb2dfb1df8634a0c",
|
||||
"type": "tabs",
|
||||
"children": [
|
||||
{
|
||||
"id": "52a36e40b9c1e252",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "file-explorer",
|
||||
"state": {
|
||||
"sortOrder": "alphabetical",
|
||||
"autoReveal": false,
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-folder-closed",
|
||||
"title": "Files"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "2c43a3b8b250ec4b",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "search",
|
||||
"state": {
|
||||
"query": "",
|
||||
"matchingCase": false,
|
||||
"explainSearch": false,
|
||||
"collapseAll": false,
|
||||
"extraContext": false,
|
||||
"sortOrder": "alphabetical"
|
||||
},
|
||||
"icon": "lucide-search",
|
||||
"title": "Search"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "bef1b4e0dcac47ac",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "bookmarks",
|
||||
"state": {
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-bookmark",
|
||||
"title": "Bookmarks"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "horizontal",
|
||||
"width": 200
|
||||
},
|
||||
"right": {
|
||||
"id": "165c68de881d9c62",
|
||||
"type": "split",
|
||||
"children": [
|
||||
{
|
||||
"id": "56bb9a9be0aad677",
|
||||
"type": "tabs",
|
||||
"children": [
|
||||
{
|
||||
"id": "2d2d24ac04d84dfa",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "backlink",
|
||||
"state": {
|
||||
"file": "GDD/GDD.md",
|
||||
"collapseAll": false,
|
||||
"extraContext": false,
|
||||
"sortOrder": "alphabetical",
|
||||
"showSearch": false,
|
||||
"searchQuery": "",
|
||||
"backlinkCollapsed": false,
|
||||
"unlinkedCollapsed": true
|
||||
},
|
||||
"icon": "links-coming-in",
|
||||
"title": "Backlinks"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "9b473e8ba1177409",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "outgoing-link",
|
||||
"state": {
|
||||
"file": "GDD/GDD.md",
|
||||
"linksCollapsed": false,
|
||||
"unlinkedCollapsed": true
|
||||
},
|
||||
"icon": "links-going-out",
|
||||
"title": "Outgoing links"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "aa2f1e787db366cd",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "tag",
|
||||
"state": {
|
||||
"sortOrder": "frequency",
|
||||
"useHierarchy": true,
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-tags",
|
||||
"title": "Tags"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "29c62914f1935eb6",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "all-properties",
|
||||
"state": {
|
||||
"sortOrder": "frequency",
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-archive",
|
||||
"title": "All properties"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "8dc46f1b185ecc04",
|
||||
"type": "leaf",
|
||||
"state": {
|
||||
"type": "outline",
|
||||
"state": {
|
||||
"file": "GDD/GDD.md",
|
||||
"followCursor": false,
|
||||
"showSearch": false,
|
||||
"searchQuery": ""
|
||||
},
|
||||
"icon": "lucide-list",
|
||||
"title": "Outline"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"direction": "horizontal",
|
||||
"width": 300,
|
||||
"collapsed": true
|
||||
},
|
||||
"left-ribbon": {
|
||||
"hiddenItems": {
|
||||
"switcher:Open quick switcher": false,
|
||||
"graph:Open graph view": false,
|
||||
"canvas:Create new canvas": false,
|
||||
"daily-notes:Open today's daily note": false,
|
||||
"templates:Insert template": false,
|
||||
"command-palette:Open command palette": false,
|
||||
"bases:Create new base": false
|
||||
}
|
||||
},
|
||||
"active": "ca9ae29dd35549a6",
|
||||
"lastOpenFiles": [
|
||||
"Engine/sedb6yZpr",
|
||||
"Engine/Main Loop and Time.md",
|
||||
"Engine/Randomness.md",
|
||||
"GDD/GDD.md",
|
||||
"Home.md",
|
||||
"Game/Game Constraints.md",
|
||||
"Open Questions.md.tmp.234529.84c632e447bb",
|
||||
"Home.md.tmp.234529.043e8195cd1a",
|
||||
"GDD/Inspiration.md",
|
||||
"GDD/Inspiration.md.tmp.234529.bae427cc494d",
|
||||
"GDD/Units.md",
|
||||
"GDD/Units.md.tmp.234529.78abac70c7e3",
|
||||
"GDD/Characters.md",
|
||||
"GDD/Characters.md.tmp.234529.9a90cdbaf210",
|
||||
"GDD/Ideas/Enemy Archetypes.md",
|
||||
"GDD/Ideas/Enemy Archetypes.md.tmp.234529.be6735876c7b",
|
||||
"GDD/Ideas/Unit Archetypes.md",
|
||||
"GDD/Ideas/Unit Archetypes.md.tmp.234529.e5a9149ef6cc",
|
||||
"GDD/Ideas/Characters with own Card Pools.md",
|
||||
"GDD/Ideas/Characters with own Card Pools.md.tmp.234529.42ebd48e29e2",
|
||||
"GDD/Ideas/Resources.md",
|
||||
"GDD/Ideas/Resources.md.tmp.234529.a8ac0f0ee74e",
|
||||
"GDD/Ideas/Card Types.md",
|
||||
"GDD/Ideas/Card Types.md.tmp.234529.13bf9d1c7f6f",
|
||||
"GDD/Ideas/Gameplay Loop.md",
|
||||
"GDD/Discussions/Stages und Mapgröße.md",
|
||||
"GDD/Discussions/Einheiten Karten oder Spawn Gebäude.md",
|
||||
"GDD/Discussions/Grundlegende Gamedesign Fragen.md",
|
||||
"GDD/Discussions/GDD Workflow.md",
|
||||
"Open Questions.md",
|
||||
"Decision Log.md",
|
||||
"Engine/Build Order.md",
|
||||
"Engine/Debug and Tooling.md",
|
||||
"Engine/Audio.md",
|
||||
"Engine/Input.md",
|
||||
"Engine/Scripting.md"
|
||||
]
|
||||
}
|
||||
@@ -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]`.
|
||||
|
||||
@@ -6,7 +6,7 @@ tags:
|
||||
|
||||
# Build Order
|
||||
|
||||
- [ ] **1. Skeleton:** split CMake into `siege_engine` and `siege_deck`; write `Application`, `FrameClock`, `SimClock` and the main loop. `--frames N` keeps working. See [[Main Loop and Time]].
|
||||
- [x] **1. Skeleton:** split CMake into `siege_engine` and `siege_deck`; write `Application`, `FrameClock`, `SimClock` and the main loop. `--frames N` keeps working. See [[Main Loop and Time]].
|
||||
- [ ] **2. RenderDevice:** SDL_GPU device and swapchain, the GLSL → SPIR-V build step, clear the screen, ImGui on `imgui_impl_sdlgpu3`. See [[Rendering]].
|
||||
- [ ] **3. Renderer2D:** sprite batch, text, debug overlay.
|
||||
- [ ] **4. SceneRenderer3D:** glTF loading, instanced static meshes, camera, a ground-plane picking ray to a tile.
|
||||
|
||||
@@ -30,7 +30,7 @@ flowchart TD
|
||||
```
|
||||
|
||||
> [!important] Dependency rule
|
||||
> `Engine/` must never include anything from `Game/`. The CMake target split enforces this.
|
||||
> `Engine/` must never include anything from `Game/`. Both targets share `Source/` as their include root, so the compiler can't prevent it; the `check_engine_deps` build step (`cmake/CheckEngineDeps.cmake`) fails the build instead.
|
||||
|
||||
## Source layout
|
||||
|
||||
@@ -61,7 +61,9 @@ Source/
|
||||
|---|---|---|
|
||||
| `siege_engine` | static lib | SDL3 family, glm, EnTT, ImGui, spdlog, script runtime |
|
||||
| `siege_deck` | executable | `siege_engine` + `Game/` |
|
||||
| `siege_tests` (later) | executable | engine + game logic, headless |
|
||||
| `siege_tests` | executable | engine + game logic, headless; Catch2 v3 (`Tests/`) |
|
||||
|
||||
`ctest --preset debug` runs every `siege_tests` case (each `TEST_CASE` is its own ctest entry) plus the `smoke` test: `siege_deck --frames 30` on SDL's offscreen video driver, so it needs no display.
|
||||
|
||||
## Principles
|
||||
|
||||
|
||||
@@ -17,9 +17,8 @@ while (running) {
|
||||
|
||||
scenes.Update(frameClock.Dt()); // UI, tweens, card hand, camera: real time
|
||||
|
||||
simClock.Accumulate(frameClock.Dt() * simClock.Speed());
|
||||
int steps = 0;
|
||||
while (simClock.ConsumeStep() && steps++ < kMaxStepsPerFrame) // spiral-of-death guard
|
||||
simClock.Accumulate(frameClock.Dt()); // scaled by Speed(), backlog capped at kMaxStepsPerFrame steps
|
||||
while (simClock.ConsumeStep())
|
||||
scenes.FixedUpdate(kSimDt); // 1/60 s: movement, targeting, projectiles, damage
|
||||
|
||||
renderer.BeginFrame();
|
||||
@@ -42,7 +41,7 @@ The planning phase is simply `simClock.SetSpeed(0)`. Cards still animate and hov
|
||||
|
||||
At 1×, 2× or 3× the loop runs **more fixed steps per frame, never bigger ones**. A 3× frame runs three 1/60 s steps, not one 1/20 s step, so fast projectiles can't skip past enemies at high speed.
|
||||
|
||||
`kMaxStepsPerFrame` caps the catch-up work after a stall (window drag, breakpoint). The simulation slows down rather than freezing the frame.
|
||||
`kMaxStepsPerFrame` caps the catch-up work after a stall (window drag, breakpoint). `SimClock::Accumulate` clamps the backlog to that many steps and drops the rest, so the simulation slows down rather than freezing the frame, and the lost time never piles up across frames.
|
||||
|
||||
## Interpolation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user