Files
siege_deck/AGENTS.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

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 .#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#<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); 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 <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::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].