AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

game-engine

Expert skill for building web-based game engines and games using HTML5, Canvas, WebGL, and JavaScript. Use when asked to create games, build game engines, implement game physics, handle collision detection, set up game loops, manage sprites, add game controls, or work with 2D/3D rendering. Covers techniques for platformers, breakout-style games, maze games, tilemaps, audio, multiplayer via WebRTC, and publishing games.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--game-engine at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 15

references/basics.md

Game Development Basics

A comprehensive reference covering web game development technologies, game architecture, and the anatomy of a game loop.

Sources:

  • https://developer.mozilla.org/en-US/docs/Games/Introduction
  • https://developer.mozilla.org/en-US/docs/Games/Anatomy

Web Technologies for Game Development

Graphics and Rendering

  • WebGL -- Hardware-accelerated 2D and 3D graphics based on OpenGL ES 2.0. Provides direct GPU access for high-performance rendering.
  • Canvas API -- 2D drawing surface via the <canvas> element. Suitable for 2D games, sprite rendering, and pixel manipulation.
  • SVG -- Scalable Vector Graphics for resolution-independent visuals. Useful for UI elements and simple vector-based games.
  • HTML/CSS -- Standard web technologies for building game UI, menus, HUDs, and overlays.

Audio

  • Web Audio API -- Advanced audio engine supporting real-time playback, synthesis, spatial audio, effects processing, and dynamic mixing.
  • HTML Audio Element -- Simple sound playback for background music and basic sound effects.

Input and Controls

  • Gamepad API -- Support for game controllers and gamepads, including button mapping and analog stick input.
  • Touch Events API -- Multi-touch input handling for mobile devices.
  • Pointer Lock API -- Locks the mouse cursor within the game area and provides raw coordinate deltas for precise camera/aiming control.
  • Device Sensors -- Accelerometer and gyroscope access for motion-based input.
  • Full Screen API -- Enables immersive full-screen game experiences.

Networking and Multiplayer

  • WebSockets API -- Persistent, bidirectional communication channel for real-time multiplayer, chat, and live updates.
  • WebRTC API -- Peer-to-peer connections for low-latency multiplayer, voice chat, and data channels.
  • Fetch API -- HTTP requests for downloading game assets, loading level data, and transmitting non-real-time game state.

Data Storage and Performance

  • IndexedDB API -- Client-side structured storage for save games, cached assets, and offline play support.
  • Typed Arrays -- Direct access to raw binary data buffers for GL textures, audio samples, and compact game data.
  • Web Workers API -- Background thread execution for offloading heavy computations (physics, pathfinding, AI) without blocking the main thread.

Languages and Compilation

  • JavaScript -- The primary language for web game development.
  • C/C++ via Emscripten -- Compile existing native game code to JavaScript or WebAssembly for web deployment.
  • WebAssembly (Wasm) -- Near-native execution speed for performance-critical game code.

Types of Games You Can Build

The modern web platform supports a full range of game types:

  • 3D action games and shooters
  • Role-playing games (RPGs)
  • 2D platformers and side-scrollers
  • Puzzle and strategy games
  • Card and board games
  • Casual and mobile-friendly games
  • Multiplayer experiences with real-time networking

Advantages of Web-Based Game Development

  1. Universal reach -- Games run on smartphones, tablets, PCs, and Smart TVs through the browser.
  2. No app store dependency -- Deploy directly on the web without store approval processes.
  3. Full revenue control -- No mandatory revenue share; use any payment processing system.
  4. Instant updates -- Push updates immediately without waiting for store review.
  5. Own your analytics -- Collect your own data or choose any analytics provider.
  6. Direct player relationships -- Engage players without intermediaries.
  7. Inherent shareability -- Games are linkable and discoverable via standard web mechanisms.

Anatomy of a Game Loop

Every game operates through a continuous cycle of steps:

  1. Present -- Display the current game state to the player.
  2. Accept -- Receive user input (keyboard, mouse, gamepad, touch).
  3. Interpret -- Process raw input into meaningful game actions.
  4. Calculate -- Update the game state based on actions, physics, AI, and time.
  5. Repeat -- Loop back to present the updated state.

Games may be event-driven (turn-based, waiting for player action) or per-frame (continuously updating via a main loop).


Building a Game Loop with requestAnimationFrame

Basic Main Loop

window.main = () => {
  window.requestAnimationFrame(main);

  // Your game logic here: update state, render frame
};

main(); // Start the cycle

Key points:

  • requestAnimationFrame() synchronizes callbacks to the browser's repaint schedule (typically 60 Hz).
  • Schedule the next frame before performing loop work to maximize available computation time.

Self-Contained Main Loop (IIFE)

;(() => {
  function main() {
    window.requestAnimationFrame(main);

    // Game logic here
  }

  main();
})();

Stoppable Main Loop

;(() => {
  function main() {
    MyGame.stopMain = window.requestAnimationFrame(main);

    // Game logic here
  }

  main();
})();

// To stop the loop:
window.cancelAnimationFrame(MyGame.stopMain);

Timing and Frame Rate

DOMHighResTimeStamp

requestAnimationFrame passes a DOMHighResTimeStamp to your callback, providing timing precision to 1/1000th of a millisecond.

;(() => {
  function main(tFrame) {
    MyGame.stopMain = window.requestAnimationFrame(main);

    // tFrame is a high-resolution timestamp in milliseconds
    // Use it for delta-time calculations
  }

  main();
})();

Frame Time Budget

At 60 Hz, each frame has approximately 16.67ms of available processing time. The browser's frame cycle is:

  1. Start new frame (previous frame displayed to screen)
  2. Execute requestAnimationFrame callbacks
  3. Perform garbage collection and per-frame browser tasks
  4. Sleep until VSync, then repeat

Simple Update and Render Pattern

The simplest approach when your game can sustain the target frame rate:

;(() => {
  function main(tFrame) {
    MyGame.stopMain = window.requestAnimationFrame(main);

    update(tFrame); // Process game logic
    render();       // Draw the frame
  }

  main();
})();

Assumptions:

  • Each frame can process input and update state within the time budget.
  • The simulation runs at the same rate as the display refresh (typically ~60 FPS).
  • No frame interpolation is needed.

Decoupled Update and Render with Fixed Timestep

For robust handling of variable refresh rates and consistent simulation behavior:

;(() => {
  function main(tFrame) {
    MyGame.stopMain = window.requestAnimationFrame(main);
    const nextTick = MyGame.lastTick + MyGame.tickLength;
    let numTicks = 0;

    // Calculate how many simulation updates are needed
    if (tFrame > nextTick) {
      const timeSinceTick = tFrame - MyGame.lastTick;
      numTicks = Math.floor(timeSinceTick / MyGame.tickLength);
    }

    queueUpdates(numTicks);
    render(tFrame);
    MyGame.lastRender = tFrame;
  }

  function queueUpdates(numTicks) {
    for (let i = 0; i < numTicks; i++) {
      MyGame.lastTick += MyGame.tickLength;
      update(MyGame.lastTick);
    }
  }

  MyGame.lastTick = performance.now();
  MyGame.lastRender = MyGame.lastTick;
  MyGame.tickLength = 50; // 20 Hz simulation rate (50ms per tick)

  setInitialState();
  main(performance.now());
})();

Benefits:

  • Deterministic simulation -- Game logic runs at a fixed frequency regardless of display refresh rate.
  • Smooth rendering -- Rendering can interpolate between simulation states for visual smoothness.
  • Portable behavior -- Game behaves the same on 60 Hz, 120 Hz, and 144 Hz displays.

Alternative Architecture Patterns

Separate setInterval for Updates

// Game logic updates at a fixed rate
setInterval(() => {
  update();
}, 50); // 20 Hz

// Rendering synchronized to display
requestAnimationFrame(function render(tFrame) {
  requestAnimationFrame(render);
  draw();
});

Drawback: setInterval continues running even when the tab is not visible, wasting resources.

Web Worker for Updates

// Heavy game logic runs in a background thread
const updateWorker = new Worker('game-update-worker.js');

requestAnimationFrame(function render(tFrame) {
  requestAnimationFrame(render);
  updateWorker.postMessage({ ticks: numTicksNeeded });
  draw();
});

Benefits: Does not block the main thread. Ideal for physics-heavy or AI-intensive games. Drawback: Communication overhead between worker and main thread.

requestAnimationFrame Driving a Web Worker

;(() => {
  function main(tFrame) {
    MyGame.stopMain = window.requestAnimationFrame(main);

    // Signal worker to compute updates
    updateWorker.postMessage({
      lastTick: MyGame.lastTick,
      numTicks: calculatedNumTicks
    });

    render(tFrame);
  }

  main();
})();

Benefits: No reliance on legacy timers. Worker performs computation in parallel.


Handling Tab Focus Loss

When a browser tab loses focus, requestAnimationFrame slows down or stops entirely. Strategies:

| Strategy | Description | Best For | |---|---|---| | Treat gap as pause | Skip elapsed time; do not update | Single-player games | | Simulate the gap | Run all missed updates on regain | Simple simulations | | Sync from server/peer | Fetch authoritative state | Multiplayer games |

Monitor the numTicks value after a focus-regain event. A very large value indicates the game was suspended and may need special handling rather than trying to simulate all missed frames.


Comparison of Timing Approaches

| Approach | Pros | Cons | |---|---|---| | Simple update/render per frame | Easy to implement, responsive | Breaks on slow/fast hardware | | Fixed timestep + interpolation | Consistent simulation, smooth visuals | More complex to implement | | Quality scaling | Maintains frame rate dynamically | Requires adaptive quality systems |


Performance Best Practices

  • Detach non-frame-critical code from the main loop. Use events and callbacks for UI, network responses, and other asynchronous operations.
  • Use Web Workers for computationally expensive tasks like physics, pathfinding, and AI.
  • Leverage GPU acceleration through WebGL for rendering.
  • Stay within the frame budget -- monitor your update + render time to keep it under 16.67ms for 60 FPS.
  • Throttle garbage collection pressure by reusing objects and avoiding per-frame allocations.
  • Plan your timing strategy early -- changing the game loop architecture mid-development is difficult and error-prone.

Popular 3D Frameworks and Libraries

  • Three.js -- General-purpose 3D library with a large ecosystem.
  • Babylon.js -- Full-featured 3D game engine with physics, audio, and scene management.
  • A-Frame -- Declarative 3D/VR framework built on Three.js.
  • PlayCanvas -- Cloud-hosted 3D game engine with a visual editor.
  • Phaser -- Popular 2D game framework with physics and input handling.