Tutorials

Start with Tutorial 00 if you have never made a mod. It changes a nearby sign using two small text files. You do not need to learn all of Lua before trying it; Modding Basics explains the syntax as you need it, and the Glossary explains unfamiliar words.

These lessons use Red, local single-player, with a practice save. Each lesson names its starting files, prints complete finished code, and links every required download. The lessons distinguish loading successfully from checking the visible or audible result. Use Troubleshooting when the MODS panel or a validation command reports an error.

Choose your next result

Lesson	You make	Difficulty	Read first
00: First change	Your words on the Pallet Town sign	First-time programmer	Getting Started
01: Sprite and text	Sign text and a Mew recolor	Beginner	Tutorial 00; Save Editor for the art preview
02: Balance patch	Move, species-stat, and trainer-party edits	Beginner	Tutorial 00; IDs in Modding Basics
03: New species	Original Emberkit art and encounters	Intermediate	Tutorial 02
04: Item and ball	Two shop items and a capture attempt	Intermediate	Tutorial 02
05: Move	An attack Abra can learn	Intermediate	Tutorial 02; callbacks in Modding Basics
06: NPC	A character who greets you	Intermediate	Tutorial 00; tables and IDs
07: Map	A connected route with encounters	Intermediate	Tutorial 06 finished files
08: Quest	A Nugget request with saved progress	Intermediate	Tutorial 07 finished files
09: Music	Your audio file as a town theme	Intermediate	Tutorial 00
10: Mechanic	A curse status and a test Pokémon	Advanced	Tutorials 05/06; Events and Hooks
11: UI screen	A quest log sharing the quest's progress	Advanced	Tutorial 08 finished files; Events and Hooks
12: Mini total conversion	A starting world, original starter, and battle	Advanced	Tutorials 03/06/07

You can follow the numbered order or take a shorter route. An artist can go from 00 to 01, then 02/03; a musician can go from 00 to 09. For a story mod, follow 00 → 06 → 07 → 08 → 11, reading the callback explanation before 11. The concept pages explain why the APIs work as they do; the cookbook is for smaller changes once you know the setup.

How the files fit together

Simple lessons are independent: turn off earlier examples while checking a new one. Tutorials 06, 07, 08, and 11 are successive snapshots of one mod, tutorial_world. Keep exactly one installed snapshot, replace its files as you progress, and keep the same mod ID and save slot. Each finished snapshot includes the previous lesson's required content; the linked start snapshot supplies the same starting files if you arrive directly.

Tutorial 12 is independent again and includes its own original art. Test it with the earlier examples disabled and a new save slot. Keep each modded practice save with its matching files so you can return to it.

Gen 2 and Gen 3

Every lesson targets Red (Gen 1) with "api": 2 and "games": ["red"]. A Gold, Crystal or Gen 3 boot skips these mods. The same ideas carry over, but the files do not run unchanged:

• IDs. Text, map, trainer, script and type IDs (_PalletTownSignText, PALLET_TOWN, OPP_BROCK, TEXT_VIRIDIANMART_CLERK, PSYCHIC_TYPE) are Gen 1 names. Later games use their own.
• Shops and startup (04, 12). text_pointers has no Gen 2 or Gen 3 target. field has no Gen 3 target; Gold reads only some boot keys.
• Scripts and maps (06 to 08, 10 to 12). Gen 2 and Gen 3 map scripts are native row lists, and Gen 3 blocks are 16 px rather than 32 px.
• Battle callbacks (05, 10). move_effects and statuses keep their verbs but act on each generation's own battlers and status rules.
• Screens and art (01, 11). Gen 3 screens draw inside the 240x160 frame; image paths are per-game cache paths.

For one mod that runs on all three generations, opt in to "api": 3 and read Portable Mods across Gen 1, 2 and 3. To see what a mod would hit, add a game to its games list and run python3 tools/modkit.py gen2check <mod> or gen3check <mod>, then test in that game.

Link Play is a separate launcher workflow using a vanilla cart or a sealed custom cart. Authored mods may be included in a sealed custom cart; freely enabling arbitrary loose mods is not a supported link mode. See Link Play for player setup.