Project 03 · After Breakout

Build a platformer prototype

This is not a full game. It is the smallest loop that feels like a platformer: gravity pulls you down, a floor stops you, and a jump only works when you are grounded.

Runnable mini platformer

Move with arrows or A/D. Jump with Space or W. Reach the gold square. If you fall off the right, Restart puts you back on the first ledge.

What you need

Velocity from physics basics, plus a rectangle overlap test. The longer platformer physics lesson adds coyote time after this prototype works.

What you will learn

Why a wall hit and a floor hit must be resolved on different axes, and why jump must read a grounded flag instead of “if Space then vy = -12”.

Build in five checkpoints

Give the player velocity. Store x, y, vx, vy. Gravity is a constant added to vy every frame.
Move X, then resolve walls. If the player overlaps a platform after the horizontal step, push them back out on X only.
Move Y, then resolve floors and ceilings. After the vertical step, a downward overlap means grounded. An upward overlap means you hit your head.
Jump only when grounded. Set vy to a negative value, then immediately clear the grounded flag so one key press cannot fire twice.
Add a goal and a fail. Touching the gold square wins. Falling below the canvas loses. Restart rebuilds position and velocity together.

Separate the axes

player.x += player.vx;
for (const platform of platforms) {
    if (overlap(player, platform)) {
        if (player.vx > 0) player.x = platform.x - player.w;
        else player.x = platform.x + platform.w;
        player.vx = 0;
    }
}

player.grounded = false;
player.y += player.vy;
for (const platform of platforms) {
    if (overlap(player, platform)) {
        if (player.vy > 0) {
            player.y = platform.y - player.h;
            player.grounded = true;
        } else {
            player.y = platform.y + platform.h;
        }
        player.vy = 0;
    }
}

If you resolve X and Y in one test, a corner hit can glue the player to a wall and look “grounded” when they are not. That is the most common beginner platformer bug.

This prototype vs a finished platformer

Idea	This page	A finished platformer
Jump	One impulse while grounded	Coyote time, jump buffer, variable jump height
Level	Four rectangles	Tiles, moving platforms, one-way floors
Camera	Fixed canvas	Follow the player, clamp to room bounds
Feel	No animation, no dust	Stretch, landing squash, particles

InstantGames does not ship a full platformer yet, so this project stays a prototype on purpose. Use it to practice the physics lesson, not to claim a commercial engine.

Common mistakes

Adding gravity directly to y instead of to vy.
Treating a wall overlap as a floor, which creates wall jumps you did not design.
Allowing jump whenever Space is held, which becomes an infinite hover.

Use it when you already have Snake and Breakout and want gravity. Do not start here as a first game. A grid tick is easier to see than a falling body.

Lessons used

Input · Physics basics · Platformer physics · State

Add coyote time from the platformer physics lesson, or go back to Breakout if bounce response still feels unclear.

Collision ideas follow MDN’s 2D collision notes. Updated 2026-08-13; the prototype was checked locally with keyboard jump, wall slides, and restart.