pokemon/gen1recomp
1
0
Fork 0
mirror of https://github.com/bryanthaboi/gen1recomp.git synced 2026-08-12 08:21:02 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
gen1recomp/tests/engine/gate_gen2_mod_api.lua
T
bryanthaboi ae6cac89e1 G2 support
2026-08-11 11:53:30 -04:00

993 lines
44 KiB
Lua
Raw Permalink Blame History

-- Parity gate for the Gen 1 / Gen 2 mod API boundary.
--
-- The rule this file exists to hold: hook names, event names and registry
-- names are SHARED across generations, and the only things that differ are
-- where a registry's content lands and whether the mod runs at all. A mod
-- opts into Gen 2 with `gen2compat` in its manifest and is left out of a Gold
-- boot entirely without it, because a mod that half-applies reads as broken.
--
-- Runs ROM-free: the generation is injected through the loader rather than by
-- booting Gold (T.sdk.loadMods opts.generation).
package.path = "./?.lua;./?/init.lua;" .. package.path
local T = require("tests.modkit")
local GameVersion = require("src.core.GameVersion")
local Manifest = require("src.mods.Manifest")
local Schemas = require("src.mods.Schemas")
local StateStack = require("src.core.StateStack")
-- ------- 1. the version table knows its generation
T.eq(GameVersion.generation("red"), 1, "Red is Gen 1")
T.eq(GameVersion.generation("blue"), 1, "Blue is Gen 1")
T.eq(GameVersion.generation("yellow"), 1, "Yellow is Gen 1")
T.eq(GameVersion.generation("gold"), 2, "Gold is Gen 2")
-- ------- 2. manifest: gen2compat is opt-in and defaults off
local function manifest(extra)
local raw = { id = "fix", name = "Fixture", version = "1.0.0",
entry = "main.lua", api = 2 }
for key, value in pairs(extra or {}) do raw[key] = value end
return Manifest.validate(raw, "mods/fix")
end
T.eq(manifest().gen2compat, false,
"a manifest that says nothing is Gen 1 only")
T.eq(manifest({ gen2compat = true }).gen2compat, true,
"gen2compat = true is carried through")
T.eq(manifest({ gen2compat = false }).gen2compat, false,
"gen2compat = false is carried through")
T.check(not pcall(manifest, { gen2compat = "yes" }),
"a non-boolean gen2compat is rejected")
-- ------- 3. registry target routing
--
-- One routing table per generation (Schemas.routing): Gen 2 keeps the shared
-- target for everything it can serve and reports the rest instead of merging
-- into a table nothing reads, and Gen 1 does the same for the registries that
-- only exist because Gold does. Gen 1 used to consult nothing at all; the
-- catalog now holds content BOTH ways round, so the claim is the symmetrical
-- one -- a registry is gated in a generation exactly when it has no home
-- there, whichever generation that is.
for name, spec in pairs(Schemas.REGISTRIES) do
T.eq(Schemas.targetFor(name, spec, 1), spec.target,
"Gen 1 keeps the catalog target: " .. name)
if Schemas.GEN1[name] == nil then
T.eq(Schemas.gatedFor(name, 1), false,
"a registry Gen 1 routing says nothing about is not gated there: " .. name)
else
-- the mirror of the gated rows below: a Gen 2-only system, so there is no
-- Gen 1 target to keep and a Red mod's write is dropped and reported
-- rather than merged into a namespace no Gen 1 boot reads. The per-
-- registry cases are in tests/engine/gen2_content_registries.lua.
T.eq(Schemas.gatedFor(name, 1), true, "gated under Gen 1: " .. name)
T.eq(spec.target, nil,
"a Gen 1-gated registry carries no Gen 1 target: " .. name)
T.check(Schemas.targetFor(name, spec, 2) ~= nil,
"and has a Gen 2 home, or the name is dead in both: " .. name)
end
end
-- the registries Gold genuinely reads off game.data keep their name AND their
-- path, which is what lets one mod source target both generations.
-- `commands` is here rather than in the routed set below because the Gen 2 VM
-- resolves a mod verb out of the SAME merged data.commands table Gen 1's
-- runner does (src/script/gen2/Vm.lua:runModCommand, reached from the
-- Opcodes.MOD_COMMAND row a cart can never write).
for _, name in ipairs({ "pokemon", "moves", "items", "type_chart", "screens",
"strings", "font", "audio", "music", "sfx", "cries",
"map_songs", "commands",
-- `tokens` because TextBox.substitute reads
-- game.data.tokens on every box in both games, and
-- `growth_rates` because src/mods/Builtins.lua's Gen 2
-- registrant seeds Gold's curves as the same
-- { expForLevel } record Gen 1 uses, so one mod record
-- serves both (src/battle/gen2/Mon.lua:growthFor is the
-- single accessor all six Gen 2 readers go through)
"tokens", "growth_rates",
-- `battle_sprite_scales` because
-- src/ui/gen2/BattleState.lua:imageScale walks
-- data.battle_sprite_scales for a record whose .path
-- matches the pic being drawn, skipping `_owners`,
-- exactly as Gen 1's BattleState.imageBattleScale
-- does, and picScale falls through to the species'
-- battleScaleFront / battleScaleBack after it. Only
-- the default differs (Red draws 32x32 back pics at
-- 2x, Gold's 48x48 ones fill their box at 1x) and the
-- default is not a registry record either side.
--
-- `render_pipelines` because src/core/Game2.lua:load
-- calls Pipelines.install(self.data) AFTER mods:load,
-- so src/render/Pipelines.lua walks the MERGED table,
-- and Game2:draw composites the whole-frame half
-- through Pipelines.wantsPresent / Pipelines.present.
-- Gold does not composite `drawWorld` yet -- its
-- overworld draws straight to the window -- and
-- Game2:load retires a restored drawWorld-only level
-- rather than leaving it on and drawing nothing, so
-- that half is inert rather than broken. Routing it
-- is still right: the registry has a live reader, and
-- a gated registry would drop the `present` half too.
"battle_sprite_scales", "render_pipelines" }) do
local spec = Schemas.REGISTRIES[name]
T.check(spec ~= nil, "catalog still has registry: " .. name)
T.eq(Schemas.targetFor(name, spec, 2), spec.target,
"available under Gen 2 at its Gen 1 path: " .. name)
T.eq(Schemas.gatedFor(name, 2), false, "not gated under Gen 2: " .. name)
end
-- The tables Gold namespaces: same registry NAME, a Gen 2 Data path
-- underneath it. src/core/Game2.lua:load reads each of these into game.data
-- before mods:load runs, and the consumer holds it by reference --
-- src/world/gen2/World.lua:dataTable for the overworld four, the menus for
-- palettes/icons/battle_anims/constants -- so the merge lands in the table the
-- game walks. The battle-rule six have no table on disk at all: they come
-- into existence AS the merge (src/mods/Builtins.lua seeds Gold's own records
-- there), and each consumer reads them through a per-id lookup that falls back
-- to the module's records, so a mod-free boot behaves identically.
-- The pairing is asserted both ways round: routed is NOT the Gen 1 target
-- (that would mean merging into a table no Gold boot reads) and NOT nil (that
-- would mean the write is being dropped).
for name, path in pairs({ maps = "gen2Maps", tilesets = "gen2Tilesets",
sprites = "gen2Sprites", text = "gen2Text",
encounters = "gen2Encounters",
trainers = "gen2Trainers",
palettes = "gen2Palettes", icons = "gen2Icons",
battle_anims = "gen2BattleAnims",
constants = "gen2Constants",
statuses = "gen2Statuses",
move_effects = "gen2MoveEffects",
item_effects = "gen2ItemEffects",
balls = "gen2Balls",
ai_classes = "gen2AiClasses",
evolution_methods = "gen2EvolutionMethods" }) do
local spec = Schemas.REGISTRIES[name]
T.check(spec ~= nil, "catalog still has registry: " .. name)
T.eq(Schemas.targetFor(name, spec, 2), path,
"available under Gen 2 at its Gen 2 path: " .. name)
T.check(Schemas.targetFor(name, spec, 2) ~= spec.target,
"a routed registry does not keep the Gen 1 path: " .. name)
T.eq(Schemas.gatedFor(name, 2), false, "not gated under Gen 2: " .. name)
T.eq(Schemas.targetFor(name, spec, 1), spec.target,
"and Gen 1 is untouched by the routing: " .. name)
end
-- The mirror set: six registries that exist because GOLD does. They carry no
-- Gen 1 target at all, so the routed path is the only path they ever have, and
-- Schemas.GEN1 gates them on Red the way Schemas.GEN2 gates `map_scripts` on Gold.
-- Each is held to a live consumer, which is the claim that matters: a routed
-- registry nothing reads is the silent no-op the whole routing table exists to
-- prevent. The per-consumer cases are in
-- tests/engine/gen2_content_registries.lua; here the pairing itself is pinned.
-- held_items src/core/gen2/ItemEffects.lua:heldItemFor / applyHeldItems,
-- written back onto data.items for Battle:itemDef
-- phone_contacts src/core/gen2/Phone.lua:useRegistry
-- decorations src/core/gen2/Decorations.lua:attributes
-- apricorns src/core/gen2/Apricorns.lua:useRegistry
-- landmarks src/core/gen2/Nests.lua:landmarkId / landmark
-- radio_channels src/ui/gen2/MapRadio.lua:channelRecord
for name, path in pairs({ held_items = "gen2HeldItems",
phone_contacts = "gen2PhoneContacts",
decorations = "gen2Decorations",
apricorns = "gen2Apricorns",
landmarks = "gen2Landmarks.landmarks",
radio_channels = "gen2RadioChannels" }) do
local spec = Schemas.REGISTRIES[name]
T.check(spec ~= nil, "catalog still has registry: " .. name)
T.eq(Schemas.targetFor(name, spec, 2), path,
"a Gen 2-only registry is available under Gen 2: " .. name)
T.eq(Schemas.gatedFor(name, 2), false, "not gated under Gen 2: " .. name)
T.eq(spec.target, nil,
"and carries no Gen 1 target to fall back on: " .. name)
T.eq(Schemas.gatedFor(name, 1), true,
"so a Red boot reports the write rather than merging it: " .. name)
T.eq(Schemas.targetFor(name, spec, 1), nil,
"and has no Gen 1 path at all: " .. name)
end
-- and the ones Gold has no home for are gated, not silently retargeted.
-- One cause is left behind these: Gold reimplements the system WITHOUT
-- reading a registry, so there is no table a merge could land in that anything
-- would read. Closing one is a consumer change in the Gen 2 module first and
-- a routing row second, which is exactly how growth_rates closed --
-- src/battle/gen2/Mon.lua grew growthFor / registerInto and takes an
-- expForLevel record ahead of the coefficient row, so the registry now routes
-- to the SHARED Gen 1 path and one mod record serves both games.
--
-- `tokens` was on this list by mistake rather than by cause: TextBox.new runs
-- TextBox.substitute on every box in both generations and substitute reads
-- game.data.tokens, so the shared target was live on Gold the whole time.
-- `battle_sprite_scales` and `render_pipelines` came off it the way
-- growth_rates did, consumer first: src/ui/gen2/BattleState.lua:imageScale now
-- reads data.battle_sprite_scales, and src/core/Game2.lua:load installs
-- src/render/Pipelines.lua on Gold's merged dataset after mods:load so
-- Game2:draw composites a `present` pipeline. Both are asserted in the shared
-- set above.
--
-- `transitions` stays because Gold's own intro
-- (src/ui/gen2/BattleTransition.lua) keys STYLES as a boolean SET of the four
-- cart wipes rather than the { frames, draw, sound, flash } record this
-- registry carries, and has no styleDef lookup a mod id could reach.
--
-- map_scripts is the one genuine script-side gap left: src/script/gen2/Vm.lua
-- runs the cart's bytecode out of data.gen2Scripts keyed by ROM pointer, and a
-- Lua row list merged into that pool is not something the VM can run.
for _, name in ipairs({ "map_scripts", "rulesets", "transitions",
"field", "text_pointers", "link_fields" }) do
local spec = Schemas.REGISTRIES[name]
T.check(spec ~= nil, "catalog still has registry: " .. name)
T.eq(Schemas.targetFor(name, spec, 2), nil,
"gated registry has no Gen 2 target: " .. name)
T.eq(Schemas.gatedFor(name, 2), true, "gated under Gen 2: " .. name)
end
-- A routed registry is only routed if the records already sitting at that
-- path pass the shared schema, so this pins the two optional warp fields Gen 2
-- carries (the ROM map-group pair) that a strict record would otherwise
-- reject on every one of Gold's 368 maps.
do
local spec = Schemas.REGISTRIES.maps
local gen2Map = {
id = "MOD_TOWN", tileset = "TILESET_JOHTO", width = 2, height = 2,
blocks = { 1, 2, 3, 4 },
warps = { { x = 6, y = 3, destMap = "ELMS_LAB", destWarp = 1,
destGroup = 24, destMapNum = 5 } },
}
T.check(Schemas.check(spec, "maps", "MOD_TOWN", gen2Map, "register"),
"a Gen 2 warp row validates against the shared maps schema")
local gen1Map = {
id = "MOD_TOWN", tileset = "OVERWORLD", width = 2, height = 2,
blocks = { 1, 2, 3, 4 },
warps = { { x = 1, y = 1, destMap = "PALLET_TOWN", destWarp = 1 } },
}
T.check(Schemas.check(spec, "maps", "MOD_TOWN", gen1Map, "register"),
"and the Gen 1 warp row still does, the added fields being optional")
end
-- ------- 3b. the per-generation RECORD shape
--
-- Routing says where a registration lands; this says what a record there looks
-- like. A registry whose Gen 2 records differ carries gen2Fields / gen2Keys /
-- gen2Write beside the Gen 1 slots and Schemas.shapeFor folds them onto the
-- canonical names, which is what let the six shaped registries above be routed
-- at all: without it a Gold species would be judged against Red's `special`.
do
local spec = Schemas.REGISTRIES.pokemon
T.eq(Schemas.shapeFor("pokemon", spec, 1), spec,
"Gen 1 gets the catalog spec itself, not a copy")
local gen2 = Schemas.shapeFor("pokemon", spec, 2)
T.check(gen2 ~= spec, "Gen 2 gets a derived spec")
T.eq(Schemas.shapeFor("pokemon", gen2, 2), gen2,
"resolving a derived spec again is a no-op")
T.check(gen2.fields.levelMoves ~= nil and gen2.fields.level1Moves == nil,
"the Gen 2 species shape is folded onto `fields`")
T.eq(gen2.gen2Fields, nil, "and the gen2* keys are gone from the derived spec")
T.eq(gen2.target, "pokemon",
"a reshaped registry that is not rerouted keeps its path")
-- the split special stats, which is the difference that makes register
-- usable on Gold at all
local gold = {
id = "MODMON", name = "MODMON", dex = 252,
types = { "GRASS" },
baseStats = { hp = 45, attack = 49, defense = 49, speed = 45,
specialAttack = 65, specialDefense = 65 },
catchRate = 45, baseExp = 64, growthRate = "MEDIUM_SLOW",
levelMoves = { { level = 1, move = "FIX_TACKLE" } },
evolutions = {},
spriteFront = "a.png", spriteBack = "b.png", picSize = 5,
}
T.check(Schemas.check(spec, "pokemon", "MODMON", gold, "register", 2),
"a Gen 2 species record registers under Gen 2")
T.check(not Schemas.check(spec, "pokemon", "MODMON", gold, "register", 1),
"and the same record is not a Gen 1 species")
local _, err = Schemas.check(spec, "pokemon", "FIXMON_A",
{ baseStats = { special = 80 } }, "patch", 2)
T.check(err ~= nil and err:match("special"),
"a Gen 1 baseStats.special is rejected under Gen 2: " .. tostring(err))
end
do
-- trainers routes one level further in, into .classes, and battle_anims
-- CLEARS the Gen 1 write (there the ids are the subtables the Gen 1 write
-- would have routed into)
local trainers = Schemas.shapeFor("trainers", Schemas.REGISTRIES.trainers, 2)
T.eq(trainers.target, "gen2Trainers", "the derived spec carries the routed path")
T.check(trainers.write ~= nil and trainers.baseAt ~= nil
and trainers.baseIds ~= nil,
"trainers reaches into .classes through write/baseAt/baseIds")
local anims = Schemas.shapeFor("battle_anims", Schemas.REGISTRIES.battle_anims, 2)
T.eq(anims.write, nil, "gen2Write = false clears the Gen 1 write")
T.eq(anims.baseAt, nil, "and the Gen 1 baseAt with it")
T.check(anims.keys ~= nil and anims.value == nil,
"a Gen 2 shape described by keys clears the Gen 1 value slot")
end
-- a Gen 2 shape on a registry with no Gen 2 home would be dead code: nothing
-- ever validates against it, because the write is dropped before it is checked
for name, spec in pairs(Schemas.REGISTRIES) do
if Schemas.hasGen2Shape(spec) then
T.eq(Schemas.gatedFor(name, 2), false,
"a registry with a Gen 2 shape is not gated: " .. name)
end
end
-- every routing entry names a real registry, so a rename cannot leave a
-- stale row behind that silently stops gating anything
for name in pairs(Schemas.GEN2) do
T.check(Schemas.REGISTRIES[name] ~= nil,
"Schemas.GEN2 names a real registry: " .. name)
end
-- a routed path must not be some other registry's path: two registries
-- folding into one table would let the second one's ids overwrite the first's
do
local claimed = {}
for name, spec in pairs(Schemas.REGISTRIES) do
local path = Schemas.targetFor(name, spec, 2)
if path then
T.check(claimed[path] == nil or claimed[path] == name,
("two registries share one Gen 2 path (%s): %s and %s")
:format(path, tostring(claimed[path]), name))
claimed[path] = name
end
end
end
-- ------- 4. the shared names, raised from Gold's own call sites
--
-- The rule: when a Gen 2 call site lands for something Gen 1 already names,
-- it reuses the EXACT name, so one mod's subscription serves both games. The
-- catalog reads the names back out of the source (tests/modkit/catalog.lua
-- scans for Runtime.emit / Runtime.call), so each name below is held to
-- having BOTH a site inside a Gen 2 module and a site outside one. A
-- "gen2.world.stepped" would satisfy the first half and fail the second,
-- which is exactly the drift this gate exists to catch; so would quietly
-- deleting Gold's site while docs/mod-api-gen2-compat.md still promises it.
--
-- Payload parity cannot be checked here (the shapes come from a live Gold
-- boot, and this file is ROM-free); tests/engine/gate_hooks.lua and
-- gate_events.lua carry the per-payload cases, and the Gen 2 sites were
-- proved against the gold_* drivers.
local Catalog = T.catalog
-- Gold's modules live under a gen2/ directory, except the two that own the
-- boot and the extractor and carry the generation in their name
local function isGen2Site(path)
return path:match("gen2") ~= nil or path:match("Gen2") ~= nil
or path:match("Game2") ~= nil
end
local GEN2_EVENTS = {
-- overworld
"map.entered", "map.exited", "map.reloaded", "player.warped",
"world.stepped", "world.interacted", "world.npc_spawned",
"world.trainer_engaged", "world.blacked_out", "world.block_replaced",
"world.boulder_moved", "world.tod_changed", "world.object_toggled",
"flag.changed",
-- battle
"battle.started", "battle.ended", "battle.turn_started", "battle.turn_ended",
"battle.move_used", "battle.damage_dealt", "battle.fainted",
"battle.status_inflicted", "battle.battler_switched", "battle.ball_thrown",
"battle.exp_gained", "pokemon.level_up", "pokemon.move_learned",
-- the catch and the evolution themselves: pushCaught emits after the mon is
-- in the party or the box, Evolution.apply after the species swap, both
-- matching the Gen 1 payload keys
"pokemon.caught", "pokemon.evolved",
-- boot, save and the script VM
"game.ready", "save.created", "save.loaded", "save.loading", "save.writing",
"script.started", "script.ended",
-- The new-game speech. Gold's is a different scene (Elm, not Oak, and its
-- own src/ui/gen2/OakSpeech.lua), but it is the SAME moment -- the intro
-- asking the player for the answers a save is built from -- so it keeps Gen
-- 1's four names and payload keys rather than inventing "intro.elm_speech".
"intro.oak_speech.started", "intro.oak_speech.step",
"intro.oak_speech.answered", "intro.oak_speech.finished",
}
local GEN2_HOOKS = {
-- overworld
"warp.destination", "movement.collision", "movement.speed",
"encounter.roll", "encounter.species", "encounter.fishing",
"world.tod", "map.palette", "fieldmove.eligibility",
-- menus and the battle intro
"ui.start_menu.items", "ui.title_menu.items", "ui.options.rows",
"ui.party.submenu", "ui.naming.grid", "ui.pc.items", "ui.list_menu",
"transition.style",
-- battle
"battle.damage", "battle.crit", "battle.accuracy", "battle.turn_order",
"battle.enemy_action", "battle.run", "battle.exp_award", "exp.gain",
"catch.rate", "trainer.party",
-- one wrap cancels or forces an evolution in either game: Gold passes `data`
-- where Gen 1 passes `game`, and positions 2-4 (mon, row, trigger) match
"evolution.check",
-- save and the script VM
"save.write", "save.new_game", "script.command",
-- the intro's step list, wrapped before the first card draws. Same hook,
-- same (steps, speech) arguments and same "return the list" contract as
-- src/ui/OakSpeech.lua's, so one wrapper reorders either game's speech.
"intro.oak_speech.build",
-- Battle seams Gold raises from src/battle/gen2/Battle.lua and
-- src/ui/gen2/BattleState.lua. battle.low_health_alarm carries `data` on
-- Gold where Gen 1's vanilla link reads ctx.battle.data: Gold's battle
-- screen has no .data field, so the key is ADDED beside the Gen 1 ones
-- rather than the payload being reshaped (docs/mod-api-gen2-compat.md warns
-- that a Gen 1 mod reaching through ctx.battle.data instead of calling
-- nextFn gets nil there).
"battle.catch_exp", "battle.low_health_alarm", "battle.overlay",
-- One pic path resolver for both games: the Gen 1 site is the SHARED
-- src/pokemon/Sprites.lua and Gold's own battle screen calls the same hook
-- with the Gen 1 ctx keys plus `letter` and `shiny`, which Red has no
-- concept of.
"pokemon.sprite",
-- The player's own trainer pic, same story: the Runtime.call is the shared
-- src/pokemon/Sprites.lua and Gold's battle back pic, Hall of Fame and intro
-- resolve their own path into Sprites.playerPic with the Gen 1 ctx keys.
"player.sprite",
-- The frame itself, from src/core/Game2.lua, in the same places
-- src/core/Game.lua raises them: the logic tick before the pad is read, a
-- pointer with the touch overlay given first refusal, the palette zone list
-- handed to the present pass, the letterbox and the HUD rect.
"input.step", "input.pointer",
"render.zones", "render.compose", "render.letterbox", "render.hud",
}
local function assertShared(name, sites, kind)
local gen2, gen1 = 0, 0
for _, path in ipairs(sites) do
if isGen2Site(path) then gen2 = gen2 + 1 else gen1 = gen1 + 1 end
end
T.check(gen2 > 0, ("Gold raises the %s: %s"):format(kind, name))
T.check(gen1 > 0,
("the %s %s is shared, not a Gen 2 invention (no Gen 1 site)")
:format(kind, name))
end
for _, name in ipairs(GEN2_EVENTS) do
assertShared(name, Catalog.eventSites(name), "event")
end
for _, name in ipairs(GEN2_HOOKS) do
assertShared(name, Catalog.hookSites(name), "hook")
end
-- and the lists are COMPLETE, not a sample. Without this half the gate only
-- catches a seam being taken away; a Gen 2 site landing for a Gen 1 name and
-- never reaching docs/mod-api-gen2-compat.md is the other drift, and it is the
-- more likely one -- the doc is where an author looks to decide whether a
-- subscription serves both games, so an unlisted shared seam reads as absent.
local function assertListed(names, catalogNames, sites, kind)
local listed = {}
for _, name in ipairs(names) do listed[name] = true end
for _, name in ipairs(catalogNames) do
if not Catalog.isModEvent(name) then
local gen2, gen1 = false, false
for _, path in ipairs(sites(name)) do
if isGen2Site(path) then gen2 = true else gen1 = true end
end
if gen2 and gen1 then
T.check(listed[name],
("%s %s has a site in both generations but is not in this gate's "
.. "list; add it here and to docs/mod-api-gen2-compat.md")
:format(kind, name))
end
end
end
end
assertListed(GEN2_EVENTS, Catalog.events(), Catalog.eventSites, "event")
assertListed(GEN2_HOOKS, Catalog.hooks(), Catalog.hookSites, "hook")
-- and nothing anywhere invents a generation-prefixed name. New-in-Gen-2
-- systems (held_item.trigger, egg.hatched) get plain names of their own;
-- "gen2." would be a namespace no Gen 1 mod could ever match.
for _, name in ipairs(Catalog.events()) do
T.check(name:sub(1, 5) ~= "gen2.", "no generation-prefixed event: " .. name)
end
for _, name in ipairs(Catalog.hooks()) do
T.check(name:sub(1, 5) ~= "gen2.", "no generation-prefixed hook: " .. name)
end
-- ------- 4b. the seams Gen 2 invents
--
-- The other half of the shared-name rule. Section 4 holds a name Gen 1
-- already has to keeping it; these are the systems Red does not have at all
-- (friendship, breeding, the Pokegear, the radio, Pokerus, the roamers, Kurt,
-- the Bug Contest, the Unown puzzle, mail, held items, shininess and gender),
-- so a NEW name is justified -- and the discipline is the same one from the
-- other side: a plain name, never a "gen2." namespace no Gen 1 mod could
-- match, so that when Red ever grows the system the name is already right.
--
-- Three things are asserted per seam, and each one has failed at some point in
-- a review of this programme:
--
-- 1. the site exists at all. docs/mod-api-gen2-compat.md promises these by
-- name, so a deleted emit is doc drift the moment it happens.
-- 2. every site is inside a Gen 2 module. If a Gen 1 site ever appears the
-- seam is no longer Gen 2-only and belongs in the shared lists above,
-- where BOTH halves are checked -- this is the tripwire for that move.
-- 3. the site is guarded by Runtime.wants / wantsHook for its own name, so a
-- mod-free boot allocates no payload table. Several of these sit in the
-- step loop (happiness.changed, roamer.moved) or in the damage path
-- (held_item.trigger, eight triggers a turn), where an unguarded emit is
-- a per-frame cost every player pays for a feature nobody enabled.
--
-- Payload keys are not checkable here (this file is ROM-free);
-- tests/engine/gen2_new_seams.lua drives each one through a live bus and
-- asserts the payload the call site documents.
local GEN2_ONLY_EVENTS = {
"happiness.changed", "breeding.egg_created", "egg.hatched",
"phone.call_received", "clock.day_changed", "pokerus.infected",
"roamer.moved", "roamer.encountered", "apricorn.converted",
"bug_contest.scored", "unown.unlocked", "radio.channel",
"mail.written", "mail.read",
-- The GS boot cinema, card by card. Red boots straight into its title
-- screen, so there is no Gen 1 moment for these to share a name with; they
-- are plain names rather than "gen2." ones so that the day Red grows a
-- cinema the name is already right. Each fires as its card comes UP, with
-- movie_ended the one card END worth a name of its own (it is where the
-- attract loop restarts).
"intro.boot.copyright", "intro.boot.gamefreak", "intro.boot.movie",
"intro.boot.movie_ended", "intro.boot.title",
}
local GEN2_ONLY_HOOKS = {
"held_item.trigger", "breeding.compatibility", "phone.contact_list",
"shiny.roll", "gender.roll",
}
local sourceCache = {}
local function sourceOf(path)
if sourceCache[path] == nil then
local handle = io.open(path, "r")
sourceCache[path] = handle and handle:read("*a") or false
if handle then handle:close() end
end
return sourceCache[path] or nil
end
local function assertGen2Only(name, sites, kind, guard)
T.check(#sites > 0, ("Gold raises the Gen 2-only %s: %s"):format(kind, name))
local guarded = false
for _, path in ipairs(sites) do
T.check(isGen2Site(path),
("a Gen 2-only %s is raised from a Gen 2 module (%s is not one): %s")
:format(kind, path, name))
local body = sourceOf(path)
if body and body:find(('%s("%s")'):format(guard, name), 1, true) then
guarded = true
end
end
T.check(guarded,
("the %s %s is guarded by %s, so a mod-free boot pays nothing")
:format(kind, name, guard))
end
for _, name in ipairs(GEN2_ONLY_EVENTS) do
assertGen2Only(name, Catalog.eventSites(name), "event", "Runtime.wants")
end
for _, name in ipairs(GEN2_ONLY_HOOKS) do
assertGen2Only(name, Catalog.hookSites(name), "hook", "Runtime.wantsHook")
end
-- complete both ways, like the shared lists: a seam raised ONLY from Gen 2
-- modules is by definition a Gen 2-only one, so if it is not listed above it
-- has skipped the guard check, the doc's payload table and gen2_new_seams.lua
-- all at once.
local function assertGen2OnlyListed(names, catalogNames, sites, kind)
local listed = {}
for _, name in ipairs(names) do listed[name] = true end
for _, name in ipairs(catalogNames) do
if not Catalog.isModEvent(name) then
local anyGen1 = false
for _, path in ipairs(sites(name)) do
if not isGen2Site(path) then anyGen1 = true end
end
if not anyGen1 then
T.check(listed[name],
("%s %s is raised from Gen 2 modules alone but is not listed as a "
.. "Gen 2-only seam; add it here and to "
.. "docs/mod-api-gen2-compat.md"):format(kind, name))
end
end
end
end
assertGen2OnlyListed(GEN2_ONLY_EVENTS, Catalog.events(), Catalog.eventSites,
"event")
assertGen2OnlyListed(GEN2_ONLY_HOOKS, Catalog.hooks(), Catalog.hookSites,
"hook")
-- ------- 5. the gate, through a real load
local GEN1_ONLY = {
["mods/fix_gen1_only/manifest.json"] = [[{
"id": "fix_gen1_only",
"name": "Fixture Gen 1 Only",
"version": "1.0.0",
"entry": "main.lua",
"api": 2
}]],
["mods/fix_gen1_only/main.lua"] = [[
local mod = ...
mod.content.pokemon:patch("FIXMON_A", { catchRate = 111 })
]],
}
local GEN2_READY = {
["mods/fix_gen2_ready/manifest.json"] = [[{
"id": "fix_gen2_ready",
"name": "Fixture Gen 2 Ready",
"version": "1.0.0",
"entry": "main.lua",
"api": 2,
"gen2compat": true
}]],
["mods/fix_gen2_ready/main.lua"] = [[
local mod = ...
-- one registry with a Gen 2 home, one without: the first applies in both
-- generations, the second applies in Gen 1 and reports in Gen 2.
-- `transitions` is the gated one because Gold draws its own battle intro
-- (src/ui/gen2/BattleTransition.lua) and never composes through the Gen 1
-- Renderer, so nothing on a Gold boot would ever read the merged record.
mod.content.pokemon:patch("FIXMON_A", { catchRate = 123 })
mod.content.transitions:register("FIXTURE_WIPE", { frames = 30 })
]],
}
local function files(...)
local out = {}
for _, set in ipairs({ ... }) do
for path, body in pairs(set) do out[path] = body end
end
return out
end
local function statusOf(run, id)
for _, entry in ipairs(run.loader:status().available) do
if entry.id == id then return entry end
end
return nil
end
-- Gen 1: both mods run, both patches land
do
local run = T.sdk.loadMods({ "mods/fix_gen1_only", "mods/fix_gen2_ready" }, {
fs = T.sdk.memfs(files(GEN1_ONLY, GEN2_READY)),
generation = 1,
})
T.eq(statusOf(run, "fix_gen1_only").state, "loaded",
"Gen 1: a mod with no gen2compat loads")
T.eq(statusOf(run, "fix_gen2_ready").state, "loaded",
"Gen 1: a gen2compat mod loads too")
T.eq(run.data.pokemon.FIXMON_A.catchRate, 123,
"Gen 1: the later mod's patch merged")
T.check(run.data.transitions ~= nil
and run.data.transitions.FIXTURE_WIPE ~= nil,
"Gen 1: transitions merged")
run.release()
end
-- Gen 2: the undeclared mod is skipped whole, the declared one runs
do
local run = T.sdk.loadMods({ "mods/fix_gen1_only", "mods/fix_gen2_ready" }, {
fs = T.sdk.memfs(files(GEN1_ONLY, GEN2_READY)),
generation = 2,
})
local skipped = statusOf(run, "fix_gen1_only")
T.eq(skipped.state, "wrong_generation",
"Gen 2: a mod with no gen2compat is not loaded")
T.check(skipped.note ~= nil and skipped.note:match("gen2compat"),
"Gen 2: the skip says why")
T.eq(skipped.error, nil,
"Gen 2: a skip is not reported as a failure")
T.eq(skipped.enabled, true,
"Gen 2: the player's enable flag is untouched by the skip")
T.eq(statusOf(run, "fix_gen2_ready").state, "loaded",
"Gen 2: the declared mod loads")
-- the skipped mod's registration must leave no trace: 111 would mean it ran
T.eq(run.data.pokemon.FIXMON_A.catchRate, 123,
"Gen 2: only the declared mod's patch merged")
-- a gated registry takes the write, drops it, and says so
T.check(run.data.transitions == nil
or run.data.transitions.FIXTURE_WIPE == nil,
"Gen 2: a gated registry merges nothing")
local told = false
for _, message in ipairs(run.errors) do
if message:match("transitions") and message:match("Gen 2") then told = true end
end
T.check(told, "Gen 2: the dropped registration is reported, not silent")
run.release()
end
-- The drop is worded from the loader's own generation, because the gating runs
-- both ways: a Red boot rejecting a write to a Gen 2-only registry must not
-- claim the registry has "no Gen 2 target". The registry name and the drop
-- were always right; the sentence was one-directional.
do
local MIRROR = {
["mods/fix_gen1_drop/manifest.json"] = [[{
"id": "fix_gen1_drop",
"name": "Fixture Gen 1 Drop",
"version": "1.0.0",
"entry": "main.lua",
"api": 2
}]],
["mods/fix_gen1_drop/main.lua"] = [[
local mod = ...
mod.content.decorations:patch("deco:2", { name = "COZY" })
]],
}
local run = T.sdk.loadMods({ "mods/fix_gen1_drop" },
{ fs = T.sdk.memfs(MIRROR), generation = 1 })
local told
for _, message in ipairs(run.errors) do
if message:match("decorations") then told = message end
end
T.check(told ~= nil,
"Gen 1: a write to a Gen 2-only registry is reported")
T.check(told and told:match("Gen 1"),
"Gen 1: and the report names Gen 1, not Gen 2: " .. tostring(told))
T.eq(run.data.gen2Decorations, nil, "Gen 1: and nothing merged")
run.release()
end
-- ------- 5b. the vanilla records at a routed path are GOLD's
--
-- Six of the routed registries are the battle rules, and there the registry is
-- not just a merge target: src/battle/gen2/Catching.lua:recordFor,
-- Battle.statusRecordFor / moveEffectRecordFor, Ai.layersFor,
-- Evolution.methodFor and src/core/gen2/ItemEffects.lua:recordFor all read the
-- merged table. So WHICH module seeds it is load bearing, and it is not the
-- one that seeds Red: the ids collide. src/mods/Builtins.lua swaps the
-- registrant per generation and this holds it to that -- seeding Red's
-- GREAT_BALL would leave Gold's x1.5 multiplier nil, which reads as a ball
-- that quietly stopped working.
do
local gen1 = T.sdk.loadNone({ generation = 1 })
local gen2 = T.sdk.loadNone({ generation = 2 })
local ball1 = gen1.loader.content.balls:get("GREAT_BALL")
local ball2 = gen2.loader.content.balls:get("GREAT_BALL")
T.check(ball1 ~= nil and ball1.hpFactor ~= nil and ball1.multiplier == nil,
"Gen 1 seeds Red's GREAT_BALL (an HP factor, no multiplier)")
T.check(ball2 ~= nil and ball2.multiplier == 1.5,
"Gen 2 seeds Gold's GREAT_BALL (the x1.5 the cart multiplies by)")
-- statuses are the clearest case of the shared NAME over different ids:
-- Red writes BRN into mon.status where Gold writes "burn"
T.check(gen1.loader.content.statuses:get("BRN") ~= nil,
"Gen 1 seeds Red's status ids")
T.check(gen2.loader.content.statuses:get("burn") ~= nil
and gen2.loader.content.statuses:get("BRN") == nil,
"Gen 2 seeds Gold's status ids and none of Red's")
-- Ai.layersFor walks the merged table for mod-registered scoring passes, so
-- Red's LAYER_1..LAYER_3 landing there would join Gold's ten
T.check(gen1.loader.content.ai_classes:get("LAYER_1") ~= nil,
"Gen 1 seeds Red's move-scoring layers")
T.check(gen2.loader.content.ai_classes:get("LAYER_1") == nil
and gen2.loader.content.ai_classes:get("SMART") ~= nil,
"Gen 2 seeds Gold's scoring passes instead")
-- and the Gen 2 VM's verb table is the mod verbs alone: a Gen 1 row-list
-- verb handed Gold's ctx would find no runner on it
T.check(gen1.loader.content.commands:get("show_text") ~= nil,
"Gen 1 seeds the row-list verbs")
T.eq(gen2.loader.content.commands:get("show_text"), nil,
"Gen 2 seeds none of them")
T.eq(gen2.data.commands, nil,
"and a mod-free Gold boot leaves data.commands absent entirely")
-- the seeded records land at the routed path, not the Gen 1 one
T.check(gen2.data.gen2Statuses ~= nil and gen2.data.gen2Statuses.burn ~= nil,
"the Gen 2 records merge into their Gen 2 path")
T.eq(gen2.data.statuses, nil,
"and nothing is written to the Gen 1 path a Gold boot never reads")
T.check(gen1.data.statuses ~= nil and gen1.data.statuses.BRN ~= nil,
"while Gen 1 is untouched by any of it")
gen1.release()
gen2.release()
end
-- A gated registry is an absent id space, not an empty one. Gold's species
-- carry a growthRate exactly as Red's do, so a patch that keeps one must not
-- be reported as referencing something that does not exist just because the
-- Gen 1 `growth_rates` namespace has no Gen 2 home. A ROUTED registry is the
-- opposite: `evolution_methods` has real ids on Gold now, so the same pass
-- resolves an evolution's method against them and a typo is caught.
local function refsFixture(body)
return {
["mods/fix_refs/manifest.json"] = [[{
"id": "fix_refs",
"name": "Fixture Refs",
"version": "1.0.0",
"entry": "main.lua",
"api": 2,
"gen2compat": true
}]],
["mods/fix_refs/main.lua"] = body,
}
end
-- The ROM-free fixture dataset is Gen 1 shaped, and Gold hangs its experience
-- curves off data.pokemon.growthRates (which src/mods/Builtins.lua's Gen 2
-- registrant seeds the growth_rates registry from). A generation-2 run over
-- unmodified fixtures therefore seeds no curves, and every fixture species'
-- growthRate reads as a dangling reference -- an artifact of the dataset, not
-- of the engine: on a real Gold boot the ids line up exactly (both sides say
-- GROWTH_MEDIUM_SLOW). Added per-run rather than to tests/fixture_data, whose
-- shape is Gen 1's and whose fingerprint is a committed golden.
local function gen2Fixtures()
local data = T.fixtures.fresh()
-- pokegold data/growth_rates.asm's MEDIUM_SLOW row, under the id the fixture
-- species reference
data.pokemon.growthRates = {
MEDIUM_SLOW = { numerator = 6, denominator = 5, squared = -15,
linear = 100, constant = 140 },
}
return data
end
local function danglingRefs(run)
local dangling = {}
for _, message in ipairs(run.errors) do
if message:match("unresolved reference") then
dangling[#dangling + 1] = message
end
end
return dangling
end
do
-- the Gen 2 evolution row shape: `into` rather than `species`, and Gold's
-- own EVOLVE_* method ids, which src/core/gen2/Evolution.lua seeds
local run = T.sdk.loadMods({ "mods/fix_refs" }, {
fs = T.sdk.memfs(refsFixture([[
local mod = ...
local base = mod.content.pokemon:get("FIXMON_A")
mod.content.pokemon:patch("FIXMON_A", {
catchRate = 90,
growthRate = base.growthRate,
evolutions = { { method = "EVOLVE_LEVEL", level = 16,
into = "FIXMON_B" } },
})
]])),
data = gen2Fixtures(),
generation = 2,
})
local dangling = danglingRefs(run)
T.eq(#dangling, 0,
"Gen 2: a record whose refs all resolve reports nothing ("
.. table.concat(dangling, "; ") .. ")")
T.eq(run.data.pokemon.FIXMON_A.catchRate, 90, "Gen 2: the patch still landed")
run.release()
end
do
local run = T.sdk.loadMods({ "mods/fix_refs" }, {
fs = T.sdk.memfs(refsFixture([[
local mod = ...
mod.content.pokemon:patch("FIXMON_A", {
evolutions = { { method = "EVOLVE_BY_VIBES", level = 16,
into = "FIXMON_B" } },
})
]])),
data = gen2Fixtures(),
generation = 2,
})
local dangling = danglingRefs(run)
T.eq(#dangling, 1,
"Gen 2: a routed registry HAS an id space, so a bad method is caught")
T.check(dangling[1] and dangling[1]:match("evolution_methods"),
"Gen 2: and the report names the registry it could not resolve against")
run.release()
end
-- the skip is contagious as a SKIP. A mod that DID claim gen2compat but sits
-- on one that did not is left out with the dependency's own wording, not
-- failed with "dependency X failed to load": neither mod has a bug and neither
-- belongs on the boot error list the player is shown.
do
local DEPENDENT = {
["mods/fix_gen2_dependent/manifest.json"] = [[{
"id": "fix_gen2_dependent",
"name": "Fixture Gen 2 Dependent",
"version": "1.0.0",
"entry": "main.lua",
"api": 2,
"gen2compat": true,
"dependencies": ["fix_gen1_only"]
}]],
["mods/fix_gen2_dependent/main.lua"] = [[
local mod = ...
mod.content.pokemon:patch("FIXMON_A", { catchRate = 222 })
]],
}
local run = T.sdk.loadMods({ "mods/fix_gen1_only", "mods/fix_gen2_dependent" }, {
fs = T.sdk.memfs(files(GEN1_ONLY, DEPENDENT)),
generation = 2,
})
local dependent = statusOf(run, "fix_gen2_dependent")
T.eq(dependent.state, "wrong_generation",
"Gen 2: a dependent of a gate-skipped mod is skipped, not failed")
T.eq(dependent.error, nil,
"Gen 2: the dependent's skip is not reported as a failure")
T.check(dependent.note ~= nil and dependent.note:match("gen2compat"),
"Gen 2: the dependent's skip names the dependency's reason")
T.eq(#run.errors, 0, "Gen 2: neither mod contributes a boot error")
run.release()
end
-- the player's override: options.modsGen2 forces a mod past the gate, because
-- the manifest flag is the AUTHOR's claim and a mod written before the field
-- existed can never carry one
do
local fs = T.sdk.memfs(files(GEN1_ONLY))
fs.write("options.lua", require("src.core.SaveSerializer").encode({
mods = {}, modsGen2 = { fix_gen1_only = true },
}))
local run = T.sdk.loadMods({ "mods/fix_gen1_only" },
{ fs = fs, generation = 2 })
local forced = statusOf(run, "fix_gen1_only")
T.eq(forced.state, "loaded", "Gen 2: the override loads an unclaimed mod")
T.eq(forced.gen2Forced, true, "Gen 2: the manager sees the override")
T.check(forced.note ~= nil and forced.note:match("not verified"),
"Gen 2: a forced mod still says its author never claimed this game")
T.eq(run.data.pokemon.FIXMON_A.catchRate, 111,
"Gen 2: the forced mod's patch merged")
run.release()
end
-- a skipped mod is skipped before validation, so a Gen 1 mod with a broken
-- manifest does not ALSO shout about its entry file on a Gold boot
do
local BROKEN = {
["mods/fix_broken/manifest.json"] = [[{
"id": "fix_broken",
"name": "Fixture Broken",
"version": "1.0.0",
"entry": "missing.lua",
"api": 2
}]],
}
local run = T.sdk.loadMods({ "mods/fix_broken" },
{ fs = T.sdk.memfs(BROKEN), generation = 2 })
T.eq(statusOf(run, "fix_broken").state, "wrong_generation",
"Gen 2: the generation gate runs before entry-file validation")
T.eq(#run.errors, 0, "Gen 2: a skipped mod contributes no boot errors")
run.release()
end
-- ------- 6. StateStack:clear, which is what Gold's boot cinema hands off
-- through now that it runs the engine stack
do
local stack = setmetatable({}, { __index = StateStack })
stack:init()
local order = {}
local function state(name)
return { isOpaque = true, exit = function() order[#order + 1] = name end }
end
stack:push(state("a"))
stack:push(state("b"))
stack:push(state("c"))
stack:clear()
T.eq(stack:top(), nil, "clear empties the stack")
T.eq(table.concat(order, ","), "c,b,a", "clear unwinds top-first")
end
-- Without this the file printed its FAILs and exited 0, so the runner marked
-- the gate "ok" while it was red -- a gate that cannot fail is not a gate.
T.finish("gate_gen2_mod_api")
Reference in New Issue View Git Blame Copy Permalink