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

src/battle/BattleState.lua

@@ -617,6 +617,44 @@ local function newBattle(game)
   return self
 end
 
+local function scopedPlayerParty(game, indices)
+  if indices == nil then return nil, nil end
+  if type(indices) ~= "table" then
+    Logger.warn("trainer battle party scope is not a table; using full party")
+    return nil, nil
+  end
+  local count = #indices
+  local keyCount = 0
+  for key in pairs(indices) do
+    keyCount = keyCount + 1
+    if type(key) ~= "number" or key % 1 ~= 0 or key < 1 or key > count then
+      Logger.warn("trainer battle party scope is malformed; using full party")
+      return nil, nil
+    end
+  end
+  if count == 0 or keyCount ~= count then
+    Logger.warn("trainer battle party scope is empty or sparse; using full party")
+    return nil, nil
+  end
+  local party, normalized, seen = {}, {}, {}
+  for i = 1, count do
+    local index = indices[i]
+    if type(index) ~= "number" or index % 1 ~= 0
+        or not game.save.party[index] or seen[index] then
+      Logger.warn("trainer battle party scope contains an invalid index; using full party")
+      return nil, nil
+    end
+    seen[index] = true
+    normalized[i] = index
+    party[i] = game.save.party[index]
+  end
+  return party, normalized
+end
+
+function BattleState:playerPartyView()
+  return self.playerParty or self.game.save.party
+end
+
 -- opts.hooked: rod encounter, announced with _HookedMonAttackedText
 function BattleState.newWild(game, species, level, opts)
   local self = newBattle(game)
@@ -692,13 +730,15 @@ local function applySpecialMoves(data, oppClass, partyIndex, party)
   end
 end
 
-function BattleState.newTrainer(game, oppClass, partyIndex)
+function BattleState.newTrainer(game, oppClass, partyIndex, opts)
   local self = newBattle(game)
   self.kind = "trainer"
   self.oppClass = oppClass
   -- the object_event trainer arg (roster index).  computeMusicKind keys
   -- data/scripts/victories.lua on class#party, so keep it on the battle (#782).
   self.partyIndex = partyIndex or 1
+  self.playerParty, self.playerPartyIndices = scopedPlayerParty(game,
+    opts and opts.playerPartyIndices)
   self.trainer = game.data.trainers[oppClass]
   assert(self.trainer, "unknown trainer class " .. tostring(oppClass))
   -- pret GetTrainerName_: RIVAL1/2/3 copy wRivalName into wTrainerName
@@ -742,7 +782,7 @@ function BattleState.newTrainer(game, oppClass, partyIndex)
     end
   end
   self.enemyIndex = 1
-  local playerMon = Party.firstHealthy(game.save.party)
+  local playerMon = Party.firstHealthy(self:playerPartyView())
   if not playerMon then
     Logger.warn("trainer battle with no healthy party; skipping")
     self.dead = true
@@ -2002,7 +2042,7 @@ function BattleState:update(dt)
     -- loops the party menu until a healthy mon is picked, so B and
     -- fainted picks land back here and reopen it
     if self.player.mon.hp <= 0 then
-      if Party.firstHealthy(self.game.save.party) then
+      if Party.firstHealthy(self:playerPartyView()) then
         self:openReplacementMenu()
       end
       return
@@ -3890,7 +3930,8 @@ function BattleState:awardExp()
   -- (RemoveFaintedPlayerMon), so it drops out of the divisor and only
   -- the surviving participants are counted and paid
   local participants, alive = 0, {}
-  for _, mon in ipairs(self.game.save.party) do
+  local playerParty = self:playerPartyView()
+  for _, mon in ipairs(playerParty) do
     if self.participants and self.participants[mon] then
       participants = participants + 1
       if mon.hp > 0 then table.insert(alive, mon) end
@@ -3984,9 +4025,9 @@ function BattleState:awardExp()
       -- experience.asm:9-13); each mon gets its own GainedText with the
       -- "with EXP.ALL," tail (wBoostExpByExpAll) -- pokered prints no
       -- summary line
-      for _, mon in ipairs(self.game.save.party) do
+      for _, mon in ipairs(playerParty) do
         if mon.hp > 0 then
-          ctx.applyShare(mon, math.max(1, ctx.participants) * #self.game.save.party * 2, "expAll")
+          ctx.applyShare(mon, math.max(1, ctx.participants) * #playerParty * 2, "expAll")
         end
       end
     end
@@ -4027,7 +4068,7 @@ function BattleState:enemyMonFainted()
       local nextName = nextMon.nickname or self.data.pokemon[nextMon.species].name
       local style = tostring((self.game.save.options or {}).battleStyle or "shift")
         :lower()
-      local partyCount = #self.game.save.party
+      local partyCount = #self:playerPartyView()
       -- ReplaceFaintedEnemyMon (core.asm:892-896): DrawEnemyPokeballs puts the
       -- foe's party ball row -- and the HUD chrome PlaceEnemyHUDTiles lays
       -- down under it (draw_hud_pokeball_gfx.asm:9-11, 33-45, 134-141) -- into
@@ -4054,6 +4095,7 @@ function BattleState:enemyMonFainted()
             local game = self.game
             Screens.push(game, "PartyMenu", {
               battle = self,
+              party = self:playerPartyView(),
               forceSwitch = true,
               onSwitch = function(mon)
                 if mon ~= self.player.mon and mon.hp > 0 then
@@ -4226,7 +4268,7 @@ function BattleState.isOaksLabStarterRival(self)
 end
 
 function BattleState:playerMonFainted()
-  local nextMon = Party.firstHealthy(self.game.save.party)
+  local nextMon = Party.firstHealthy(self:playerPartyView())
   -- Being out of useable POKéMON blacks you out even when the battle was
   -- already decided in our favour.  A double faint -- our last mon dying
   -- to residual damage on the turn it lands the KO -- used to hit the
@@ -4299,6 +4341,7 @@ function BattleState:openReplacementMenu()
   self:ui(function()
     return self:buildScreen("PartyMenu", {
       battle = self,
+      party = self:playerPartyView(),
       -- ChooseNextMon: pick immediately (no SWITCH/STATS/CANCEL)
       forceSwitch = true,
       onSwitch = function(mon)
@@ -4779,6 +4822,7 @@ function BattleState:openParty()
   self:ui(function()
     return self:buildScreen("PartyMenu", {
       battle = self,
+      party = self:playerPartyView(),
       onSwitch = function(mon)
         if mon == self.player.mon then
           self:say(Strings("%s is\nalready out!", self.player.name))
@@ -4825,8 +4869,8 @@ function BattleState:finish()
   -- here it did not, so say so rather than silently papering over it.
   -- The old-man / PROF.OAK demo also skips it: the party never fought
   -- (Yellow's Pallet intro runs before the player owns a mon at all).
-  if self.result ~= "lose" and not self.demo
-     and not Party.firstHealthy(self.game.save.party) then
+  if self.kind ~= "link" and self.result ~= "lose" and not self.demo
+     and not Party.firstHealthy(self:playerPartyView()) then
     Logger.warn("battle finished %s with no healthy party; forcing blackout",
                 tostring(self.result))
     self.result = "lose"
@@ -5707,7 +5751,7 @@ function BattleState:drawHUDs(slide)
     for i = 10, 17 do hudTile(0x76, i * 8, 88) end
     hudTile(0x6F, 72, 88)
     love.graphics.setColor(1, 1, 1, 1)
-    self:drawBallRow(self.playerParty or self.game.save.party, 88, 80, 8)
+    self:drawBallRow(self:playerPartyView(), 88, 80, 8)
   end
   local hidePlayer = self.safari or self.demo
   if showStatus and self.player and not hidePlayer and not self.showPlayerBack

src/core/BattleCheckpoint.lua

@@ -44,6 +44,7 @@ local BATTLE_FIELDS = {
   "sideToxic", "isGymLeader", "musicKind", "lastBall", "lockedBall",
   "lowHealthAlarmDisabled", "lowHealthAlarmOn", "victoryMusicPlayed",
   "endBattleText",
+  "playerPartyIndices",
 }
 
 local function partyIndex(party, mon)
@@ -91,6 +92,23 @@ local function integer(value, min, max)
     and value >= (min or -math.huge) and value <= (max or math.huge)
 end
 
+local function exactIndexSet(indices, maxIndex, requireMember)
+  if type(indices) ~= "table" then return nil end
+  local count, keys = #indices, 0
+  for key in pairs(indices) do
+    keys = keys + 1
+    if not integer(key, 1, count) then return nil end
+  end
+  if keys ~= count or (requireMember and count == 0) then return nil end
+  local seen = {}
+  for i = 1, count do
+    local index = indices[i]
+    if not integer(index, 1, maxIndex) or seen[index] then return nil end
+    seen[index] = true
+  end
+  return seen
+end
+
 local function validateMoveList(data, moves)
   if type(moves) ~= "table" then return false end
   for _, move in ipairs(moves) do
@@ -200,6 +218,16 @@ function BattleCheckpoint.validate(game, checkpoint)
   if type(party) ~= "table" or not validateBattler(game.data, model.player, #party) then
     return nil, "invalid_content", "Player battle state is invalid."
   end
+  local scopedIndices
+  if model.playerPartyIndices ~= nil then
+    if model.kind ~= "trainer" then
+      return nil, "invalid_checkpoint", "Battle party scope is invalid."
+    end
+    scopedIndices = exactIndexSet(model.playerPartyIndices, #party, true)
+    if not scopedIndices or not scopedIndices[model.player.index] then
+      return nil, "invalid_checkpoint", "Battle party scope is invalid."
+    end
+  end
   if model.kind == "wild" then
     if not validateMon(game.data, model.enemyMon)
         or not validateBattler(game.data, model.enemy, 1) then
@@ -220,12 +248,15 @@ function BattleCheckpoint.validate(game, checkpoint)
     end
   end
   for _, indices in ipairs({ model.participants, model.leveledUp }) do
-    if type(indices) ~= "table" then
+    local referenced = exactIndexSet(indices, #party, false)
+    if not referenced then
       return nil, "invalid_checkpoint", "Battle party reference set is missing."
     end
-    for _, index in ipairs(indices) do
-      if not integer(index, 1, #party) then
-        return nil, "invalid_checkpoint", "Battle party reference is invalid."
+    if scopedIndices then
+      for index in pairs(referenced) do
+        if not scopedIndices[index] then
+          return nil, "invalid_checkpoint", "Battle party reference is invalid."
+        end
       end
     end
   end
@@ -276,7 +307,9 @@ function BattleCheckpoint.restore(game, checkpoint, copy)
   local model = checkpoint.runtime.battle
   local battle
   if model.kind == "trainer" then
-    battle = BattleState.newTrainer(game, model.oppClass, model.partyIndex)
+    battle = BattleState.newTrainer(game, model.oppClass, model.partyIndex, {
+      playerPartyIndices = model.playerPartyIndices,
+    })
     battle.enemyParty = assert(copy(model.enemyParty))
     battle.enemyIndex = model.enemyIndex
   else

src/ui/PartyMenu.lua

@@ -289,6 +289,7 @@ function PartyMenu.new(game, opts)
   opts = opts or {}
   local self = setmetatable({}, PartyMenu)
   self.game = game
+  local party = opts.party or (opts.battle and opts.battle.playerParty)
   -- PartyMenuInit (home/pokemon.asm) seeds the cursor from
   -- wPartyAndBillsPCSavedMenuItem rather than from zero, and
   -- HandlePartyMenuInput writes wCurrentMenuItem back into it on every
@@ -297,7 +298,7 @@ function PartyMenu.new(game, opts)
   -- both zero the byte, which BattleState mirrors.  The clamp covers a
   -- party that shrank (deposit / release) while the saved index was
   -- pointing past the end. #768
-  local count = #(opts.party or (game.save and game.save.party) or {})
+  local count = #(party or (game.save and game.save.party) or {})
   self.index = math.min(math.max(1, game.partyMenuSavedIndex or 1),
                         math.max(1, count))
   self.onSwitch = opts.onSwitch
@@ -314,7 +315,7 @@ function PartyMenu.new(game, opts)
   self.tmhm = opts.tmhm
   self.forceSwitch = opts.forceSwitch
   self.battle = opts.battle
-  self.party = opts.party -- link battles pass their clamped copies
+  self.party = party -- link/scoped battles pass their local party view
   self.swapFrom = nil
   self.submenu = nil
   self.subIndex = 1

src/world/OverworldController.lua

@@ -3092,6 +3092,27 @@ local function meetTrainerTheme(cls)
          or "Music_MeetMaleTrainer"
 end
 
+-- Public pre-trainer gate. A mod may retain continueBattle while a registered
+-- preparation screen is on top, then resume once with an optional ordered
+-- save-party index scope. The hook is cold on a no-mod boot.
+function OverworldState.prepareTrainerBattle(game, context, startBattle)
+  if not Runtime.wantsHook("trainer.before_battle") then
+    startBattle()
+    return false
+  end
+  local started = false
+  local function continueBattle(options)
+    if started then return false end
+    started = true
+    startBattle(options)
+    return true
+  end
+  local deferred = Runtime.call("trainer.before_battle",
+    function() return false end, game, context, continueBattle)
+  if deferred ~= true and not started then continueBattle() end
+  return deferred == true
+end
+
 -- Run the pre-battle text -> battle -> won text -> flags sequence.
 -- skipBattleText is for map scripts shaped like SilphCo11FDefaultScript
 -- (scripts/SilphCo11F.asm), which DisplayTextID the challenge line BEFORE
@@ -3119,7 +3140,7 @@ function OverworldState:engageTrainer(npc, onDone, endBattleText, skipBattleText
                   or (header and header.won and Game.data.text[header.won])
 
   local BattleState = require("src.battle.BattleState")
-  local function startBattle()
+  local function startBattle(options)
     -- TalkToTrainer (home/trainers.asm:88) prints the before-battle text
     -- FIRST and only then runs `call EngageMapTrainer` / `jp
     -- StartTrainerBattle`, so a trainer challenged on foot gets the sting
@@ -3134,7 +3155,8 @@ function OverworldState:engageTrainer(npc, onDone, endBattleText, skipBattleText
       local theme = meetTrainerTheme(d.trainerClass)
       if theme then require("src.core.Music").play(Game.data, theme) end
     end
-    local battle = BattleState.newTrainer(Game, d.trainerClass, d.trainerParty)
+    local battle = BattleState.newTrainer(Game, d.trainerClass, d.trainerParty,
+      options)
     battle.checkpointOrigin = {
       kind = "trainer_encounter",
       map = self.map.id,
@@ -3171,10 +3193,22 @@ function OverworldState:engageTrainer(npc, onDone, endBattleText, skipBattleText
     end
     self:pushBattle(battle)
   end
+  local function prepareBattle()
+    if not Runtime.wantsHook("trainer.before_battle") then
+      startBattle()
+      return
+    end
+    OverworldState.prepareTrainerBattle(Game, {
+      trainerClass = d.trainerClass,
+      partyIndex = d.trainerParty or 1,
+      mapId = self.map.id,
+      npcId = npc.id,
+    }, startBattle)
+  end
   if skipBattleText then
-    startBattle()
+    prepareBattle()
   else
-    Game.stack:push(TextBox.new(Game, battleText, startBattle))
+    Game.stack:push(TextBox.new(Game, battleText, prepareBattle))
   end
 end