Gen1Recomp Wiki

Welcome! This project lets you play Gen 1, 2 and 3 Pokemon games on a computer and change parts of the game with mods: small add-ons that change things such as dialogue, art, music, or battle rules. You can use someone else's mod or make your own.

The game needs a ROM, a game-cartridge data file that you supply. The app imports that file to create its game data. The project and its mods do not include the original ROM or extracted game content.

Find your entry point

What you want to do	Start here	What you need
Play the game or install a mod	Start Playing	The app and your supported ROM; no programming
Make something, with no programming experience	Your First Change	A running Red game and a plain-text editor
Set up a mod when you already know programming	Getting Started	A mod folder; command-line tools are optional
Replace art	Art Pipeline	Your own art; the guide explains file placement
Add music or sound	Audio Authoring	Your own audio or an interest in chiptune
Translate text	Translations	A small translation to try first
Build an NPC, map, or quest	Tutorials	The basic mod-file workflow
Find one recipe	Cookbook	A working mod to edit
Write one mod for Gen 1, 2 and 3	Portable API 3	A mod folder with "api": 3 and a games list
Find a field or API	Choose a Registry, Mod Object	A task or API name to look up

Unfamiliar word? Use the Glossary. New to files and code? Read Modding Basics alongside your first exercise. Something failed? Troubleshooting explains where to find the error and what to try next.

What a mod can do

Start small: change a sign, make a move stronger, or play your own song in Pallet Town. Later, you can add creatures, locations, story events, menus, and new rules. A total conversion combines many changes into a different game built on this engine.

A simple mod has two files:

my_first_mod/
├── manifest.json    describes the mod
└── main.lua         contains the instructions the game runs

The code is written in Lua, the engine's programming language. This is a complete main.lua, but it still needs the manifest shown in Getting Started:

return function(mod)
  mod.content.text:override("_PalletTownSignText", "HELLO FROM MY MOD!")
end

The first exercise explains where to save both files, how to find the sign, and how to undo the change.

Supported games

The current source lists Red, Blue, Yellow, Gold, Silver, Crystal, FireRed, LeafGreen, Ruby, Sapphire, and Emerald in the launcher; the Gen 3 games are marked beta there. A mod must support the game you select: a manifest's games list names the games it runs on, and a mod that does not claim the booted game is skipped, not broken. The beginner exercises start with Red; a Red example is not automatically a working Gold or Emerald mod. A mod with "api": 3 can share one entry file across all three generations; see Portable API 3. Follow the scope stated on each page.

The launcher wording comes from src/core/GameVersion.lua. For a different app release, use the choices available in that release.

How the wiki is organized

• Tutorials teach a task step by step, with complete example files and a result you can check.
• Concepts explain why a technique works: registries, events and hooks, load timing, game data, saves, compatibility, and the cross-generation Portable API 3.
• Cookbook recipes help you make one specific change in an existing mod.
• Reference pages give exact fields, arguments, and behavior for lookup.
• Guides cover playing, creative workflows, tools, and larger projects.

The rules of the platform

With mods off, the engine aims to preserve the original game behavior. Turning off a mod removes its active changes on the next launch. If your save contains content that mod added, read the Save Model before removing it; switching a mod off is not a backup of an earlier save.

The loader reports mod errors and isolates failed contributions where supported. Read the error in the manager instead of assuming that a mod which appears in the list successfully loaded.

Publish original assets or asset transforms: instructions that build a changed image locally from the player's imported data. Do not package the ROM or extracted assets. See Publishing.

Existing API compatibility is described in Compatibility; new Gen 1-only mods should use API 2, and mods that should run on more than one generation should use API 3.

For wiki contributors

Follow the Docs Style Guide. The registry reference is produced by a generator; update its source and regenerate it. The style guide documents the commands and the checks to run before sharing edits.