Build playable prototypes in code and in Godot: game loops, input, collision, physics, state machines, data-driven tuning, jams and publishing.

Game Prototyping & Systems

## Why this matters

Almost every mechanic is a collision question in disguise. Did the bullet hit the enemy? Is the player standing on a platform? Did the mouse click a button? Is the coin inside the pickup radius? You need an answer that is correct, fast enough to run hundreds of times per frame, and simple enough to debug at 2 a.m. during a jam. For 2D prototypes the answer is usually the **axis-aligned bounding box**, or AABB.

## What an AABB is

An AABB is a rectangle whose sides line up with the x and y axes (it is never rotated). Store it the same way you draw it:

```javascript
const player = { x: 10, y: 20, w: 16, h: 24 };   // x, y = top-left corner
```

Its edges are:

- left = `x`, right = `x + w`
- top = `y`, bottom = `y + h`

Even when the art is a circle or a character with flowing hair, a box that roughly fits is usually good enough. Many games make the **hitbox** slightly smaller than the sprite so near-misses feel fair to the player.

## The overlap test

Two boxes overlap when they overlap on **both** axes at once. Thinking about the opposite is easier: they are apart if one is completely to the left, right, above or below the other. Flip that and you get the classic test:

```javascript
function aabbOverlap(a, b) {
  return a.x < b.x + b.w &&   // a's left is left of b's right
         a.x + a.w > b.x &&   // a's right is right of b's left
         a.y < b.y + b.h &&   // a's top is above b's bottom
         a.y + a.h > b.y;     // a's bottom is below b's top
}
```

Worked example. `a = {x: 0, y: 0, w: 10, h: 10}` and `b = {x: 5, y: 5, w: 10, h: 10}`:

- 0 < 15, 10 > 5, 0 < 15, 10 > 5: all true, so they overlap (a 5×5 square is shared).

Move `b` to `x: 10`. Now `a.x + a.w > b.x` is `10 > 10`, which is false. The boxes **touch** along an edge but do not overlap. Using strict `<` and `>` means touching is not a hit, which is what you want for a player standing exactly on top of a floor: they rest on it without "colliding into" it every frame. Whichever rule you pick, pick it deliberately and use it everywhere.

## Point in rectangle

Clicks, cursor hover and small projectiles are points. A point is inside a box if it lies within both ranges:

```javascript
function pointInRect(px, py, r) {
  return px >= r.x && px < r.x + r.w &&
         py >= r.y && py < r.y + r.h;
}
```

Here the left/top edge counts as inside and the right/bottom edge does not. That "half-open" convention means a point on the shared border of two touching tiles belongs to exactly one of them, never both or neither.

## Checking many objects

A simple loop is fine for prototypes:

```javascript
function findHits(player, others) {
  const hits = [];
  others.forEach((o, i) => {
    if (aabbOverlap(player, o)) hits.push(i);
  });
  return hits;
}
```

Returning indices (or the objects) and letting the caller decide what to do keeps the collision code **pure**: it answers a question and changes nothing. The game then decides that touching a coin adds score, touching spikes costs a life, and so on. Mixing detection with response makes bugs hard to find.

With a few hundred objects, checking every pair is still cheap. When you have thousands, games use a **broad phase** such as a uniform grid: only test objects in the same or neighbouring cells. Do not build that until profiling says you need it.

## Tunnelling

Collision is checked at discrete moments. A fast bullet moving 40 pixels per frame can be on one side of a 10-pixel wall in one frame and on the other side in the next, never overlapping it. Fixes, roughly from simplest:

- cap the speed or make thin walls thicker,
- split the movement into smaller sub-steps,
- use a **swept** test or a ray cast along the path.

This is also why the previous lesson capped delta time.

## Beyond boxes

- **Circles:** two circles overlap when the distance between centres is less than the sum of radii. Compare squared distances to avoid `Math.sqrt`.
- **Rotated shapes:** use the Separating Axis Theorem (SAT), covered in the Nybbit video. Engines like Godot do this for you.

## Common mistakes

- **Using `<=`** in one place and `<` in another, so touching counts as a hit sometimes.
- **Treating x, y as the centre** in one function and the corner in another.
- **Forgetting width/height** and comparing only `x` values.
- **Changing state inside the detection function**, which makes the order of checks matter.
- **Hitboxes equal to sprite bounds**, which makes near-misses feel unfair.

## Quick recap

- An AABB is `{x, y, w, h}` with sides along the axes.
- Boxes overlap when they overlap on both axes; strict comparisons mean touching is not a hit.
- Points use a half-open range so shared borders belong to one box.
- Keep detection pure; let the game decide the response.
- Watch out for tunnelling with fast objects.

## Try it

Open the Do tab to write `aabbOverlap`, `pointInRect` and `findHits` as pure functions.

Detect overlaps between axis-aligned boxes and points, and find every object a player touches.

Collision detection

Simple AABB Collision Explained [Colliders: Part 1]

AABB vs SAT - 2D Collision Detection

## Why this matters

Jumping is the signature verb of a whole genre, and "game feel" lives in a handful of numbers: how hard gravity pulls, how fast the jump starts, what happens when the player lets go of the button. You do not need a physics engine to get a great jump. You need three ideas (velocity, acceleration, ground contact) and the discipline to tune them as design values, not magic numbers.

## Position, velocity, acceleration

Each frame:

1. **acceleration** changes **velocity**,
2. **velocity** changes **position**.

Gravity is a constant downward acceleration. With `y` growing downwards on a canvas, gravity is **positive**:

```javascript
const GRAVITY = 1800;   // pixels per second per second

function applyPhysics(dt) {
  player.vy += GRAVITY * dt;    // velocity changes by acceleration
  player.y  += player.vy * dt;  // position changes by velocity
}
```

Updating velocity first and then position with the new velocity is called **semi-implicit Euler** integration. It is simple and stable enough for most games. Because both lines multiply by `dt`, the jump is roughly the same height at 30 fps and 144 fps (here about 90 px vs 98 px; a fixed timestep makes it identical on every machine).

## Landing on the ground

Without a floor the player falls forever. The simplest floor is a single line:

```javascript
const GROUND_Y = 180;

if (player.y + player.h >= GROUND_Y) {
  player.y = GROUND_Y - player.h;   // snap on top of the ground
  player.vy = 0;                    // stop falling
  player.onGround = true;
} else {
  player.onGround = false;
}
```

Two things matter. **Snap** the player to the surface so they never sink in. **Zero the velocity**, or gravity keeps building speed while they stand still and the next step off a ledge becomes a sudden plunge. For platforms, apply the same idea with the AABB test from the last lesson: if the player is falling (`vy > 0`) and overlaps a platform, put them on top of it.

## The jump

A jump is an instant upward velocity, applied only when standing:

```javascript
const JUMP_SPEED = 600;

function jump() {
  if (!player.onGround) return;   // no infinite air jumps
  player.vy = -JUMP_SPEED;        // negative = up on a canvas
  player.onGround = false;
}
```

Gravity then slows the rise, stops it at the peak and pulls the player back down. Physics gives you the shape for free: the peak height is `JUMP_SPEED² / (2 × GRAVITY)`. With 600 and 1800 that is 100 pixels, and the time to the peak is `600 / 1800 = 0.33` seconds. Designers often work backwards: choose the height and time to peak you want, then solve for gravity and jump speed. The GDC talk "Building a Better Jump" walks through this method.

## Variable jump height

In many platformers, tapping jump gives a hop and holding it gives a full jump. A simple way to get that: when the player **releases** the button while still rising fast, cut the upward speed.

```javascript
const JUMP_CUT = 0.5;

function releaseJump() {
  const minRise = -JUMP_SPEED * JUMP_CUT;
  if (player.vy < minRise) player.vy = minRise;   // still rising fast: slow down
}
```

If the player is already falling or rising slowly, nothing changes, so a late release does not cause a strange mid-air stop.

## Feel tricks worth knowing

- **Coyote time:** allow a jump for about 0.1 s after walking off a ledge. Players perceive this as fair, not as cheating.
- **Jump buffering:** remember a jump press made just before landing and perform it on landing.
- **Higher gravity when falling:** many games multiply gravity by 1.5 to 2 on the way down for a snappier arc.
- **Terminal velocity:** cap `vy` so long falls stay readable.

Each of these is a few lines once the basic state (`vy`, `onGround`) exists. Add them one at a time and playtest each.

## Treat numbers as design data

Put tuning values in one place, name them, and show them on screen or in a debug panel while you play:

```javascript
const TUNING = { GRAVITY: 1800, JUMP_SPEED: 600, JUMP_CUT: 0.5, MAX_FALL: 900 };
```

A designer who can change jump height in five seconds will try twenty variations; one who must hunt through code will try two.

## Common mistakes

- **Gravity with the wrong sign.** On a canvas, down is positive.
- **Not resetting `vy` on landing**, so speed keeps building while standing.
- **Jumping without checking `onGround`**, which gives infinite jumps.
- **Forgetting `dt`** in either line, which makes the jump depend on frame rate.
- **Setting `onGround` only to true**, never back to false when walking off a ledge.

## Quick recap

- Acceleration changes velocity; velocity changes position, both times `dt`.
- Snap to the ground, zero `vy`, track `onGround`.
- Jump = set `vy` to a negative speed, only from the ground.
- Releasing early cuts upward speed for variable height.
- Name your tuning values and tweak them while playing.

## Try it

Open the Do tab to implement `applyPhysics`, `jump` and `releaseJump` for a canvas platformer.

Add gravity, ground contact, jumping and variable jump height to a canvas platformer.

Simple physics

Math for Game Programmers: Building a Better Jump

5 tips for better platformer controls

## Why this matters

A prototype quickly grows more than one "mode": a title screen, the game itself, a pause screen, a game-over screen with a restart button. Without structure this becomes a nest of flags (`isPaused`, `isDead`, `hasStarted`, `showMenu`) that can contradict each other. Players then find the bug where pressing pause on the game-over screen revives them. A **finite state machine** (FSM) removes that whole class of bugs by making the modes explicit.

## The idea

A finite state machine has:

- a fixed set of **states** (exactly one is current),
- a set of **events** (things that happen: a key press, a hit, a timer),
- **transitions**: rules saying "in state S, event E moves you to state T".

Anything not listed is ignored. For a typical arcade game:

| from | event | to | side effect |
|---|---|---|---|
| menu | START | playing | score = 0, lives = 3 |
| playing | PAUSE | paused | |
| paused | RESUME | playing | |
| playing | HIT | playing or gameover | lives - 1; gameover at 0 |
| playing | SCORE | playing | score + points |
| gameover | RESTART | menu | |

The table *is* the design. Write it before any code, and show it to teammates: holes ("what does Escape do on the game-over screen?") become obvious.

## A pure transition function

The cleanest implementation is a function that takes the current game and an event and returns the **next** game, without changing the input:

```javascript
function createGame() {
  return { state: "menu", score: 0, lives: 3 };
}

function transition(game, event) {
  switch (game.state) {
    case "menu":
      if (event.type === "START") return { state: "playing", score: 0, lives: 3 };
      return game;
    case "playing":
      if (event.type === "PAUSE") return { ...game, state: "paused" };
      if (event.type === "SCORE") return { ...game, score: game.score + event.points };
      if (event.type === "HIT") {
        const lives = game.lives - 1;
        return { ...game, lives, state: lives <= 0 ? "gameover" : "playing" };
      }
      return game;
    // paused and gameover follow the same pattern
    default:
      return game;
  }
}
```

Events are objects (`{ type: "SCORE", points: 10 }`) so they can carry data. The spread `{ ...game, ... }` copies the old fields and overrides a few, so the original is untouched.

Why bother with purity?

- **Testing:** `transition(createGame(), { type: "START" })` is a one-line test with no canvas, timer or keyboard.
- **Replays and debugging:** a list of events plus the starting state reproduces any bug exactly.
- **Undo, rewind, networking:** keeping old states is free when nothing mutates them.

## Ignoring invalid events

Notice the `return game;` lines. A `HIT` in the menu, a `PAUSE` on the game-over screen, a `SCORE` while paused: all ignored. This is the main safety property of an FSM. Instead of asking "which flags must I check here?", each state lists what it accepts and everything else is a no-op.

## Wiring it to the loop

The game loop asks the state what to do:

```javascript
let game = createGame();

function update(dt) {
  if (game.state === "playing") updateWorld(dt);   // physics only while playing
}

function draw() {
  drawWorld();
  if (game.state === "menu") drawTitle();
  if (game.state === "paused") drawOverlay("Paused");
  if (game.state === "gameover") drawOverlay(`Game over: ${game.score}`);
}

window.addEventListener("keydown", (e) => {
  if (e.key === "Enter") game = transition(game, { type: game.state === "gameover" ? "RESTART" : "START" });
  if (e.key === "Escape") game = transition(game, { type: game.state === "paused" ? "RESUME" : "PAUSE" });
});
```

Input handlers translate keys into events; the transition function decides what those events mean right now.

## When states get bigger

- **Enter/exit actions:** run code once when entering a state (play a jingle on game over).
- **Hierarchical states:** "playing" can contain sub-states like "alive", "respawning", "level-complete".
- **Per-entity FSMs:** enemies use the same pattern: idle, patrol, chase, attack. The NesHacker video shows how classic games used state machines for almost everything.
- **Behaviour trees** replace FSMs for complex AI, but an FSM is the right first tool for game flow.

## Common mistakes

- **Boolean soup:** several flags that can be true at once instead of one `state` value.
- **Mutating the input** in a function meant to be pure, so tests pass or fail depending on order.
- **Forgetting to reset** score and lives on START, so a new run keeps the old score.
- **Handling events everywhere:** pause logic scattered across input, physics and UI code.
- **Using `<` instead of `<=`** for lives, so the player gets an extra life at zero.

## Quick recap

- One `state` value, a fixed list of events, and a transition table.
- A pure `transition(game, event)` returns a new game and ignores invalid events.
- The loop updates and draws based on the current state.
- Write the table first; it is the design.

## Try it

Open the Do tab to implement `createGame` and a pure `transition` function for menu, playing, paused and game over.

Model menu, play, pause and game-over as a finite state machine with a pure transition function.

Game states

An introduction to finite state machines and the state pattern for game development

How NES Games Use State Machines For Everything

Detect AABB collisions, add gravity and jumping, and structure game flow as a state machine.