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>
6.3 KiB
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 '...'.
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 .#gccgives 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 30withSDL_VIDEO_DRIVER=offscreen, so it needs no display. - A bare
ctestfrom a build directory that isn't a preset works too;--presetonly addsoutputOnFailure. python3is not installed. Use sed/awk, a heredoc, or acmake -Pscript.
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_depsfails the build if any file underSource/EngineincludesGame/.... - New source files go in
CMakeLists.txtby hand. No globbing. Engine files are listed inadd_library(siege_engine ...), tests inadd_executable(siege_tests ...). - Dependencies are pinned twice, to the same version. Each dependency is a
CPMAddPackagewhoseVERSIONmatches nixpkgs, plus an entry inflake.nix'sdeps.NAMEmust be thefind_packagename. Bumping one side means bumping the other. Check the nixpkgs version withnix eval --raw --inputs-from . nixpkgs#<pkg>.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); constantskName. 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 onPch.hand don't includeCommon.hthemselves. - Namespaces:
SiegeDeck::Engine(nested-name form, not nested blocks). File-local helpers go in an unnamed namespace; clang-tidy'smisc-*flagsstaticand external-linkage helpers. - File header: new files start with the
// Created by darman on <date>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::expectedfor 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;maincatches 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
Applicationowns every subsystem as a member. Declaration order is lifetime order: a subsystem is declared after everything it depends on. Scenes reach the engine throughEngineContext(a struct of references). No singletons, no globals.- Two clocks:
FrameClock(real time, for UI/cards/camera, never paused) andSimClock(fixed 1/60 s steps,SetSpeed(0)is the planning phase, 2x/3x runs more steps rather than bigger ones). SeeDocs/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
RenderDeviceexists,Application::DrawFramefills 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 againstcmake-build-debug. clangd in the editor is fine. - The compositor may resize the window (tiling). Read
Window::Size()andPixelSize()every frame; don't cache the requested size. FrameClocktests sleep for real, so timing bounds are loose, and the slow one is tagged[slow].