🎬 Game Loop
O acumulador de timestep fixo que separa atualizações de simulação determinísticas da renderização a ritmo variável, com pausa/retoma e interpolação.
Testes:
tests/test_gameloop.cpp(27 casos) RFs: RF2.7, RF2.8
Visão Geral#
O Game Loop é o coração da engine — o ciclo que corre do início ao fim do jogo. A Caffeine implementa o padrão Fixed Timestep com Acumulador: desvincula a lógica de física (que precisa de tempo consistente) da renderização (que pode variar livremente).
Padrão: accumulator += dt → while (accum >= fixedDt) update(fixedDt) → render(alpha)
Inspirado em Game Programming Patterns — Game Loop.
Responsabilidade do chamador: o
GameLoopnão possui clock próprio e não faz polling de input — ele recebedeltaTimepronto viatick(dt). Medir o tempo real (ex: comTimer) e bombearSDL_PollEventé tarefa do código que chamatick(), normalmente omainda aplicação.
API#
namespace Caffeine {
enum class GameState : u8 {
Init, // tick() é ignorado; aguardando init()
Running, // update + render
Paused, // sem fixed update; render continua (UI, menu)
Shutdown // tick() é ignorado
};
struct GameLoopConfig {
f64 fixedDeltaTime = 1.0 / 60.0; // 60 updates lógicos/segundo
f64 maxFrameTime = 0.25; // clamp do dt — evita "spiral of death"
u32 targetFPS = 0; // 0 = unlimited (armazenado; não aplicado pelo loop)
bool vsync = true; // idem — controle real é do RHI/janela
bool interpolation = true; // calcula alpha; se false, alpha = 0
};
// ============================================================================
// @brief Interface alternativa aos std::function: derive e registre via
// setCallbacks(). Os dois mecanismos coexistem e AMBOS são chamados
// (primeiro m_callbacks, depois os std::function).
// ============================================================================
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 (só a partir de Init)
void tick(f64 deltaTime); // um frame; ignorado em Init/Shutdown
void pause(); // Running → Paused (só a partir de Running)
void resume(); // Paused → Running (só a partir de Paused)
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; }
// Hooks livres (chamados DEPOIS do IGameCallbacks, se ambos existirem)
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
Fluxo Detalhado por Frame (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; frameCount++]
ELAPSED --> RUNNING{state Running?}
RUNNING -->|no| RENDER[onRender alpha]
RUNNING -->|yes| ACC[accumulator += dt]
ACC --> LOOP{accumulator >= fixedDt?}
LOOP -->|yes| FIX[onFixedUpdate; accumulator -= fixedDt]
FIX --> LOOP
LOOP -->|no| ALPHA[alpha from interpolation]
ALPHA --> RENDER
RENDER --> END[onEndFrame]
Notas de comportamento (confirmadas pelo código e pelos testes):
- Pausado:
onRender/onBeginFrame/onEndFramecontinuam;accumulatorfica congelado e os steps pendentes disparam ao darresume(). targetFPS/vsync: apenas armazenados — o loop não dorme nem sincroniza; cabe ao chamador/RHI aplicar throttling e vsync.shutdown()a partir deInité ignorado (sem transição).
Spiral of Death Prevention#
deltaTime = std::min(deltaTime, m_config.maxFrameTime); // default 250ms
Efeito: em hardware lento, o jogo entra em "slow motion" temporário em vez de travar num loop infinito de catch-up.
Interpolação de Renderização#
Sem interpolação, entidades "teletransportam" entre posições a cada fixed step:
Caffeine::Vec2 renderPos = Caffeine::Math::lerp(entity.prevPos, entity.currPos, alpha);
// alpha = 0.0 → início do step atual
// alpha = 1.0 → fim do step atual
Requisito: sistemas de física devem salvar prevPos antes de atualizar currPos. Com interpolation = false, alpha é sempre 0.0.
Exemplos de Uso#
// ── Setup básico ──────────────────────────────────────────────
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 (o chamador mede o tempo e bombeia input) ───────
Caffeine::Core::Timer timer;
timer.start();
while (loop.state() != Caffeine::GameState::Shutdown) {
SDL_PumpEvents(); // ou InputManager::beginFrame(), conforme o app
Caffeine::Core::Duration dt = timer.tick();
loop.tick(dt.seconds);
}
Com IGameCallbacks em vez de 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);
Estados do Loop#
stateDiagram-v2 [*] --> Init Init --> Running: init() Running --> Paused: pause() Paused --> Running: resume() Running --> Shutdown: shutdown() Paused --> Shutdown: shutdown()
| Estado | Comportamento |
|---|---|
Init |
tick() ignorado; pause()/resume()/shutdown() ignorados |
Running |
Loop normal: begin → N×fixed update → render(alpha) → end |
Paused |
Sem fixed update; elapsedTime e frameCount avançam; render continua |
Shutdown |
Terminal; tick() ignorado |
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Fixed timestep para lógica | Física determinística, replay, multiplayer |
Acumulador com clamp (min) |
Evita "spiral of death" em hardware lento |
| Loop sem clock/input próprios | Testável (tick(dt) determinístico) e sem acoplamento a SDL |
IGameCallbacks + std::function |
Classe de jogo ou lambdas, à escolha do chamador |
targetFPS/vsync só armazenados |
Throttling real pertence ao RHI/janela, não ao loop |
Critério de Aceitação#
- [x]
tests/test_gameloop.cpp: defaults, transições de estado, contagem de frames, taxa de fixed update, clamp anti-spiral,alpha ∈ [0,1) - [x] Spiral of death não ocorre: FPS pode cair mas loop não trava
- [x]
state()transiciona Init → Running ⇄ Paused → Shutdown (transições inválidas ignoradas) - [ ] 3600 frames com
fixedDtacumulado = 60.0 ± 0.001 (sem drift) — teste de longa duração ainda pendente
Dependências#
- Upstream: Timer (chamador mede
dt), tipos desrc/caffeine/core/Types.hpp - Downstream: ECS World (
../ecs/core.md), Renderer, Input (../input/input-system.md) — todos via callbacks, sem acoplamento
Referências#
src/caffeine/core/GameLoop.hpp/src/caffeine/core/GameLoop.cpptests/test_gameloop.cppdocs/architecture_specs.md— §1 Game Loopcore/timer.md— Mede odtalimentado ao loop- Game Programming Patterns — Game Loop