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>
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# 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]`.
|
||||
Reference in New Issue
Block a user