(or Codex, or Gemini, or whatever AI you've got)
Do you love playing Pokémon ROM hacks but have little to no technical or artistic know-how to make your own? Look no further. This plugin turns your AI coding agent into a genuine ROM-hacking expert — years of hard-won knowledge, pulled from the far corners of the ROM-hacking community, built right in and sitting at your fingertips. You describe the hack of your dreams, in plain English, and it writes the code, builds the game, tests that it actually works, and shows you screenshots — all without you touching a wiki, a forum thread, or a line of code.
- Install the plugin in an AI coding agent that supports the Agent Skills standard — Claude Code, Codex CLI, Gemini CLI, and others all work.
- Install Docker Desktop and open it once. (The game compiles inside it — after that, you can forget it's there.)
- Say "check my setup." Your agent tells you exactly what's left, if anything, and how to fix it. There's a one-time ~1 GB download of the game engine, so budget about 2 GB of free disk space overall.
- Say "start a new game" and describe your idea. You'll get your own project folder and a playable game file for any GBA emulator (mGBA is the usual choice).
From there, it's just a conversation:
"Add a rival who picks the type that beats mine." "Make surfing available before the third gym." "Design a new Pokémon — an electric sheep — and put it on Route 2." "The cave music is too gloomy. Something more mysterious." "Put my game on my handheld."
It builds hacks of Pokémon Emerald, using pokeemerald-expansion — the community project that rebuilt Emerald's source code and modernized it with mechanics from the newer generations. You don't need to know what any of that means to use this.
Not affiliated with or endorsed by Nintendo, Game Freak, or The Pokémon Company.
flowchart LR
you["🗣️ You say what you want<br/><i>'give the rival a Squirtle'</i>"]
agent["🤖 Your agent makes the change<br/>and builds the game"]
prove["🔍 It tests the change<br/>and shows you screenshots"]
play["🎮 You play it"]
you --> agent --> prove --> play
play -.->|"'cool, now make<br/>the gym harder'"| you
That's the whole loop. A few things happen behind the curtain that make this different from just asking an AI to write game code:
- It knows this engine cold. Years of measured knowledge is built in — how big a map can be, how many sprites fit, which mistakes fail silently — so it warns you before your idea hits a wall, not after.
- It proves changes instead of assuming them. Every change gets tested by actually running your game in an emulator and checking the game's own memory. "It should work" becomes "here's the evidence it works."
- Your work is always safe. Your game lives in its own folder with its own history, backed up in a form that can rebuild the whole project on any computer.
- No searching around. No wikis to trawl, no forum threads from 2011, no tool chains to assemble. You ask, in the same chat you already use.
- Your game is for you. poryrom builds games for personal play — it won't help package or distribute them, and nothing Nintendo-owned is ever included in this project or your game folder. The engine it builds on is downloaded from that community project's own public page.
- Emerald only, on purpose. Being an expert in one engine is the whole point.
- It's honest about limits. Some of its self-tests only run on the machine where a game was first created — the README-level version of that story is: it will tell you, not pretend.
The technical story — what's actually in this repo, how verification works, the two detailed architecture diagrams — lives in docs/architecture.md. The knowledge base itself is in docs/: 17 pages covering everything from what makes a hack good (design-craft — start there) to the exact bytes of a Pokémon.
This repository contains only original tooling and documentation, MIT-licensed — see LICENSE. It contains no Nintendo code or assets and no ROMs. Pokémon and Pokémon Emerald are trademarks of Nintendo / Creatures Inc. / GAME FREAK inc.; this project is not affiliated with or endorsed by them.