Files
siege_deck/Docs/SiegeDeck/Engine/Engine Overview.md
T
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

87 lines
3.7 KiB
Markdown

---
tags:
- engine
- architecture
---
# Engine Overview
## Scope
The **engine** is game-agnostic. It knows nothing about cards, towers, lanes or waves. It provides:
- the main loop and time model
- windowing and platform services
- input, rendering, assets and audio
- a script host
- scenes and an ECS world
- RNG
- debug tooling
The **game** layer defines everything specific to the tower defense deck-builder.
```mermaid
flowchart TD
Main[Main.cpp] --> Game
Game[Game layer<br/>cards · deck · towers · enemies · lanes · waves · run map] --> Engine
Scripts[Content scripts<br/>Assets/Scripts] -. bound via .-> Game
Engine[siege_engine<br/>loop · render · assets · audio · input · script host · scenes · ECS] --> Libs
Libs[SDL3 · SDL_GPU · SDL_image · SDL_ttf · SDL_mixer · glm · EnTT · ImGui · spdlog]
```
> [!important] Dependency rule
> `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
```
Source/
Engine/ static lib `siege_engine`
Core/ Log, Assert, Result (std::expected), Id/Handle, StringId
Platform/ Window, SDL init, paths (base/pref), file watcher
Time/ FrameClock, SimClock, Timer, Tween
Input/ InputState, ActionMap
Render/ RenderDevice, SceneRenderer3D, Renderer2D, Camera, text
Animation/ rigid node clips, animator
Assets/ AssetManager, Handle<T>, loaders, hot reload
Audio/ AudioSystem (buses, voice limiting)
Script/ ScriptHost / backend (language TBD)
Scene/ Scene, SceneStack
Ecs/ World (entt::registry wrapper), common components
Random/ Rng, RngStreams
Debug/ ImGui layer, panel registry, script console, profiling
Application.h/.cpp
Game/ everything specific to siege-deck
Main.cpp a few lines: build AppConfig, run the game
```
## CMake targets
| Target | Kind | Links |
|---|---|---|
| `siege_engine` | static lib | SDL3 family, glm, EnTT, ImGui, spdlog, script runtime |
| `siege_deck` | executable | `siege_engine` + `Game/` |
| `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
1. **No singletons.** `Application` owns every subsystem and passes an `EngineContext&` to scenes. That keeps code testable and allows a headless run (the existing `--frames N` flag).
2. **Handles over shared ownership.** Assets are `Handle<T>` (index plus generation), not `Ref<T>`. See [[Assets]].
3. **Instances reference definitions by ID.** A live tower stores a `DefId`, never a copy of its definition, so hot-reloaded content takes effect immediately.
4. **Scripts on events, C++ per tick.** See [[Scripting]].
5. **Single-threaded by design.** Asynchronous asset loading can come later behind the same API.
6. **Recoverable errors are values; fatal ones are exceptions.** Loaders return `std::expected`: a broken asset or script logs an error and falls back, it doesn't crash. Startup failures and broken invariants throw from constructors and are caught once in `main`. See [[Decision Log#Error handling split]].
## Subsystems
- [[Main Loop and Time]]
- [[Scenes and ECS]]
- [[Rendering]] and [[Rigid-Part Animation]]
- [[Assets]]
- [[Scripting]]
- [[Randomness]]
- [[Input]]
- [[Audio]]
- [[Debug and Tooling]]