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

127 lines
6.3 KiB
Markdown

# 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#<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]`.