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

3.7 KiB

tags
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.

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