How-to
Build a small browser arcade with AI
Start with one character, one joke and one complete loop. Make those work before you build the next room.
Last updated:
Use the build-browser-arcade skill
Download the workflow we kept from this build. The ZIP contains the skill, its Codex metadata and project notes. It does not contain the private game source, artwork or music.
- Download and unzip the file. Keep the whole
build-browser-arcadefolder together, including itsreferencesandagentsfolders. - Copy that folder into
~/.codex/skills/on the machine where you run Codex. The result should be~/.codex/skills/build-browser-arcade/SKILL.md. - Start a new Codex session in your own project and use the prompt below. The skill gives you the workflow; it does not provide access to the private source repository.
Start a session
Use $build-browser-arcade to build a small arcade for my existing website. Start with one playable loop and show the art at desktop and phone sizes before making more assets.1. Decide what the player gets to do
The arcade on this site began as a game version of my portfolio, with project doors and themed rooms. The office-feedback enemies became the better first release. They arrive with comments such as “Make the logo bigger” and “It doesn't pop.” You fight through six waves and a boss, then walk right to start another lap.
Write the first release in one sentence. Name the player's action, the first opponent, the reward and the restart. Put the distinctive part in the first encounter. Keep future rooms on a separate list so they don't become requirements for finishing this loop.
Prompt 1 of 9
Help me build a small browser arcade for my existing website. The player is [character], the first encounter is [opponent and joke], the main action is [action], and victory leads to [restart or finish]. Inspect the existing site and any game code first. Propose the smallest complete loop. Keep future rooms out of this pass.
Check: You can describe the whole first loop without saying “and later we will add”.
2. Give the game its own home
Keep editable game code, art sources, prompts and tests in a standalone repository. The website should receive the runnable export. This lets you extend the game without moving the rest of the portfolio around.
Our implementation uses Canvas 2D and native JavaScript modules, with no runtime packages. The main folders are src/engine, src/combat, src/audio, src/title, src/attract, art and tests. That was enough for this game's movement, fights, backgrounds and small room system. An existing engine may be the right choice for a different game; inspect what is already there before replacing it.
The complete Classic Cottrell source repository is private. This page provides the process and prompts, rather than a public game-source download. The reusable skill is available in the ZIP above so you can use the workflow in your own project.
Prompt 2 of 9
Set up the game separately from the website, or reuse its existing repository. Keep development assets and tests in the game repo. Define a small mountGame(container, options) interface with a destroy method. Document how the host closes the game and restores focus. Don't add an engine or package unless the agreed loop needs it.
Check: You can run the game by itself, and closing the embedded version removes its listeners and audio.
3. Approve one frame at the real size
Supply the actual character, face or logo reference. Ask the assistant to inspect it before making assets. If the task is to use an existing face, another interpretation of that face is a different task.
Our game uses a 180-pixel internal height, a view that follows the browser width, a palette of no more than 32 colours, and hard pixels. The character sheets use a higher source density than the world coordinates. Decide those relationships before making animation sheets, or every scale adjustment becomes harder to judge.
Preview a hero, a pickup and the background together at desktop and phone widths. Our Terry emblem looked reasonable in an enlarged asset preview and still needed shrinking in the game. It now draws at 24 by 24 world units. Keep the source image and change the draw size when size is the problem.
Prompt 3 of 9
Inspect [reference file]. Show one hero, one pickup and one background together at the proposed in-game size. Use [palette and internal resolution]. Preserve the supplied identity. Show desktop and phone layouts before producing the full animation sheets. Label source pixels, world units and display scale separately.
Check: The selected frame looks right in the game window, including the pickup's size beside the hero.
4. Finish one fight before adding waves
Start with movement, facing, a hit, a reaction and a restart. Then build the approved combo and one opponent's attack. Our three Space presses produce punch, punch, hop-kick. The final loop mixes human reviewers and monsters before its boss.
Attach speech to the person saying it. Keep the complete line within the viewport and use a font that is readable at the actual display size. A separate box below the action made it harder to tell who was speaking in our version.
Have reviewers speak as they enter. Give short lines at least five seconds, with longer lines held for up to seven. Keep that timer separate from attack windup. Then check the sequence: first encounter, later waves, boss, victory and another lap with fresh enemies and pickups.
Prompt 4 of 9
Build one testable fight using the approved assets. Keep dialogue duration separate from attack timing. Speech should appear over its speaker, start on arrival, remain readable through hit reactions and stay within phone and desktop viewports. Once it works, add [wave order] and verify that victory resets into another lap.
Check: A new player sees the joke during the first encounter and can read the line while playing.
5. Test the sound you will ship
Our title music and cues are synthesized with WebAudio. The level uses a separate track I made in Google Flow. Sound previews are useful for comparing punch, footstep and pickup ideas before changing the mix heard during play.
Keep mute shared across music and effects. Request sound from an intentional reveal or start action, then handle the browser refusing it. A scroll can reveal the game without granting audio playback. A Start sound button provides the next deliberate action.
Check the actual track in the active checkout. Ours disappeared from one preview because the ignored audio folder hadn't been copied into that clone. A test that turns music off or replaces it cannot catch that. Verify that the real file loads, plays, loops, mutes, resumes and stops when returning to the title. Confirm permission to include any supplied track in the public export.
Prompt 5 of 9
Use [authorized music file] for gameplay and [sound direction] for the title and effects. Verify the real file exists and plays from the dev server. Share mute across all audio, handle blocked playback visibly, and stop sound on close, replay and hide. Keep sound sketches separate from the integrated mix.
Check: You can hear the real track, mute everything, return to the title and close the game without leaving audio running.
6. Let the attract demo use the real game
Drive scripted input through the same movement and combat code the player uses. Our attract demo walks into the opening encounter, fights, fades out and returns to the intro. A real key or pointer action cancels the script so the player can take over.
Test at more than one width. A fixed list of directions and times can work on one screen and miss an enemy on another. Reduced motion keeps the title still instead of starting automatic combat.
Prompt 6 of 9
Build an attract demo using the existing input and combat interfaces. It should reach the opening fight, finish or time out safely, fade and reset. Real input must cancel pending scripted actions and the fade without swallowing that real input. Keep a static title under reduced motion.
Check: The demo repeats without leaving held keys, and taking over works during both the fight and the fade.
7. Embed the reviewed runtime
Export an explicit list of runnable modules, selected sprites, fonts and authorized audio. Give the export a content-based version and manifest. Import that directory into the website, rather than copying the private repository.
Load it only when someone opens the arcade. Keep the ordinary project links available without JavaScript and when the game cannot load. Let the game expand the page instead of covering the portfolio by default.
Our final reveal is a charcoal Play strip with a small gold glint along its bottom border. Sound, help, fullscreen and close sit inside the game. The help is a compact panel. Close destroys the game and returns focus to Play. Reduced motion keeps the border still.
Prompt 7 of 9
Export only the reviewed runtime into the existing site. Mount it lazily after Play or the agreed reveal action. Keep ordinary content usable without JavaScript and on loading failure. Put sound, compact help, fullscreen and close inside the game. Honour reduced motion and restore focus to Play when closing.
Check: The closed page makes no game or music requests, and the open game does not take away the site's ordinary links.
8. Check the change, then check the release
For a small revision, change the layer responsible and run the checks that reach it. A smaller pickup needs a draw-size change. A longer message needs a speech timer. Repeating a whole release process after every preview made this build more expensive than it needed to be.
Before publication, run the release checks together. Our game has npm test; PNG checks use python tools/check-pngs.py in a development environment with Pillow; npm run build writes the runtime. The source browser suite requires its dev server, Chrome and the real local song. The host has its own build, contrast and browser checks.
For the November 2026 release, 157 game tests and 15 arcade browser checks passed. We checked desktop, phone-sized and reduced-motion layouts in Chromium. That does not replace physical iPhone or Safari testing, which remains open.
Prompt 8 of 9
For this revision, identify the smallest affected tests and reuse the running dev server. For the release, verify real music, the first fight, boss/reset, desktop and phone layout, reduced motion, close/focus and exported asset requests. Report commands and results, and distinguish emulation from physical-device testing.
Check: The report names the tested behaviour and the gaps, rather than just saying “all good”.
9. Verify the public result and leave a handoff
A branch push backs up work. A merged release and successful deployment make it public. Keep those actions separate in the conversation so everyone knows which result has been requested.
After an approved deployment, check the public URL for the expected runtime version. Open Play, start the game, reach a reviewer line and close it again. Our release went through website PR #36 and a live-site smoke check.
Leave the current commands, selected assets, music setup, known gaps and next small extension in the standalone game repo. Keep old experiments as history, with a current release note that makes clear which decisions replaced them. Then choose one new room or opponent to work on.
Prompt 9 of 9
Prepare the release for review and state whether you are pushing a branch or publishing. After authorized publication, verify the actual public page and expected runtime version. Update the standalone game handoff with the release, setup steps, asset provenance, known gaps and the next small task.
Check: The live page runs the version you approved, and a fresh session can find the current source without reconstructing the chat.