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

assets/2d-platform-game.md

2D Platform Game Template

A complete step-by-step guide for building a 2D platformer game using Phaser (v2.x / Phaser CE) with Arcade Physics. This template walks through every stage of development: setting up the project, creating platforms from JSON level data, adding a hero with physics-based movement and jumping, collectible coins, walking enemies, death and stomp mechanics, a scoreboard, sprite animations, win conditions with a door/key system, and multi-level progression.

What you will build: A classic side-scrolling platformer where a hero navigates platforms, collects coins, avoids or stomps on spider enemies, finds a key to unlock a door, and progresses through multiple levels -- with score tracking, animations, and physics.

Prerequisites: Basic to intermediate JavaScript knowledge, familiarity with HTML, and a local web server for development (e.g., browser-sync, live-server, or Python's SimpleHTTPServer).

Source: Based on the Mozilla HTML5 Games Workshop - Platformer. Project starter files available at the workshop repository.


Start Here

This tutorial builds a 2D platformer using the Phaser framework. Phaser handles rendering, physics, input, audio, and asset loading so you can focus on game logic.

What You Will Build

The finished game features:

  • A hero character the player controls with the keyboard
  • Platforms the hero can walk and jump on
  • Collectible coins that increase the score
  • Walking spider enemies that kill the hero on contact (but can be stomped from above)
  • A key and door system: the hero must pick up a key to unlock the door and complete the level
  • Multiple levels loaded from JSON data files
  • A scoreboard showing collected coins
  • Sprite animations for the hero (idle, running, jumping, falling)

Project Structure

project/
  index.html
  js/
    phaser.min.js        (Phaser 2.6.2 or Phaser CE)
    main.js              (all game code goes here)
  audio/
    sfx/
      jump.wav
      coin.wav
      stomp.wav
      key.wav
      door.wav
  images/
    background.png
    ground.png
    grass:8x1.png        (platform tile images in various sizes)
    grass:6x1.png
    grass:4x1.png
    grass:2x1.png
    grass:1x1.png
    hero.png             (hero spritesheet: 36x42 per frame)
    hero_stopped.png     (single frame for initial steps)
    coin_animated.png    (coin spritesheet)
    spider.png           (spider spritesheet)
    invisible_wall.png   (invisible boundary for enemy AI)
    key.png              (key spritesheet)
    door.png             (door spritesheet)
    key_icon.png         (HUD icon for key)
    font:numbers.png     (bitmap font for score)
  data/
    level00.json
    level01.json

Level Data Format

Each level is defined in a JSON file. The JSON structure describes positions of every entity:

{
    "hero": { "x": 21, "y": 525 },
    "door": { "x": 169, "y": 546 },
    "key": { "x": 750, "y": 524 },
    "platforms": [
        { "image": "ground", "x": 0, "y": 546 },
        { "image": "grass:8x1", "x": 208, "y": 420 },
        { "image": "grass:4x1", "x": 420, "y": 336 },
        { "image": "grass:2x1", "x": 680, "y": 252 }
    ],
    "coins": [
        { "x": 147, "y": 525 },
        { "x": 189, "y": 525 },
        { "x": 399, "y": 399 },
        { "x": 441, "y": 336 }
    ],
    "spiders": [
        { "x": 121, "y": 399 }
    ],
    "decoration": {
        "grass": [
            { "x": 84, "y": 504, "frame": 0 },
            { "x": 420, "y": 504, "frame": 1 }
        ]
    }
}

Each entity type (hero, door, key, platforms, coins, spiders) has x and y coordinates. Platforms also specify which image asset to use for that platform tile.


Initialise Phaser

The first step is setting up the HTML file and creating the Phaser game instance.

HTML Entry Point

Create an index.html file that loads Phaser and your game script:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Platformer Game</title>
    <style>
        html, body {
            margin: 0;
            padding: 0;
            background: #000;
        }
    </style>
    <script src="js/phaser.min.js"></script>
    <script src="js/main.js"></script>
</head>
<body>
    <div id="game"></div>
</body>
</html>
  • The <div id="game"> is the container where Phaser will insert the game canvas.
  • Phaser is loaded first, then your game script.

Creating the Game Instance

In js/main.js, create the Phaser game object and register a game state:

// Create a Phaser game instance
// Parameters: width, height, renderer, DOM element ID
window.onload = function () {
    let game = new Phaser.Game(960, 600, Phaser.AUTO, 'game');

    // Add and start the play state
    game.state.add('play', PlayState);
    game.state.start('play');
};
  • 960, 600 sets the game canvas dimensions in pixels.
  • Phaser.AUTO lets Phaser choose between WebGL and Canvas rendering automatically.
  • 'game' is the ID of the DOM element that will contain the canvas.

The PlayState Object

Define the game state as an object with lifecycle methods:

PlayState = {};

PlayState.init = function () {
    // Called first when the state starts
};

PlayState.preload = function () {
    // Load all assets here
};

PlayState.create = function () {
    // Create game entities and set up the world
};

PlayState.update = function () {
    // Called every frame (~60 times per second)
    // Handle game logic, input, collisions here
};
  • init -- runs first; used for configuration and receiving parameters.
  • preload -- used to load all assets (images, audio, JSON) before the game starts.
  • create -- called once after assets are loaded; used to create sprites, groups, and game objects.
  • update -- called every frame at ~60fps; used for input handling, physics checks, and game logic.

At this point you should see an empty black canvas rendered on the page.


The Game Loop

Phaser uses a game loop architecture. Every frame, Phaser calls update(), which is where you handle input, move sprites, and check collisions. Before the loop starts, preload() loads assets and create() sets up the initial game state.

Loading and Displaying the Background

Start by loading and displaying a background image to verify the game loop is working:

PlayState.preload = function () {
    this.game.load.image('background', 'images/background.png');
};

PlayState.create = function () {
    // Add the background image at position (0, 0)
    this.game.add.image(0, 0, 'background');
};
  • this.game.load.image(key, path) loads an image and assigns it a key for later reference.
  • this.game.add.image(x, y, key) creates a static image at the given position.

You should now see the background image rendered in the game canvas.

Understanding the Frame Cycle

preload() -> [assets loaded] -> create() -> update() -> update() -> update() -> ...

Each call to update() represents one frame. The game targets 60 frames per second. All movement, input reading, and collision detection happen inside update().


Creating Platforms

Platforms are the surfaces the hero walks and jumps on. They are loaded from the level JSON data and created as physics-enabled sprites arranged in a group.

Loading Platform Assets

Load the level JSON data and all platform tile images in preload:

PlayState.preload = function () {
    this.game.load.image('background', 'images/background.png');

    // Load level data
    this.game.load.json('level:1', 'data/level01.json');

    // Load platform images
    this.game.load.image('ground', 'images/ground.png');
    this.game.load.image('grass:8x1', 'images/grass_8x1.png');
    this.game.load.image('grass:6x1', 'images/grass_6x1.png');
    this.game.load.image('grass:4x1', 'images/grass_4x1.png');
    this.game.load.image('grass:2x1', 'images/grass_2x1.png');
    this.game.load.image('grass:1x1', 'images/grass_1x1.png');
};

Spawning Platforms from Level Data

Create a method to load the level and spawn each platform as a sprite inside a physics group:

PlayState.create = function () {
    // Add the background
    this.game.add.image(0, 0, 'background');

    // Load level data and spawn entities
    this._loadLevel(this.game.cache.getJSON('level:1'));
};

PlayState._loadLevel = function (data) {
    // Create a group for platforms
    this.platforms = this.game.add.group();

    // Spawn each platform from the level data
    data.platforms.forEach(this._spawnPlatform, this);
};

PlayState._spawnPlatform = function (platform) {
    // Add a sprite at the platform's position using the specified image
    let sprite = this.platforms.create(platform.x, platform.y, platform.image);

    // Enable physics on this platform
    this.game.physics.enable(sprite);

    // Make platform immovable so it doesn't get pushed by the hero
    sprite.body.allowGravity = false;
    sprite.body.immovable = true;
};
  • this.game.add.group() creates a Phaser group -- a container for related sprites that enables batch operations and collision detection.
  • this.platforms.create(x, y, key) creates a sprite inside the group.
  • sprite.body.immovable = true prevents the platform from being pushed by other physics bodies.
  • sprite.body.allowGravity = false prevents platforms from falling due to gravity.

You should now see the ground and grass platform tiles rendered on the screen.


The Main Character Sprite

Now add the hero character that the player will control.

Loading the Hero Image

Add the hero image to preload. Initially we use a single static image; we will switch to a spritesheet later for animations:

// In PlayState.preload:
this.game.load.image('hero', 'images/hero_stopped.png');

Spawning the Hero

Add the hero to _loadLevel and create a spawn method:

PlayState._loadLevel = function (data) {
    this.platforms = this.game.add.group();
    data.platforms.forEach(this._spawnPlatform, this);

    // Spawn the hero at the position defined in level data
    this._spawnCharacters({ hero: data.hero });
};

PlayState._spawnCharacters = function (data) {
    // Create the hero sprite
    this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero');

    // Set the anchor to the bottom-center for easier positioning
    this.hero.anchor.set(0.5, 1);
};
  • anchor.set(0.5, 1) sets the sprite's origin point to the horizontal center and vertical bottom. This makes it easier to position the hero on top of platforms, since the y position refers to the hero's feet rather than the top-left corner.

Keyboard Controls

Capture keyboard input so the player can move the hero left, right, and jump.

Setting Up Input Keys

In init, configure the keyboard controls:

PlayState.init = function () {
    // Force integer rendering for pixel-art crispness
    this.game.renderer.renderSession.roundPixels = true;

    // Capture arrow keys
    this.keys = this.game.input.keyboard.addKeys({
        left: Phaser.KeyCode.LEFT,
        right: Phaser.KeyCode.RIGHT,
        up: Phaser.KeyCode.UP
    });
};
  • addKeys() captures the specified keys and returns an object with key state references.
  • Phaser.KeyCode.LEFT, RIGHT, UP correspond to the arrow keys.
  • renderSession.roundPixels = true prevents pixel-art sprites from appearing blurry due to sub-pixel rendering.

Reading Input in Update

Handle the key states in update. For now, just log the direction; the next step adds physics-based movement:

PlayState.update = function () {
    this._handleInput();
};

PlayState._handleInput = function () {
    if (this.keys.left.isDown) {
        // Move hero left
    } else if (this.keys.right.isDown) {
        // Move hero right
    } else {
        // Stop (no key held)
    }
};
  • this.keys.left.isDown returns true while the left arrow key is held down.
  • The else clause handles the case where neither left nor right is pressed (the hero should stop).

Moving Sprites with Physics

Enable Arcade Physics so the hero can move with velocity and interact with platforms through collisions.

Enabling the Physics Engine

Enable Arcade Physics in init:

PlayState.init = function () {
    this.game.renderer.renderSession.roundPixels = true;

    this.keys = this.game.input.keyboard.addKeys({
        left: Phaser.KeyCode.LEFT,
        right: Phaser.KeyCode.RIGHT,
        up: Phaser.KeyCode.UP
    });

    // Enable Arcade Physics
    this.game.physics.startSystem(Phaser.Physics.ARCADE);
};

Adding a Physics Body to the Hero

Enable physics on the hero sprite in _spawnCharacters:

PlayState._spawnCharacters = function (data) {
    this.hero = this.game.add.sprite(data.hero.x, data.hero.y, 'hero');
    this.hero.anchor.set(0.5, 1);

    // Enable physics body on the hero
    this.game.physics.enable(this.hero);
};

Moving with Velocity

Now update _handleInput to set the hero's velocity based on key presses:

const SPEED = 200; // pixels per second

PlayState._handleInput = function () {
    if (this.keys.left.isDown) {
        this.hero.body.velocity.x = -SPEED;
    } else if (this.keys.right.isDown) {
        this.hero.body.velocity.x = SPEED;
    } else {
        this.hero.body.velocity.x = 0;
    }
};
  • body.velocity.x sets the horizontal speed in pixels per second.
  • A negative value moves the sprite left; positive moves it right.
  • Setting velocity to 0 when no keys are pressed makes the hero stop immediately.

The hero can now move left and right, but will fall through platforms and off the screen because there is no gravity or collision handling yet.


Gravity

Add gravity so the hero falls downward and collides with platforms.

Setting Global Gravity

Enable gravity for the entire physics world in init:

PlayState.init = function () {
    this.game.renderer.renderSession.roundPixels = true;

    this.keys = this.game.input.keyboard.addKeys({
        left: Phaser.KeyCode.LEFT,
        right: Phaser.KeyCode.RIGHT,
        up: Phaser.KeyCode.UP
    });

    this.game.physics.startSystem(Phaser.Physics.ARCADE);

    // Set global gravity
    this.game.physics.arcade.gravity.y = 1200;
};
  • gravity.y = 1200 applies a downward acceleration of 1200 pixels per second squared to all physics-enabled sprites (unless they opt out with allowGravity = false).

Collision Detection Between Hero and Platforms

Add collision detection in update so the hero lands on platforms instead of falling through:

PlayState.update = function () {
    this._handleCollisions();
    this._handleInput();
};

PlayState._handleCollisions = function () {
    // Make the hero collide with the platform group
    this.game.physics.arcade.collide(this.hero, this.platforms);
};
  • arcade.collide(spriteA, groupB) checks for physics collisions between the hero and every sprite in the platforms group. When the hero lands on a platform, the physics engine prevents it from passing through and resolves the overlap.
  • It is important to call _handleCollisions() before _handleInput() so collision data (like whether the hero is touching the ground) is up to date when we process input.

The hero now falls due to gravity and lands on the platforms. You can walk left and right on the platforms.


Jumps

Allow the hero to jump when the up arrow key is pressed -- but only when standing on a platform (no mid-air jumps).

Implementing the Jump Mechanic

Add a jump constant and update _handleInput:

const SPEED = 200;
const JUMP_SPEED = 600;

PlayState._handleInput = function () {
    if (this.keys.left.isDown) {
        this.hero.body.velocity.x = -SPEED;
    } else if (this.keys.right.isDown) {
        this.hero.body.velocity.x = SPEED;
    } else {
        this.hero.body.velocity.x = 0;
    }

    // Handle jumping
    if (this.keys.up.isDown) {
        this._jump();
    }
};

PlayState._jump = function () {
    let canJump = this.hero.body.touching.down;

    if (canJump) {
        this.hero.body.velocity.y = -JUMP_SPEED;
    }

    return canJump;
};
  • this.hero.body.touching.down is true when the hero's physics body is touching another body on its underside -- meaning the hero is standing on something.
  • Setting velocity.y to a negative value launches the hero upward (the y-axis points downward in screen coordinates).
  • The canJump check prevents the hero from jumping while already in the air, enforcing single-jump behavior.
  • The method returns whether the jump was performed, which is useful later for playing sound effects.

Adding a Jump Sound Effect

Load a jump sound and play it on successful jumps:

// In PlayState.preload:
this.game.load.audio('sfx:jump', 'audio/sfx/jump.wav');

// In PlayState.create:
this.sfx = {
    jump: this.game.add.audio('sfx:jump')
};

// In PlayState._jump, after setting velocity:
PlayState._jump = function () {
    let canJump = this.hero.body.touching.down;

    if (canJump) {
        this.hero.body.velocity.y = -JUMP_SPEED;
        this.sfx.jump.play();
    }

    return canJump;
};

Pickable Coins

Add collectible coins that the player can pick up to increase their score.

Loading Coin Assets

Load the coin spritesheet and coin sound effect in preload:

// In PlayState.preload:
this.game.load.spritesheet('coin', 'images/coin_animated.png', 22, 22);
this.game.load.audio('sfx:coin', 'audio/sfx/coin.wav');
  • load.spritesheet(key, path, frameWidth, frameHeight) loads a spritesheet and slices it into individual frames of 22x22 pixels for animation.

Spawning Coins from Level Data

Update _loadLevel to create a coins group and spawn each coin:

PlayState._loadLevel = function (data) {
    this.platforms = this.game.add.group();
    this.coins = this.game.add.group();

    data.platforms.forEach(this._spawnPlatform, this);
    data.coins.forEach(this._spawnCoin, this);

    this._spawnCharacters({ hero: data.hero });
};

PlayState._spawnCoin = function (coin) {
    let sprite = this.coins.create(coin.x, coin.y, 'coin');
    sprite.anchor.set(0.5, 0.5);

    // Add a tween animation to make the coin bob up and down
    this.game.physics.enable(sprite);
    sprite.body.allowGravity = false;

    // Coin bobbing animation with a tween
    sprite.animations.add('rotate', [0, 1, 2, 1], 6, true); // 6fps, looping
    sprite.animations.play('rotate');
};
  • Each coin is created inside the coins group for easy collision detection.
  • allowGravity = false prevents coins from falling.
  • The animations.add creates a frame animation using the spritesheet frames 0, 1, 2, 1 at 6fps, looping continuously.

Collecting Coins

Add the coin sound to the sfx object and detect overlap between the hero and coins:

// In PlayState.create, add to the sfx object:
this.sfx = {
    jump: this.game.add.audio('sfx:jump'),
    coin: this.game.add.audio('sfx:coin')
};

// In PlayState._handleCollisions:
PlayState._handleCollisions = function () {
    this.game.physics.arcade.collide(this.hero, this.platforms);

    // Detect overlap between hero and coins (no physical collision, just overlap)
    this.game.physics.arcade.overlap(
        this.hero, this.coins, this._onHeroVsCoin, null, this
    );
};

PlayState._onHeroVsCoin = function (hero, coin) {
    this.sfx.coin.play();
    coin.kill();  // Remove the coin from the game
    this.coinPickupCount++;
};
  • arcade.overlap() checks if two sprites/groups overlap without resolving collisions physically. When an overlap is detected, it calls the callback function (_onHeroVsCoin).
  • coin.kill() removes the coin sprite from the game world.
  • this.coinPickupCount tracks the number of coins collected (initialize it in _loadLevel).

Initializing the Coin Counter

PlayState._loadLevel = function (data) {
    this.platforms = this.game.add.group();
    this.coins = this.game.add.group();

    data.platforms.forEach(this._spawnPlatform, this);
    data.coins.forEach(this._spawnCoin, this);

    this._spawnCharacters({ hero: data.hero });

    // Initialize coin counter
    this.coinPickupCount = 0;
};

Walking Enemies

Add spider enemies that walk back and forth on platforms. The hero can stomp on them from above but dies if touching them from the side.

Loading Enemy Assets

// In PlayState.preload:
this.game.load.spritesheet('spider', 'images/spider.png', 42, 32);
this.game.load.image('invisible-wall', 'images/invisible_wall.png');
this.game.load.audio('sfx:stomp', 'audio/sfx/stomp.wav');
  • The spider spritsheet has frames for a crawling animation.
  • Invisible walls are placed at platform edges to keep spiders from walking off -- they are not rendered visually but have physics bodies.

Spawning Enemies

Update _loadLevel and add a spawn method for spiders:

PlayState._loadLevel = function (data) {
    this.platforms = this.game.add.group();
    this.coins = this.game.add.group();
    this.spiders = this.game.add.group();
    this.enemyWalls = this.game.add.group();

    data.platforms.forEach(this._spawnPlatform, this);
    data.coins.forEach(this._spawnCoin, this);
    data.spiders.forEach(this._spawnSpider, this);

    this._spawnCharacters({ hero: data.hero });

    // Make enemy walls invisible
    this.enemyWalls.visible = false;

    this.coinPickupCount = 0;
};

Creating Invisible Walls on Platforms

Modify _spawnPlatform to add invisible walls at both edges of each platform:

PlayState._spawnPlatform = function (platform) {
    let sprite = this.platforms.create(platform.x, platform.y, platform.image);
    this.game.physics.enable(sprite);
    sprite.body.allowGravity = false;
    sprite.body.immovable = true;

    // Spawn invisible walls at the left and right edges of this platform
    this._spawnEnemyWall(platform.x, platform.y, 'left');
    this._spawnEnemyWall(platform.x + sprite.width, platform.y, 'right');
};

PlayState._spawnEnemyWall = function (x, y, side) {
    let sprite = this.enemyWalls.create(x, y, 'invisible-wall');

    // Anchor to the bottom of the wall and adjust position based on side
    sprite.anchor.set(side === 'left' ? 1 : 0, 1);

    this.game.physics.enable(sprite);
    sprite.body.immovable = true;
    sprite.body.allowGravity = false;
};
  • Each platform gets two invisible walls, one at each edge.
  • The walls act as barriers that prevent spiders from walking off the edge.
  • The anchor is set so the wall aligns to the correct side of the platform.

Spawning and Animating Spiders

PlayState._spawnSpider = function (spider) {
    let sprite = this.spiders.create(spider.x, spider.y, 'spider');
    sprite.anchor.set(0.5, 1);

    // Add the crawl animation
    sprite.animations.add('crawl', [0, 1, 2], 8, true);
    sprite.animations.add('die', [0, 4, 0, 4, 0, 4, 3, 3, 3, 3, 3, 3], 12);
    sprite.animations.play('crawl');

    // Enable physics
    this.game.physics.enable(sprite);

    // Set initial movement speed
    sprite.body.velocity.x = Spider.SPEED;
};

// Spider speed constant
const Spider = { SPEED: 100 };
  • Spiders have two animations: crawl (looping) and die (played once on death).
  • velocity.x = 100 starts the spider moving to the right at 100 pixels per second.

Making Spiders Bounce Off Walls

Add collision handling so spiders reverse direction when hitting invisible walls or platform edges:

// In PlayState._handleCollisions:
PlayState._handleCollisions = function () {
    thi