docs: Initialize comprehensive project documentation

Migrates existing GDD and engine design notes from HacknPlan into a new Obsidian vault.

This establishes a centralized, version-controlled knowledge base covering engine architecture, game constraints, design decisions, and open questions.
This commit is contained in:
2026-09-24 23:55:48 +02:00
parent bae6567842
commit 45b246c1d7
36 changed files with 1682 additions and 0 deletions
@@ -0,0 +1,58 @@
---
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() * simClock.Speed());
int steps = 0;
while (simClock.ConsumeStep() && steps++ < kMaxStepsPerFrame) // spiral-of-death guard
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). The simulation slows down rather than freezing the frame.
## 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]]