🦍 Planning Workbook: Donkey Kong

How to use this workbook: work top to bottom. It walks you through planning Donkey Kong with the method from 01-How-to-Plan-a-Game, then gives you a build order. It says what each piece is and which technique to reach for — you open the Technique Playground and write the code. Wherever you see ✍️ YOUR TURN or a checkbox, that's your work.

The game in a nutshell

A big ape sits at the top of a construction site and rolls barrels down at you. You're the little hero at the bottom. Run along the girders, climb the ladders, and jump over the barrels as you make your way to the top to win.

This is a platformer, which means one big new idea compared to Pac-Man: gravity. Things fall down unless something holds them up.

Step 1 — Say it in one sentence

Starting version — ✍️ YOUR TURN: make it yours.

"Climb from the bottom to the top of the girders, jumping over rolling barrels along the way."

Step 2 — What's on the screen? (objects)

• Hero — the player you control. (a small rectangle is fine)
• Girders / platforms — the floors you run on. (long thin rectangles)
• Ladders — let you move between floors. (tall thin shapes)
• Barrels — the danger; they roll and fall. (circles)
• Donkey Kong — sits at the top and throws barrels. (a big rectangle)
• Goal — the spot at the top you're trying to reach. (could be DK himself, or a princess)
• Score + Lives text — the HUD.

✍️ YOUR TURN: note the shape/color you'll use for each.

Step 3 — What does each object DO? (behaviors)

✍️ YOUR TURN: fill in the blanks.

• Hero: runs left/right, __________ (up in the air), and climbs ladders.
• Girders: hold up the hero and the barrels — they don't __________.
• Barrels: appear at the top, __________ across girders, and fall down at the edges.
• Donkey Kong: every so often, __________ a new barrel.

Step 4 — The rules ("when ___, then ___")

Some done, some for you.

• When the hero stands on a girder → he doesn't fall through it. (That's what a solid platform does.)
• When the hero presses jump and is on the ground → he leaps up.
• When the hero touches a barrel → __________________________.
• When the hero reaches the goal at the top → __________________________.
• When lives = 0 → __________________________.

Step 5 — States (scenes)

Title → Playing → Win (reached the top) or Game Over (lives = 0) → back to Title.

(Technique 11 covers scenes.)

🧩 Your Architecture Map

Two rows filled in as examples. ✍️ YOUR TURN: complete the rest.

🏗️ Build order (your milestones)

Build one at a time. Run and check the "✅ works when" line before moving on.

Milestone 1 — Draw the level

Build the girders and ladders from a text map (Technique 10). Here's a starter — = is a girder, H is a ladder, P is where the hero starts, K is Donkey Kong, G is the goal. Paste it and then redesign it:

=                   =
=                   =
= K   H           G =
======H==============
=     H             =
=     H             =
=     H      H      =
=============H=======
=            H      =
=            H      =
=   H        H      =
====H================
=   H               =
=   H               =
=   H          H    =
===============H=====
=              H    =
=              H    =
= P            H    =
=====================

Turn each = into a solid girder (area + body({isStatic:true})), each H into a ladder (just area — no body, because you pass through ladders, you don't stand on them).

Use 32×32 tiles (tileWidth: 32, tileHeight: 32). The map is 21 tiles wide and 20 tall, so the level is 672 × 640 pixels — start your game with kaplay({ width: 672, height: 640, letterbox: true }) so the whole thing fits on screen.

🔑 Two things about this map are deliberate — don't "tidy" them away:

1. Every floor has three empty rows above it. That's your headroom. A jump needs somewhere to go, and a barrel needs somewhere to be jumped over. If you redesign the level, keep at least three blank rows between girders or Milestone 3 and Milestone 5 become impossible.

2. Each ladder pokes one tile above the floor it leads to, and replaces the girder it passes through. Look at the ladder in column 6: it runs from row 2 down to row 6, and the girder row 3 has an H instead of an = — that's the hole the hero climbs through. The tile sticking up above the floor is what lets him finish the climb and stand there without falling back down the hole. This geometry is what makes Milestone 4 work, so copy the pattern for any ladder you add.

• 🔧 Techniques: 1, 2, 10, 7
• ✅ Works when: you see five floors, four ladders, Donkey Kong at the top left, and the goal at the top right.

💡 If your girders look right but the ladders sit hugging the corner of their tile, that's because a tile's position is its top-left corner, not its middle. Either make the ladder rectangle a full 32 wide, or nudge the object over after the level is built. Cosmetic only — don't let it block you.

Milestone 2 — The hero falls and lands

Turn on gravity (Technique 6: setGravity(...)). Add the hero as a body with an area. Drop him above a girder.

• ✅ Works when: the hero falls and lands on a girder instead of falling forever. (If he falls through, his area/body or the girder's isStatic isn't set right — check Technique 7.)
• 🔧 Techniques: 6, 7

Milestone 3 — Run and jump

Read left/right keys to move the hero (Technique 4 + 5). Read the jump key (space) and make him jump — but only when he's on the ground (Technique 6 shows the isGrounded() check so he can't fly).

• ✅ Works when: you can run along a girder and jump into the air, landing back down.
• 🔧 Techniques: 4, 5, 6

Milestone 4 — Climb ladders

This is the trickiest bit, so plan it before coding. A ladder is an area you can overlap. The idea: while the hero is overlapping a ladder and you press Up (or Down), move him up/down and switch gravity off so he doesn't just fall while climbing. When he steps off the ladder, gravity comes back on.

Remember the map geometry from Milestone 1: the girder has a hole where the ladder passes through it, and the ladder sticks up one tile above that hole. So the climb goes: overlap the ladder at the bottom → gravity off → rise through the hole → arrive on the tile above the floor, still overlapping the ladder so you don't drop back down → press left or right to step onto solid girder → gravity comes back on.

• 🤔 DECISION: how will you know he's "on a ladder"? (Hint: a collision/overlap check with the "ladder" tag — Technique 8 — can set a canClimb flag that you turn off when the overlap ends.)
• ⚠️ The classic bug: you turn gravity off on the way up but never turn it back on, so the hero floats forever. Decide now where the "gravity on" line lives. onCollideEnd (see the Cheatsheet, Collisions) is the natural home for it.
• ✅ Works when: the hero can go up and down every ladder, and he stops being weightless the moment he steps off.
• 🔧 Techniques: 8, plus 4/6 for the movement and gravity toggle

Milestone 5 — Rolling barrels

Make Donkey Kong spawn a barrel at the top every couple of seconds (Technique 9). A barrel is a body (so gravity makes it fall off ledges) that also moves sideways.

Notice that your ladder holes double as barrel chutes — a barrel rolling along a floor will drop through the first hole it meets and land on the floor below. That's free level design; you don't have to code it.

• 🤔 DECISION — how does a barrel move? Pick your first version:
  • Easiest: barrel always rolls one direction and falls off the edge of each girder to the one below.
  • Fancier: barrel changes direction sometimes, or rolls toward the hero's side.
  • Note your choice.
• When a barrel touches the hero → lose a life (Technique 12); if 0 → Game Over.
• Clean up barrels that roll off the bottom so they don't pile up (Technique 9 shows how to auto-remove off-screen objects).
• ✅ Works when: barrels roll down the level and touching one costs a life.
• 🔧 Techniques: 9, 6, 7, 8, 12

Milestone 6 — Reach the top + title/game-over screens

The G tile in your map is the goal. Give it an area() and the tag "goal"; when the hero touches it → Win scene. Wrap the game in a Title screen (start) and a Game Over screen (shows score, restart).

• ✅ Works when: getting to the top wins, running out of lives ends the game, and you can restart.
• 🔧 Techniques: 8, 11, 12

Milestone 7 (stretch) — Points for jumping barrels

Give the hero points when he successfully jumps over a barrel. Think about how you'd detect that: the hero is in the air (not grounded) and a barrel passes beneath him. Plan the check before you write it.

• 🔧 Techniques: 8, 12, plus the isGrounded() idea from 6

🌟 Stretch goals (only after it works!)

• A jump/land sound and a barrel-thud (Technique 15).
• Make Donkey Kong "throw" — a little animation before each barrel drops.
• A hammer power-up that lets you smash barrels for a few seconds.
• Multiple levels that get taller and faster.
• Swap the rectangles for real sprite images (Technique 2).

🧗 A note on the hardest parts

Two things trip everyone up on their first platformer — expect them, and you won't be discouraged:

1. Falling through floors. Almost always means the floor isn't a static body, or the faller doesn't have an area + body. Re-check Technique 7.
2. Ladders feel weird. That's normal — climbing is genuinely fiddly because you're fighting gravity. Get running and jumping rock-solid first (Milestones 2–3), then tackle ladders. Keep your first ladder version dead simple.

✅ Donkey Kong planning checklist

• I filled in the Architecture Map (all rows).
• I understand gravity is the new idea here, and only solid/static things stop falls.
• I decided how ladders work for my first version.
• I decided how barrels move for my first version.
• I know my win condition (reach the top) and lose condition (0 lives).
• I have my milestone list and I'm building one at a time.

Start with Milestone 1. Get the hero falling and landing before anything else — that one win makes the rest click. 🦍