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

2.4 KiB
Raw Permalink Blame History

tags
tags
engine
time

Main Loop and Time

The simulation runs on a fixed timestep, and rendering, UI and tweens run at a variable rate. This directly supports the phased game (see Game Constraints).

The loop

while (running) {
    frameClock.Tick();                         // real dt, clamped to 0.25 s
    input.BeginFrame(); PumpSdlEvents();       // ImGui sees events first and may capture them

    scenes.Update(frameClock.Dt());            // UI, tweens, card hand, camera: real time

    simClock.Accumulate(frameClock.Dt());      // scaled by Speed(), backlog capped at kMaxStepsPerFrame steps
    while (simClock.ConsumeStep())
        scenes.FixedUpdate(kSimDt);            // 1/60 s: movement, targeting, projectiles, damage

    renderer.BeginFrame();
    scenes.Render(renderer, simClock.Alpha()); // interpolate between the previous and current transform
    debugUi.Render();
    renderer.EndFrame();
}

Two clocks

Clock Drives Pausable Scaled by game speed
FrameClock UI, card hand, menus, camera, UI tweens no no
SimClock combat simulation, gameplay tweens yes (speed 0 = planning phase) yes

The planning phase is simply simClock.SetSpeed(0). Cards still animate and hover because they run on FrameClock.

Game speed

At 1×, 2× or 3× the loop runs more fixed steps per frame, never bigger ones. A 3× frame runs three 1/60 s steps, not one 1/20 s step, so fast projectiles can't skip past enemies at high speed.

kMaxStepsPerFrame caps the catch-up work after a stall (window drag, breakpoint). SimClock::Accumulate clamps the backlog to that many steps and drops the rest, so the simulation slows down rather than freezing the frame, and the lost time never piles up across frames.

Interpolation

  • A PrevTransform component is copied from Transform3D before each fixed step.
  • Rendering blends the two with SimClock::Alpha(), so motion stays smooth on high-refresh monitors while the simulation runs at 60 Hz.
  • Entities that teleport (spawns, snaps) reset PrevTransform to avoid a one-frame smear.

Timers and tweens

  • Timer and TweenSystem let you choose which clock they run on.
  • Tweens are engine-level because a deck-builder's feel is mostly tweens: fanning the hand, drawing, cards flying to targets, damage popups.

Related: Scenes and ECS, Rigid-Part Animation