Merge pull request #1286 from MaxTomahawk/adaptive-trainers/battle-party-scope

feat(mod-api): add trainer battle party scope

tests/engine/trainer_battle_party_scope.lua

@@ -0,0 +1,131 @@
+-- Trainer battles may use a battle-local view of save-party records without
+-- mutating, reordering, or hiding those records in the authoritative save.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+love = love or require("tests.love_stub")
+
+local T = require("tests.harness").suite("trainer battle party scope")
+local BattleState = require("src.battle.BattleState")
+local BagMenu = require("src.ui.BagMenu")
+local Fixtures = require("tests.modkit").fixtures
+local PartyMenu = require("src.ui.PartyMenu")
+local Pokemon = require("src.pokemon.Pokemon")
+local SaveData = require("src.core.SaveData")
+local Bag = require("src.inventory.Bag")
+
+local Data = Fixtures.fresh()
+Data.items.POTION = { id = "POTION", index = 99, name = "POTION",
+  price = 300, tossable = true }
+
+local function makeGame()
+  local save = SaveData.newGame()
+  save.party = {
+    Pokemon.new(Data, "FIXMON_A", 10),
+    Pokemon.new(Data, "FIXMON_B", 11),
+    Pokemon.new(Data, "FIXMON_C", 12),
+  }
+  local stack = { states = {} }
+  function stack:push(value) self.states[#self.states + 1] = value end
+  function stack:pop() return table.remove(self.states) end
+  function stack:top() return self.states[#self.states] end
+  return { data = Data, save = save, stack = stack }
+end
+
+local game = makeGame()
+local originalParty = game.save.party
+local first, second, third = unpack(originalParty)
+local battle = BattleState.newTrainer(game, "OPP_FIX_YOUNGSTER", 1, {
+  playerPartyIndices = { 2, 3 },
+})
+T.check(game.save.party == originalParty,
+  "scoping never replaces the authoritative save-party table")
+T.check(game.save.party[1] == first and game.save.party[2] == second
+    and game.save.party[3] == third,
+  "scoping never reorders authoritative save-party records")
+T.same(battle.playerPartyIndices, { 2, 3 },
+  "the battle records normalized save-party indices")
+T.check(battle.playerParty[1] == second and battle.playerParty[2] == third,
+  "the local party view contains the same selected Pokemon records")
+T.check(battle.player.mon == second,
+  "initial send chooses the first healthy scoped member")
+
+local menu = PartyMenu.new(game, { battle = battle })
+T.check(menu.party == battle.playerParty,
+  "battle party menus traverse only the local eligible view")
+
+Bag.add(game.save, "POTION", 1)
+local bag = BagMenu.new(game, { battle = battle })
+local potion
+for _, row in ipairs(bag.items) do
+  if row.value == "POTION" then potion = row; break end
+end
+T.check(potion ~= nil, "the fixture potion is available for target selection")
+bag.onChoose(potion, bag)
+local targetPicker = game.stack:top()
+T.check(targetPicker and targetPicker.party == battle.playerParty,
+  "in-battle item target selection traverses only eligible members")
+
+second.hp = 0
+battle.player.mon.hp = 0
+battle:playerMonFainted()
+T.eq(battle.result, nil,
+  "a healthy scoped replacement prevents premature exhaustion")
+third.hp = 0
+battle:playerMonFainted()
+T.eq(battle.result, "lose",
+  "an excluded healthy save-party member cannot prevent scoped exhaustion")
+T.check(first.hp > 0, "the excluded save-party member remains untouched")
+
+local expGame = makeGame()
+expGame.save.inventory.EXP_ALL = 1
+local expBattle = BattleState.newTrainer(expGame,
+  "OPP_FIX_YOUNGSTER", 1, { playerPartyIndices = { 2, 3 } })
+local excludedExp = expGame.save.party[1].exp
+local participantExp = expGame.save.party[2].exp
+local sharedExp = expGame.save.party[3].exp
+expBattle.participants = { [expGame.save.party[2]] = true }
+expBattle:awardExp()
+T.eq(expGame.save.party[1].exp, excludedExp,
+  "EXP.ALL cannot award an excluded save-party member")
+T.check(expGame.save.party[2].exp > participantExp,
+  "a scoped participant receives battle experience")
+T.check(expGame.save.party[3].exp > sharedExp,
+  "EXP.ALL traverses other eligible scoped members")
+
+local fallbackGame = makeGame()
+local fallback = BattleState.newTrainer(fallbackGame,
+  "OPP_FIX_YOUNGSTER", 1, { playerPartyIndices = { 0, 99, 1.5, 0 } })
+T.eq(fallback.playerParty, nil,
+  "a malformed or empty scope degrades to the vanilla full-party path")
+T.eq(fallback.player.mon, fallbackGame.save.party[1],
+  "invalid scope fallback preserves vanilla initial send")
+
+local partialGame = makeGame()
+local partial = BattleState.newTrainer(partialGame,
+  "OPP_FIX_YOUNGSTER", 1, { playerPartyIndices = { 2, 99 } })
+T.eq(partial.playerParty, nil,
+  "one invalid member makes the entire scope fall back")
+
+local duplicateGame = makeGame()
+local duplicate = BattleState.newTrainer(duplicateGame,
+  "OPP_FIX_YOUNGSTER", 1, { playerPartyIndices = { 2, 2 } })
+T.eq(duplicate.playerParty, nil,
+  "duplicate members make the entire scope fall back")
+
+local malformedOptionsGame = makeGame()
+local malformedOptions = BattleState.newTrainer(malformedOptionsGame,
+  "OPP_FIX_YOUNGSTER", 1, 7)
+T.eq(malformedOptions.playerParty, nil,
+  "a malformed options value degrades to the vanilla full-party path")
+
+local linkGame = makeGame()
+local linkBattle = BattleState.newTrainer(linkGame,
+  "OPP_FIX_YOUNGSTER", 1, { playerPartyIndices = { 2, 3 } })
+linkBattle.kind = "link"
+linkBattle.result = "guestWin"
+linkGame.save.party[2].hp, linkGame.save.party[3].hp = 0, 0
+linkBattle:finish()
+T.eq(linkBattle.result, "guestWin",
+  "link spectator outcomes are not rewritten by trainer eligibility scope")
+
+T.finish()

tests/engine/trainer_talk_sting_bug764.lua

@@ -13,6 +13,8 @@ package.path = "./?.lua;./?/init.lua;" .. package.path
 
 local T = require("tests.modkit")
 local OW = require("src.world.OverworldController")
+local Hooks = require("src.mods.Hooks")
+local Runtime = require("src.mods.Runtime")
 
 local function setUpvalue(fn, name, val)
   local i = 1
@@ -96,6 +98,89 @@ T.eq(rivalCount, 0, "rival classes play no encounter sting here")
 local _, seenCount = stingFor("OPP_LASS", true)
 T.eq(seenCount, 0, "self.engaging suppresses a second sting")
 
+-- A deferred preparation may cancel instead of constructing a battle. For a
+-- sight trainer, that must leave a one-position latch: otherwise the still
+-- undefeated adjacent trainer sees the stationary player again next frame and
+-- immediately reopens the preparation screen.
+local oldEvents, oldHooks, oldErrors = Runtime.events, Runtime.hooks,
+  Runtime.errors
+local cancelHooks = Hooks.new()
+Runtime.install(oldEvents, cancelHooks, oldErrors)
+cancelHooks:wrap("trainer.before_battle", function(_, _, _, continue)
+  continue({ cancel = true })
+  return true
+end, 0, "cancel_probe")
+local cancelNpc = { id = "npc#cancel", cellX = 0, cellY = -1,
+  facing = "down", moving = false, def = { trainerClass = "OPP_LASS",
+    trainerParty = 1, index = 1 } }
+fakeSelf.player = { cellX = 0, cellY = 0, moving = false }
+fakeSelf.map.id = "FIX_ROUTE"
+fakeSelf.engaging = false
+pushed, plays = {}, {}
+local completed = 0
+fakeSelf:engageTrainer(cancelNpc, function() completed = completed + 1 end)
+pushed[1].onDone()
+T.eq(completed, 1, "cancel completes the deferred encounter without a battle")
+T.same(fakeSelf.cancelledTrainerSight, {
+  npcId = "npc#cancel", playerX = 0, playerY = 0,
+}, "cancel suppresses immediate sight re-entry at the current player cell")
+
+local approaches = 0
+fakeSelf.npcs = { cancelNpc }
+fakeSelf.trainerDefeated = function() return false end
+fakeSelf.startTrainerApproach = function() approaches = approaches + 1 end
+fakeGame.stack.top = function() return fakeSelf end
+fakeGame.data.trainerHeader = function() return { range = 2 } end
+T.check(setUpvalue(OW.checkTrainerSight, "mapScripts", {
+  talkScript = function() return nil end,
+}), "mapScripts upvalue on checkTrainerSight")
+fakeSelf:checkTrainerSight()
+T.eq(approaches, 0,
+  "a cancelled adjacent trainer cannot reacquire the stationary player")
+fakeSelf.player.cellX = 1
+fakeSelf:checkTrainerSight()
+T.eq(fakeSelf.cancelledTrainerSight, nil,
+  "moving one cell releases the cancelled sight latch")
+fakeSelf.player.cellX = 0
+fakeSelf:checkTrainerSight()
+T.eq(approaches, 1,
+  "returning to the sight line permits a fresh trainer challenge")
+Runtime.install(oldEvents, oldHooks, oldErrors)
+
+-- OverworldState is a singleton reused by StateStack. A title/load cycle must
+-- clear this volatile latch too, or CONTINUE at the same map and cell inherits
+-- the cancelled sight suppression from the previous session.
+local Camera = require("src.render.Camera")
+local Collision = require("src.world.Collision")
+local Encounter = require("src.world.Encounter")
+local ScriptRunner = require("src.script.ScriptRunner")
+local oldCameraNew, oldCollisionLoad = Camera.new, Collision.load
+local oldEncounterLoad, oldRunnerNew = Encounter.load, ScriptRunner.new
+local oldGameModule = package.loaded["src.core.Game"]
+local oldScriptsModule = package.loaded["data.scripts.init"]
+Camera.new = function() return {} end
+Collision.load = function() end
+Encounter.load = function() end
+ScriptRunner.new = function() return {} end
+package.loaded["src.core.Game"] = {
+  data = {}, save = { lastOutdoor = "FIX_ROUTE" },
+}
+package.loaded["data.scripts.init"] = {}
+local lifecycle = setmetatable({
+  cancelledTrainerSight = {
+    npcId = "FIX_ROUTE_obj_1", playerX = 0, playerY = 0,
+  },
+  setMap = function() end,
+  refreshStandingOnWarp = function() end,
+}, { __index = OW })
+lifecycle:enter("FIX_ROUTE", 0, 0, "down", { via = "boot" })
+T.eq(lifecycle.cancelledTrainerSight, nil,
+  "fresh overworld entry clears a cancelled trainer sight latch")
+Camera.new, Collision.load = oldCameraNew, oldCollisionLoad
+Encounter.load, ScriptRunner.new = oldEncounterLoad, oldRunnerNew
+package.loaded["src.core.Game"] = oldGameModule
+package.loaded["data.scripts.init"] = oldScriptsModule
+
 if realMusic ~= nil then package.loaded["src.core.Music"] = realMusic
 else package.loaded["src.core.Music"] = nil end
 if realBattle ~= nil then package.loaded["src.battle.BattleState"] = realBattle

tests/modkit/cases/checkpoints.lua

@@ -358,11 +358,13 @@ T.same(checkpoints:capture(game), beforeFailure,
 -- The same public facade must carry a real battle checkpoint end to end. The
 -- engine-side fixture is deliberately constructed outside the probe mod; the
 -- mod sees and calls only mod.checkpoints.
-local function makeBattleGame()
+local function makeBattleGame(kind)
   local data = Fixtures.fresh()
   local save = SaveData.newGame()
   save.meta.playthroughId = "public-battle-playthrough"
-  save.party = { Pokemon.new(data, "FIXMON_A", 20) }
+  save.party = { Pokemon.new(data, "FIXMON_A", 20),
+    Pokemon.new(data, "FIXMON_B", 19),
+    Pokemon.new(data, "FIXMON_C", 18) }
   -- The tiny fixture registry intentionally omits several full-game defaults.
   -- Normalize those once, then place the save on its fixture map.
   SaveData.validate(save, data)
@@ -387,7 +389,8 @@ local function makeBattleGame()
     self.player = { cellX = x, cellY = y, facing = facing, surfing = false }
   end
   function battleOw:restoreBattleContinuation(restoredBattle, origin)
-    if origin.kind ~= "wild_encounter" or origin.map ~= self.map.id then
+    local expected = kind == "trainer" and "trainer_encounter" or "wild_encounter"
+    if origin.kind ~= expected or origin.map ~= self.map.id then
       return false
     end
     restoredBattle.onFinish = function() end
@@ -397,9 +400,19 @@ local function makeBattleGame()
     data = data, save = save, stack = stack, overworld = battleOw,
   }, { __index = GameMethods })
   stack.states[1] = battleOw
-  local battle = BattleState.newWild(battleGame, "FIXMON_B", 12)
+  local battle
+  if kind == "trainer" then
+    battle = BattleState.newTrainer(battleGame, "OPP_FIX_YOUNGSTER", 1, {
+      playerPartyIndices = { 2, 3 },
+    })
+  else
+    battle = BattleState.newWild(battleGame, "FIXMON_B", 12)
+  end
   battle.phase, battle.queue = "menu", {}
-  battle.checkpointOrigin = { kind = "wild_encounter", map = "FIX_TOWN" }
+  battle.checkpointOrigin = kind == "trainer"
+    and { kind = "trainer_encounter", map = "FIX_TOWN", npcId = "TRAINER_1",
+      trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 1 }
+    or { kind = "wild_encounter", map = "FIX_TOWN" }
   battle.musicKind = battle:computeMusicKind()
   battle.onFinish = function() end
   stack.states[2] = battle
@@ -437,6 +450,62 @@ if battleSnapshot then
     "public battle capture/restore/capture is a normalized differential roundtrip")
 end
 
+checkpointRngState = "scoped-trainer-rng-A"
+local scopedGame, scopedBattle = makeBattleGame("trainer")
+local scopedSnapshot, scopedCaptureCode = checkpoints:capture(scopedGame)
+T.check(scopedSnapshot ~= nil,
+  "public checkpoints capture a scoped trainer battle: "
+    .. tostring(scopedCaptureCode))
+if scopedSnapshot then
+  T.same(scopedSnapshot.runtime.battle.playerPartyIndices, { 2, 3 },
+    "capture stores the battle-local save-party index scope")
+  local restored, code, message = checkpoints:restore(scopedGame, scopedSnapshot)
+  T.check(restored == true,
+    "public checkpoints restore a scoped trainer battle: "
+      .. tostring(code) .. " / " .. tostring(message))
+  local scopedRestored = scopedGame.stack:top()
+  T.same(scopedRestored.playerPartyIndices, { 2, 3 },
+    "restore reconstructs the same ordered party scope")
+  T.check(scopedRestored.playerParty[1] == scopedGame.save.party[2]
+      and scopedRestored.playerParty[2] == scopedGame.save.party[3],
+    "restored scope points at authoritative save-party records")
+
+  scopedSnapshot.runtime.battle.playerPartyIndices = nil
+  local oldRestored, oldCode = checkpoints:restore(scopedGame, scopedSnapshot)
+  T.check(oldRestored == true,
+    "an old checkpoint without party scope remains compatible: "
+      .. tostring(oldCode))
+  T.eq(scopedGame.stack:top().playerParty, nil,
+    "an old checkpoint restores the vanilla full-party view")
+end
+
+local function scopedCheckpoint()
+  local freshGame = makeBattleGame("trainer")
+  local snapshot = assert(checkpoints:capture(freshGame))
+  return freshGame, snapshot
+end
+
+local excludedGame, excludedSnapshot = scopedCheckpoint()
+excludedSnapshot.runtime.battle.player.index = 1
+local excludedRestored, excludedCode = checkpoints:restore(excludedGame,
+  excludedSnapshot)
+T.check(excludedRestored == false and excludedCode == "invalid_checkpoint",
+  "a scoped checkpoint rejects an active battler outside the eligible view")
+
+local malformedGame, malformedSnapshot = scopedCheckpoint()
+malformedSnapshot.runtime.battle.playerPartyIndices.extra = 3
+local malformedRestored, malformedCode = checkpoints:restore(malformedGame,
+  malformedSnapshot)
+T.check(malformedRestored == false and malformedCode == "invalid_checkpoint",
+  "a scoped checkpoint rejects non-array scope members instead of failing open")
+
+local participantGame, participantSnapshot = scopedCheckpoint()
+participantSnapshot.runtime.battle.participants = { 1 }
+local participantRestored, participantCode = checkpoints:restore(
+  participantGame, participantSnapshot)
+T.check(participantRestored == false and participantCode == "invalid_checkpoint",
+  "a scoped checkpoint rejects excluded participant references")
+
 -- The mod receives the normal public hook facade, never BattleState. START
 -- at the restored safe decision reaches its semantic auxiliary action without
 -- selecting a native command.

tests/modkit/cases/trainer_before_battle.lua

@@ -0,0 +1,92 @@
+-- A sandboxed mod can defer an ordinary trainer engagement and later resume
+-- it with a battle-local player-party scope, using only public mod surfaces.
+
+package.path = "./?.lua;./?/init.lua;" .. package.path
+love = love or require("tests.love_stub")
+
+local T = require("tests.modkit")
+local OW = require("src.world.OverworldController")
+
+local FIXTURE = {
+  ["mods/scope_probe/manifest.json"] = [[{
+    "id": "scope_probe",
+    "name": "Scope Probe",
+    "version": "1.0.0",
+    "entry": "main.lua",
+    "api": 2
+  }]],
+  ["mods/scope_probe/main.lua"] = [[
+    local mod = ...
+    mod.hooks:wrap("trainer.before_battle", function(next, game, context, continue)
+      mod.exports.game = game
+      mod.exports.context = context
+      mod.exports.continue = continue
+      return true
+    end)
+  ]],
+}
+
+local vanilla = T.sdk.loadNone({})
+local vanillaCalls, vanillaOptions = 0
+OW.prepareTrainerBattle({ id = "game" }, {
+  trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 1,
+  mapId = "FIX_ROUTE", npcId = "TRAINER_1",
+}, function(options)
+  vanillaCalls, vanillaOptions = vanillaCalls + 1, options
+end)
+T.eq(vanillaCalls, 1, "no mod starts the trainer battle exactly once")
+T.eq(vanillaOptions, nil, "no mod supplies no battle-local party scope")
+vanilla.release()
+
+local run = T.sdk.loadMods({ "mods/scope_probe" }, {
+  fs = T.sdk.memfs(FIXTURE),
+})
+T.eq(#run.errors, 0,
+  "the public preparation probe loads clean (" .. tostring(run.errors[1]) .. ")")
+local game = { id = "live-game" }
+local calls, options = 0
+OW.prepareTrainerBattle(game, {
+  trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 2,
+  mapId = "FIX_ROUTE", npcId = "TRAINER_7",
+}, function(value)
+  calls, options = calls + 1, value
+end)
+T.eq(calls, 0, "a claiming public hook defers battle construction")
+local out = run.loader.exports.scope_probe or {}
+T.check(out.game == game, "the hook receives the live game")
+T.same(out.context, {
+  trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 2,
+  mapId = "FIX_ROUTE", npcId = "TRAINER_7",
+}, "the hook receives data-only trainer identity context")
+T.eq(out.continue({ playerPartyIndices = { 2, 4 } }), true,
+  "the retained continuation resumes the deferred battle")
+T.eq(calls, 1, "resume constructs the battle exactly once")
+T.same(options, { playerPartyIndices = { 2, 4 } },
+  "ordered eligible indices cross the public seam unchanged")
+T.eq(out.continue({ playerPartyIndices = { 1 } }), false,
+  "the continuation refuses a second invocation")
+T.eq(calls, 1, "a duplicate resume cannot start a second battle")
+run.release()
+
+local cancelRun = T.sdk.loadMods({ "mods/scope_probe" }, {
+  fs = T.sdk.memfs(FIXTURE),
+})
+local starts, cancels = 0, 0
+OW.prepareTrainerBattle(game, {
+  trainerClass = "OPP_FIX_YOUNGSTER", partyIndex = 2,
+  mapId = "FIX_ROUTE", npcId = "TRAINER_7",
+}, function()
+  starts = starts + 1
+end, function()
+  cancels = cancels + 1
+end)
+local cancelOut = cancelRun.loader.exports.scope_probe or {}
+T.eq(cancelOut.continue({ cancel = true }), true,
+  "the retained continuation can cancel a deferred encounter")
+T.eq(starts, 0, "cancelling never constructs a trainer battle")
+T.eq(cancels, 1, "cancelling invokes the encounter's completion callback")
+T.eq(cancelOut.continue(), false,
+  "a cancelled continuation remains one-shot")
+cancelRun.release()
+
+T.finish("trainer_before_battle")