--- 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
cards · deck · towers · enemies · lanes · waves · run map] --> Engine Scripts[Content scripts
Assets/Scripts] -. bound via .-> Game Engine[siege_engine
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, 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` (index plus generation), not `Ref`. 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]]