React Game Loop Hooks#

Production-ready custom React hooks for game loops and animations using requestAnimationFrame.

Installation#

Copy the hook file into your project:

bash

# From your skill directory
cp <skill-dir>/assets/hooks/useGameLoop.ts src/hooks/

<skill-dir> resolves to your OpenClaw skill installation directory.

Dependencies#

• React >= 16.8 (hooks support)
• TypeScript >= 4.0 (for type safety)
• react-dom >= 16.8 (for requestAnimationFrame types in browser environment)

This is a browser-only hook — it requires requestAnimationFrame, which is not available in Node.js or SSR environments.

API Reference#

useGameLoop(options)#

ts

import { useGameLoop } from './hooks/useGameLoop';

Parameters:

OptionTypeDefaultDescriptiononFrame``(deltaTime: number, elapsedTime: number) => void—Called every frame with delta (ms) and elapsed time (ms). Required.maxDeltaTime``number``100Maximum delta clamp in ms. Prevents huge jumps after tab-switch or lag.

Returns:

FieldTypeDescriptionstart``() => voidStart the game loopstop``() => voidStop the game loopisRunning``booleanCurrent loop state

Patterns#

Stale-closure safety#

Use useRef for callbacks/state read inside async/closure contexts (e.g. requestAnimationFrame, setInterval, event listeners). Always sync ref in useEffect.

ts

const cbRef = useRef(onFrame);
useEffect(() => { cbRef.current = onFrame; }, [onFrame]);

Cleanup on unmount#

Always return cleanup from useEffect. For RAF/intervals, store handle in ref and cancel on unmount.

ts

useEffect(() => {
  const id = requestAnimationFrame(tick);
  return () => cancelAnimationFrame(id);
}, []);

Error resilience#

Wrap user callbacks in try/catch so errors don't break internal loop state.

ts

try {
  callbackRef.current(delta, elapsed);
} catch (err) {
  console.error('hook callback error:', err);
}

Delta-time clamping#

For game loops, clamp deltaTime to avoid huge jumps after tab-switch or lag spikes.

ts

const delta = Math.min(rawDelta, maxDeltaTime);

Example#

See assets/examples/GameTimer.tsx for a complete usage example showing elapsed time and FPS display.

Reference#

• assets/hooks/useGameLoop.ts — requestAnimationFrame-based game loop with start/stop/isRunning controls, deltaTime clamping, and error resilience
• assets/examples/GameTimer.tsx — basic usage example