This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Preparing your mod for Gen 2 and Gen 3

You have a mod that works on Red, Blue or Yellow, and you want it to work on Gold, Silver, Crystal, or the Game Boy Advance games (FireRed, LeafGreen, Ruby, Sapphire, Emerald). This is the migration guide: what breaks, what the engine papers over for you, what it refuses to paper over, and the order to do the work in.

Starting a new mod? Skip most of this page. Write it against mod API 3 and Portable mods across Gen 1, 2 and 3: one entry file, no engine modules, and mod:supports to ask what each game serves. This page is for mods that already exist, or that need engine modules the portable API does not cover. Sections say "Gen 2" or "Gen 3" where the two differ, and "Gold" where an example was checked on Gold only.

Quick migration route

Use this page when you already have a working Red, Blue, or Yellow mod and want to try it on a Gen 2 or Gen 3 game. You need the engine checkout, Python 3, luajit, an imported Gen 2 or Gen 3 game for the final boot, and a clean working copy of the mod. Run commands from the engine repository root, the directory that contains tools/modkit.py.

The complete manifest is mods/my_mod/manifest.json and the entry file is mods/my_mod/main.lua; use the manifest reference for the fields the checker reads. The examples below are placed in that entry file unless a label says they belong in the SDK test harness.

1. Run python3 tools/modkit.py gen2check my_mod (or gen3check my_mod for the GBA games) and save the output. Errors identify changes required before the mod can claim that generation; warnings and unresolved: notes need review. The checker is a scan, so it is not the final gameplay test.
2. Add or update the manifest’s games entry only after deciding which games you have actually tested. A claim tells the launcher to load the mod on that game. If the mod only touches registries, hooks and events, consider moving it to "api": 3 instead; see Portable mods.
3. Prefer the shared mod.* registries, hooks, and events. Replace a Gen 1-only module access with the shared seam named by the checker when one exists.
4. Run the headless load check for the generation, then boot the imported game and exercise the feature you changed. Read the manager’s load errors and the runtime log separately.
5. If the feature fails, revert the last compatibility change, capture the exact finding or log message, and fix one site at a time. Do not treat a clean scan as proof that an unobserved feature works.

The detailed sections below explain the reasons behind each step. The adapter matrix and edge-case patterns are reference material for authors who need them; they are not prerequisites for a registry-only mod.

The Gen 2 examples and adapter details on this page were checked on Gold. "gen2" covers Gold, Silver and Crystal, which share one engine, but do not assume that a Gold-only module, hook, or field has the same backing on Crystal until it has been checked against that game and build. Gen 3 has its own adapter and its own tables, covered in Gen 3.

What actually breaks, and why

Gold is not a skin over the Gen 1 engine. It is a second engine living beside the first one: src/core/Game2.lua owns the boot, src/world/gen2/World.lua is the overworld, src/battle/gen2/Battle.lua is the battle, and src/script/gen2/Vm.lua runs the cart's own bytecode instead of a Lua row list. A Gold boot never loads src/core/Game.lua, src/world/OverworldController.lua or src/battle/BattleState.lua at all.

The GBA games are a third engine: src/core/Game3.lua owns the boot, the overworld is src/core/game3/field.lua over src/world/game3, the battle is src/core/game3/battle, and scripts run the cart's bytecode through src/core/game3/scripting. Gen 3 files use snake_case names under game3/ folders (src/ui/game3/start_menu.lua), not Gen 1 CamelCase.

The mod API on top is deliberately one API: the same registry names, the same hook names, the same event names, the same mod.* facade. A mod that stays on that surface mostly moves across unchanged. What does not move is everything underneath it.

The failure that motivated all of this is quiet, which is what makes it worth a whole page. A mod with engine_internals writes local Game = require("src.core.Game") and patches a method on it. Under Gold that require used to succeed: the file is on disk, require finds it, hands back a perfectly good module table, and your patch lands on it. Nothing ever instantiates that table, so the patch runs zero times and the only symptom is that your mod does nothing. No error, no warning, no crash to bisect.

Two things fixed that. First, a mod is not loaded on a Gen 2 or Gen 3 boot unless it says it is for that generation, so the default outcome is "not running" rather than "running wrong". Second, when it does say so, a require made from your own file is answered by an adapter that presents the Gen 1 API over that engine's internals, and a member the adapter cannot honestly back reads nil instead of reading plausibly-wrong.

Step 1: run the checker before you change anything

modkit gen2check reads your manifest, statically scans every .lua the package carries, and cross-references what it finds against the adapter's own coverage table. Run it first: it tells you the size of the job in a few seconds. gen3check is the same tool against the Gen 3 adapter (MK400 then reads no Gen 3 game in "games").

python3 tools/modkit.py gen2check <id-or-path> [<id-or-path>...]
python3 tools/modkit.py gen3check <id-or-path> [<id-or-path>...]

Real output, against a follower mod written for Yellow:

-- PokePCFollowers_VoxelMerge: api 1, profile content, no games declared, permissions engine_internals, 0 dependencies, game_version unset
MK400 ERROR manifest.json: no Gen 2 game in "games" (and no gen2compat), so a Gen 2 boot skips this mod; the rest of this report is what it would hit once it claims one
MK404 ERROR main.lua:575: BattleState.newWild has no Gen 2 backing: Gold has no factory that returns an unpushed battle, and World:startBattle constructs and pushes in one call. A mod that wraps newWild to rewrite the species must be pointed at the encounter.species hook, which Gold raises with the same name and shape; this reads nil
MK409 WARN  main.lua:13: allow-lists a Gen 1 version string, which excludes this mod from a Gen 2 game by construction; test for the capability the code needs instead of the version
modkit: unresolved: 1 site: requires whose result is neither bound to a name nor indexed here, so where the module goes is not followed (main.lua:221)
modkit: src.world.PikachuFollower.onMapEntered closes over 'shouldSpawn' on a Gen 2 boot, so the upvalue surgery at main.lua:325 lands as it does on Gen 1
FAIL PokePCFollowers_VoxelMerge on gen 2: will not work (3 errors, 3 warnings)

Three kinds of line, and the difference matters:

• MK4xx ERROR / MK4xx WARN are findings with a file and a line. Errors set the exit code; warnings do not unless you pass --strict.
• modkit: notes are things the tool derived rather than found, or could not decide at all. They never change the exit code.
• The verdict: will load, will load but degrade, or will not work.

The rule ladder:

rule	what it means
MK400	the manifest claims no game of this generation, so its boot skips the mod
MK401	a dependency claims no game of this generation, which takes you down with it
MK402	you require a Gen 1-only module the adapter does not serve
MK403	this generation runs a sibling of the module instead (gen2/, or game3/ in snake_case)
MK404	a member you touch has no backing on this generation (the adapter's own reason is quoted)
MK405	a member you touch degrades and says so once
MK406	the signature moved under an alias
MK407	debug upvalue surgery this generation's arm cannot take
MK408	upvalue surgery the scan could not resolve either way
MK409	a version allow-list, or a Gen 1 screen id
MK410	the entry chunk reads a member of a game that is not up yet

Flags: --strict promotes warnings to failures, --notes prints the adapter's note for every backed member you touch (worth reading once per mod, because several backed members are backed with a caveat), --json emits one document for the whole batch, --quiet drops everything except the findings, so a clean mod prints nothing at all and the exit code is the whole answer. Exit code is 0 clean, 1 on a fatal finding, 2 on usage.

Name several mods in one invocation and they are read as one install set, so a mod and its dependencies can answer each other's MK401.

What the checker cannot see, and says so

It is a static scan, not a run. It follows a require made through your own tryRequire-style wrapper, local ok, M = pcall(require, "..."), an inline require("src.world.Map").waterTiles(...), a bracket index M["member"] and a local hop local F = M.

What it cannot follow it names instead of ignoring. Every unfollowed reach comes back as an unresolved: note carrying a file and a line: a require name built at runtime or concatenated, a require whose result is neither bound nor indexed on the spot, a multiple assignment whose value it cannot pair to a name, an engine module indexed with a computed key, rawget or rawset on a bound module (that goes to the table the require shim hands back, so on Gold it reaches the adapter facade and not the module behind it), an engine module read as a value rather than indexed, and a debug upvalue call whose target it could not tie to a module.

The practical consequence is worth stating plainly: an empty finding list plus no unresolved: notes means the scan followed everything it saw. An empty finding list on its own does not.

It is also silent about any member the coverage table does not record. A clean gen2check means "nothing known-broken was found", not "this works". Boot it.

Step 2: declare which games the mod is for

Nothing moves on disk. A mod is installed once, into mods/<id>/, and that one directory serves every game. There is no mods/gen1/, no mods/gen2/, and no per-generation copy: targeting is something the manifest declares, not something the filesystem encodes.

{
  "id": "my_mod",
  "name": "My Mod",
  "version": "1.0.0",
  "entry": "main.lua",
  "api": 2,
  "games": ["gen1", "gen2"]
}

games is an optional array. Each entry is one of:

token	means
"red", "blue", "yellow", "gold", "silver", "crystal", "firered", "leafgreen", "ruby", "sapphire", "emerald"	that one game
"gen1", "gen2", "gen3"	every game of that generation (case-insensitive; "gen 2" also parses)
"frlg", "rse"	the FireRed/LeafGreen or Ruby/Sapphire/Emerald family
"all"	every game this engine has

The scaffold writes the key for you:

python3 tools/modkit.py scaffold my_mod --games gen1,gen2

--games takes the same tokens, comma-separated (gen3, frlg, rse, version ids). Pass --api 3 to scaffold a portable mod.

Omitting games keeps the old meaning exactly. No games key means Gen 1 only, plus Gen 2 if the legacy "gen2compat": true flag is set. There is no legacy flag for Gen 3: gen2compat is not a Gen 3 claim. Every manifest written before the key existed means precisely what it always meant. gen2compat is still accepted and is purely additive: it adds the Gen 2 games to whatever games says, so no manifest can lose a game it already ran on.

An unknown token warns and is dropped under api 1 and refuses the manifest under api 2. A games array naming no game this engine knows falls back to the default rather than orphaning the mod. A non-array games is a hard error.

What you are claiming

Adding a game to games is you saying I have run this there. It is not a request for best-effort support and the loader does not treat it as one: a mod that claims a game is loaded on that boot in full, with its registrations, its subscriptions and its entry chunk, exactly like a mod written for it. If it is half-working, the player sees a broken mod, not a partially-supported one. That is the whole reason the key exists rather than being inferred.

Every token is enforced, per game. "games": ["blue"] really does not load on Red. "games": ["gold"] alone does not load on Red either. If you want a mod everywhere, say so: ["gen1", "gen2", "gen3"] or ["all"].

Dependencies are contagious. A mod whose hard dependency does not run here is left out too, carrying the dependency's own wording (depends on X, which does not run here (For Blue, not Red)). It is reported as a skip rather than a failure and neither mod lands on the boot error list, but the mod does not run. Every hard dependency in the chain has to cover the same games, unless the spec scopes itself out of a game (next).

A dependency can scope itself to some games. A spec written as an object may carry its own games list, and optionally a game_version engine range, beside id and range:

"dependencies": [
  { "id": "pokegear_cards", "range": "^1.0.0", "games": ["gen2"] }
]

On a boot the scope does not cover, the loader treats the spec as if it were not written: the dependency is not required there, does not order the load there, and cannot skip or fail you there (src/mods/ModTargets.lua specApplies; the cycle check and the load order read the same answer). On a covered boot it is a hard dependency like any other. This is how a ["gen1", "gen2"] mod leans on a Gold-only helper without dragging it onto Red: the helper claims ["gold"], the dependent scopes the spec to ["gen2"], and both boots come up clean. gen2check follows the scope too, so a dependency scoped away from Gen 2 draws no MK401, and the launcher's dependency verdict never shows an out-of-scope dependency as Needs <id> (not for Gold).

The player can overrule you, in one direction only. The in-game mod manager offers TRY HERE ANYWAY for any mod that does not claim this game. The choice is per game, so forcing a mod onto Red does not force it onto Gold. A forced mod loads normally and keeps a note saying its author never verified it here; the launcher shows it as Forced onto Gold by you (untested). The skip line reads like For Gen 1, not FireRed.

What the player sees

All three surfaces read the same derivation, the two UIs and the loader, so they cannot disagree about your mod. The launcher's mod panel carries a Show for: chip row and a per-mod tag (GEN 1, GEN 1+2, RED/GOLD, BLUE), greyed out with Not for this game when the mod does not run on the selected game. The in-game manager shows the same as ENABLED (NOT THIS GAME) with the skipped glyph. The launcher's dependency verdict asks the same question of your dependencies: Needs <id> (not for Gold) rather than Ready.

Enablement is per game as well, and it is a different switch from targeting. Each installed mod carries one enable checkbox per game (options.modsByVersion); the launcher panel, the in-game manager and the loader all read the same per-game answer, and the first launch after the switch went per-game copies the old shared flag to every game, so nothing turns itself off. Disabling a mod on Gold says nothing about Red.

Step 3: prefer the API over the modules

Before doing any adapter work, check whether you need the modules at all. In new code, take the live game from mod.game and the world from mod.world. Both resolve per generation inside the loader: mod.game is the Gen 1 singleton, the Game2 instance or the Gen 3 game, read on every touch rather than cached; mod.world is the Gen 1, Gen 2 or Gen 3 WorldAPI behind one method set. Neither needs engine_internals. The game.ready payload and every ui.* hook's first argument carry the same live game.

The shared method set keeps growing on the world side: mod.world answers availableFieldActions / useFieldAction (the contextual field shortcuts, where Gold adds its own headbutt, whirlpool, waterfall, sweet_scent and squirtbottle ids beside the shared ones) and the read-only mapOverview minimap on both generations, each resolved through that generation's own bike, collision, badge and fishing rules. The battle screen's battle.bottom_ui_visible and battle.status_hud_visible hooks answer on Gold too, so a HUD-hiding mod needs no adapter at all.

Anything you can express as a registry write, a hook or an event subscription is generation-agnostic already and needs nothing from this page. API 3 goes further: see Portable mods. The adapter exists for code written before Gold did, and for the small number of things the API genuinely does not reach.

Step 4: the adapter, module by module

On a Gen 2 boot with mods present, require is interposed, and a require made from a mod's own chunk for one of fifteen Gen 1 names is answered by src/mods/Gen2Compat.lua. Engine code is unaffected: the shim compares the caller's chunk against the engine tree, so engine files still get the real Gen 1 module on both generations. This is not a dev-mode feature; it installs on any Gold boot that has mods.

the name you require	kind	what you get	backed / warned / absent
src.core.Game	facade	a live proxy onto the Game2 instance	70 / 9 / 12
src.world.OverworldController	facade	over src/world/gen2/World.lua	56 / 5 / 72
src.world.Map	alias	src/world/gen2/Map.lua	28 / 2 / 9
src.world.NPC	alias	src/world/gen2/Npc.lua	27 / 0 / 1
src.pokemon.Boxes	facade	over src/core/gen2/Boxes.lua	22 / 0 / 0
src.battle.BattleState	facade	over src/ui/gen2/BattleState.lua	23 / 2 / 37
src.ui.PartyMenu	facade	over src/ui/gen2/PartyMenu.lua	19 / 2 / 13
src.world.WorldAPI	alias	src/world/gen2/WorldAPI.lua	16 / 2 / 0
src.world.PikachuFollower	alias	src/world/gen2/Follower.lua	10 / 0 / 11
src.script.ScriptRunner	facade	over src/script/gen2/Vm.lua	10 / 7 / 1
src.ui.OptionsMenu	facade	over src/ui/gen2/OptionsMenu.lua	8 / 0 / 1
src.world.FieldDefaults	facade	the playerSprites answer and named refusals	5 / 2 / 3
src.world.Collision	facade	DELTA / target / occupied / canMove	4 / 1 / 0
src.ui.StartMenu	facade	over src/ui/gen2/StartMenu.lua	4 / 0 / 0
src.ui.BoxMenu	alias	src/ui/gen2/PcMenu.lua	1 / 0 / 0

The counts are read straight off Gen2Compat.coverage, so they drift as the adapter learns; run the snippet below for the current ones.

Alias means the adapter is the Gen 2 module. Your monkey-patch, your rawset sentinel and your == idempotency check all land on the table Gold actually runs, and getmetatable(npc) == NPC is true. Five names are aliases because nothing less would work.

Note that src.ui.BoxMenu points at src/ui/gen2/PcMenu.lua, not at src/ui/gen2/BoxMenu.lua. Gen 1's BoxMenu is Bill's PC top menu, whose Gold counterpart is PcMenu; Gold's BoxMenu is the withdraw/deposit list that Gen 1 builds inline.

Facade means a translating wrapper. .overworld resolves Game2.world, writeOptions resolves Game2:persistOptions, game.data.sprites resolves data.gen2Sprites, and NPC.new(data, mapId, objDef) is sniffed apart from NPC.new(mapId, objDef, spriteDef) with the movement vocabulary translated alongside it.

The four UI facades (PartyMenu, StartMenu, OptionsMenu, BattleState) are write-through: reads fall to the Gen 2 class and writes go to the Gen 2 class, so PartyMenu.update = wrapper patches the live class Gold pushes. Your write also reads back as your own value, so rawequal holds and an idempotency check works. That is what makes the ordinary capture-and-chain idiom safe: a wrapper calling the value it captured reaches Gold's real constructor rather than re-entering the facade's own override. Writing nil clears the member instead of re-exposing the override underneath.

The src.world.OverworldController facade sits over the live World, not over a class, so seven of its fields (map, player, npcs, entities, ghosts, npcPool, camera) read and write through to the running world: Gen 1's module is the singleton, so a write has to land somewhere real. A write made before a world exists is dropped with a warning rather than shadowing the world it would have applied to.

backed, warned, absent

The adapter publishes what it covers, and the checker consumes that same table rather than a copy. Exactly three statuses, and a member listed as both resolves to the weaker one:

• backed: present, and it does the Gen 1 job on Gold. Read the note anyway where there is one. Several backed members are backed with a caveat (Boxes.COUNT is 14 on Gold and not 12; BattleState.say ignores sayAuto's delay because Gold's messages always auto-advance; Collision.DELTA is Gold's live table, so adding a key mutates Gold's own movement).
• warned: present, answers nil or degrades, and names itself once in the log with your mod attributed. OverworldController.neighbors is the shape of the category: Gold's rows are { id, ox, oy, image } where Gen 1's are { map = mapDef, ox, oy }, so the field warns and answers nil rather than handing back a list whose nb.map is nil on every row.
• absent: deliberately not on the table. It reads nil, which is the honest failure.

"Absent" means not served, not wrong. Every one was left off for a stated reason, and the reason is in the coverage note. BattleState.newWild is the clearest case: Gold has no factory returning an unpushed battle, because World:startBattle constructs and pushes in one call, so a newWild taking a species and a level would be a lie about what Gold's battle screen is. The route for what you were actually doing, rewriting the species of a wild encounter, is the encounter.species hook, which Gold raises under the same name with the same shape.

A member the table does not record is not a guarantee of anything, and the checker is silent about it too.

Reading the coverage yourself

The table is queryable, and it is the same query the checker makes. This is a read-only reference snippet, not a complete main.lua file:

Example status: reference outline; run it only in the SDK/checker context described above.

local Gen2Compat = require("src.mods.Gen2Compat")

Gen2Compat.modules()                 -- the 15 served names, sorted
Gen2Compat.serves("src.world.Map")   -- true
Gen2Compat.memberStatus("src.battle.BattleState", "newWild")  -- "absent"

local c = Gen2Compat.coverage("src.world.Map")
-- { module, kind = "facade"|"alias", target, members = { [name] = status },
--   notes = { [name-or-topic] = "one line" } }

notes keys are documentation topics, not a member list: dotted paths (save.money), field names (warpAt), hook names (hook ui.pc.items) and bare topics (identity, iteration, rawset) all appear there. members is the authoritative set.

Gen 3

The same shim serves Gen 3 from src/mods/Gen3Compat.lua: the same fifteen Gen 1 names, answered over the GBA engine. Only src.world.WorldAPI is an alias (to src/world/game3/WorldAPI.lua); the rest are facades.

the name you require	over	backed / warned / absent
src.core.Game	src/core/Game3.lua	75 / 21 / 2
src.world.OverworldController	src/core/game3/field.lua	25 / 3 / 37
src.world.Map	src/core/game3/map.lua	16 / 1 / 25
src.world.NPC	src/core/game3/objects.lua	2 / 1 / 6
src.world.WorldAPI	src/world/game3/WorldAPI.lua	24 / 0 / 0
src.world.Collision	src/core/game3/collision.lua	4 / 1 / 0
src.world.FieldDefaults	named refusals	4 / 3 / 3
src.world.PikachuFollower	no Gen 3 module	8 / 0 / 9
src.battle.BattleState	src/core/game3/battle	11 / 0 / 20
src.script.ScriptRunner	src/core/game3/scripting/vm.lua	8 / 5 / 6
src.pokemon.Boxes	src/core/game3/storage.lua	8 / 0 / 6
src.ui.StartMenu, OptionsMenu, PartyMenu, BoxMenu	src/ui/game3/*	6 / 0 / 3, 6 / 0 / 4, 7 / 0 / 10, 6 / 0 / 6

Gen 3 differs from Gold in ways the adapter cannot hide:

• Blocks are 16 px and zero-based (32 px on Gen 1 and 2), the screen is 240x160, and screens draw inside a 160x144 interior unless the state sets gbaCanvas = true.
• NPC.new has no constructor (object templates come from the extracted map events); spawn through mod.world:spawnNpc(mapId, objDef).
• Gen 3 scripts are the cart's bytecode run by a VM; the portable queueScript rows are the way to script from a mod. world.talk takes scriptKey for native scripts, and Gen 1 talk scripts through that path are refused.
• Registries without a Gen 3 target (apricorns, audio, battle_sprite_scales, constants, field, held_items, link_fields, phone_contacts, radio_channels, rulesets, text_pointers, tilesets, transitions) are dropped and reported once per mod.
• Hook and event names with a Gen 3 call site are listed in the Gen 3 compatibility notes; ask mod:supports("hooks", name) at run time. Mon state names (gender.roll, shiny.roll, breeding.compatibility, egg.hatched, happiness.changed, pokerus.infected, roamers) are raised on Gen 3 as on Gen 2; phone, radio and apricorn names are not.

Query the table the way the checker does:

local Gen3Compat = require("src.mods.Gen3Compat")
Gen3Compat.modules()
Gen3Compat.memberStatus("src.world.Map", "warpAt")

The patterns no adapter can fix

Five shapes come up in nearly every real Gen 1 mod, and none can be fixed on the engine side without lying to you. Each has a route that works on every generation. The examples are written for Gold; on Gen 3 swap the Gen 2 names for the Gen 3 ones (Gen2PcMenu becomes a game3/pc_menu screen, and so on), or better, use the shared hook.

1. A hardcoded version allow-list

Example status: illustrative anti-pattern; do not paste this fragment alone.

local v = GameVersion.get()
if v ~= "red" and v ~= "blue" and v ~= "yellow" then return false end

This excludes you from Gold by construction, and it does so after everything else in your mod has been made to work, which produces the most confusing possible outcome: the adapter resolves, your patches land, and the feature still never appears. MK409 catches it.

Instead, test for the thing the branch actually depends on:

Example status: illustrative insertion; place the capability check inside the feature that needs it.

local Follower = require("src.world.PikachuFollower")
if Follower.setShouldSpawn then ... end   -- present on Gold, absent on Gen 1

Version tests stay legitimate for genuinely per-cart content, which is what Yellow's starter rename is. They are never right as a gate on a whole feature.

2. String-matching a screen id

Example status: illustrative anti-pattern; do not paste this fragment alone.

if id == "BoxMenu" then ... end

Gold's builtin screens are registered under Gen2-prefixed ids, so this matches nothing there. Screens.GEN2_IDS is the full list, 59 ids. Gen 3 has no Gen 1 builtin screens at all: mod.ui.push with an unregistered id raises there (the Gen 3 bridge is what an api 3 mod gets; api 1 and 2 mods keep the Screens-based push and the Gen 1 TextBox), and screens come from your own content.screens records.

Instead, either match both ids or take the seam the screen offers. Most screens a mod wants to decorate raise a hook whose name is shared across both generations (ui.start_menu.items, ui.options.rows, ui.party.submenu, ui.pc.items, ui.naming.grid, ui.list_menu), and a hook subscription needs no id at all. Where you must key off the id:

Example status: illustrative insertion; add the table and branch to an existing handler.

local BOX_IDS = { BoxMenu = true, Gen2PcMenu = true }
if BOX_IDS[id] then ... end

Watch the pairing. ui.pc.items has the same name on both sides but a different menu behind it: Gen 1 raises it over the WHICH-PC list, Gold over Bill's PC's own rows. And Gen 1's BoxMenu pairs with Gen2PcMenu, not Gen2BoxMenu.

3. debug.setupvalue on an engine local

Example status: illustrative anti-pattern; do not paste this fragment alone.

local idx = findUpvalue(PikachuFollower.update, "shouldSpawn")
debug.setupvalue(PikachuFollower.update, idx, myPredicate)

This only ever worked because the Gen 1 file happened to hold that predicate in a file-local of that name. Nothing about the engine promises it. Today the Gen 2 follower declares local shouldSpawn for exactly this reason, so follower mods reaching for it work unchanged on Gold. That is a deliberate courtesy, not a contract.

Instead, use the named seam when there is one, and fall back only when there is not:

Example status: illustrative insertion; adapt the seam names to the feature you are migrating.

if Follower.setShouldSpawn then
  Follower.setShouldSpawn(myPredicate)      -- Gen 2
else
  patchUpvalue(Follower.update, "shouldSpawn", myPredicate)   -- Gen 1 today
end

setShouldSpawn writes the same cell debug.setupvalue reaches, so the two cannot disagree. The presence test is doing real work: Gen 1's PikachuFollower has no setShouldSpawn, so this is not a rename you can apply blindly. Note also that the predicate is called (game, world) on Gold where Gen 1 passes (game, ow): the same object under a different name, so a predicate reading ow.player or ow.map is unchanged.

4. Capturing state off src.core.Game at file scope

Example status: illustrative anti-pattern; do not paste this fragment alone.

local Game = require("src.core.Game")
local save = Game.save          -- nil forever
local party = Game.save.party   -- error at load

The module require itself is fine and is meant to be: the Gen 2 src.core.Game is a proxy that reads the live Game2 instance on every touch, precisely so a mod capturing it at file scope keeps working once a save and a world exist. What does not survive is capturing a field off it at file scope, which snapshots nil. MK410 catches it.

Example status: illustrative insertion; place this read inside your ready-event handler.

local Game = require("src.core.Game")
mod.events:on("game.ready", function(ev)
  local game = ev.game            -- the real Game2 instance
  local party = Game.save.party   -- read now, not at file scope
end)

Three further properties of the proxy that a Gen 1 mod can trip over:

• Identity. The proxy can never compare equal to the Game2 instance the game.ready payload carries. Lua 5.1 fires __eq only when both operands share a metatable, so Game == ev.game is false on Gold. Do not use it as an idempotency check.
• Iteration. pairs, next and rawget see an empty table, because the proxy holds nothing of its own. Enumerate the game.ready payload instead.
• rawset. rawset(Game, k, v) lands on the proxy, reads back correctly through the same facade, and is completely invisible to the engine. That read-back is what hides it. Use a plain assignment, which writes through.

The save layout moved too, and those fields are absent rather than aliased so a wrong read is loud rather than silent: save.money is save.player.money, save.player.map / .x / .y / .facing are save.position.*, and save.player.rival is save.rival.name.

5. Monkey-patching a class, and the two ways it goes wrong

Patching a shared class method is supported, which is worth stating plainly because it is the thing most authors expect to have to rewrite:

Example status: illustrative insertion; keep the original method call in the class wrapper.

local PartyMenu = require("src.ui.PartyMenu")
local origUpdate = PartyMenu.update
function PartyMenu.update(self, dt) ... return origUpdate(self, dt) end

Two variants do not work, and neither can be made to.

Patching a member the Gen 2 class does not have. The write succeeds, reads back as your own function, and nothing ever calls it. BattleState.newWild = wrapper is the canonical case. This is the one place the read-back works against you, which is why MK404 reports the write site separately from the read site.

Patching a field on a live instance. menu.onSwitch = fn writes a field Gen 2 never reads: Gold takes it as onChoose at construction. Same for menu.swapFrom (renamed switchFrom) and for StartMenu's tx / ty / tw / th / anchor / maxVisible, which do not exist on Gold at all because the box is fixed. Pass what you need to .new instead: PartyMenu.new(game, { onSwitch = f }) with no battle, pickOnly or forceSwitch opens the plain list and calls onSwitch(mon, menu) on A, which is the Gen 1 behavior the facade reproduces.

A close relative worth calling out because it errors rather than no-ops: map.warpAt is a name collision, not a rename. Gen 1's is a table keyed by cell; Gold's Map:warpAt is a method of the same name. map.warpAt[cell] and pairs(map.warpAt) both raise, which is loud but points at your mod. Enumerate map.warps, which Gold carries as an ordered array.

A worked migration

A follower pack written for Red/Blue/Yellow. gen2check reports MK400 on the manifest, MK404 twice on BattleState.newWild and MK409 on a version allow-list, plus a note confirming its shouldSpawn surgery lands.

Before. Three separate problems in about twenty lines.

Example status: complete before-example for comparison only; it is intentionally broken on Gen 2.

local BattleState      = require("src.battle.BattleState")
local PikachuFollower  = require("src.world.PikachuFollower")
local GameVersion      = require("src.core.GameVersion")

return function(mod)
  -- (1) rewrite the starter encounter's species
  local origNewWild = BattleState.newWild
  BattleState.newWild = function(game, species, level, ...)
    if species == "PIKACHU" and level == 5 then species = "CHARMANDER" end
    return origNewWild(game, species, level, ...)
  end

  -- (2) decide whether a follower spawns
  local newShouldSpawn = function(game, ow)
    local v = GameVersion.get()
    if v ~= "red" and v ~= "blue" and v ~= "yellow" then return false end
    return packSize(game) > 0
  end

  -- (3) install it
  patchUpvalue(PikachuFollower.update,       "shouldSpawn", newShouldSpawn)
  patchUpvalue(PikachuFollower.onMapEntered, "shouldSpawn", newShouldSpawn)
end

On Gold: (1) assigns onto a name nothing reads, so the species rewrite never happens. (2) returns false for every Gold boot, so no follower ever spawns. (3) actually works, and works on a predicate that has already decided to do nothing. Two silent failures and one correct mechanism pointed at them.

After. The manifest gains "games": ["gen1", "gen2"], and:

Example status: complete after-example for comparison; adapt ids and helper functions to your mod.

local PikachuFollower = require("src.world.PikachuFollower")

return function(mod)
  -- (1) the species of a wild encounter is a hook on both generations
  mod.hooks:wrap("encounter.species", function(next, enc, ctx)
    local rolled = next(enc, ctx)
    if rolled and rolled.species == "PIKACHU" and rolled.level == 5 then
      rolled.species = "CHARMANDER"
    end
    return rolled
  end)

  -- (2) no cart check: whether there is a pack to walk is the whole question
  local newShouldSpawn = function(game, ow)
    return packSize(game) > 0
  end

  -- (3) the named seam where there is one, the upvalue where there is not
  if PikachuFollower.setShouldSpawn then
    PikachuFollower.setShouldSpawn(newShouldSpawn)
  else
    patchUpvalue(PikachuFollower.update,       "shouldSpawn", newShouldSpawn)
    patchUpvalue(PikachuFollower.onMapEntered, "shouldSpawn", newShouldSpawn)
  end
end

gen2check now reports clean, and the mod is shorter than it was on Gen 1 alone. That is the usual shape of this work: two of the three fixes replace engine surgery with an API that existed the whole time, and only the third needs a generation branch.

The one change that is not a simplification is the hook's contract. A wrapper takes (next, ...) and must call next with the arguments it was handed, where the monkey-patch could do as it liked with them. encounter.species transforms a rolled { species, level } and gets a ctx beside it: Gen 1 fills in mapId, terrain and rng, and Gold adds daytime, environment, kind ("wild" / "contest" / "script" / "sweet_scent"), tables and data. So the same subscription serves both games, and a Gold-only refinement is a field test rather than a second hook.

Testing

Headless, without a Gold cache. The SDK harness takes the generation directly (generation = 3 for the GBA games, with data = T.sdk.gen3Data()), and everything after that is the production path:

Example status: complete test outline; place it in the SDK test harness, not main.lua.

local run = T.sdk.loadMod("mods/my_mod", { generation = 2 })
T.eq(run.mod and run.mod.state, "loaded",
  "runs on gen 2: " .. tostring(run.mod and run.mod.skipReason))
T.eq(#run.errors, 0, "and loads with no boot errors")
run.release()

Assert the state, not just the error count. A gate skip is deliberately not an error, so T.eq(#run.errors, 0) on its own passes for a mod that never ran a line, which is the one result you were testing to rule out. run.mod.state is "loaded" when the entry chunk ran and "wrong_generation" when the gate or the dependency contagion took it. Keep the error assertion too: it catches a registry with no Gen 2 home and a require the adapter does not serve.

On a real boot. Nothing above substitutes for running it. The two channels are not the same:

• The log carries the adapter's own warnings, each attributed to the mod holding the facade ([my_mod] Game.renderer has no Gen 2 backing: ...). These do not appear in the manager.
• The manager's error feed is a shorter list: a mod that failed validation, a duplicate id, a registry with no Gen 2 target, a cross-validation problem, and one adapter-adjacent case, a require for a Gen 1 module the adapter does not serve. A skipped mod is not on it, and neither is a degraded member.

So: read the log for coverage problems, and the manager for load problems.

POKEPORT_IDENTITY=<name> sandboxes the save directory if you want a clean profile to test in, and POKEPORT_DEV=1 adds the console and F5 hot reload on Gen 1 only; Gen 2 and Gen 3 have neither.

What this guide does not promise

• Coverage is partial and will stay partial. 15 Gen 1 modules are served out of a much larger engine, and within those 15 the Gen 2 coverage table records 303 backed members against 32 warned and 160 absent (Gen 3: 210, 35 and 137). The absent ones are not a backlog; most are absent because there is no honest Gen 2 answer, and each carries its reason. The counts move as the adapter learns something: a member that turns out to answer nil is demoted rather than left flattering the table.
• Absent is not broken, it is not-served. A nil read is the designed outcome. If you would rather have an error, test for the member before you use it.
• The checker is a static scan. It cannot follow a require built at runtime, cannot tie every debug call to a module, and says nothing about a member the coverage table does not record. What it can do is admit each of those individually, with a file and a line, as an unresolved: note. A clean finding list with notes under it means "nothing known-broken was found in the part I could follow"; only a clean finding list with no notes means the scan followed everything.
• A backed member can still surprise you. backed means the adapter took responsibility for the Gen 1 call shape, not that Gold behaves identically. Run gen2check --notes once and read the caveats on the members you touch.
• The adapter is not a compatibility layer for new code. It exists so mods written before Gold keep working. If you are writing something now, mod.game, mod.world, the registries and the hooks mean the same thing in both games and need none of this.

See also

• Compatibility - API level, engine version, mod-vs-mod, and link play
• Portable mods across Gen 1, 2 and 3 - the API 3 route
• The modkit CLI - every subcommand, including gen2check and gen3check
• Manifest - the full manifest key reference
• Hooks - encounter.species and the shared ui.* seams

Check and recover

The checker checkpoint is a report with no known errors for the claimed game; the boot checkpoint is the mod loading and producing its intended visible change. If either fails, remove the new games claim or disable the last generation-specific change, return to the last working mod, and rerun gen2check or gen3check before editing another seam.