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
+124
View File
@@ -0,0 +1,124 @@
//
// Created by darman on 9/24/26.
//
#include "Application.h"
#include <SDL3/SDL.h>
#include <spdlog/spdlog.h>
#include <charconv>
#include <string_view>
#include <utility>
namespace SiegeDeck::Engine
{
namespace
{
std::expected<uint64, string> ParseUInt(std::string_view flag, std::string_view value)
{
uint64 result = 0;
auto [end, ec] = std::from_chars(value.data(), value.data() + value.size(), result);
if (ec != std::errc() || end != value.data() + value.size())
return std::unexpected(std::format("{} expects a non-negative integer, got '{}'", flag, value));
return result;
}
}
std::expected<AppConfig, string> AppConfig::FromArgs(int argc, char* argv[])
{
AppConfig config;
for (int i = 1; i < argc; ++i)
{
std::string_view arg = argv[i];
if (arg == "--fullscreen")
{
config.Fullscreen = true;
continue;
}
if (arg != "--frames" && arg != "--seed")
return std::unexpected(std::format("unknown argument '{}'", arg));
if (i + 1 >= argc)
return std::unexpected(std::format("{} expects a value", arg));
auto value = ParseUInt(arg, argv[++i]);
if (!value)
return std::unexpected(value.error());
if (arg == "--frames")
config.MaxFrames = *value;
else
config.Seed = *value;
}
return config;
}
Application::Application(AppConfig appConfig)
: config(std::move(appConfig)),
sdl(config.Title, config.Version),
window(sdl,
WindowDesc {
.Title = config.Title,
.Width = config.Width,
.Height = config.Height,
.Fullscreen = config.Fullscreen,
}),
context {
.App = *this,
.MainWindow = window,
.Frame = frameClock,
.Sim = simClock,
}
{
}
Application::~Application() = default;
int Application::Run()
{
while (running)
{
frameClock.Tick();
HandleEvents();
// scenes.Update(frameClock.Dt()) goes here: UI, card hand, camera.
simClock.Accumulate(frameClock.Dt());
while (simClock.ConsumeStep())
{
// scenes.FixedUpdate(simClock.StepDt()) goes here: movement, targeting, damage.
}
DrawFrame(simClock.Alpha());
if (config.MaxFrames && frameClock.FrameCount() >= *config.MaxFrames)
Quit();
}
spdlog::info("Ran {} frames, {} sim steps in {:.2f} s", frameClock.FrameCount(), simClock.StepIndex(),
frameClock.Time());
return 0;
}
void Application::HandleEvents()
{
SDL_Event event;
while (SDL_PollEvent(&event))
{
if (event.type == SDL_EVENT_QUIT)
Quit();
}
}
void Application::DrawFrame(double /*alpha*/)
{
// Wayland doesn't map a window until a frame is presented. Stand-in for RenderDevice's
// clear + present; a window surface can't be combined with SDL_GPU, so this goes in step 2.
SDL_Surface* surface = SDL_GetWindowSurface(window.Handle());
SDL_FillSurfaceRect(surface, nullptr, SDL_MapSurfaceRGB(surface, 24, 26, 32));
SDL_UpdateWindowSurface(window.Handle());
SDL_Delay(16); // no vsync yet
}
}
+77
View File
@@ -0,0 +1,77 @@
//
// Created by darman on 9/24/26.
//
#pragma once
#include "Engine/Platform/SdlContext.h"
#include "Engine/Platform/Window.h"
#include "Engine/Time/FrameClock.h"
#include "Engine/Time/SimClock.h"
#include <expected>
namespace SiegeDeck::Engine
{
class Application;
struct AppConfig
{
string Title = "Siege Deck";
string Version = "0.1.0";
int32 Width = 1280;
int32 Height = 720;
bool Fullscreen = false;
bool Vsync = false;
uint64 Seed = 0;
Optional<uint64> MaxFrames = None;
// Bad arguments are reported, not thrown: main prints them and exits with a usage error.
static std::expected<AppConfig, string> FromArgs(int argc, char* argv[]);
};
struct EngineContext
{
Application& App;
Window& MainWindow;
const FrameClock& Frame; // real time: UI, card hand, camera
SimClock& Sim; // sim time: SetSpeed(0) is the planning phase
};
class Application
{
public:
explicit Application(AppConfig appConfig);
~Application();
Application(const Application&) = delete;
Application& operator=(const Application&) = delete;
Application(Application&&) = delete;
Application& operator=(Application&&) = delete;
int Run();
void Quit() { running = false; };
EngineContext& GetContext() { return context; }
private:
void HandleEvents();
void DrawFrame(double alpha);
static constexpr double kSimDt = 1.0 / 60.0;
static constexpr int32 kMaxStepsPerFrame = 8;
AppConfig config;
// Members are constructed in declaration order and destroyed in reverse,
// so anything that depends on another subsystem is declared after it.
SdlContext sdl;
Window window;
FrameClock frameClock;
SimClock simClock { kSimDt, kMaxStepsPerFrame };
EngineContext context;
bool running = true;
};
}
+32
View File
@@ -0,0 +1,32 @@
//
// Created by darman on 9/24/26.
//
#include "SdlContext.h"
#include <SDL3/SDL.h>
#include <spdlog/spdlog.h>
namespace SiegeDeck::Engine
{
SdlContext::SdlContext(const string& appName, const string& appVersion)
{
// Must precede SDL_Init: some platforms read it during init (audio stream names, Wayland app id).
SDL_SetAppMetadata(appName.c_str(), appVersion.c_str(), nullptr);
// If this throws, the destructor doesn't run, and SDL_Init has cleaned up after itself.
if (!SDL_Init(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD))
throw std::runtime_error(std::format("SDL_Init failed: {}", SDL_GetError()));
int version = SDL_GetVersion();
spdlog::info("SDL {}.{}.{} ({} video)", SDL_VERSIONNUM_MAJOR(version), SDL_VERSIONNUM_MINOR(version),
SDL_VERSIONNUM_MICRO(version), SDL_GetCurrentVideoDriver());
}
SdlContext::~SdlContext()
{
SDL_Quit();
}
}
+31
View File
@@ -0,0 +1,31 @@
//
// Created by darman on 9/24/26.
//
#pragma once
namespace SiegeDeck::Engine
{
// Owns the process-wide SDL_Init / SDL_Quit pair. Anything that talks to SDL
// must be declared after this in Application, so it is torn down first.
//
// Only core subsystems are initialized here. Audio belongs to AudioSystem, which
// brings it up through SDL_mixer, so a machine without an audio device can still
// run the headless --frames smoke test.
//
// Exactly one per process, and never relocated: not copyable, not movable.
class SdlContext
{
public:
// Throws std::runtime_error if SDL can't initialize (fatal: nothing to fall back to).
SdlContext(const string& appName, const string& appVersion);
~SdlContext();
SdlContext(const SdlContext&) = delete;
SdlContext& operator=(const SdlContext&) = delete;
SdlContext(SdlContext&&) = delete;
SdlContext& operator=(SdlContext&&) = delete;
};
}
+61
View File
@@ -0,0 +1,61 @@
//
// Created by darman on 9/24/26.
//
#include "Window.h"
#include <SDL3/SDL.h>
#include <spdlog/spdlog.h>
namespace SiegeDeck::Engine
{
Window::Window(const SdlContext& /*sdl*/, const WindowDesc& desc)
{
// No SDL_WINDOW_VULKAN etc.: SDL_ClaimWindowForGPUDevice picks the backend later.
SDL_WindowFlags flags = SDL_WINDOW_HIGH_PIXEL_DENSITY;
if (desc.Resizable)
flags |= SDL_WINDOW_RESIZABLE;
if (desc.Fullscreen)
flags |= SDL_WINDOW_FULLSCREEN;
handle.reset(SDL_CreateWindow(desc.Title.c_str(), desc.Width, desc.Height, flags));
if (!handle)
throw std::runtime_error(std::format("SDL_CreateWindow failed: {}", SDL_GetError()));
glm::ivec2 pixels = PixelSize();
spdlog::info("Window {}x{} ({}x{} px, scale {:.2f})", desc.Width, desc.Height, pixels.x, pixels.y,
DisplayScale());
}
SDL_WindowID Window::Id() const
{
return SDL_GetWindowID(handle.get());
}
glm::ivec2 Window::Size() const
{
glm::ivec2 size { 0 };
SDL_GetWindowSize(handle.get(), &size.x, &size.y);
return size;
}
glm::ivec2 Window::PixelSize() const
{
glm::ivec2 size { 0 };
SDL_GetWindowSizeInPixels(handle.get(), &size.x, &size.y);
return size;
}
float Window::DisplayScale() const
{
float scale = SDL_GetWindowDisplayScale(handle.get());
return scale > 0.0f ? scale : 1.0f; // 0 means SDL couldn't tell
}
void Window::SetTitle(const string& title)
{
SDL_SetWindowTitle(handle.get(), title.c_str());
}
}
+59
View File
@@ -0,0 +1,59 @@
//
// Created by darman on 9/24/26.
//
#pragma once
#include <SDL3/SDL_video.h>
#include <glm/vec2.hpp>
namespace SiegeDeck::Engine
{
class SdlContext;
struct WindowDesc
{
string Title { "Siege Deck" };
int32 Width { 1600 }; // logical size; the backbuffer is larger on high-DPI displays
int32 Height { 900 };
bool Resizable { true };
bool Fullscreen { false }; // borderless desktop fullscreen, not an exclusive mode change
};
// Not movable: a Window that exists always has a live SDL_Window, and the render
// device and ImGui backend will hold on to it by reference.
class Window
{
public:
// Takes the SdlContext only as proof that SDL is initialized.
// Throws std::runtime_error if the window can't be created.
Window(const SdlContext& sdl, const WindowDesc& desc);
Window(const Window&) = delete;
Window& operator=(const Window&) = delete;
Window(Window&&) = delete;
Window& operator=(Window&&) = delete;
[[nodiscard]] SDL_Window* Handle() const { return handle.get(); }
[[nodiscard]] SDL_WindowID Id() const;
// Logical size, for UI layout and mouse coordinates.
[[nodiscard]] glm::ivec2 Size() const;
// Backbuffer size, for the swapchain and viewport.
[[nodiscard]] glm::ivec2 PixelSize() const;
// Content scale of the current display (1.0 = 96 DPI), for sizing UI and fonts.
[[nodiscard]] float DisplayScale() const;
void SetTitle(const string& title);
private:
struct Destroy
{
void operator()(SDL_Window* window) const { SDL_DestroyWindow(window); }
};
UniqueRef<SDL_Window, Destroy> handle;
};
}
+30
View File
@@ -0,0 +1,30 @@
//
// Created by darman on 9/24/26.
//
#include "FrameClock.h"
#include <SDL3/SDL_timer.h>
#include <algorithm>
namespace SiegeDeck::Engine
{
FrameClock::FrameClock() : frequency(SDL_GetPerformanceFrequency()), lastCounter(SDL_GetPerformanceCounter())
{
}
void FrameClock::Tick()
{
uint64 now = SDL_GetPerformanceCounter();
// The first frame measures from construction (startup time), which would read as one long hitch.
double elapsed = frameCount == 0 ? 0.0 : static_cast<double>(now - lastCounter) / frequency;
lastCounter = now;
dt = std::min(elapsed, kMaxDt);
time += dt;
++frameCount;
}
}
+40
View File
@@ -0,0 +1,40 @@
//
// Created by darman on 9/24/26.
//
#pragma once
namespace SiegeDeck::Engine
{
// Real (wall-clock) time between frames. Drives UI, the card hand, menus, the camera
// and UI tweens: things that keep moving while the simulation is paused.
// Not pausable and not scaled by game speed; see SimClock for that.
class FrameClock
{
public:
// A frame longer than this (window drag, breakpoint, loading hitch) counts as this long,
// so nothing driven by Dt() jumps across the screen afterwards.
static constexpr double kMaxDt = 0.25;
FrameClock();
// Call once at the start of every frame. The first call yields Dt() == 0.
void Tick();
// Seconds since the previous Tick(), clamped to kMaxDt.
[[nodiscard]] double Dt() const { return dt; }
// Sum of all clamped Dt()s: time the game has seen, not wall-clock uptime.
[[nodiscard]] double Time() const { return time; }
[[nodiscard]] uint64 FrameCount() const { return frameCount; }
private:
uint64 frequency;
uint64 lastCounter;
double dt = 0.0;
double time = 0.0;
uint64 frameCount = 0;
};
}
+41
View File
@@ -0,0 +1,41 @@
//
// Created by darman on 9/24/26.
//
#include "SimClock.h"
#include <algorithm>
namespace SiegeDeck::Engine
{
SimClock::SimClock(double stepDt, int32 maxStepsPerFrame)
: stepDt(stepDt), maxBacklog(stepDt * maxStepsPerFrame)
{
if (stepDt <= 0.0 || maxStepsPerFrame < 1)
throw std::invalid_argument("SimClock needs a positive step and at least one step per frame");
}
void SimClock::Accumulate(double realDt)
{
// Capping here, not in the step loop, keeps the caller's loop a plain while. It also
// means a stall loses its excess time for good instead of piling up across frames.
accumulator = std::min(accumulator + realDt * speed, maxBacklog);
}
bool SimClock::ConsumeStep()
{
if (accumulator < stepDt)
return false;
accumulator -= stepDt;
++stepIndex;
return true;
}
void SimClock::SetSpeed(double newSpeed)
{
// The accumulator is kept on pause, so Alpha() holds still and paused entities don't snap.
speed = std::max(newSpeed, 0.0);
}
}
+54
View File
@@ -0,0 +1,54 @@
//
// Created by darman on 9/24/26.
//
#pragma once
namespace SiegeDeck::Engine
{
// Fixed-timestep simulation time. Real time is fed in each frame, scaled by Speed(),
// and handed out again as whole steps of StepDt():
//
// sim.Accumulate(frame.Dt());
// while (sim.ConsumeStep())
// FixedUpdate(sim.StepDt());
// Render(sim.Alpha());
//
// Speed 0 is the planning phase. 2x and 3x run more steps per frame, never bigger ones,
// so fast projectiles can't skip past enemies at high speed.
class SimClock
{
public:
// maxStepsPerFrame caps catch-up work after a stall: past it, the backlog is dropped
// and the simulation slows down instead of freezing the frame (the spiral of death).
SimClock(double stepDt, int32 maxStepsPerFrame);
void Accumulate(double realDt);
// True if a whole step is available; consumes it and advances Time() and StepIndex().
bool ConsumeStep();
// 0 pauses. Negative values are treated as 0.
void SetSpeed(double newSpeed);
[[nodiscard]] double Speed() const { return speed; }
[[nodiscard]] bool Paused() const { return speed == 0.0; }
[[nodiscard]] double StepDt() const { return stepDt; }
// How far between the previous and the current step the renderer is, in [0, 1).
// Blend PrevTransform -> Transform3D by this.
[[nodiscard]] double Alpha() const { return accumulator / stepDt; }
// Simulated seconds and steps since construction. Stops advancing while paused.
[[nodiscard]] double Time() const { return static_cast<double>(stepIndex) * stepDt; }
[[nodiscard]] uint64 StepIndex() const { return stepIndex; }
private:
double stepDt;
double maxBacklog;
double speed = 1.0;
double accumulator = 0.0;
uint64 stepIndex = 0;
};
}
+25 -2
View File
@@ -1,6 +1,29 @@
#include <iostream>
#include "Engine/Application.h"
#include <spdlog/spdlog.h>
using namespace SiegeDeck;
int main(const int argc, char** argv)
{
std::cout << "Hello World!" << std::endl;
auto config = Engine::AppConfig::FromArgs(argc, argv);
if (!config)
{
spdlog::error("{}", config.error());
spdlog::info("usage: {} [--frames N] [--seed N] [--fullscreen]", argv[0]);
return 2;
}
// Fatal errors (startup, broken invariants) are exceptions and end up here. Recoverable
// ones (assets, scripts) are std::expected and are handled where they happen.
try
{
Engine::Application app { std::move(*config) };
return app.Run();
}
catch (const std::exception& e)
{
spdlog::critical("{}", e.what());
return 1;
}
}