A FireRed mod's pokemon and moves patches are merged onto the live
src.core.game3.pokemon module while the mods load (Game3:_loadMods).
Entering FireRed then runs Pokemon.install() from Runtime, which swaps
every species table for a fresh copy of the ROM pack -- names, stats,
types, learnsets, and the move names that live in the same pack. The
only reload hook, in Gen3Compat.applyMerged, re-seeded the sprites and
nothing else, so every such patch was gone before the first frame: a
translation's species_names and move_names catalogs never reached the
party screen, the summary or a battle, and a mod's base stats reverted
to the ROM's.
Write the moves and pokemon registries again onto the new tables from
that hook, the way reapplyMoves already does for the moves module. The
moves registry is part of it because its names and the battle-move copy
it mirrors into belong to the reloaded pack, and it goes first, in the
order Loader:_mergeOrder uses: the moves writer is what adds a mod's own
moves to the move index, and the species writer resolves learnsets, egg
moves and TM/HM lists through that index.
mod.content.encounters:patch on a Gold boot keys by encounter KIND
(encounters.grass.ROUTE_29), but the id space was open: a key the
catalog did not describe was treated as a mod's own data and merged
as-is. A Gen 1 encounters mod ported unchanged writes the MAP where
Gold wants the kind, so the call was accepted, merged into
data.gen2Encounters.ROUTE_29 and read by nothing -- vanilla game, no
error, nothing in the Mod Manager (#2369).
That key cannot be a mod's own data the way an extra palette id can:
src/battle/gen2/Encounter.lua, src/core/gen2/Roamers.lua,
src/core/gen2/BugContest.lua and src/world/gen2/World.lua read this
table by name and the set of names is fixed, so an unknown id is a
write nothing reads. Add an opt-in `keysClosed` shape slot (folded by
Schemas.shapeFor like the other gen2* slots) that Schemas.check honours
in its keys/keyValue branch, and set it on encounters' Gen 2 spec. An
unknown id now names the ids that do exist instead of silently
no-opping; api 2 fails the mod, api 1 keeps the warning.
Also catalogue roamMons, which the extractor has always emitted
(RomExtractorGen2:readRoamMons) and Roamers.roster has always read, but
which was missing from gen2Keys.
Only encounters opts in: palettes, battle_anims and constants keep
their open id spaces, and Red's encounters id space is untouched.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Three follow-ups on the commit below.
statusBlockedId read the status record's optional `id` field. A mod that overrides a status rather than patching it replaces the record outright, and `id` is optional in the registry (src/mods/Schemas.lua), so the field can be nil there and full paralysis would quietly stop clearing bide, thrash, charge and trapping. It now falls back on the key the record was looked up under.
`msgs.failed` is the only thing that suppresses a primary effect's success animation now, so it is no longer an internal detail: the move_effects registry documents it, and docs/modding/reference/registries.md is regenerated. That regeneration also picks up rows that had drifted from the schema before this branch (missText, trueColor, the sprite cell fields).
The parity suite gains the case the commit below changes the rules in -- PAR's own roll clearing the volatiles, and a flinch on a paralysed battler leaving them alone -- and its translated-label block now restores the shared Data.text entries through pcall, so a failing check there cannot leak "pioupiou zzz" into every later parity suite.
Gen3Compat's src.ui.StartMenu coverage row claimed the
ui.start_menu.items hook is "not raised on FireRed yet". It is raised:
src/ui/game3/start_menu.lua calls it from StartMenu.show with
(game, entries), the same name and arity as src/ui/StartMenu.lua and
src/ui/gen2/StartMenu.lua.
The note is what a mod author reads when asking whether the hook exists
on this generation, so a stale one costs a mod the hook for no reason.
- Rewrite the note to describe the FireRed arm: a row is { id, label }
and carries no onSelect to rewire, and a non-table return is dropped
without the Logger.error the other two generations emit.
- List ENTRIES as backed and note it: the facade passes the module's
list straight through, and show() rebuilds it on every open, so a mod
has to act per open rather than once.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The Gen 3 extractor emitted eggCycles/eggGroups but never egg moves, so the
gen3_dexnav hidden-mon roll was inert on FireRed: a hidden mon kept its
level-up moves and could never gain an egg move.
Decode the ROM's own gEggMoves table (pokefirered/src/data/pokemon/
egg_moves.h) into pokemon/egg_moves.lua and expose it the same way as
learnsets/tmhm:
- Versions: EGG_MOVES = 0x25EF0C plus the 20000 species offset, the 0xFFFF
run terminator and a defensive per-species cap. The table is one flat u16
stream of `{ species + 20000, move..., 0xFFFF }` runs with no final
terminator, so the first word that is neither a header nor a plausible move
id ends the scan.
- PokemonExtract: extract_egg_moves + write_egg_moves_lua, written to the
cache by run(), required by ready() so a stale cache re-extracts, and
returned as pack.eggMoves. FORMAT_VERSION 3 -> 4.
- Pokemon.eggMoves(species): runtime accessor with the same species coercion
as Pokemon.learnset; nil for a species with no egg move.
- Schemas: eggMoves on monTables/monRecord/writeMon and the Gen 3 species
field list, so a mod reads record.eggMoves as move ids and writes names back.
- Versions.CACHE_VERSION 98 -> 99 to force re-extraction.
The table is sparse: species without egg moves are absent rather than an
empty list, all the way from the ROM to the mod record.
Validated against a supported FireRed USA 1.0 dump: 165 species, 973 moves,
<=8 per species, Bulbasaur {113,130,219,204,80,345,320,174}, Mankey
{157,193,96,68,179,251,279,265} (no Toxic), Mew nil.
Tests: new tests/engine/game3_egg_moves.lua (31 checks ROM-free, 39 with a
ROM), gate_gen3_mod_api 734/734, engine tier 587/587, modkit tier 37/37,
lint --gate clean.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A full-colour icon pack renders white with purple blotches on any screen
that declares an SGB palette zone, and only in ADVANCED. Colour there is
applied after the frame is drawn: a shader reads each pixel's red channel
and swaps in one of four palette colours. That suits the game's own art,
which is already four greys. Full-colour art is not. A yellow body is
nearly all high red, so it clears 0.83 and comes back as colour 0, white in
every palette, while the darker pixels land in colour 2, which MEWMON
paints {115,33,165}.
Art that should be left alone says so with a trueColor flag and is re-blit
unshaded. Battle pics, trainer portraits and overworld sprites all carry
one. Menu icons had no way to. The icons record has no such field, and
Sprites.iconPath returned a path alone where Sprites.path and
Sprites.playerPic both return path, trueColor. Nowhere to put the flag and
nothing to read it, so the art always met the shader.
R.sprites is the precedent for allowing it. Overworld walkers are OBJ art
drawn through an OBJ palette, the same hardware class as a menu icon, and
they carry the flag already.
iconPath now takes the record's flag through opts and returns it, and a
pokemon.icon hook may set ctx.trueColor for art it substitutes, which is
the contract pokemon.sprite already has.
PartyMenu.drawIcon skips the OBP bake for flagged art and reports its
covering rect. The bake matters as much as the shader does: obpIcon is
itself a four-shade remap on the red channel, so it flattens full-colour
art before the zone pass ever runs. The flag overrides `name` rather than
being read beside it, because a hook can substitute full-colour art for a
species that resolved to a built-in class through icons.byDex, leaving name
set. The entry-shape split from #274 does not catch that case.
The reported rect is 16x16 for the two OAM-block branches and the file's
own size for single-frame art, matching what each branch actually draws.
No vanilla icon record sets the flag, so both rect buckets stay empty on a
vanilla boot and the zone lists stay exactly the ones the states returned.
GEN2_STATUS_IDS (psn/brn/frz/par/paralysis/slp -> Gen 2's own registry ids)
was declared verbatim in both PartyMenu.lua and SummaryMenu.lua; move it to
Status.GEN2_ID_ALIASES so a future status alias fix only has one copy to
update.
SummaryMenu.TYPE_NAMES was left behind after this branch switched its two
former internal uses to the shared TypeChart.displayName/DISPLAY_NAMES; it
has no remaining callers anywhere in src/ or tests/.
src/ui/gen2/PokedexMenu.lua reads its KIND label and both description
pages from data.gen2Pokedex.entries, loaded straight from disk before
mods:load runs -- a separate table from data.pokemon, the `pokemon`
registry's own merge target. mod.content.pokemon:patch(id, { dexEntry =
... }) therefore validated but never reached the screen. Adds
src/core/gen2/PokedexText.lua to project a patched dexEntry onto the
#DEX table after the merge (Game2:load, alongside the other Gen 2
post-merge registries), and a text2 field to the dexEntry schema for
the entry's second description page, which the screen already reads
but the registry had no field for. Also routes the OPTION/SEARCH panel
titles (PokedexMenu.lua) through Strings(), the same literal-wrapping
pattern already used elsewhere in this screen and its siblings.
bootGame's require("src.core.Game") was resolving to Gen2Compat's Game
facade after a Gold session, so the next Gen 1 boot got an empty proxy
whose rawget(load) is nil (iOS: "src.core.Game missing load after
reload"; Android: Game:load called on a nil value).
Two independent causes, both needed:
* callerIsMod decided "not under src/" meant "a mod", and main.lua is
not under src/, so the engine's own require was gated as a mod's.
Root chunks main.lua and conf.lua are now matched exactly, which a
mod's own mods/<id>/main.lua cannot collide with.
* devShim.generation was only ever set, never cleared, so the
generation Gold declared outlived Gold's session. Loader.endSession
drops it from SessionLifecycle.endMountedSession, and the facade
gate now requires generation == 2 rather than ~= 1.
Only platforms that return to the launcher in-process (Android, and iOS
since #1808) keep the shim alive across sessions; everywhere else the
process restart cleared it.
A custom cart pairs an identity (title, shell colour, label art) with a base
game, a list of mods pinned to exact builds with their option values frozen,
a load order, and a seal. It ships no code of its own: every mod it names is
a separately published mod, which is what keeps a cart auditable before it
runs and reproducible after an author's repo disappears.
Format and storage:
- src/carts/CartManifest.lua parses and validates cart.json, canonicalises it
for hashing and reads/writes the .g1rcart bundle. The bundle is a data-only
serialised table read through SaveSerializer, so an imported cart can never
execute code. Canonical strings are length-prefixed because option keys and
values are author-controlled and could otherwise forge a record boundary and
collide two different carts onto one hash.
- Pins name a public source: a GitHub release with its sha256, a GameBanana
file id with its md5, or "local" for a capture that only exists on this
install. A local pin is unpublishable by construction, which is what makes
"build it here, publish later" possible without inventing a hash.
- Label art rides alongside the manifest rather than inside its identity, so
re-arting a cart does not tell every player their run is out of date.
src/core/Base64.lua decodes it; strict, with no whitespace tolerance.
Saves:
- Cart playthroughs live in the cart's own slot namespace (saves/cart_<id>/),
so a cart's file never sits beside a vanilla one and uninstalling a cart
never orphans a save. Every save records the cart build it was made under.
The seal:
- A sealed cart loads its pinned list, in its order, with its options, and
nothing else. A pinned mod with no frozen options gets an empty bucket so
unfrozen keys fall to schema defaults, identical for everyone; otherwise two
players on one cart quietly run different games.
- A sealed cart refuses to load when a pin is missing or installed at another
version. Playing a subset of the cart is the exact dishonesty the seal
exists to prevent, so the refusal loads nothing at all.
- Breaking the seal is permanent, marked per save slot, and downgrades that
playthrough to open behaviour. It cannot be cleared through any public API.
Launcher:
- A game's page carries a Custom Carts control and a picker; choosing a cart
turns the page into that cart's page, with its own cartridge, title and save
slots. The rail of five games never grows and a cart id never reaches
imp.tab or imp.panelVersion.
- Loader.planCart runs before boot so a refusal is visible on the page instead
of being discovered as an error after launch.
- Save as cart captures the enabled mods for a game and names, before the
player confirms, every mod that could only be pinned to this install and
whether the result can be shared at all.
Authoring:
- tools/cartkit.py scaffolds, validates, pins and packs a cart, and installs a
release workflow. Its writer is byte-identical to the engine's serialiser.
bryanthaboi