OpenParable
Skip to content
← Back to skills

Game Loop

Development
game-loop

Game Loop is an Agent Skill for development published in the dadbodgeoff/drift repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Fixed timestep game loop with interpolation for frame-rate independent physics. Separates physics updates from rendering, prevents spiral of death, and supports hitstop/slow-mo effects.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/dadbodgeoff/drift/blob/HEAD/drift v1 depreciated/skills/game-loop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/game-loop, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Fixed Timestep Game Loop

Frame-rate independent game loop with physics interpolation and time manipulation.

When to Use This Skill

  • Building browser-based games or interactive simulations
  • Need consistent physics regardless of monitor refresh rate
  • Want smooth rendering with deterministic game logic
  • Implementing hitstop, slow-mo, or time manipulation effects

Core Concepts

The key insight is separating physics (fixed timestep) from rendering (variable). An accumulator tracks time debt, running physics at a consistent rate while interpolating between states for smooth visuals.

Frame → Accumulator += delta → While(accumulator >= fixedStep) { physics() } → Render(interpolation)

Implementation

TypeScript

interface GameLoopStats {
  fps: number;
  frameTime: number;
  physicsTime: number;
  renderTime: number;
  lagSpikes: number;
  interpolation: number;
  timeScale: number;
  isInHitstop: boolean;
}

interface GameLoopCallbacks {
  onFixedUpdate: (fixedDelta: number, now: number) => void;
  onRenderUpdate: (delta: number, interpolation: number, now: number) => void;
  onLagSpike?: (missedFrames: number) => void;
}

class GameLoop {
  private fixedTimestep: number;
  private readonly MAX_FRAME_TIME = 0.25;
  
  private accumulator = 0;
  private lastTime = 0;
  private interpolation = 0;
  
  private frameCount = 0;
  private fpsTimer = 0;
  private currentFps = 60;
  private lagSpikes = 0;
  
  private running = false;
  private animationId: number | null = null;
  private callbacks: GameLoopCallbacks;
  
  private hitstopTimer = 0;
  private hitstopIntensity = 0;
  private externalTimeScale = 1.0;

  constructor(callbacks: GameLoopCallbacks, fixedTimestep = 1 / 60) {
    this.callbacks = callbacks;
    this.fixedTimestep = fixedTimestep;
  }

  start(): void {
    if (this.running) return;
    this.running = true;
    this.lastTime = performance.now() / 1000;
    this.accumulator = 0;
    this.loop();
  }

  stop(): void {
    this.running = false;
    if (this.animationId !== null) {
      cancelAnimationFrame(this.animationId);
      this.animationId = null;
    }
  }

  triggerHitstop(frames = 3, intensity = 0.1): void {
    this.hitstopTimer = frames * this.fixedTimestep;
    this.hitstopIntensity = intensity;
  }

  setTimeScale(scale: number): void {
    this.externalTimeScale = Math.max(0, scale);
  }

  getStats(): GameLoopStats {
    return {
      fps: this.currentFps,
      frameTime: 0,
      physicsTime: 0,
      renderTime: 0,
      lagSpikes: this.lagSpikes,
      interpolation: this.interpolation,
      timeScale: this.getEffectiveTimeScale(),
      isInHitstop: this.hitstopTimer > 0,
    };
  }

  private loop = (): void => {
    if (!this.running) return;

    const now = performance.now() / 1000;
    let frameTime = now - this.lastTime;
    this.lastTime = now;

    // Cap frame time to prevent spiral of death
    if (frameTime > this.MAX_FRAME_TIME) {
      const missedFrames = Math.floor(frameTime / this.fixedTimestep);
      this.lagSpikes++;
      this.callbacks.onLagSpike?.(missedFrames);
      frameTime = this.MAX_FRAME_TIME;
    }

    frameTime *= this.getEffectiveTimeScale();

    if (this.hitstopTimer > 0) {
      this.hitstopTimer -= frameTime / this.getEffectiveTimeScale();
    }

    this.accumulator += frameTime;

    // Fixed timestep physics
    while (this.accumulator >= this.fixedTimestep) {
      this.callbacks.onFixedUpdate(this.fixedTimestep, now);
      this.accumulator -= this.fixedTimestep;
    }

    // Interpolation for smooth rendering
    this.interpolation = this.accumulator / this.fixedTimestep;
    this.callbacks.onRenderUpdate(frameTime, this.interpolation, now);

    // FPS calculation
    this.frameCount++;
    this.fpsTimer += frameTime / this.getEffectiveTimeScale();
    if (this.fpsTimer >= 1.0) {
      this.currentFps = Math.round(this.frameCount / this.fpsTimer);
      this.frameCount = 0;
      this.fpsTimer = 0;
    }

    this.animationId = requestAnimationFrame(this.loop);
  };

  private getEffectiveTimeScale(): number {
    return this.hitstopTimer > 0 ? this.hitstopIntensity : this.externalTimeScale;
  }
}

// Interpolation helpers
function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

function lerpAngle(a: number, b: number, t: number): number {
  let diff = b - a;
  while (diff > Math.PI) diff -= Math.PI * 2;
  while (diff < -Math.PI) diff += Math.PI * 2;
  return a + diff * t;
}

Usage Examples

// Game state
let playerX = 0, playerY = 0;
let playerVelX = 0, playerVelY = 0;
let prevPlayerX = 0, prevPlayerY = 0;

const gameLoop = new GameLoop({
  onFixedUpdate: (fixedDelta) => {
    // Store previous for interpolation
    prevPlayerX = playerX;
    prevPlayerY = playerY;

    // Deterministic physics
    playerVelY += 980 * fixedDelta; // Gravity
    playerX += playerVelX * fixedDelta;
    playerY += playerVelY * fixedDelta;

    // Collision
    if (playerY > 500) {
      playerY = 500;
      playerVelY = 0;
    }
  },

  onRenderUpdate: (delta, interpolation) => {
    // Smooth rendering between physics states
    const renderX = lerp(prevPlayerX, playerX, interpolation);
    const renderY = lerp(prevPlayerY, playerY, interpolation);

    ctx.clearRect(0, 0, canvas.width, canvas.height);
    ctx.fillRect(renderX - 10, renderY - 10, 20, 20);
  },

  onLagSpike: (missed) => console.warn(`Lag: missed ${missed} frames`),
});

gameLoop.start();

// Hitstop on collision
function onPlayerHit() {
  gameLoop.triggerHitstop(4, 0.05); // 4 frames at 5% speed
}

// Slow-mo death
function onPlayerDeath() {
  gameLoop.setTimeScale(0.3);
  setTimeout(() => gameLoop.setTimeScale(1.0), 2000);
}

Best Practices

  1. Always store previous state before physics update for interpolation
  2. Cap frame time to prevent spiral of death (0.25s is reasonable)
  3. Use fixed timestep for all game logic, variable only for rendering
  4. Tune hitstop values for game feel (2-5 frames typical)
  5. Consider 30Hz physics for mobile to save CPU

Common Mistakes

  • Running physics in render callback (frame-rate dependent)
  • Not interpolating positions (causes stuttering)
  • Forgetting to cap frame time (causes spiral of death on tab switch)
  • Using delta time for physics (non-deterministic)

Related Patterns

  • server-tick (server-side equivalent)
  • websocket-management (multiplayer sync)