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>
58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
---
|
||
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]]
|