# AGENTS.md Guidance for coding agents working in this repository. The README covers human setup (direnv, CLion, clangd); this file covers what you need to change code safely. ## What this is Siege Deck: a from-scratch tower defense deck-builder in C++26 on SDL3. Rounds are a paused planning phase (play cards, place towers) followed by a real-time wave. Towers sit on a tile grid; enemies walk fixed lanes. Rendering is rigid-part 3D on SDL_GPU; the simulation is 2D on the ground plane. ## Build and test Everything needs the nix devShell. Outside direnv, wrap every command in `nix develop --command bash -c '...'`. ```sh cmake --preset debug # configure (Ninja) into cmake-build-debug/ cmake --build --preset debug # siege_engine, siege_deck, siege_tests ctest --preset debug # Catch2 cases + the headless smoke test ./cmake-build-debug/bin/siege_deck --frames 30 ``` - `nix develop .#gcc` gives the same shell with gcc 15. Build with both before calling anything done: gcc is stricter about name lookup (a member can't be named like its type, e.g. `Window& Window;`). - The smoke test runs `siege_deck --frames 30` with `SDL_VIDEO_DRIVER=offscreen`, so it needs no display. - A bare `ctest` from a build directory that isn't a preset works too; `--preset` only adds `outputOnFailure`. - `python3` is not installed. Use sed/awk, a heredoc, or a `cmake -P` script. ## Layout ``` Source/ Common.h, Pch.h vocabulary types; Pch.h is force-included everywhere Engine/ static lib siege_engine: game-agnostic Game/ everything specific to Siege Deck (still empty) Main.cpp parses AppConfig, runs Application Tests/ siege_tests (Catch2 v3), mirrors Source/ Docs/SiegeDeck/ Obsidian vault: design docs, GDD, Decision Log cmake/ CPM bootstrap, ImGui build, CheckEngineDeps.cmake, CLion env ``` The planned engine layout (Core, Platform, Time, Input, Render, Assets, Audio, Script, Scene, Ecs, Random, Debug) is in `Docs/SiegeDeck/Engine/Engine Overview.md`. Put new engine code where that page says it goes. ## Rules that are enforced - **Engine never includes Game.** Both targets use `Source/` as the include root, so the compiler can't stop it. `check_engine_deps` fails the build if any file under `Source/Engine` includes `Game/...`. - **New source files go in `CMakeLists.txt` by hand.** No globbing. Engine files are listed in `add_library(siege_engine ...)`, tests in `add_executable(siege_tests ...)`. - **Dependencies are pinned twice, to the same version.** Each dependency is a `CPMAddPackage` whose `VERSION` matches nixpkgs, plus an entry in `flake.nix`'s `deps`. `NAME` must be the `find_package` name. Bumping one side means bumping the other. Check the nixpkgs version with `nix eval --raw --inputs-from . nixpkgs#.version`. ## Conventions - **Formatting:** `.clang-format` (Allman braces, 4 spaces, namespace bodies indented, 110 columns, `Type name { value }` with spaces around braces). - **Naming:** types, functions and public struct fields in PascalCase (`AppConfig::MaxFrames`); private members and locals in camelCase with no prefix (`frameClock`); constants `kName`. Constructor parameters must not shadow members: in an initializer list, later initializers would read the moved-from parameter. - **Vocabulary types from `Common.h`:** `int32`, `uint64`, `string`, `Vector`, `Map`, `Optional`/`None`, `Ref`/`MakeRef`, `UniqueRef`/`MakeUniqueRef`. Headers rely on `Pch.h` and don't include `Common.h` themselves. - **Namespaces:** `SiegeDeck::Engine` (nested-name form, not nested blocks). File-local helpers go in an unnamed namespace; clang-tidy's `misc-*` flags `static` and external-linkage helpers. - **File header:** new files start with the `// Created by darman on ` block the IDE writes. - **Comments:** explain *why*, not what. Match the existing density. ## Error handling Recoverable errors are values; fatal ones are exceptions (Decision Log: "Error handling split"). - `std::expected` for failures the caller handles on the spot: asset/script/definition loading, CLI parsing. Callers log and fall back, which hot reload depends on. - Exceptions (`std::runtime_error`, `std::invalid_argument`) for startup failures and broken invariants. Constructors throw; `main` catches once, logs, and exits with 1. - Platform types are plain RAII: throwing constructor, non-movable when there's exactly one (`SdlContext`, `Window`), no empty or moved-from state. - Never let an exception cross a C callback (SDL, the script VM). ## Architecture in brief - `Application` owns every subsystem as a member. **Declaration order is lifetime order**: a subsystem is declared after everything it depends on. Scenes reach the engine through `EngineContext` (a struct of references). No singletons, no globals. - Two clocks: `FrameClock` (real time, for UI/cards/camera, never paused) and `SimClock` (fixed 1/60 s steps, `SetSpeed(0)` is the planning phase, 2x/3x runs more steps rather than bigger ones). See `Docs/SiegeDeck/Engine/Main Loop and Time.md`. - Runs are seeded (`--seed`); combat does not need to replay bit-exactly. ## Docs The vault in `Docs/SiegeDeck/` is the design source of truth. It uses Obsidian `[[wikilinks]]`. - `Engine/Build Order.md`: the roadmap. Tick the checkbox when you finish a step. - `Decision Log.md`: append an entry (date, status, context, decision, consequences) for any architectural decision. Newest at the bottom. - `Open Questions.md`: things still undecided (e.g. the scripting language). - When code diverges from a doc, update the doc in the same change. - Don't edit `Docs/SiegeDeck/.obsidian/`. ## Gotchas - **Wayland shows no window until a frame is presented.** Until `RenderDevice` exists, `Application::DrawFrame` fills the window surface each frame. Window surfaces can't be mixed with SDL_GPU, so that stand-in goes away in Build Order step 2. - **clang-tidy on the command line fails** with a PCH `__OPTIMIZE__` mismatch against `cmake-build-debug`. clangd in the editor is fine. - **The compositor may resize the window** (tiling). Read `Window::Size()` and `PixelSize()` every frame; don't cache the requested size. - **`FrameClock` tests sleep for real**, so timing bounds are loose, and the slow one is tagged `[slow]`.