Files
siege_deck/Docs/SiegeDeck/Engine/Main Loop and Time.md
T
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

58 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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
```cpp
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]]