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:
2026-09-25 00:27:36 +02:00
co-authored by Claude Opus 5.5
parent 45b246c1d7
commit 384f1ed1f2
26 changed files with 1072 additions and 271 deletions
+133
View File
@@ -0,0 +1,133 @@
#include "Engine/Time/SimClock.h"
#include <catch2/catch_test_macros.hpp>
#include <catch2/generators/catch_generators.hpp>
#include <catch2/generators/catch_generators_adapters.hpp>
#include <catch2/generators/catch_generators_random.hpp>
#include <catch2/matchers/catch_matchers_floating_point.hpp>
using namespace SiegeDeck::Engine;
using Catch::Matchers::WithinAbs;
namespace
{
constexpr double kStep = 1.0 / 60.0;
// One frame of the main loop: feed real time in, count the steps that come out.
int32 RunFrame(SimClock& clock, double realDt)
{
clock.Accumulate(realDt);
int32 steps = 0;
while (clock.ConsumeStep())
++steps;
return steps;
}
int32 RunFrames(SimClock& clock, double realDt, int32 frames)
{
int32 steps = 0;
for (int32 i = 0; i < frames; ++i)
steps += RunFrame(clock, realDt);
return steps;
}
}
TEST_CASE("SimClock runs 60 steps per simulated second at any frame rate", "[time]")
{
double fps = GENERATE(30.0, 60.0, 75.0, 144.0, 240.0);
CAPTURE(fps);
SimClock clock { kStep, 8 };
int32 steps = RunFrames(clock, 1.0 / fps, static_cast<int32>(fps));
// Rounding can leave the last step a hair short; it runs on the next frame instead.
CHECK(steps >= 59);
CHECK(steps <= 60);
}
TEST_CASE("SimClock speed runs more steps, never bigger ones", "[time]")
{
double speed = GENERATE(2.0, 3.0);
CAPTURE(speed);
SimClock clock { kStep, 8 };
clock.SetSpeed(speed);
int32 steps = RunFrames(clock, kStep, 60);
CHECK(steps >= static_cast<int32>(60 * speed) - 1);
CHECK(steps <= static_cast<int32>(60 * speed));
CHECK(clock.StepDt() == kStep);
}
TEST_CASE("SimClock speed 0 pauses without disturbing interpolation", "[time]")
{
SimClock clock { kStep, 8 };
RunFrame(clock, kStep * 0.5);
double alpha = clock.Alpha();
uint64 stepsBefore = clock.StepIndex();
clock.SetSpeed(0.0);
REQUIRE(clock.Paused());
CHECK(RunFrames(clock, kStep, 120) == 0);
CHECK(clock.StepIndex() == stepsBefore);
CHECK(clock.Alpha() == alpha); // nothing snaps while paused
SECTION("resuming picks up where it left off")
{
clock.SetSpeed(1.0);
CHECK(RunFrame(clock, kStep * 0.5) == 1);
CHECK_THAT(clock.Alpha(), WithinAbs(0.0, 1e-9));
}
}
TEST_CASE("SimClock treats negative speed as paused", "[time]")
{
SimClock clock { kStep, 8 };
clock.SetSpeed(-2.0);
CHECK(clock.Speed() == 0.0);
CHECK(RunFrame(clock, 1.0) == 0);
}
TEST_CASE("SimClock caps catch-up work after a stall and drops the backlog", "[time]")
{
SimClock clock { kStep, 8 };
int32 stalled = RunFrame(clock, 0.25); // 15 steps' worth of time
CHECK(stalled >= 7);
CHECK(stalled <= 8);
// The dropped time is gone for good: the next normal frame is a normal frame.
CHECK(RunFrame(clock, kStep) == 1);
}
TEST_CASE("SimClock alpha stays in [0, 1)", "[time]")
{
double dt = GENERATE(take(50, random(0.0, 0.3)));
CAPTURE(dt);
SimClock clock { kStep, 8 };
for (int32 i = 0; i < 20; ++i)
{
RunFrame(clock, dt);
CHECK(clock.Alpha() >= 0.0);
CHECK(clock.Alpha() < 1.0);
}
}
TEST_CASE("SimClock time is steps times the step length", "[time]")
{
SimClock clock { kStep, 8 };
RunFrames(clock, kStep, 90);
CHECK(clock.StepIndex() == 90);
CHECK_THAT(clock.Time(), WithinAbs(1.5, 1e-12));
}
TEST_CASE("SimClock rejects a broken configuration", "[time]")
{
CHECK_THROWS_AS((SimClock { 0.0, 8 }), std::invalid_argument);
CHECK_THROWS_AS((SimClock { -kStep, 8 }), std::invalid_argument);
CHECK_THROWS_AS((SimClock { kStep, 0 }), std::invalid_argument);
}