I Rebuilt Donkey Kong with AI
and the Barrels Taught Me Progressive Onboarding

The first barrel phased through the ladder like it didn't exist. The second got stuck halfway, hovering in the void, trembling like a rendering bug from 1996. The third reversed direction and rolled back up the ramp toward Donkey Kong, in an act of rebellion not even Miyamoto could have predicted. That's when I knew that rebuilding Donkey Kong for PixelPrompt wasn't going to be just a pixel art and nostalgia exercise.

The thing is, barrel physics are just the surface. Underneath there's something far more interesting: the way Miyamoto, with 16 KB of ROM and four screens, built the most efficient onboarding system I've ever seen. No tooltips. No popups. No “press A to jump” message. Just pure level design.

Four screens that teach without speaking

Donkey Kong has four screens. Not four worlds, not four chapters: four single screens, each with a precise job to do. Each screen introduces exactly one new mechanic. Never two at once. This is the heart of progressive onboarding, and in 1981 it didn't even have a name.

Screen 1, the ramps (25m). Pauline at the top, Mario at the bottom, barrels rolling down. Gravity tells you everything: climb up, dodge barrels, you can jump. Three core mechanics communicated in a single glance, without a single word. The first barrels come slowly, with wide gaps. The player tries jumping, fails, learns the timing. Then the frequency ramps up. Then barrels start taking the ladders. The difficulty curve rises, but the vocabulary has already been taught.

Screen 2, the conveyors (50m). One new mechanic: moving belts. The floor shifts under Mario's feet. But jumping and dodging? You learned those one floor down. The game adds a single element at a time. Had it thrown in conveyors, new enemies and moving ladders all at once, it would've been a wall.

Screen 3, the elevators (75m). Vertically moving platforms. Again, one single novelty on solid foundations. The jump timing (learned in the previous screens) now applies to moving targets. Same principle, higher stakes.

Screen 4, the rivets (100m). Here the structure flips: you no longer climb, you remove rivets from the platform by walking over them. New mechanic, but every previous skill (jumping, dodging, timing) is still required. The player has been trained without realizing it.

“A good game designer never explains the rules. He lets you discover them.”

Shigeru Miyamoto

The pattern modern software forgot

What Miyamoto did under extreme hardware constraints has a name in today's product design: progressive onboarding. Instead of bombarding the user with every feature at first launch, you present them one at a time, at the moment they're needed. Four principles, all visible in DK's four screens:

• One mechanic per level. Each screen teaches exactly one new thing. Never two. Never zero.
• Context teaches. No tooltip needed when the layout makes the action obvious. Pauline at the top = climb. Rolling barrels = dodge.
• Safe failure. The first barrels are slow on purpose. You can die, but you immediately understand why. Feedback is instant and readable.
• Skill stacking. Each screen requires skills from previous ones plus one new addition. Nothing is wasted, everything accumulates.

Today I see SaaS products with 20-screen tutorials, interface-blocking popups, step-by-step guides nobody reads. Miyamoto solved it all with barrel placement and ramp angles. With 16 KB.

Developer insight: three days to get a barrel down a ladder

This is the part that cost me more time than any other feature. The basic logic (move Mario, climb ladders, jump) came together relatively quickly. Then I had to make barrels bounce down ladders. And everything broke.

The problem seems trivial: a barrel rolls down a ramp, reaches a ladder, and sometimes goes down. But in the original, barrels don't always descend. There's a variable probability depending on ladder position, current level, and a pseudo-random factor. If every barrel descended, the game would be impossible; if none did, it would be boring. Miyamoto tuned that value with a precision we'd now call A/B testing.

Then there's the collision problem. A barrel rolling down a sloped ramp that then decides to descend a vertical ladder must completely change its physics model. On the ramp it moves horizontally with a vertical offset (following the slope). On the ladder it moves vertically only. The transition between these two states is the exact point where game feel is made or broken.

I spent three entire sessions debugging barrels that phased through ladders like ghosts, got stuck halfway, fell into the void, or reversed direction for no reason. Every fix broke something else. The ladder collision grid had to align pixel-perfect with the barrel hitbox, and every ladder has slightly different dimensions.

The final solution: treat each barrel as a state machine with three states. Rolling (on ramp), descending (on ladder), falling (free fall at ladder's end). Each frame, the barrel checks if it's above a ladder and rolls a die. If the right number comes up, it transitions to descending, aligns its center X to the ladder's axis, and descends at constant speed. When it hits the next ramp, back to rolling.

Sounds obvious written down. Getting there took dozens of iterations and an embarrassing amount of console.log.

“Things that look simple when you play are almost always the ones that require the most work when you develop. The barrel rolling naturally down a ladder? Three days.”

From the PixelPrompt development diary

AI is the chisel, not the sculptor

Using AI to rebuild a game from scratch isn't asking “make me Donkey Kong” and receiving a finished product. It's more like pair programming with a colleague who knows every API in existence but has never put a coin in an arcade cabinet.

AI excels at structure: game loop, sprite management, canvas boilerplate, basic collision detection. Everything that's a known, documented pattern. Where it struggles is game feel. The right speed for a barrel, the weight of Mario's jump, the exact moment a barrel should decide whether to descend. These are values you find only by playing, testing, adjusting by half a pixel at a time. AI generates three alternatives in five minutes; I pick the one that “feels right.” I decide the design, AI writes the boilerplate.

The final result is a Donkey Kong that respects the feel of the original. Barrels bounce as they should, Mario has the right weight, and the four screens teach you to play without a single word. You can try it right now: play Donkey Kong free in your browser.

If this piece made you want to take apart more classics, that's what we do every week at PixelPrompt. We rebuild retro games with AI, analyze them piece by piece, and share what we learned. Join the crew: zero spam, just pixels and code.