π¬ Game Loop
The fixed-timestep accumulator that separates deterministic simulation updates from variable-rate rendering, with pause/resume and interpolation support.
Tests:
tests/test_gameloop.cpp(27 cases) RFs: RF2.7, RF2.8
Overview#
The Game Loop is the heart of the engine β the cycle that runs from start to finish. Caffeine implements the standard Fixed Timestep with Accumulator: it decouples physics logic (which needs consistent time) from rendering (which may vary freely).
Pattern: accumulator += dt β while (accum >= fixedDt) update(fixedDt) β render(alpha)
Inspired by Game Programming Patterns β Game Loop.
Caller responsibility:
GameLoophas no clock of its own and does not poll input β it receives a readydeltaTimethroughtick(dt). Measuring real time (for example withTimer) and pumpingSDL_PollEventis the job of the code that callstick(), usually the applicationmain.
API#
namespace Caffeine {
enum class GameState : u8 {
Init, // tick() is ignored; waiting for init()
Running, // update + render
Paused, // no fixed update; rendering continues (UI, menus)
Shutdown // tick() is ignored
};
struct GameLoopConfig {
f64 fixedDeltaTime = 1.0 / 60.0; // 60 logical updates/second
f64 maxFrameTime = 0.25; // dt clamp β avoids the "spiral of death"
u32 targetFPS = 0; // 0 = unlimited (stored; not applied by the loop)
bool vsync = true; // likewise β the RHI/window owns the real control
bool interpolation = true; // computes alpha; when false, alpha = 0
};
// Alternative interface to std::function: derive and register via
// setCallbacks(). Both mechanisms coexist and BOTH are called
// (m_callbacks first, then the std::function hooks).
class IGameCallbacks {
public:
virtual ~IGameCallbacks() = default;
virtual void onBeginFrame() {}
virtual void onFixedUpdate(f64 dt) { (void)dt; }
virtual void onRender(f64 alpha) { (void)alpha; }
virtual void onEndFrame() {}
};
class GameLoop {
public:
explicit GameLoop(const GameLoopConfig& config = {});
~GameLoop();
void init(); // Init β Running (from Init only)
void tick(f64 deltaTime); // one frame; ignored in Init/Shutdown
void pause(); // Running β Paused (from Running only)
void resume(); // Paused β Running (from Paused only)
void shutdown(); // Running/Paused β Shutdown
GameState state() const { return m_state; }
f64 elapsedTime() const { return m_elapsedTime; }
f64 interpolationAlpha() const { return m_alpha; }
u64 frameCount() const { return m_frameCount; }
f64 accumulator() const { return m_accumulator; }
void setCallbacks(IGameCallbacks* callbacks);
const GameLoopConfig& config() const { return m_config; }
// Free hooks (called AFTER IGameCallbacks when both exist)
std::function<void(f64 dt)> onFixedUpdate;
std::function<void(f64 alpha)> onRender;
std::function<void()> onBeginFrame;
std::function<void()> onEndFrame;
private:
void processFixedUpdate(f64 dt);
GameLoopConfig m_config;
IGameCallbacks* m_callbacks = nullptr;
GameState m_state = GameState::Init;
f64 m_accumulator = 0.0;
f64 m_elapsedTime = 0.0;
f64 m_alpha = 0.0;
u64 m_frameCount = 0;
};
} // namespace Caffeine
Per-frame flow (tick(dt))#
flowchart TD
START([tick dt]) --> GUARD{state Init or Shutdown?}
GUARD -->|yes| SKIP[no-op]
GUARD -->|no| BEGIN[onBeginFrame]
BEGIN --> CLAMP["dt = min(dt, maxFrameTime)"]
CLAMP --> ELAPSED[elapsedTime += dt]
ELAPSED --> RUNNING{state Running?}
RUNNING -->|no| RENDER[onRender alpha]
RUNNING -->|yes| ACC[accumulator += dt]
ACC --> LOOP{accumulator >= fixedDt?}
LOOP -->|yes| FIX[fixed update; accumulator -= fixedDt]
FIX --> LOOP
LOOP -->|no| ALPHA[alpha from interpolation]
ALPHA --> RENDER
RENDER --> END[onEndFrame; frameCount++]
Behaviour confirmed by the code and tests:
- Paused:
onRender/onBeginFrame/onEndFramestill run;accumulatorstays frozen and pending steps fire onresume(). targetFPS/vsync: only stored β the loop does not sleep or synchronize; the caller/RHI applies throttling and vsync.shutdown()fromInitis ignored (no transition).
Spiral of Death Prevention#
deltaTime = std::min(deltaTime, m_config.maxFrameTime); // default 250ms
Effect: on slow hardware the game temporarily enters slow motion instead of locking into an infinite catch-up loop.
Rendering Interpolation#
Without interpolation, entities "teleport" between positions at every fixed step:
Caffeine::Vec2 renderPos = Caffeine::Math::lerp(entity.prevPos, entity.currPos, alpha);
// alpha = 0.0 β start of the current step
// alpha = 1.0 β end of the current step
Requirement: physics systems must save prevPos before updating currPos.
With interpolation = false, alpha is always 0.0.
Usage Examples#
// ββ Basic setup βββββββββββββββββββββββββββββββββββββββββββββββ
Caffeine::GameLoopConfig cfg;
cfg.fixedDeltaTime = 1.0 / 60.0;
cfg.interpolation = true;
Caffeine::GameLoop loop(cfg);
loop.onFixedUpdate = [&](Caffeine::f64 dt) {
world.update(dt);
eventBus.dispatch();
};
loop.onRender = [&](Caffeine::f64 alpha) {
renderer.render(alpha);
};
loop.init();
// ββ Main loop (the caller measures time and pumps input) ββββββ
Caffeine::Core::Timer timer;
timer.start();
while (loop.state() != Caffeine::GameState::Shutdown) {
SDL_PumpEvents(); // or InputManager::beginFrame(), depending on the app
Caffeine::Core::Duration dt = timer.tick();
loop.tick(dt.seconds);
}
With IGameCallbacks instead of lambdas:
class MyGame : public Caffeine::IGameCallbacks {
void onFixedUpdate(Caffeine::f64 dt) override { world.update(dt); }
void onRender(Caffeine::f64 alpha) override { renderer.render(alpha); }
};
MyGame game;
loop.setCallbacks(&game);
Loop States#
stateDiagram-v2 [*] --> Init Init --> Running: init() Running --> Paused: pause() Paused --> Running: resume() Running --> Shutdown: shutdown() Paused --> Shutdown: shutdown()
| State | Behaviour |
|---|---|
Init |
tick() ignored; pause() / resume() / shutdown() ignored |
Running |
Normal loop: begin β NΓfixed update β render(alpha) β end |
Paused |
No fixed update; elapsedTime and frameCount advance; render continues |
Shutdown |
Terminal; tick() ignored |
Design Decisions#
| Decision | Rationale |
|---|---|
| Fixed timestep for logic | Deterministic physics, replay, multiplayer |
Accumulator with clamp (min) |
Avoids the "spiral of death" on slow hardware |
| Loop without its own clock/input | Testable (tick(dt) is deterministic) and not coupled to SDL |
IGameCallbacks + std::function |
Game class or lambdas, caller's choice |
targetFPS / vsync only stored |
Real throttling belongs to the RHI/window, not the loop |
Acceptance Criteria#
- [x]
tests/test_gameloop.cpp: defaults, state transitions, frame count, fixed-update rate, anti-spiral clamp,alpha β [0,1) - [x] Spiral of death does not occur: FPS may fall but the loop does not lock
- [x]
state()transitions Init β Running β Paused β Shutdown (invalid transitions ignored) - [ ] 3600 frames with
fixedDtaccumulated = 60.0 Β± 0.001 (no drift) β long-duration test still pending
Dependencies#
- Upstream: Timer (the caller measures
dt), types fromsrc/caffeine/core/Types.hpp - Downstream: ECS World (
../ecs/core.md), Renderer, Input (../input/input-system.md) β all through callbacks, no coupling
References#
src/caffeine/core/GameLoop.hpp/src/caffeine/core/GameLoop.cpptests/test_gameloop.cppdocs/architecture_specs.mdβ Β§1 Game Loopcore/timer.mdβ measures thedtfed to the loop- Game Programming Patterns β Game Loop