Building retro handheld games with Codex and the ModRetro Chromatic

With all due respect to the iPhone, the Game Boy might be the most iconic handheld device of all time. A generation of kids stomped Koopas on the bus and shared a link cable to battle their friends in Pokémon, with a device that brought games somewhere they’d never been before - your pocket. Or at least a pocket of your backpack.

With today’s powerful coding models, and tools like Codex, building your own games has never been easier (or in my opinion, more fun). But there’s something special about a game running on purpose-built hardware, like the Game Boy Color, that’s hard to replace. That’s why I am sooo excited to share that the ModRetro plugin for Codex enables anyone to build and play real Game Boy Color games on a handheld device.

You can order your own special edition ModRetro Chromatic device here.

Let’s jump right in and explain how it works.

Install the plugin

Open Plugins in the Codex desktop app and search for ModRetro Chromatic. Select ModRetro Chromatic Plugin by ModRetro, then click Install.

Open a local project folder and start a chat. Type @ and choose the plugin so Codex knows which tools to use.

Ask Codex to set up the plugin and check for any missing build tools. You can build and play your first game on your computer.

Prompt your first game

With the plugin selected in your Codex chat, describe the game you want to build. To follow along with the video, use this example prompt.

Build a top-down adventure game called Lodge Podge where a pixel beaver must chew down small trees to gather sticks to build a lodge in the center of the level.

Next, ask Codex to build the game and open the preview. You can also ask it to point you to these files in your GB Studio project folder.

Open the .gbsproj file in GB Studio to edit scenes, actors, and events.

Look in assets/ for the sprite sheets, backgrounds, and audio used by the project.

Run the compiled .gbc file in an emulator or install it on a cartridge.

From here, the hard part is up to you - prompting and iterating with Codex to figure out how to make the game fun. For example, I iterated on Lodge Podge a few times with prompts to make the beaver more chonky (for maximum cuteness), and to require gathering more varied resources, like mud and leaves, to help build the beaver lodge.

What’s in the plugin

The ModRetro Chromatic plugin contains developer tools the model can use on your behalf.

Animate a character

Ask Codex to create a sprite sheet and show you the frames side by side. To revise the animation, identify the pose or direction you want to change, then ask Codex to rebuild the preview.

Build a map the player can walk through

Ask Codex to show you a scene’s background and collision map side by side. The collision map marks which tiles block movement. Use the background to identify the area you mean, then tell Codex which tiles to mark as blocked or walkable.

Play the ROM in Codex

Ask Codex to open the game preview in its built-in browser. Use the arrow keys for the Game Boy’s D-pad, Z for A, X for B, and Enter for Start. Use the toolbar above the emulator to pause or resume.

Point to the part you want to change

Choose Annotate game in the preview toolbar, then click the game display to freeze a frame. Select the sprite, tile, or area you want to change and describe the edit. Choose Resume game to return to the emulator. After Codex makes the change, ask it to rebuild the ROM and reopen the preview.

Have Codex test a sequence of moves

You can also control the emulator from chat. Ask Codex to run the ROM, send a sequence of button presses, and capture a frame after each step. Ask for the frames side by side so you can inspect them together.

Edit in GB Studio

GB Studio is a visual editor for building Game Boy games. Open your project’s .gbsproj file and choose Game World. Select a scene in the navigator to see its properties in the sidebar. You can drag an actor to a new tile or edit collisions directly on the scene. Save the project, then return to your Codex chat and ask it to rebuild and open the preview. The GB Studio guide to scenes explains how backgrounds, actors, and triggers fit together.

Other development options

Extend a GB Studio game. If the built-in events don’t cover a mechanic, you can add a custom event in GBVM, GB Studio’s virtual-machine language, or extend the engine in C. See the GB Studio plugin guide.

Write the game in C with GBDK-2020. The ModRetro plugin can compile standalone C with GBDK’s lcc compiler. GBDK’s Game Boy APIs give you access to buttons, sprites, tiles, and palettes. Ask Codex to start with a game loop that reads the D-pad and moves a single sprite.

Write your own engine. You can have Codex implement the game loop, scrolling, and collisions from scratch. For an assembly project, build the ROM with a separately installed toolchain such as RGBDS. Then give the resulting .gb or .gbc file to the plugin to inspect and playtest.

Deploy to device

You’ll need a Chromatic, a compatible rewritable homebrew cartridge, and a USB data cable. Follow ModRetro’s quickstart to update the firmware and activate Developer Mode using the computer you’ll connect to the handheld.

Insert the cartridge, connect the Chromatic to your computer, and open the game preview in your local Codex chat.

Choose Install on Chromatic, select your connected device, and click Install. Read the confirmation carefully. Writing the new ROM erases the game on that cartridge and can erase its saves. The installer doesn’t back up the cartridge.

Choose Confirm Install when you’re ready. Leave the cable connected until the plugin reports success, then start the game on the Chromatic.

“The Power of Science is Staggering!”

With the ModRetro plugin for Codex, you can prompt your way to original Game Boy Color games and use all the tools in the thriving GBC homebrew development ecosystem. This is going to be so, so much fun. You can order your own ModRetro Chromatic device here and learn more about ModRetro and its other incredible work here. Happy Game Boy hacking!