Choose a registry

Use this page when you know what you want to change but do not yet know the registry name. A registry is the named collection of game records that a mod can change. After choosing one, use the generated Registry reference for the exact required fields.

Before you choose

Where code goes: put registry calls in your mod entry file, usually main.lua. Content is combined during startup, before the live game begins; see Lifecycle. Status: the calls on this page are small, paste-ready patches when the named id already exists. New records need the required fields shown in the generated reference.

First choose the operation:

You want to	Operation
Change part of an existing record	patch
Add a record with a new id	register
Replace a whole existing record	override
Make a record unavailable	remove

patch is the usual first choice. It keeps fields you do not mention. See Content registries for list, deep, and compose merge rules before changing a list or map_scripts entry.

Find your task

You want to make	Start with	You may also need
Change a Pokémon's stats, type, moves, sprite path, or evolution	pokemon	moves, icons, cries
Change an existing move or add a move effect	moves	move_effects, battle_anims
Change an item, Poké Ball, or item behavior	items	item_effects, balls
Change a trainer's party or reward	trainers	ai_classes, music
Change dialogue or an engine message	text	strings, text_pointers
Add or change a map, its layout, or encounters	maps	tilesets, encounters, sprites
Add map dialogue, a cutscene, or a script	map_scripts	Script commands, text
Change startup location, badge data, or overworld tables	field	constants
Add a screen, menu asset, or interface text	screens	strings, The mod object
Add music, a sound effect, a cry, palette, or font	music, sfx, cries	palettes, font
Add a script command, status, growth curve, or evolution method	commands, statuses	growth_rates, evolution_methods
Change type matchups or a text placeholder	type_chart, tokens	strings
Change a map's background song or a full-song table	map_songs, music	sfx, cries
Change a battle rule set, battle-sprite scale, or transition	rulesets, battle_sprite_scales, transitions	statuses, move_effects
Draw the world or window your own way	render_pipelines	Hook reference
Upgrade a mod's own saved data	migrations	Save Model
Add Gold/Silver/Crystal systems: held items, phone, radio, Kurt's apricorns	held_items, phone_contacts, radio_channels, apricorns	landmarks, decorations
Name a region-map section or add a secret-base decoration (Gen 2 and Gen 3)	landmarks, decorations	rom_text
Replace engine prose by its ROM label (Gold and Gen 3)	rom_text	text
Add mod fields to the cart link protocol (low level)	link_fields	Compatibility
Replace the old whole-table audio data (deprecated)	audio	music, sfx, cries, map_songs
Change a rule that is computed while the game runs	Events and Hooks	Hook reference

Read the type column

The generated reference is exact but compact. Read its type descriptions this way:

Notation	Meaning
string, number, boolean	ordinary Lua text, numeric, or true/false value
function	code the engine calls later; find its documented arguments and return value before writing it
{ field, otherField? }	a record: a Lua table with named fields; ? marks an optional field
list of T	an ordered Lua table whose entries have type T
map of K -> V	a Lua table that maps each key shaped like K to a value shaped like V
A | B	either listed shape is accepted
moves id, items id, and similar	the internal id of a record in that named registry, not its displayed name

For example, this patch changes one field on the existing move whose internal id is BLIZZARD:

mod.content.moves:patch("BLIZZARD", { accuracy = 70 })

Choose the target game

Most registry names work across generations, but their record fields or target tables can differ. Use the main schema for Red, Blue, and Yellow; use the On Gold (Gen 2) subsection for Gold, Silver, and Crystal; use the On Gen 3 subsection for FireRed, LeafGreen, Ruby, Sapphire, and Emerald; read each one you support. Some registries are Gen 2 only, have no Gold home, or have no Gen 3 home (apricorns, held_items, phone_contacts and radio_channels exist only on Gold, and rulesets, text_pointers and link_fields have no Gold or Gen 3 home), and the generated reference says so at the relevant entry. The write is dropped and reported, never merged into a table nothing reads.

To write one source for several games, declare "api": 3 and use the canonical pokemon, moves, items, trainers, and encounters records; see Portable API 3. The 47 registries and their per-game routing are summarized in Data Model.

Player link setup is separate from registry authoring: configure it in the launcher with a vanilla cart or sealed custom cart. A sealed cart is the supported route for its pinned mods; freely enabled loose mods, including cosmetic mods, are not a supported link setup. The generated link_fields entry is low-level cart-protocol material, not a way to approve loose mods.

Next steps

• Read Content registries before choosing between patch, override, and list wrappers.
• Use Reference: Registries when you need the exact field names and required values.
• Use Tutorial 00 for a first visible change, or Troubleshooting if your mod does not load.