# IDEA.md – an arcade game of your own in the browser This is a self-contained brief. Give it in full to Claude Code (or a similar tool), ideally together with a design package from Claude Design, to build a game of your own. It draws on Ironfang, an action platformer in the spirit of Black Tiger that was designed in Claude Design, built in Claude Code and given its icon by Codex. ## 1. What to build A 2D action platformer in the browser with the mechanics of the classic arcade games and entirely original content: world, characters, names, graphics and text. In Ironfang: - **eight depths** with their own themes, a timer per depth and a boss at the bottom of each - **a hero** who walks, jumps (with a shorter jump when the button is released), climbs, strikes with a chain flail (also diagonally upwards and crouching), throws knives and drops through planks - **nine kinds of enemies**, **pilgrims** to free (dialogue and reward), **secrets** behind cracked walls, **chests** with keys, **urns**, and a **shop** where the currency is traded for armour and flail – and every upgrade changes how the hero looks - **score, lives, game over and continue**, an ending and a high score table - **keyboard, gamepad and touch**, with rebindable keys - **music and sound effects**, synthesised - **an installable web app** that can be played offline **Not in the first version**: two players, hand-drawn maps for every depth, recorded music. ## 2. Stack and architecture What **matters** is marked; the rest can be swapped. - **TypeScript and Vite, plain Canvas 2D, no game engine.** Internal resolution 384 × 216, integer-scaled with letterboxing, a fixed 60 Hz time step and rendering per frame. - **Important: graphics as code.** The design package's scripts draw characters, tiles and scenes to canvas. Palette swaps, themes and every combination of equipment then come for free, and no image files need shipping. Bake every drawing during loading, so the first enemy on screen doesn't cause a hitch. - **Important: copy the design package's scripts unchanged**, and mark every change you have to make in the copy. A new version of the design can then be copied in and the changes re-applied. - **Level logic without browser dependencies** (grammar, collision, level building, reachability), so the tools can run it straight from node. - **The high scores**: a small PHP API that saves to a JSON file outside the web root under an exclusive lock, with a plausibility check of the score per depth and a limit per address (addresses stored as a hash and cleared after an hour). `localStorage` as a fallback. No database. - **A service worker** generated at build time, with a version that is a hash of everything the build ships. ## 3. Decisions that turned out to matter **Design first.** A design package with an art bible (palette, themes, fonts, pixel rules), every character with anchor and hitbox, a hand-drawn first level, flows for the other levels, every screen and a handoff describing physics, economy, boss patterns and sound. **Deterministic levels.** The first depth is hand-drawn. The others are built from flows: one room per cell, each room a frame around a template for its room type (start, corridor, shaft, pilgrim, shop, chest, secret, hazard, boss), and neighbours in the flow become openings. Nothing is randomised at runtime – the same depth is the same map for everyone on the high score table. The boss room gets only one entrance. **A reachability test for every level.** Work out with the hero's real limits (two tiles tall, a jump three tiles up and four across, ladders both ways, planks from above) that the boss room, the shop, every pilgrim and every chest can be reached from the start, that every depth has its pilgrims and at least one secret, and that alternative routes really are alternatives – wall one off and check the other is enough. **A play test that steps exactly.** Expose a hook in the game that freezes the loop, steps exactly n ticks and lets the test drive input. The outcome then doesn't depend on how fast the computer is. Test running speed, jump height, attack windows, the shop, a chest, a boss, game over and continue, and run through every room on every depth with the boss defeated. **Use the signature rooms as a style reference, not literally**, if they don't stay within the hero's limits. ## 4. Pitfalls - **Hitboxes must be reachable by the hero's attacks.** Measure where the boss's hit area ends up in the game against the reach of the strike and the knife. A boss rising out of a liquid can end up out of reach. - **Liquids change the jump.** A lower jump in water turns pools into traps. Make jumping in water a swim stroke, and let the reachability test treat liquid as what it actually is. - **Secrets must not show.** Don't draw items on top of walls, and don't let item tiles inherit the wall's graphics. - **Pixel fonts run together.** Add a pixel between characters and measure layouts with that width. - **Don't draw text before the font has loaded** – a cache of text drawn in the fallback font sticks. - **iOS 26+ puts a blur over the top edge** of a home-screen web app. Put everything in a fixed, opaque container over the whole screen, with the status bar's height as a border in the background colour, and don't use the old `apple-mobile-web-app` tags. - **The service worker must get a new version when anything changes**, including the page itself. Upload it last, after everything it lists. Never cache the high score API. - **Don't trust scores from the client.** The checks only stop the obvious. ## 5. Requirements and measurements - Running speed around 90 px/s, jump height around 64 px, a shorter jump when the button is released. - A crisp image at 2×–5× scaling, 60 frames per second on a phone. - Every depth reachable according to the test; the play test green through every room and every boss. ## 6. How it's verified - Type checking before the build; a type error stops the build. - The reachability test for every level, and the play test in a headless browser against the built game. - Touch mode with emulation, and then on real phones. - Game feel and sound playtested by a human. ## 7. Way of working - **Milestones as tasks**: engine (scaling, time step, input, text), first depth playable, enemies and economy, boss and game flow, the remaining depths, sound, high scores, mobile. - **Open questions become decision tasks with a default**, so the build can continue while the question is open. - **One task at a time**, with the measurement in the closing comment. ## 8. The prompt > Build a 2D action platformer in the browser in [TypeScript and Vite on plain Canvas 2D], with [Black Tiger] as the model for the mechanics but with entirely original content. [Eight] depths with a boss in each, a hero with [a chain flail and throwing knives], enemies, secrets, a shop and a high score table. It should work with keyboard, gamepad and touch and be installable and playable offline. > > Read all of IDEA.md below first, and the design package if there is one. > > Work like this: > 1. Split the build into milestones and ask me about the open decisions – put a default on each. > 2. Keep the level logic free of the browser and write a reachability test for every level. > 3. Add a hook that steps the game exactly, and test the built game in a browser. > 4. Leave the game feel and the sound to me to playtest. > > [paste IDEA.md here]