main.lua

------------------------------------------------------------------------
-- AI Rivals
------------------------------------------------------------------------
-- Four persistent AI trainers walk Kanto on their own clock.  They route
-- across the real map graph, train, queue at gym doors, win and LOSE gym
-- battles, keep their own badge case, and turn up to fight the player with
-- whatever party they actually have at that moment.
--
-- WHAT THIS FILE OWNS
--   * the module loader (this mod is many files; the engine loads one)
--   * RivalManager: the roster, the save bucket, the engine seams
--   * every subscription and hook link
-- The thinking lives in src/; nothing below decides anything about a rival.
--
-- THE THREE SEAMS THAT MAKE IT WORK WITHOUT A SECOND BATTLE ENGINE
--   1. `trainers` registry + the `trainer.party` hook.  Each rival owns one
--      trainer record whose party is a placeholder.  When a battle against
--      that class starts, the hook swaps in the rival's LIVE party -- so the
--      player fights CHARMELEON Lv28 because the rival really has one.
--   2. `mod.world:spawnNpc` / `removeNpc`.  A rival is a real overworld
--      object only while the player shares its map; everywhere else it is a
--      row in a table being advanced by the tick.
--   3. `core.update`.  One accumulator, one tick every 1.5s, a bounded
--      number of rivals per tick.  Nothing in this mod runs per frame.
------------------------------------------------------------------------

------------------------------------------------------------------------
-- Module loader
------------------------------------------------------------------------
-- The engine loads exactly one chunk per mod, so a multi-file mod brings its
-- own require.  `mod:read` is the supported way to get at a file inside the
-- mod directory -- it works identically from a folder install and from a
-- packed .modpkg (mod:read works in both installs).  Each module receives
-- (req, mod) as varargs, which is why every file opens `local req, mod = ...`.

return function(mod)

local loaded, loading = {}, {}

local function req(name)
  local hit = loaded[name]
  if hit ~= nil then return hit end
  if loading[name] then
    error("ai_rivals: circular require of " .. name, 0)
  end
  loading[name] = true
  local source = mod:read(name .. ".lua")
  if not source then
    error("ai_rivals: missing module " .. name .. ".lua", 0)
  end
  -- Sandbox binds load/loadstring to the mod env; prefer loadstring (works
  -- on Lua 5.1 AND as a 5.2 alias), then the 5.2+ string `load`.  Both are
  -- pcall'd so a build where the other does not take a string never kills
  -- the mod load.
  local chunk, err
  if type(loadstring) == "function" then
    local ok, c = pcall(loadstring, source, "@ai_rivals/" .. name .. ".lua")
    if ok then chunk = c else err = c end
  end
  if not chunk and type(load) == "function" then
    local ok, c = pcall(load, source, "@ai_rivals/" .. name .. ".lua")
    if ok then chunk = c else err = c end
  end
  if not chunk then error("ai_rivals: " .. tostring(err), 0) end
  local value = chunk(req, mod)
  loading[name] = nil
  loaded[name] = value == nil and true or value
  return loaded[name]
end

local Util       = req("src/Util")
local MapGraph   = req("src/MapGraph")
local Pathfinder = req("src/Pathfinder")
local BattleSim  = req("src/BattleSim")
local Rival      = req("src/Rival")
local AI         = req("src/AI")
local Simulation = req("src/Simulation")
local Sprites    = req("src/Sprites")
local Version    = req("src/Version")
local Dialogue   = req("src/Dialogue")
local DoubleBattles = req("src/DoubleBattles")
local WonderTrade = req("src/WonderTrade")
local KantoCompat = req("src/KantoCompat")
local Memory = req("src/Memory")
local Relationships = req("src/Relationships")
local TeamPlan = req("src/TeamPlan")
local Story = req("src/Story")
local Presence = req("src/Presence")
local Weather = req("src/Weather")
local Economy = req("src/Economy")
local League = req("src/League")
local LifePath = req("src/LifePath")
local Career = req("src/Career")
local Phone = req("src/Phone")
local Comms = req("src/Comms")
local BattleFlow = req("src/BattleFlow")
local RuntimePolicy = req("src/RuntimePolicy")
local RosterPolicy = req("src/RosterPolicy")
local Gen2Talk = req("src/Gen2Talk")
local Scout = req("src/Scout")
local Achievements = req("src/Achievements")
local Rankings = req("src/Rankings")
local NOTABLE = req("data/notable")
local Pokegear = req("src/Pokegear")
local Tournaments = req("src/Tournaments")
local Status = req("src/ui/Status")
local Commands = req("src/debug/Commands")

local Compat     = req("src/Compat")

-- The complete double-battle implementation is bundled into this mod so a
-- companion works without a second installation.
DoubleBattles(mod)

local ROSTER        = req("data/rivals")

-- A roster row's home maps for the game actually loaded. Accepts the flat
-- list form too, so a third-party roster written before 2.10 keeps working.
local function homeMapsFor(def)
  local maps = def and def.homeMaps
  if type(maps) ~= "table" then return {} end
  if type(maps[1]) == "string" then return maps end
  return maps[(M and M.versionKey) or "default"] or maps.default or {}
end
local PERSONALITIES = req("data/personalities")
local GYMS          = req("data/gyms")
local LINES         = req("data/dialogue")

local SAVE_VERSION = 9
local TALK_TEXT = "AIR_RIVAL_TALK"      -- the text id our spawned NPCs carry
local SCREEN = "AiRivalsStatus"

-- The manager.  Declared up here -- before the map helpers below reference
-- it -- so a closure is never left holding the global `M` (which would be
-- nil and crash the first gauntlet resolution).  `Sprites` is already
-- required above.
local M = {
  game = nil,
  data = nil,
  graph = nil,
  -- 3.5.0 (from the 3.4.1 patch): ONE rival battle at a time.
  --
  -- A rival battle is a TRANSACTION, not an instant: dialogue, the deferred
  -- launch, the battle itself, then the bookkeeping and gauntlet progression
  -- that follow battle.ended. Every one of those windows could previously be
  -- re-entered -- by a second talk in the same frame, a nearby rival's duel
  -- AI, a repeated Gen 2 engagement event, or a stale delayed callback -- and
  -- the second entrant would corrupt the first's state.
  --
  -- The sequence ID is what makes a STALE callback distinguishable from a live
  -- one: a callback carrying an older id cannot start anything.
  rivalBattleSequenceActive = false,
  rivalBattleSequenceId = 0,
  rivalBattleActiveRivalId = nil,

  rivals = {},          -- ordered list
  byId = {},
  sim = nil,
  sprites = Sprites.new(mod),
  dialogue = nil,
  spawned = {},         -- rival id -> npc handle id, current map only
  pending = nil,        -- the rival whose battle is about to start
  ready = false,
  generation = 1,
  news = {},            -- 1.14.0: ring buffer of world-news lines
  ticker = { text = nil, age = 0, duration = 8, offset = 0 },
  tickerQueue = {},
  companionId = nil,
  worldStartPending = false,
  pendingRivalMenu = nil,
  pendingRivalAction = nil,
  pendingPhoneTrainer = nil,
  pendingTrainerContact = nil,
  phoneTrainerDefs = {},
  phoneContactObjects = {},
  radioStation = "POKEMON_MUSIC",
  radioEnabled = false,
  customMusicFolder = "custom_music",
  customMusicTrack = nil,
  customMusicSource = nil,
  challengeModes = {},
  tournaments = nil,
  tournamentExpActive = false,
  perf = {
    simulation = { samples = 0, average = 0, maximum = 0 },
    walking = { samples = 0, average = 0, maximum = 0 },
    -- Observational only: whole core.update body, so it sees the steady-state
    -- cost (F1/F2/F4-F7 in docs/performance.md) that sim/walk cannot. Does not
    -- feed slowStrikes/autoLowSeconds -- adding a measurement must not change
    -- when the mod decides it is struggling.
    frame = { samples = 0, average = 0, maximum = 0 },
    autoLowSeconds = 0, recoveries = 0,
  },
  log = {},             -- replaced below with the news-writing function
}

-- Player tournament matches are special events: every ordinary EXP award
-- produced by the engine during one of these battles is doubled.  The flag is
-- raised only after the bracket launches its player match and is cleared by
-- battle.ended/blackout, so wild battles and ordinary rival challenges are
-- untouched.
mod.hooks:wrap("exp.gain", function(next, c)
  local gained = next(c)
  if M.tournamentExpActive then
    return math.max(1, math.floor((tonumber(gained) or 0) * 2))
  end
  return gained
end)

local function performanceClockMs()
  local value
  pcall(function()
    if love and love.timer and love.timer.getTime then
      value = love.timer.getTime() * 1000
    elseif os and os.clock then
      value = os.clock() * 1000
    end
  end)
  return value
end

function M:recordPerformance(kind, started)
  local finished = performanceClockMs()
  if not (started and finished) then return end
  local elapsed = math.max(0, finished - started)
  local row = self.perf and self.perf[kind]
  if not row then return end
  row.samples = (row.samples or 0) + 1
  row.average = row.samples == 1 and elapsed
    or (row.average * 0.9 + elapsed * 0.1)
  row.maximum = math.max(row.maximum or 0, elapsed)
  local limit = kind == "walking" and 8 or 12
  if elapsed > limit then
    row.slowStrikes = (row.slowStrikes or 0) + 1
  else
    row.slowStrikes = math.max(0, (row.slowStrikes or 0) - 1)
  end
  if row.slowStrikes >= 3 then
    self.perf.autoLowSeconds = math.max(self.perf.autoLowSeconds or 0, 20)
    row.slowStrikes = 0
  end
end

-- The world log is a function the simulation calls for every event; it turns
-- each one into a line of news the player can read ("Matt caught a Pikachu",
-- "Larissa beat Misty").  `news` holds the freshest lines.
M.log = function(rival, event)
  return M:addNews(rival, event)
end

-- The newest news line, for the status screen.
function M:latestNews()
  local news = self.news
  return news[#news] and news[#news].text or "The world is quiet."
end

-- Turn a simulation event into a line of news.  Every event the tick logs
-- (catches, levels, evolutions, gym results, duels, trainer battles, ghost
-- hunts, League runs) becomes a sentence the player can read.
function M:addNews(rival, event)
  if not (rival and event and type(event) == "table") then return end
  local name = rival.name or rival.id or "?"
  local line
  local kind = event.kind
  if event.gym ~= nil then
    line = event.won
      and (name .. " beat " .. tostring(event.gym.leader or "a Gym Leader") .. "!")
      or (name .. " lost to " .. tostring(event.gym.leader or "a Gym Leader") .. ".")
  elseif kind == "caught" then
    line = name .. " caught a " .. Util.spaced(event.species or "Pokemon") .. "."
  elseif kind == "level" then
    line = name .. "'s " .. Util.spaced(event.species or "mon")
      .. " reached Lv" .. tostring(event.level) .. "."
  elseif kind == "evolve" then
    line = name .. "'s " .. Util.spaced(event.from or "mon") .. " evolved into "
      .. Util.spaced(event.into or "something") .. "!"
  elseif kind == "move" then
    line = name .. " learned " .. Util.spaced(event.move or "a move") .. "."
  elseif kind == "tournament_eliminated" then
    line = name .. " was knocked out of a " .. tostring(event.format or "SINGLE"):lower()
      .. " tournament by " .. tostring(event.by or "another rival") .. "."
  elseif kind == "tournament_won" then
    line = name .. " won a " .. tostring(event.format or "SINGLE"):lower() .. " tournament!"
  elseif kind == "duel" then
    if event.dethroned then
      line = name .. " dethroned the Champion!"
    else
      line = name .. (event.won and " beat " or " lost to ")
        .. tostring(event.vs or "a rival") .. " in a duel."
    end
  elseif kind == "skirmish" then
    line = name .. (event.won and " beat " or " lost to ")
      .. tostring(event.vs or "a rival") .. " in a skirmish."
  elseif kind == "trainer_battle" then
    line = name .. (event.won and " beat " or " lost to ")
      .. Util.spaced(event.trainer or "a trainer") .. "."
  elseif kind == "ghost" then
    line = name .. (event.won and " beat " or " lost to ")
      .. tostring(event.ghost or "a ghost") .. "."
  elseif kind == "title_match" then
    -- 4.6.0. Named from the CHALLENGER's side either way, because "X took the
    -- title from Y" and "Y held them off" are the same event told once.
    local holder = event.holderName or tostring(event.holder or "the Champion")
    local challengerName = event.challengerName or tostring(event.challenger or "a rival")
    if event.won then
      line = challengerName .. " took the title from " .. holder .. "!"
    else
      line = holder .. " held the title against " .. challengerName .. "."
    end
  elseif kind == "league" then
    if event.won and event.qualified then
      -- Cleared the Elite Four while somebody else wears the crown: this is a
      -- challenger now, not a champion, and saying so is the point.
      line = name .. " cleared the Elite Four and wants a title shot."
    elseif event.won then
      line = name .. " conquered the League!"
    elseif event.stage then
      -- Saying WHERE they fell is what makes a repeated failure a story rather
      -- than a repeated line. The escalating gate above means this is now a
      -- handful of items over a session instead of one every sixteen ticks.
      line = name .. " fell at the League, stage " .. tostring(event.stage) .. "."
    else
      line = name .. " fell at the League."
    end
  elseif kind == "champion" then
    line = tostring(event.text or name)
  elseif kind == "bought_balls" then
    line = name .. " bought " .. tostring(event.count or 0) .. " Poke Ball(s)."
  elseif kind == "tm_found" then
    line = name .. " found a TM for " .. Util.spaced(event.move or "a move") .. "."
  elseif kind == "tm_bought" then
    line = name .. " bought a TM for " .. Util.spaced(event.move or "a move") .. "."
  elseif kind == "tm_learned" then
    line = name .. " taught " .. Util.spaced(event.move or "a move")
      .. " to " .. Util.spaced(event.species or "a Pokemon") .. "."
  elseif kind == "hm_obtained" then
    line = name .. " obtained the HM for " .. Util.spaced(event.move or "a field move") .. "."
  elseif kind == "hm_taught" then
    line = name .. " taught " .. Util.spaced(event.move or "an HM")
      .. " to " .. Util.spaced(event.species or "a Pokémon") .. "."
  elseif kind == "hm_used" then
    line = name .. " used " .. Util.spaced(event.move or "an HM")
      .. " to reach " .. Util.spaced(event.map or "a new area") .. "."
  elseif kind == "hm_hunt" then
    line = name .. " is hunting " .. Util.spaced(event.species or "a Pokémon")
      .. " that can learn " .. Util.spaced(event.move or "an HM") .. "."
  elseif kind == "sold" then
    line = name .. " sold " .. tostring(event.count or 0)
      .. " duplicate(s) for Y" .. tostring(event.money or 0) .. "."
  elseif kind == "candy" then
    line = name .. " used a Rare Candy on "
      .. Util.spaced(event.species or "a Pokemon") .. "."
  elseif kind == "dex" then
    line = name .. " filled " .. tostring(event.milestone or 0)
      .. " Pokédex entries!"
  elseif kind == "hunt" then
    line = name .. " is hunting a " .. Util.spaced(event.species or "Pokemon") .. "."
  elseif kind == "trade" then
    line = name .. " traded a " .. Util.spaced(event.gave or "Pokemon")
      .. " for " .. Util.spaced(event.got or "Pokemon")
      .. " with " .. tostring(event.with or "a rival") .. "."
  elseif kind == "wonder_trade" then
    line = name .. " Wonder Traded " .. Util.spaced(event.gave or "a duplicate")
      .. " for a shiny " .. Util.spaced(event.got or "Pokemon") .. "!"
  elseif kind == "ace" then
    line = name .. " made " .. Util.spaced(event.species or "a Pokemon")
      .. " their team ace after forming a special bond."
  elseif kind == "rematch" then
    line = name .. (event.won and " beat " or " lost to ")
      .. Util.spaced(event.trainer or "a leader") .. " in a rematch."
  elseif kind == "life_transition" then
    line = LifePath.transitionHeadline(name, event.from, event.to)
  elseif kind == "life_path" then
    -- §22/§23: phrased as something the world noticed, never as a system
    -- announcement, and rare by construction -- at most two rivals per save
    -- can ever produce one of these.
    line = LifePath.headline(name, event.path)
  elseif kind == "career" then
    line = Career.promotionHeadline(name, rival and rival:lifePathId(), event.level)
  elseif kind == "sighting" then
    -- Already rate-limited and already phrased by Presence.observe; this arm
    -- exists so sightings share the one news channel rather than opening a
    -- second one the player has to watch.
    line = event.note
  elseif kind == "camp" then
    return   -- a camp is something you FIND, not something you are told about
  elseif kind == "milestone" then
    -- §21/§31: milestones are recorded for every rival, but only the flagged
    -- ones are worth interrupting the player for.
    if event.notable ~= true then return end
    line = Story.milestoneHeadline(name, Story.MILESTONE_BY_ID[event.milestone])
  elseif kind == "chapter" then
    line = Story.chapterHeadline(name, event.chapter, event.facts)
  elseif kind == "team_style" then
    -- 1.34.0. Only an actual identity CHANGE reaches here, and identity moves
    -- only on accumulated evidence, so this is rare by construction.
    line = name .. " is rebuilding their team around a "
      .. TeamPlan.label(event.style):lower() .. " strategy."
  elseif kind == "relationship" then
    -- 1.33.0.  Only a DERIVED state transition reaches here, and only through
    -- Relationships.headline, so the player is never told the same shift twice
    -- in two different sentences.  A change with no headline (into NEUTRAL,
    -- say) is real but not news.
    local other = self.byId[event.with]
    line = Relationships.headline(name, other and other.name or "the player",
                                  event.state)
  elseif kind == "news" then
    line = tostring(event.text)
  end
  if not line then return end
  self.news[#self.news + 1] = { tick = self.sim and self.sim.tick or 0, text = line }
  if #self.news > 40 then table.remove(self.news, 1) end
  local headline = "WORLD NEWS  •  " .. line
  if self.ticker and self.ticker.text then
    self.tickerQueue = self.tickerQueue or {}
    local previous = self.tickerQueue[#self.tickerQueue] or self.ticker.text
    if previous ~= headline then
      self.tickerQueue[#self.tickerQueue + 1] = headline
      -- Headlines are transient UI, not history. Keep the newest few so rapid
      -- training events cannot create an unbounded, increasingly stale queue.
      while #self.tickerQueue > 8 do table.remove(self.tickerQueue, 1) end
    end
  else
    self.ticker = { text = headline, age = 0, duration = 8, offset = 0 }
  end
  return line
end

-- The map where the intro gauntlet plays out.
-- pret/pokered (and gen1recomp) use OAKS_LAB for the interior lab map and
-- PALLET_TOWN for the outdoor town.  The player receives their starter and
-- meets Oak *inside* OAKS_LAB, so that is the primary home for the gauntlet.
-- PALLET_TOWN is kept as a fallback for total conversions that only ship the
-- outdoor map.  Gen 2 has neither under these names, so the gauntlet simply
-- does not start there (same as 1.6.0).
-- pret/pokered and Yellow both use OAKS_LAB for the interior.  Resolve from
-- the live map table first (graph can lag if build ran on incomplete data).
--
-- 2.7.0 -- GOLD.  The comment above used to claim "Gen 2 has neither under
-- these names, so the gauntlet simply does not start there", and the code did
-- not do that: the candidate list held only Kanto maps and the fallback
-- RETURNED "OAKS_LAB" regardless.  On Gold that named a map the game does not
-- have, so the mod announced a gauntlet in Oak's Lab, told the player the
-- rivals were waiting there, and sent them to a room that does not exist.
--
-- Gold's equivalents are Elm's lab and New Bark Town.  They are candidates in
-- their own right rather than aliases, and the fallback is now nil -- a boot
-- with none of these really has nowhere to hold the gauntlet, and saying so is
-- better than naming a room at random.
local GAUNTLET_LAB_CANDIDATES = {
  "OAKS_LAB", "ELMS_LAB", "PALLET_TOWN", "NEW_BARK_TOWN",
}
local function mapExists(id)
  if not id then return false end
  local g = M.graph
  if type(g) == "table" then
    if type(g.has) == "function" then
      local ok, hit = pcall(g.has, g, id)
      if ok and hit then return true end
    elseif type(g.nodes) == "table" and g.nodes[id] then
      return true
    end
  end
  local maps = M.data and (M.data.maps or M.data.gen2Maps)
  if type(maps) == "table" and maps[id] then return true end
  local game = M.game
  local gmaps = game and game.data and game.data.maps
  if type(gmaps) == "table" and gmaps[id] then return true end
  return false
end
local function resolveGauntletLab(graph)
  for _, id in ipairs(GAUNTLET_LAB_CANDIDATES) do
    if mapExists(id) then return id end
    if type(graph) == "table" then
      if type(graph.has) == "function" then
        local ok, hit = pcall(graph.has, graph, id)
        if ok and hit then return id end
      elseif type(graph.nodes) == "table" and graph.nodes[id] then
        return id
      end
    end
  end
  -- No lab and no starting town in this boot. nil is the honest answer; every
  -- caller below treats it as "there is no gauntlet here".
  return nil
end
local function gauntletLabId()
  return resolveGauntletLab(M.graph)
end

-- Is the intro gauntlet possible in this game at all? Read by the intro
-- screen, so a boot with no lab never offers a battle it cannot stage.
function M:gauntletLab()
  return resolveGauntletLab(M.graph)
end

function M:gauntletPossible()
  return self:gauntletLab() ~= nil
end

-- The room's name as a player would say it. Known rooms get their real name;
-- anything else (a conversion, a randomiser) falls back to the spaced map id,
-- which is at least true -- unlike naming somebody else's laboratory.
local LAB_LABELS = {
  OAKS_LAB = "Oak's Lab",
  ELMS_LAB = "Elm's Lab",
  PALLET_TOWN = "Pallet Town",
  NEW_BARK_TOWN = "New Bark Town",
}

function M:labLabel(id)
  id = id or self:gauntletLab()
  if not id then return "the lab" end
  return LAB_LABELS[id] or Util.spaced(id)
end

-- Gen 2 only: rival id -> the numeric class constant its overworld object
-- must carry to engage a trainer battle.  Filled at registration time.
local GEN2_CLASS = {}
local REGISTERED_TRAINERS = {}

------------------------------------------------------------------------
-- Options
------------------------------------------------------------------------

mod.options:define({
  { key = "rivals", label = "RIVALS", type = "choice", default = "all",
    choices = { { "OFF", "off" }, { "TWO", "two" }, { "ALL", "all" } } },
  { key = "encounters", label = "RIVAL DUELS", type = "toggle", default = true },
  { key = "pace", label = "WORLD PACE", type = "choice", default = "normal",
    choices = { { "SLOW", "slow" }, { "NORMAL", "normal" }, { "FAST", "fast" } } },
  { key = "performance", label = "WALKING COST", type = "choice", default = "balanced",
    choices = { { "LOW", "low" }, { "BALANCED", "balanced" }, { "FULL", "full" } } },
  { key = "relationships", label = "RIVAL BONDS", type = "toggle", default = true },
  { key = "sightings", label = "RIVAL SIGHTINGS", type = "toggle", default = true },
  { key = "life_paths", label = "RIVAL LIFE PATHS", type = "toggle", default = true },
  { key = "news_ticker", label = "NEWS TICKER", type = "toggle", default = true },
  { key = "debug", label = "LK DEBUG", type = "toggle", default = false },
})

local PACE = { slow = 3.0, normal = 1.5, fast = 0.6 }

local function runningOnIOS()
  local ok, os = pcall(function()
    return love and love.system and love.system.getOS and love.system.getOS()
  end)
  return ok and (os == "iOS" or os == "IOS")
end

-- Gen 2 tells us so by having no Gen 1 map-script dispatch.  We ask the
-- manifest-independent way: mod.game is Gold's Game2 instance, whose data
-- carries gen2Maps.  Nothing here changes behaviour except the routes we can
-- take to start a battle and show text.
local function detectGeneration(data)
  if data and (data.gen2Maps or data.gen2Trainers) and not data.maps then
    return 2
  end
  return 1
end

local function mapsTable(data)
  if not data then return {} end
  return data.maps or data.gen2Maps or {}
end

local function activeRoster()
  local chosen
  pcall(function()
    chosen = tonumber(mod.save:get("aiRivalCount"))
  end)
  return RosterPolicy.active(ROSTER, chosen, mod.options:get("rivals"))
end

------------------------------------------------------------------------
-- Content registration (load time)
------------------------------------------------------------------------

-- GEN 1 registration: one trainer record per rival.  `parties` must be
-- non-empty and valid at registration time because the schema checks it, but
-- the party the player actually fights never comes from here -- see the
-- trainer.party hook.  The placeholder is the rival's own first starter
-- preference, so even if the hook were somehow bypassed the battle is coherent
-- rather than empty.
-- Every cross-reference in a trainers record is schema-checked against the
-- MERGED tables, so naming a species, portrait or AI class the loaded game
-- does not have is a load error rather than a warning.  That is the correct
-- strictness, and it means this mod must resolve each reference against the
-- game in front of it: Yellow, a randomizer, a total conversion and the
-- ROM-free fixture dataset all carry different id sets.  A field whose target
-- is missing is OMITTED (the engine's own default covers it); only the party
-- species has no default, so it walks the preference chain and the record is
-- skipped entirely if nothing in it exists.
local function registerGen1Trainers(data)
  local versionKey = Version.starterKey(data)
  local pokemon = (data and data.pokemon) or {}
  local trainers = (data and data.trainers) or {}
  local aiClasses = (data and data.ai_classes) or {}

  for _, def in ipairs(ROSTER) do
    local species = Rival.firstAvailableStarter(def, versionKey, pokemon,
                                                nil, M:starterOpts())
    if species then
      -- Also recognise an already-merged record after a hot reload. The local
      -- guard covers boot + ready in one load; this covers a replaced mod
      -- chunk while the engine's content registry remains alive.
      if trainers[def.trainerClass] then
        REGISTERED_TRAINERS[def.trainerClass] = true
      end
      local record = {
        id = def.trainerClass,
        name = def.name,
        parties = { { { species = species, level = 5 } } },
        baseMoney = def.baseMoney or 50,
      }
      -- borrow the vanilla class's portrait and battle AI only where they
      -- exist; without them the engine draws its default pic and uses the
      -- generic AI, which is a coherent trainer, just a plainer one
      if trainers[def.basePic] then record.basePic = def.basePic end
      if aiClasses[def.aiClass] then record.aiClass = def.aiClass end
      if not REGISTERED_TRAINERS[def.trainerClass] then
        local ok = Util.guard("trainers:register:" .. def.id, function()
          mod.content.trainers:register(def.trainerClass, record)
        end)
        if ok then REGISTERED_TRAINERS[def.trainerClass] = true end
      end
    end
  end
end

-- GEN 2 registration.  Gold's trainers table is shaped differently: it is
-- keyed by CLASS, each class carries a numeric `index` and a `trainers`
-- MEMBER list, and each member row carries its own `party` (Gen 1's `parties`
-- list does not exist).  Registering a Gen 1-shaped record is a schema miss,
-- so the whole branch is Gen 2-shaped or nothing.
--
-- Two strategies, per rival:
--
--   * `gen2Shadow` names a vanilla class whose every member's party is
--     replaced in place.  The story rival's classes (RIVAL1, RIVAL2) become
--     this rival: no new record is registered, the class keeps its own index,
--     portrait, AI and member ids, and every scripted battle of that class --
--     however the story scripts call it -- is a battle against this rival.
--   * without one, a fresh class is registered past the highest index the
--     game has, so a rival with no vanilla slot to ride still exists as a
--     schema-valid class.  The player can meet it but Gold has no way to
--     start a trainer battle against it without the engine patch (docs).
local function registerGen2Trainers(data)
  local gen2 = data and (data.gen2Trainers or data.trainers)
  local classes = gen2 and gen2.classes
  if type(classes) ~= "table" then return end

  local maxIndex = 0
  for _, cls in pairs(classes) do
    if type(cls) == "table" and type(cls.index) == "number" then
      maxIndex = math.max(maxIndex, cls.index)
    end
  end
  local fresh = maxIndex

  local pokemon = (data and data.pokemon) or {}
  for _, def in ipairs(ROSTER) do
    local species = Rival.firstAvailableStarter(def, "gen2", pokemon,
                                                nil, M:starterOpts())
    if species then
      local placeholder = { { species = species, level = 5 } }
      local shadow = def.gen2Shadow and classes[def.gen2Shadow]
      if shadow then
        local members = shadow.trainers
        if type(members) == "table" and #members > 0 then
          for _, row in ipairs(members) do
            row.party = Util.copy(placeholder)
          end
          if def.baseMoney and not shadow.baseMoney then
            shadow.baseMoney = def.baseMoney
          end
        end
        -- the numeric class constant the spawned overworld object carries so
        -- the A press engages this class
        GEN2_CLASS[def.id] = type(shadow.index) == "number" and shadow.index or 0
      else
        fresh = fresh + 1
        local record = {
          id = def.trainerClass,
          name = def.name,
          index = fresh,
          baseMoney = def.baseMoney or 50,
          trainers = { {
            index = 1,
            id = def.id .. "1",
            name = def.name,
            party = Util.copy(placeholder),
          } },
        }
        local existing = classes[def.trainerClass]
        if existing then
          REGISTERED_TRAINERS[def.trainerClass] = true
          GEN2_CLASS[def.id] = tonumber(existing.index) or fresh
        else
          GEN2_CLASS[def.id] = fresh
        end
        if not REGISTERED_TRAINERS[def.trainerClass] then
          local ok = Util.guard("trainers:register:" .. def.id, function()
            mod.content.trainers:register(def.trainerClass, record)
          end)
          if ok then REGISTERED_TRAINERS[def.trainerClass] = true end
        end
      end
    end
  end
end

local function registerTrainers(data)
  if detectGeneration(data) == 2 then
    registerGen2Trainers(data)
    return
  end
  registerGen1Trainers(data)
end

-- One shared handler for every Gen 1 map. Dynamic NPCs are only interactable
-- when they carry a text ID whose map has a matching map_scripts.talk entry;
-- world.interacted is notification-only/absent in several engine builds.
local function rivalTalkHandler(game, ow, npc, done)
  local npcKey
  pcall(function() npcKey = npc and (npc.id or npc.name or (npc.def and npc.def.name)) end)
  local rival = M:rivalAtNpc(npcKey) or M:facedRival()
  if not rival then if done then done() end return end

  if M:gauntletActive() then
    local rows = M:talkGauntlet(rival)
    if type(rows) == "table" and ow and ow.runner then
      ow.runner:run(rows, { npc = npc, onDone = done })
    elseif done then done() end
    return
  end

  -- Normal world interaction: show the greeting text box first, then open
  -- the action menu once the player advances past it. This keeps dialogue
  -- readable and avoids the previous deferred-menu flag getting stuck.
  M.game = game or M.game
  if M.rivalInteractionOpen then
    if done then done() end
    return
  end
  M.rivalInteractionOpen = true
  local line = M.pendingLine or (M.dialogue and M.dialogue:greeting(rival)) or (rival.name .. ".")
  M.pendingLine = nil
  local rows = { { "show_text", tostring(line) } }
  local function finishOpen()
    -- Script callbacks still run inside the event dispatcher on some builds.
    -- Let core.update push the menu from the next idle overworld frame.
    M.pendingRivalMenu = rival.id
    if done then done() end
  end
  if ow and ow.runner and type(ow.runner.run) == "function" then
    local okRun = pcall(function()
      ow.runner:run(rows, { npc = npc, onDone = finishOpen })
    end)
    if not okRun then
      -- Runner refused; fall back to immediate menu after a one-shot ticker.
      local flat = tostring(line):gsub("[\n\r\v\f]+", " "):gsub("%s+", " "):match("^%s*(.-)%s*$") or ""
      M.ticker = { text = flat, age = 0, duration = 6, offset = 0 }
      finishOpen()
    end
  else
    local flat = tostring(line):gsub("[\n\r\v\f]+", " "):gsub("%s+", " "):match("^%s*(.-)%s*$") or ""
    M.ticker = { text = flat, age = 0, duration = 6, offset = 0 }
    finishOpen()
  end
end

-- Register the stable text ID beside every loaded Gen 1 map. Compose
-- registration does not replace vanilla scripts; unsupported conversion maps
-- fail locally and retain the event-hook fallback.
local function registerTalkScripts(data)
  if detectGeneration(data) == 2 then
    -- Gold reaches a mod-spawned NPC through OverworldController.talkTo, not
    -- through map_scripts.talk (which needs a `text` id the Gen 2 interact
    -- ladder never consults) and not through world.interacted (which Gold
    -- only raises with kind "npc" for objects carrying a cart scriptKey).
    -- See src/Gen2Talk.lua for the full reasoning.  Registering the handler
    -- is free; the router installs itself once a world exists.
    Gen2Talk.register("ai_rivals:rivals", function(world, npc)
      local key = Gen2Talk.npcKey(npc)
      local rival = M:rivalAtNpc(key) or M:facedRival()
      if not rival then return false end
      local game = (world and world.game) or M.game or mod.game
      rivalTalkHandler(game, world, npc, nil)
      return true
    end, 40)
    Gen2Talk.install()
    return
  end
  local ids = { OAKS_LAB = true, PALLET_TOWN = true }
  for id in pairs(mapsTable(data) or {}) do ids[id] = true end
  M.talkScriptMaps = M.talkScriptMaps or {}
  for id in pairs(ids) do
    if not M.talkScriptMaps[id] then
      local ok = pcall(function() mod.content.map_scripts:register(id, {
        priority = -5,
        talk = { [TALK_TEXT] = rivalTalkHandler },
      }) end)
      if ok then M.talkScriptMaps[id] = true end
    end
  end
end

------------------------------------------------------------------------
-- Roster construction
------------------------------------------------------------------------

function M:seedAffectionGraph()
  local seed = tonumber(self.seedValue) or tonumber(self.pathSeed) or self:worldSeed() or 1
  for _, rival in ipairs(self.rivals or {}) do
    rival.bonds = type(rival.bonds) == "table" and rival.bonds or Relationships.new()
    Relationships.seedAffection(rival.bonds, "player", seed, rival.id)
    for _, other in ipairs(self.rivals or {}) do
      if other.id ~= rival.id then
        Relationships.seedAffection(rival.bonds, other.id, seed, rival.id)
      end
    end
  end
end

function M:build(data)
  self.data = data
  self.generation = detectGeneration(data)
  -- which starting set the roster hands out; see src/Version.lua
  self.versionKey = Version.starterKey(data)
  self.graph = MapGraph.build(mapsTable(data))
  -- 4.2.0: build the Kanto trainer phone directory from the loaded ROM data.
  -- The directory is derived at runtime, so Red/Blue/Yellow keep their own
  -- trainer roster and no ROM-derived trainer data is shipped by the mod.
  self.phoneTrainerDefs = Comms.discoverTrainers(data, self.graph, self.generation)
  self.byTrainerClass = Comms.indexByTrainerClass(self.phoneTrainerDefs)
  self.phoneContactObjects = {}
  -- 2.5.0: the phone, absorbed from 1.30. Guarded at every step -- Gen 1 has
  -- no Pokegear, so on Red/Blue/Yellow the numbers exist for save
  -- compatibility and calls are delivered through the news ticker instead.
  self.phone = Phone.new(self)
  self.comms = self.comms or Comms.new(nil)
  Util.guard("phone", function() self.phone:bootstrapAll() end)

  self.dialogue = Dialogue.new(LINES, GYMS,
    { compat = self.compat, save = mod.save,
      relationships = function() return self:relationshipsEnabled() end })

  -- Resolve the data-file map name lists against the game that is actually
  -- loaded, so a name this cache does not have is dropped rather than routed
  -- to.  Yellow renames a couple of maps; a total conversion renames many.
  -- The ladder itself is per generation: Gold's badges are Johto's, so the
  -- gen2 section carries its own order/centers/training lists.
  local source = self.generation == 2 and GYMS.gen2 or GYMS
  local gyms = Util.copy(source)
  gyms.centers = self.graph:filterExisting(source.centers)
  gyms.training = self.graph:matching(source.trainingPrefixes)
  -- the badge ladder is the ENGINE's, not ours: constants.badges is what the
  -- player's own trainer card reads, so the rivals climb the same one
  local badges = data and data.constants and data.constants.badges
  if type(badges) == "table" and #badges > 0 then
    local order = {}
    for _, entry in ipairs(badges) do
      local id = type(entry) == "table" and entry.id or entry
      if type(id) == "string" and gyms.byBadge[id] then order[#order + 1] = id end
    end
    if #order > 0 then gyms.order = order end
  end
  self.gyms = gyms

  local ctx = { data = data, personalities = PERSONALITIES,
                graph = self.graph, gyms = gyms,
                -- AI.Destination.HEAL and Rival:isAtPokemonCenter/
                -- blackoutToNearestPokemonCenter read ctx.healingMaps; the
                -- one place that ever built the actual list wrote it onto
                -- gyms.centers instead (see Rival.lua's OWN correct read at
                -- self.ctx.gyms.centers). The three readers therefore always
                -- saw nil/empty -- a rival told to HEAL routed to "wherever
                -- it already is", and a blackout had no real Center to fall
                -- back to. Same table, both names, until the readers are
                -- unified onto gyms.centers directly.
                healingMaps = gyms.centers,
                versionKey = self.versionKey,
                compat = self.compat, save = mod.save,
                -- the emergency-party fallback in Rival:battleParty needs the
                -- same deal the manager uses, or it would hand out a species
                -- from a different permutation
                starterSeed = self:worldSeed(), roster = ROSTER,
                -- 1.33.0: the relationship gate reaches attemptDuel, which is
                -- handed a rival rather than a world view. Refreshed each tick
                -- below so toggling the option takes effect immediately.
                relationships = self:relationshipsEnabled(),
                manager = self }
  self.rivalContext = ctx

  self.rivals, self.byId = {}, {}
  for _, def in ipairs(activeRoster()) do
    local rival = Rival.new(def, ctx)
    self.rivals[#self.rivals + 1] = rival
    self.byId[def.id] = rival
  end
  self.rivalCount = #self.rivals
  self:seedAffectionGraph()

  local performance = mod.options:get("performance") or "balanced"
  self.sim = Simulation.new({
    budget = performance == "low" and 1 or (performance == "full" and 4 or 2),
    socialInterval = performance == "low" and 4
      or (performance == "full" and 1 or 2),
    tickSeconds = PACE[mod.options:get("pace")] or PACE.normal,
  })
  self.tournaments = Tournaments.new(self)
  self.ready = true
end

-- Apply the new-game roster-size answer immediately. Trainer and sprite
-- definitions remain registered for compatibility, but only these live Rival
-- objects are simulated, spawned, saved, or placed in the intro gauntlet.
function M:setRivalCount(value)
  local count = RosterPolicy.clamp(value, #ROSTER, 4)
  if not self.rivalContext then return false end
  local old = self.byId or {}
  local rivals, byId = {}, {}
  for i = 1, count do
    local def = ROSTER[i]
    local rival = old[def.id] or Rival.new(def, self.rivalContext)
    rivals[#rivals + 1], byId[def.id] = rival, rival
  end
  for id, rival in pairs(old) do
    if not byId[id] then
      local npcId = self.spawned and self.spawned[id]
      if npcId then pcall(function() mod.world:removeNpc(npcId) end) end
      if self.spawned then self.spawned[id] = nil end
      if self.companionId == id then self.companionId = nil end
      if self.pending and self.pending.id == id then self.pending = nil end
    end
  end
  self.rivals, self.byId, self.rivalCount = rivals, byId, count
  if self.gauntlet and type(self.gauntlet.order) == "table" then
    local order = {}
    for _, rival in ipairs(rivals) do order[#order + 1] = rival.id end
    self.gauntlet.order = order
    self.gauntlet.index = math.min(tonumber(self.gauntlet.index) or 1, #order)
    if self.gauntlet.active then
      local lab = self.gauntlet.lab or gauntletLabId()
      for _, rival in ipairs(rivals) do
        rival.map, rival.x, rival.y = lab, nil, nil
        rival.destination, rival.route, rival.routeIndex = nil, nil, 1
        rival.path = nil
        if #rival.party == 0 then
          local species = Rival.firstAvailableStarter(
            rival.def, self.versionKey, self.data and self.data.pokemon,
            nil, self:starterOpts())
          if species then rival:markStarter(rival:addPokemon(species, 5)) end
        end
        rival:setState("IDLE", "in the lab")
      end
    end
  end
  return true
end

-- A brand new rival: put it on its home map with one starter, the way the
-- player starts.  Growth is earned from here, never granted.
function M:seed(rival)
  local def = rival.def
  local home
  for _, id in ipairs(homeMapsFor(def)) do
    if self.graph:has(id) then home = id break end
  end
  rival.map = home or next(self.graph.nodes)
  rival.x, rival.y = nil, nil
  -- Seed a starter only into an EMPTY party.  M:load re-seeds on every
  -- empty bucket during boot + New Game; an unguarded add used to stack a
  -- starter per call, which is how a rival reached the lab with a full
  -- party of starters.
  if #rival.party == 0 then
    local species = Rival.firstAvailableStarter(def, self.versionKey,
                                                self.data and self.data.pokemon,
                                                nil, self:starterOpts())
    if species then rival:markStarter(rival:addPokemon(species, 5)) end
  end
  rival:setState("IDLE", "new")
  AI.evaluate(rival, self:worldView())
end

-- ------------------------------------------------------------------
-- The intro gauntlet (Oak's lab)
-- ------------------------------------------------------------------
-- On a new game every rival starts in Oak's lab and battles the player IN
-- TURN, once each, before anyone heads out into Kanto.  The player's party
-- is healed between battles, so each fight is the fair starter-vs-starter
-- showdown the moment is supposed to be.
--
-- Rules that keep it honest and removable:
--   * It is a NEW-GAME feature: a save that has no gauntlet bucket (an older
--     save, or one made mid-playthrough) simply plays without one.
--   * Gen 2 has no Oak's lab, so the gate is `does the graph have the map`.
--   * During the gauntlet the world tick is paused: no rival grinds, catches
--     or leaves town until the player has fought them all.
--   * The battles are forced through the talk verb (a plot battle, so the
--     RIVAL DUELS option is not consulted), one rival per turn, in roster
--     order.  A rival the player has not reached yet just says who is next.
--   * The healing is the one vanilla write this mod makes, and it is exactly
--     the engine's own heal (`Pokemon.heal`) applied to the player's party.

function M:gauntletActive()
  local g = self.gauntlet
  return g ~= nil and g.active == true and type(g.order) == "table"
    and #g.order > 0
end

-- The rival whose turn it is, or nil when the gauntlet is over/absent.
function M:gauntletRival()
  if not self:gauntletActive() then return nil end
  return self.byId[self.gauntlet.order[self.gauntlet.index]]
end

-- Start the gauntlet: put every rival in the lab with its starter.  Returns
-- false (and leaves normal seeding to the caller) when the game has no lab
-- or the roster is empty.
function M:gauntletDone()
  if self.gauntletFinished == true then return true end
  if self.gauntlet and self.gauntlet.finished == true then return true end
  -- Durable one-bit key is the ultimate authority. Never re-open once set.
  local durable = false
  pcall(function()
    if mod.save and mod.save.get and (mod.save:get("gauntletFinished") == true
        or mod.save:get("gauntletMode") == "skip") then
      durable = true
    end
  end)
  if durable then
    self.gauntletFinished = true
    if self.gauntlet then self.gauntlet.finished = true; self.gauntlet.active = false end
    return true
  end
  return false
end

-- True once the vanilla lab rival (Blue) has been fought.  AI rivals only
-- start their walk-up after this beat so they do not interrupt Oak/Blue.
function M:blueLabBattled()
  if self.blueBattled == true then return true end
  local names = {
    "EVENT_BATTLED_RIVAL_IN_OAKS_LAB",
    "EVENT_BEAT_OAKS_LAB_RIVAL",
    "EVENT_OAKS_LAB_RIVAL_BEATEN",
  }
  local function flagTrue(flags, name)
    if type(flags) ~= "table" then return false end
    local v = flags[name]
    return v == true or v == 1 or v == "true"
  end
  local save = self.game and self.game.save
  local flags = save and save.flags
  for _, name in ipairs(names) do
    if flagTrue(flags, name) then
      self.blueBattled = true
      return true
    end
  end
  pcall(function()
    local okFlags, Flags = pcall(function()
      return require("src.script.Flags")
    end)
    if okFlags and Flags and Flags.get and save then
      for _, name in ipairs(names) do
        if Flags.get(save, name) then
          self.blueBattled = true
        end
      end
    end
  end)
  if self.blueBattled then return true end
  pcall(function()
    if mod.flags and mod.flags.get then
      for _, name in ipairs(names) do
        if mod.flags:get(name) then self.blueBattled = true end
      end
    end
  end)
  return self.blueBattled == true
end

function M:beginGauntlet()
  -- Absolute one-time gate. Once the durable flag is set, never re-arm.
  pcall(function()
    if mod.save and mod.save.get and mod.save:get("gauntletFinished") == true then
      self.gauntletFinished = true
      if self.gauntlet then
        self.gauntlet.active = false
        self.gauntlet.finished = true
      end
    end
  end)
  if self:gauntletDone() then
    return false
  end
  -- Extra safety: if we somehow still have a finished structure, refuse.
  if self.gauntlet and self.gauntlet.finished then
    self.gauntletFinished = true
    return false
  end
  local lab = gauntletLabId()
  -- 2.7.0: no lab, no gauntlet. Previously the resolver returned "OAKS_LAB"
  -- whatever the game was, so on Gold this armed a sequence pointed at a room
  -- that does not exist -- which is what put four rivals "waiting in Oak's
  -- Lab" on a game that has no Oak's Lab.
  if not lab then return false end
  local order = {}
  -- Prefer live rivals list; fall back to roster defs
  if type(self.rivals) == "table" and #self.rivals > 0 then
    for _, r in ipairs(self.rivals) do
      if r and r.id then order[#order + 1] = r.id end
    end
  else
    local ok, roster = pcall(activeRoster)
    if ok and type(roster) == "table" then
      for _, def in ipairs(roster) do order[#order + 1] = def.id end
    end
  end
  if #order == 0 then
    for _, def in ipairs(ROSTER) do order[#order + 1] = def.id end
  end

  -- 3.3.0: THE GAUNTLET IS CAPPED, THE WORLD IS NOT.
  --
  -- Every selected rival lives in the world; only the first
  -- M.GAUNTLET_MAX of them queue up in the lab. Four consecutive battles is
  -- already a long opening -- eight would be a wall between the player and
  -- Route 1 -- so the roster and the gauntlet are now separate numbers rather
  -- than the same one by accident.
  --
  -- The rivals left out are not removed or delayed: they are seeded straight
  -- into the world alongside the others when the gauntlet ends, so "all
  -- rivals in the game at once" holds however large the roster gets.
  while #order > M.GAUNTLET_MAX do table.remove(order) end

  -- Set active FIRST so status never stays on "pending" if later work fails.
  self.gauntlet = {
    active = true, index = 1, order = order, lab = lab,
    phase = "wait_blue", phaseT = 0, challenging = false,
  }
  -- Never clear a previously-set finished flag. Only reach here if not done.
  self.gauntletFinished = false

  for _, rival in ipairs(self.rivals or {}) do
    rival.map = lab
    rival.x, rival.y = nil, nil
    rival.destination = nil
    rival.route = nil
    rival.routeIndex = 1
    rival.path = nil
    if #rival.party == 0 then
      local species
      pcall(function()
        species = Rival.firstAvailableStarter(
          rival.def, self.versionKey, self.data and self.data.pokemon,
          nil, self:starterOpts())
      end)
      if not species and self.data and type(self.data.pokemon) == "table" then
        -- Yellow-safe defaults
        for _, cand in ipairs({ "CHARMANDER", "SQUIRTLE", "BULBASAUR",
                                "PIKACHU", "RATTATA", "PIDGEY" }) do
          if self.data.pokemon[cand] then species = cand break end
        end
        if not species then
          for id, _ in pairs(self.data.pokemon) do species = id break end
        end
      end
      if species then
        pcall(function() rival:addPokemon(species, 5) end)
      end
    end
    pcall(function() rival:setState("IDLE", "in the lab") end)
  end

  pcall(function()
    local world = self:worldView()
    if world and lab and world.playerMap == lab then
      self:spawnFor(lab)
    end
  end)
  return true
end

-- Keep every rival parked in the lab until the intro gauntlet is finished.
function M:holdGauntletInLab()
  if self:gauntletDone() then return end
  if not self.gauntlet or not self.gauntlet.active then
    if not self:beginGauntlet() then return end  -- begin itself refuses if done
  end
  local lab = (self.gauntlet and self.gauntlet.lab) or gauntletLabId()
  for _, rival in ipairs(self.rivals) do
    rival.map = lab
    rival.destination = nil
    rival.route = nil
  end
end

-- The engine's own heal, applied to the player's party.  This is the one
-- vanilla write the mod makes, and it is scoped to the gauntlet only.
function M:healPlayerParty()
  local party = self.game and self.game.save and self.game.save.party
  if type(party) ~= "table" then return end
  local ok, Pokemon = pcall(require, "src.pokemon.Pokemon")
  for _, mon in ipairs(party) do
    if type(mon) == "table" and mon.stats and mon.stats.hp then
      if ok and type(Pokemon.heal) == "function" then
        Util.guard("gauntlet:heal", Pokemon.heal, mon)
      else
        mon.hp = mon.stats.hp
        mon.status = nil
      end
    end
  end
end

-- A gauntlet line, with {NAME} rewritten to be the rival the player must
-- battle NEXT (the speaker in these buckets is the one waiting).
function M:gauntletLine(rival, bucket)
  local current = self:gauntletRival()
  local raw = self.dialogue:pick(rival, bucket or {}, 8)
  if not raw then return (rival.name .. ": ...") end
  local tokens = self.dialogue:tokens(rival)
  tokens.NAME = current and current.name or "the next rival"
  return self.dialogue:expand(raw, tokens)
end

-- The talk-verb answer while the gauntlet is active.  The current rival
-- forces a battle (refusing only while the player has no Pokemon yet); every
-- other rival just names who is next.
function M:talkGauntlet(rival)
  local current = self:gauntletRival()
  if not current then return nil end
  local g = self.gauntlet
  local party = self.game and self.game.save and self.game.save.party
  if current == rival then
    -- The director owns an automatic challenge once this slot has begun. An A
    -- press can arrive again while the text box is closing; returning no rows
    -- prevents that input from queuing a second copy of the same conversation
    -- (and a second battle) behind the first one.
    if g and (g.dialogueIndex == g.index or g.phase == "dialogue"
        or g.phase == "launch_battle" or g.phase == "battling"
        or g.challenging) then
      return nil
    end
    if type(party) ~= "table" or #party == 0 then
      return { { "show_text",
        self:gauntletLine(rival, self.dialogue.lines.gauntletNeedStarter) } }
    end
    self.pending = rival
    -- Record the exact gauntlet battle that is currently live. Both
    -- battle.ended and world.blacked_out can fire for one encounter, so the
    -- resolver must be able to recognise and ignore a duplicate event.
    if self.gauntlet then
      self.gauntlet.activeBattleRival = rival.id
      self.gauntlet.activeBattleIndex = self.gauntlet.index
    end
    rival:setState("CHALLENGING_PLAYER", "gauntlet")
    return {
      { "show_text", self.dialogue:challenge(rival) },
      { "start_battle", "trainer", rival.def.trainerClass, 1 },
    }
  end
  return { { "show_text", self:gauntletLine(rival, self.dialogue.lines.gauntletWait) } }
end

-- A gauntlet battle is over: heal the player, advance the turn, and when the
-- last rival has been fought, let everyone leave the lab and start living.
function M:endGauntletBattle(rival)
  local g = self.gauntlet
  if not (g and g.active) then return end
  -- Only the currently active gauntlet battle can advance the sequence. This
  -- blocks a stale battle event, a duplicate callback, or a normal trainer
  -- battle from consuming another rival's turn.
  if g.activeBattleRival and rival and g.activeBattleRival ~= rival.id then
    return
  end
  if g.activeBattleIndex and g.activeBattleIndex ~= g.index then
    return
  end
  -- Accept the fight even if index drifted: match by order membership
  local idx = g.index
  -- battle.ended and world.blacked_out can both fire for the same loss.
  -- Resolve a given Gauntlet slot only once, otherwise the index advances twice
  -- and the player is forced to repeat or skip battles.
  if g.lastResolvedIndex == idx then return end
  if rival and g.order[idx] ~= rival.id then
    for i, id in ipairs(g.order) do
      if id == rival.id then idx = i break end
    end
  end
  if rival and g.order[idx] ~= rival.id then
    -- Still not a gauntlet rival; ignore
    return
  end
  self:healPlayerParty()
  g.lastResolvedIndex = idx
  g.activeBattleRival = nil
  g.activeBattleIndex = nil
  g.dialogueIndex = nil
  g.launchTries = 0
  self._gauntletBattleLauncher = nil
  self._gauntletQueued = false
  self.pending = nil
  g.index = (idx or g.index) + 1
  g.phase = "between"
  g.phaseT = 0
  g.challenging = false
  if g.index > #g.order then
    self:finishGauntlet()
  end
  self:save()
end

-- Scatter destinations so the four do not all stack on one tile.
--
-- 2.10.0: version-keyed. These were Kanto-only, and Gold's map table contains
-- every Kanto map, so on Gold the four were released straight into postgame
-- content the player cannot reach for another forty hours. Johto's opening
-- corridor is the equivalent: New Bark -> Route 29 -> Cherrygrove -> Route 30,
-- ending at Violet, whose Gym is the first on the Johto ladder in data/gyms.
--
-- A map this game does not have is dropped by the caller, exactly as an
-- unknown Gen 1 map already was, so a conversion shipping neither set simply
-- keeps its rivals where the gauntlet left them.
local POST_LAB_STARTS_BY_KEY = {
  default = {
    { map = "ROUTE_1",       dest = "VIRIDIAN_CITY" },
    { map = "VIRIDIAN_CITY", dest = "ROUTE_2" },
    { map = "ROUTE_2",       dest = "PEWTER_CITY" },
    { map = "PALLET_TOWN",   dest = "ROUTE_1" },
  },
  gen2 = {
    { map = "ROUTE_29",        dest = "CHERRYGROVE_CITY" },
    { map = "CHERRYGROVE_CITY", dest = "ROUTE_30" },
    { map = "ROUTE_30",        dest = "VIOLET_CITY" },
    { map = "NEW_BARK_TOWN",   dest = "ROUTE_29" },
  },
}

local function postLabStarts()
  local key = M and M.versionKey
  return POST_LAB_STARTS_BY_KEY[key or "default"]
    or POST_LAB_STARTS_BY_KEY.default
end

-- Release rivals into the world: remove lab NPCs, send them onto Kanto
-- routes, and start the normal AI (train / heal / gym).
function M:finishGauntlet()
  if self.gauntletFinished then return end
  -- Set the durable one-time flag FIRST so any concurrent enter/tick
  -- cannot re-arm the sequence. This is the permanent completion bit.
  self.gauntletFinished = true
  pcall(function()
    if mod.save and mod.save.set then
      mod.save:set("gauntletFinished", true)
    end
  end)
  local g = self.gauntlet
  if g then
    g.active = false
    g.finished = true
  end

  -- Prevent the normal rival challenge system from firing the moment
  -- the four leave the lab (the "level 13 Clefairy rematch" bug).
  for _, r in ipairs(self.rivals or {}) do
    r.encounterCooldown = math.max(r.encounterCooldown or 0, 1200)  -- long lock
    -- 1.11.0: no free balls on leaving the lab.  Rivals start with the
    -- player's pocket money and buy Poké Balls at the first mart / center
    -- they heal at (Rival:restockBalls), so balls come from money won in
    -- battles, never from thin air.
    pcall(function()
      if r.setState then r:setState("TRAVELLING", "post-gauntlet lock") end
    end)
  end

  -- Hard-clear every lab NPC we own
  pcall(function() self:despawnAll() end)
  pcall(function()
    local ow = self.game and self.game.overworld
    if ow and ow.map and ow.map.npcs and ow.map.id == gauntletLabId() then
      local remove = {}
      for i, npc in ipairs(ow.map.npcs) do
        local name = npc.def and npc.def.name
        if type(name) == "string" and name:match("^AIR_") then
          remove[#remove + 1] = i
        end
      end
      for j = #remove, 1, -1 do
        table.remove(ow.map.npcs, remove[j])
      end
    end
  end)
  self.spawned = {}

  for i, r in ipairs(self.rivals) do
    local start = postLabStarts()[((i - 1) % #postLabStarts()) + 1]
    local home = start.map
    -- Do not replace these progression-safe starts with personality homes.
    -- That previously put Chris back in Pallet Town beside Oak's Lab while his
    -- abstract state claimed he was training. The first rival now begins on
    -- Route 1, and every start is reachable without badges or HMs.
    r.map = home
    r.x, r.y = nil, nil
    -- Pay for enough early-route capture attempts even when this scatter start
    -- bypasses Viridian's mart. This is purchased stock, never a free grant.
    pcall(function() if r.buyDepartureBalls then r:buyDepartureBalls(5) end end)
    r.destination = nil
    r.route = nil
    r.routeIndex = 1
    r.path = nil
    r.spawnedAt = nil
    pcall(function()
      r:setState("TRAVELLING", "left the lab")
      r.objective = "TRAIN"
      if r.setDestination then
        r:setDestination(start.dest or "VIRIDIAN_CITY")
      else
        r.destination = start.dest or "VIRIDIAN_CITY"
      end
    end)
    pcall(function() AI.evaluate(r, self:worldView()) end)
    -- If AI.evaluate left them on the lab, force them out again
    if r.map == gauntletLabId() then
      r.map = home
      r.destination = start.dest or "ROUTE_1"
    end
  end

  self.gauntlet = nil
  self:save()
end

-- Character creation and recovery use the same durable path. Skipping awards
-- no wins, badges, money or story flags; it only retires the optional intro
-- sequence and places the untouched rivals at their legal world starts.
function M:skipGauntlet(reason)
  -- Release first. Setting gauntletMode=skip before finishGauntlet would make
  -- gauntletDone return true and strand already-created rivals in Oak's Lab.
  if not self.gauntletFinished then self:finishGauntlet() end
  pcall(function()
    if mod.save and mod.save.set then mod.save:set("gauntletMode", "skip") end
  end)
  self.gauntlet = nil
  self._gauntletStarting = false
  self._gauntletQueued = false
  self._gauntletBattleLauncher = nil
  self.pending = nil
  -- The rivals are positioned now but their clocks do not start until the
  -- player owns a starter and the normal Oak/Blue lab battle has resolved.
  self.worldStartPending = true
  pcall(function() self:save() end)
  return true, "Rival gauntlet skipped" .. (reason and (" (" .. reason .. ").") or ".")
end

-- How far (Manhattan tiles) the current rival will notice the player and
-- begin the walk-up. Lab interiors are small; 10 still covers the whole room
-- and any larger converted labs.
local GAUNTLET_DETECT = 10
-- Tiles that count as "in the player's face" and ready to battle.
local GAUNTLET_ENGAGE = 1
-- Seconds between each one-tile step (walking cadence).
local GAUNTLET_STEP_S = 0.18

-- Move only the rival object. Companions use FOLLOWERS_EX's entity movement
-- fields, letting NPC:update animate the step without the shared script queue.
-- Other movement retains the compatibility facade used by autonomous rivals.
function M:moveRivalNpc(rival, x, y, facing, onDone)
  rival.map = rival.map or gauntletLabId()
  local mapId = rival.map
  local npcId = self.spawned and self.spawned[rival.id]
  if rival.walking then return false end
  local handle
  pcall(function()
    if mod.world and mod.world.npc then
      handle = mod.world:npc(mapId, npcId or ("AIR_" .. tostring(rival.id)))
    end
  end)
  local entity = self.companionId == rival.id and self:liveRivalEntity(rival)
  local ex = entity and math.abs((entity.cellX or rival.x or x) - x) or 0
  local ey = entity and math.abs((entity.cellY or rival.y or y) - y) or 0
  if entity and facing and ex + ey == 1 then
    rival.walking, rival.walkAge, rival.facing = true, 0, facing
    entity.facing, entity.hopStep = facing, nil
    entity.targetX, entity.targetY = x, y
    local ow = self:activeMap()
    local p = ow and ow.player
    entity.stepFrames = (p and (p.stepFramesCur or p.stepFrames)) or 16
    entity.moving, entity.progress = true, 0
    rival.walkTarget = { x = x, y = y, onDone = onDone }
    return true
  end
  local localMove = handle and (handle.setPosition or handle.teleport)
  if localMove then
    local ok, moved = pcall(localMove, handle, x, y, facing)
    if ok and moved ~= false then
      rival.x, rival.y, rival.facing = x, y, facing or rival.facing
      rival.spawnedAt = { x, y }
      rival.walking = false
      if onDone then pcall(onDone) end
      return true
    end
  end

  -- Engines exposing only the global scripted queue keep the existing
  -- interactable object in place; input responsiveness takes priority over a
  -- cosmetic step, and the follower retries on a later map/pulse.
  rival.walking = false
  return false
end

-- One tile toward the player. Returns true when within engage range.
function M:labWalkGrid()
  local overview
  pcall(function()
    if mod.world and mod.world.mapOverview then
      overview = mod.world:mapOverview()
    end
  end)
  local grid = Pathfinder.grid(overview)
  if grid and grid.w and grid.h and grid.w >= 3 then return grid end
  -- Synthetic lab: walkable center aisle between bookcase blocks.
  -- '.' walkable, ' ' blocked (shelves / walls).
  local rows = {
    "          ",
    "  ......  ",
    "  ......  ",
    "  ......  ",
    "  ......  ",
    "  ......  ",
    "  ......  ",
    "  ......  ",
  }
  return Pathfinder.grid({ rows = rows, width = 10, mapId = "OAKS_LAB" })
end

-- One tile toward the player along a walkable path (aisles, not shelves).
function M:gauntletStepTowardPlayer(rival, world)
  if not (rival and world and world.playerX and world.playerY) then return false end
  local rx = rival.x or 3
  local ry = rival.y or 6
  local px, py = world.playerX, world.playerY
  local dist = math.abs(px - rx) + math.abs(py - ry)
  if dist <= GAUNTLET_ENGAGE then return true end

  local grid = self:labWalkGrid()
  local path
  pcall(function()
    path = Pathfinder.find(grid, rx, ry, px, py, {
      adjacent = true,
      budget = 300,
    })
  end)

  local nx, ny, facing = rx, ry, nil
  if type(path) == "table" and #path > 0 then
    local step = path[1]
    nx, ny = step.x, step.y
    facing = step.dir
  else
    -- Greedy step only onto walkable cells
    local dx, dy = px - rx, py - ry
    local cands = {}
    if math.abs(dx) >= math.abs(dy) then
      cands[#cands + 1] = { rx + (dx > 0 and 1 or -1), ry, dx > 0 and "right" or "left" }
      cands[#cands + 1] = { rx, ry + (dy > 0 and 1 or -1), dy > 0 and "down" or "up" }
    else
      cands[#cands + 1] = { rx, ry + (dy > 0 and 1 or -1), dy > 0 and "down" or "up" }
      cands[#cands + 1] = { rx + (dx > 0 and 1 or -1), ry, dx > 0 and "right" or "left" }
    end
    for _, c in ipairs(cands) do
      if Pathfinder.walkable(grid, c[1], c[2]) then
        nx, ny, facing = c[1], c[2], c[3]
        break
      end
    end
  end

  if nx == rx and ny == ry then
    local adx, ady = px - rx, py - ry
    if math.abs(adx) >= math.abs(ady) then
      nx = rx + (px > rx and 1 or -1)
      facing = px > rx and "right" or "left"
    else
      ny = ry + (py > ry and 1 or -1)
      facing = py > ry and "down" or "up"
    end
  end

  rival.map = gauntletLabId()
  pcall(function() self:moveRivalNpc(rival, nx, ny, facing) end)
  if not self.spawned[rival.id] then
    pcall(function() self:spawnFor(gauntletLabId()) end)
  end
  return (math.abs(px - nx) + math.abs(py - ny)) <= GAUNTLET_ENGAGE
end

function M:gauntletPlayerInRange(rival, world)
  if not (rival and world and world.playerX) then return false end
  local rx, ry = rival.x or 2, rival.y or 2
  local dist = math.abs(world.playerX - rx) + math.abs(world.playerY - ry)
  return dist <= GAUNTLET_DETECT
end

-- Queue the challenge dialogue + trainer battle for the current rival.
function M:getOverworld()
  local game = self.game
  if not game then return nil end
  if game.overworld and game.overworld.isOverworld then
    return game.overworld
  end
  local stack = game.stack and game.stack.states
  if type(stack) == "table" then
    for i = #stack, 1, -1 do
      if stack[i].isOverworld then return stack[i] end
    end
  end
  return nil
end

-- True when Oak/text/cutscenes are done and a new script may run.
function M:overworldIdle()
  local ow = self:getOverworld()
  if not ow then return false end
  if ow.transitioning then return false end
  if ow.runner and ow.runner.isRunning and ow.runner:isRunning() then
    return false
  end
  if ow.scriptMoves and #ow.scriptMoves > 0 then return false end
  -- A text box stacked over the world also means "not yet"
  local game = self.game
  local stack = game and game.stack
  if stack and stack.top and stack:top() ~= ow then
    return false
  end
  return true
end

-- Some iOS stack implementations keep a closing ListMenu as stack:top() for
-- several frames. This weaker check is safe for deferred UI handoffs: scripts
-- and transitions must be idle, but stale stack identity cannot brick input.
function M:overworldRunnerIdle()
  local ow = self:getOverworld()
  if not ow or ow.transitioning then return false end
  if ow.runner and ow.runner.isRunning and ow.runner:isRunning() then return false end
  if ow.scriptMoves and #ow.scriptMoves > 0 then return false end
  return true
end

-- Queue the challenge. Prefer OverworldState:queueScript (FIFO drain when
-- idle) -- WorldAPI:queueScript refuses while Oak is still talking.
function M:gauntletStartChallenge(rival)
  if not rival then return false end
  if self._gauntletQueued then return true end
  local party = self.game and self.game.save and self.game.save.party
  if type(party) ~= "table" or #party == 0 then return false end

  local ow = self:getOverworld()
  if not ow then
    Util.lastError = "auto-challenge: no overworld"
    return false
  end
  if not (runningOnIOS() and type(ow.queueScript) == "function")
      and not (ow.runner and type(ow.runner.run) == "function") then
    Util.lastError = "auto-challenge: no script runner"
    return false
  end
  -- Never queue a second intro fight while Oak/another script is still busy.
  -- The old implementation relied on queueScript + start_battle.  On some
  -- builds queueScript accepts the rows but the trainer verb is never drained,
  -- leaving the first AI rival frozen after saying "Let's battle!".  The
  -- gauntlet now owns the battle launch directly and only uses the script
  -- runner for the dialogue box.
  if not self:overworldIdle() then return false end

  self.pending = rival
  pcall(function() rival:setState("CHALLENGING_PLAYER", "gauntlet") end)
  if self.gauntlet then
    self.gauntlet.activeBattleRival = rival.id
    self.gauntlet.activeBattleIndex = self.gauntlet.index
  end

  local line
  pcall(function()
    if self.dialogue and self.dialogue.lines and self.dialogue.lines.gauntletChallenge then
      line = self:gauntletLine(rival, self.dialogue.lines.gauntletChallenge)
    end
  end)
  if not line and self.dialogue and self.dialogue.challenge then
    line = self.dialogue:challenge(rival)
  end
  line = line or (rival.name .. ": Let's battle!")

  -- iOS is stricter about constructing and pushing a BattleState from mod
  -- code. Use the same queued trainer script as ordinary map encounters so
  -- the engine owns text dismissal, touch focus and battle-state timing.
  if runningOnIOS() and type(ow.queueScript) == "function" then
    self._gauntletQueued = true
    if self.gauntlet then
      self.gauntlet.dialogueIndex = self.gauntlet.index
      self.gauntlet.phase = "battling"
      self.gauntlet.challenging = true
    end
    local queued, accepted = pcall(function()
      return ow:queueScript({
        { "show_text", line },
        { "start_battle", "trainer", rival.def.trainerClass, 1 },
      })
    end)
    if queued and accepted ~= false then return true end
    self._gauntletQueued = false
    if self.gauntlet then
      self.gauntlet.dialogueIndex = nil
      self.gauntlet.phase = "challenge"
      self.gauntlet.challenging = false
    end
    Util.lastError = "iOS gauntlet queue: " .. tostring(accepted)
    return false -- never fall through to the unsupported direct iOS push
  end

  local function directTrainerBattle()
    local ok, result = pcall(function()
      local Game = self.game
      if not Game then
        local okGame, G = pcall(require, "src.core.Game")
        if not okGame then error(G) end
        Game = G
      end
      local controller = Game.overworld or ow
      if not (controller and type(controller.pushBattle) == "function") then
        error("overworld cannot push battles")
      end
      local BattleState = require("src.battle.BattleState")
      local classId = rival.def and rival.def.trainerClass
      if not classId then error("rival has no trainer class") end

      -- trainer.party is hooked below, so BattleState.newTrainer only needs
      -- the registered class and member index.  The hook swaps in the rival's
      -- live party immediately before the battle is presented.
      local battle = BattleState.newTrainer(Game, classId, 1)
      if not battle or battle.dead then error("trainer battle was refused") end
      if not battle.onFinish then
        battle.onFinish = function(resultValue)
          if controller.afterBattle then
            controller:afterBattle(resultValue, battle)
          end
        end
      end
      controller:pushBattle(battle)
      return true
    end)
    if not ok or result ~= true then
      Util.lastError = "gauntlet battle launch: " .. tostring(result)
      -- Keep the one-shot dialogue token and retry only the launch once the
      -- text state has completely left the stack. Replaying the introduction
      -- here was the source of the endless second-rival conversation loop.
      return false
    end
    return true
  end

  -- Mark this slot as queued BEFORE entering the runner.  Some engine builds
  -- can complete a one-line text script synchronously, so setting the flag
  -- afterwards could resurrect a stale "queued" state after the battle had
  -- already been launched.
  self._gauntletQueued = true
  if self.gauntlet then
    self.gauntlet.dialogueIndex = self.gauntlet.index
    self.gauntlet.phase = "dialogue"
    self.gauntlet.challenging = true
  end

  -- Run only the dialogue through the normal script runner.  Its completion
  -- callback launches the actual trainer battle, eliminating the unreliable
  -- script `start_battle` seam for this intro sequence.
  local ok, err = pcall(function()
    ow.runner:run({ { "show_text", line } }, {
      onDone = function()
        local g = self.gauntlet
        if not (g and g.active and g.dialogueIndex == g.index
            and g.activeBattleRival == rival.id) then return end
        self._gauntletBattleLauncher = directTrainerBattle
        g.phase = "launch_battle"
        g.phaseT = 0
      end,
    })
  end)
  if not ok then
    Util.lastError = "gauntlet dialogue: " .. tostring(err)
    self.pending = nil
    if self.gauntlet then
      self.gauntlet.activeBattleRival = nil
      self.gauntlet.activeBattleIndex = nil
      self.gauntlet.dialogueIndex = nil
      self.gauntlet.challenging = false
      self.gauntlet.phase = "challenge"
    end
    self._gauntletQueued = false
    return false
  end

  return true
end

function M:gauntletDirector(dt)
  if not self:gauntletActive() then return end
  local g = self.gauntlet
  g.phase = g.phase or "wait_party"
  g.phaseT = (g.phaseT or 0) + (dt or 0)

  local world = self:worldView()
  local lab = gauntletLabId()
  if not (world and lab and world.playerMap == lab) then return end

  local party = self.game and self.game.save and self.game.save.party
  local hasParty = type(party) == "table" and #party > 0

  if g.phase == "wait_party" or g.phase == "wait_blue" then
    -- Park on upper lab slots only (never the exit) until Blue is beaten.
    for i, r in ipairs(self.rivals) do
      local cell = LAB_SLOTS[((i - 1) % #LAB_SLOTS) + 1]
      if r.map == lab then
        local tx, ty = cell[1], cell[2]
        if r.x ~= tx or r.y ~= ty then
          pcall(function() self:moveRivalNpc(r, tx, ty, "down") end)
          r.x, r.y = tx, ty
        end
      end
    end
    if hasParty and self:blueLabBattled() then
      g.phase = "approach"
      g.phaseT = 0
    else
      g.phase = hasParty and "wait_blue" or "wait_party"
    end
    return
  end

  if g.phase == "between" then
    if g.phaseT >= 0.6 then
      g.phase = "approach"
      g.phaseT = 0
      g.approachAge = 0
      self._gauntletStarting = false
      self._gauntletQueued = false
    end
    return
  end

  if g.phase == "dialogue" then
    return -- wait for the one-shot introduction to close
  end

  if g.phase == "launch_battle" then
    -- ScriptRunner's onDone can run before the text state is actually popped.
    -- Launch on a later idle overworld update and retry the launch, never the
    -- dialogue, if a particular engine build needs another frame.
    if not self:overworldIdle() then return end
    local launch = self._gauntletBattleLauncher
    if type(launch) ~= "function" then
      Util.lastError = "gauntlet battle launch: missing deferred launcher"
      return
    end
    local ok = false
    pcall(function() ok = launch() end)
    if ok then
      self._gauntletBattleLauncher = nil
      g.phase = "battling"
      g.launchTries = 0
    else
      g.launchTries = (g.launchTries or 0) + 1
    end
    return
  end

  if g.phase == "battling" then
    return -- wait for battle.ended
  end

  if g.phase == "approach" then
    local rival = self:gauntletRival()
    if not rival then
      self:finishGauntlet()
      return
    end
    g.approachAge = (g.approachAge or 0) + (dt or 0)

    -- Always treat lab as in-range after Blue; walk toward player.
    if g.phaseT >= GAUNTLET_STEP_S then
      g.phaseT = 0
      local ready = false
      pcall(function()
        ready = self:gauntletStepTowardPlayer(rival, world)
      end)
      if ready then
        g.phase = "challenge"
        g.phaseT = 0
        g.approachAge = 0
      end
    end
    -- Failsafe: do not wait forever for pathing — start the fight
    if g.approachAge >= 2.5 then
      g.phase = "challenge"
      g.phaseT = 0
      g.approachAge = 0
    end
    return
  end

  if g.phase == "challenge" then
    local rival = self:gauntletRival()
    if not rival then
      self:finishGauntlet()
      return
    end
    if not hasParty then
      g.phase = "wait_party"
      return
    end

    -- Wait out Oak's post-Blue speech / any text box, then queue the fight
    if self._gauntletQueued then return end

    if g.phaseT >= 0.35 then
      g.phaseT = 0
      -- Prefer queuing while busy (FIFO); only force-run when idle
      local ok = false
      pcall(function() ok = self:gauntletStartChallenge(rival) end)
      if ok then
        g.challenging = true
        -- gauntletStartChallenge sets dialogue; its completion callback moves
        -- to launch_battle, and only a successful push moves to battling.
        g.challengeTries = 0
      else
        g.challengeTries = (g.challengeTries or 0) + 1
        -- Keep retrying while scripts run; only skip after long idle failure
        if g.challengeTries >= 40 and runningOnIOS() then
          -- Never silently count a failed iOS launch as a defeated rival.
          -- Keep the slot honest and leave the explicit SKIP GAUNTLET recovery
          -- available in the Rivals screen.
          g.challengeTries = 0
          Util.lastError = Util.lastError or "iOS gauntlet battle is waiting to start"
        elseif g.challengeTries >= 40 and self:overworldIdle() then
          g.index = g.index + 1
          g.challengeTries = 0
          g.challenging = false
          self._gauntletQueued = false
          if g.index > #g.order then
            self:finishGauntlet()
          else
            g.phase = "approach"
            g.approachAge = 0
          end
        end
      end
    end
    return
  end
end

------------------------------------------------------------------------
-- Persistence
------------------------------------------------------------------------
-- Everything lives under this mod's own namespaced bucket, which the engine
-- routes into save.modData.  Removing the mod leaves an unread bucket behind
-- and nothing else: no vanilla flag, badge, item or party slot is touched by
-- any code in this mod, which is what makes it removable.

function M:save()
  if not self.ready then return end
  local out = { version = SAVE_VERSION, tick = self.sim and self.sim.tick or 0,
                rivals = {} }
  for _, rival in ipairs(self.rivals) do
    out.rivals[rival.id] = rival:serialize()
  end
  if self.gauntlet and not self.gauntletFinished then
    out.gauntlet = Util.copy(self.gauntlet)
  end
  out.gauntletFinished = self.gauntletFinished == true
  out.eliteChampionId = self.eliteChampionId
  out.playerChampion = self.playerChampion == true
  out.companionId = self.companionId
  out.worldStartPending = self.worldStartPending == true
  out.rivalCount = #self.rivals
  out.news = Util.copy(self.news or {})
  -- 1.36.0: the "recently seen" log is world state, not rival state -- it is
  -- what the PLAYER noticed, so it lives here rather than on any one rival.
  out.presence = Presence.serialize(self.presence)
  -- 2.1.0 §32: the life-path seed. Written once and never recomputed, so a
  -- rival's destiny is the same on every load of this save.
  out.pathSeed = self.pathSeed
  out.seedValue = self.seedValue
  -- 3.0.0: the player's contacts. World state, not rival state -- a phone book
  -- belongs to whoever owns the phone.
  out.comms = Comms.serialize(self.comms)
  out.radioStation = self.radioStation
  out.radioEnabled = self.radioEnabled == true
  out.customMusicFolder = self.customMusicFolder
  out.customMusicTrack = self.customMusicTrack
  out.challengeModes = Util.copy(self.challengeModes or {})
  out.tournaments = self.tournaments and self.tournaments:serialize() or nil
  mod.save:set("state", out)
  -- Durable one-bit backup so a partial state blob cannot re-open the intro
  pcall(function()
    mod.save:set("gauntletFinished", self.gauntletFinished == true)
  end)
end


function M:syncRivalComms()
  self.comms = self.comms or Comms.new(nil)
  for _, rival in ipairs(self.rivals or {}) do
    if rival.phoneContact then
      local id = "PHONE_AIR_" .. string.upper(tostring(rival.id))
      local record = Comms.offer(self.comms, id, {
        name = rival.name,
        kind = "RIVAL",
        trainerId = rival.def and rival.def.trainerClass,
      }, self.seedValue or self.pathSeed or 0)
      if record then
        record.name = rival.name
        record.kind = "RIVAL"
        record.trainerId = rival.def and rival.def.trainerClass
        record.rivalId = rival.id
        record.number = tostring(rival.phoneNumber)
        record.offered = true
        record.accepted = true
      end
    end
  end
end

function M:load()
  if not self.ready then return end
  local saved = mod.save:get("state")
  if type(saved) == "table" and tonumber(saved.rivalCount) then
    self:setRivalCount(saved.rivalCount)
  end
  local rivals = type(saved) == "table" and saved.rivals or nil
  if self.sim and type(saved) == "table" then
    self.sim.tick = tonumber(saved.tick) or 0
  end
  -- Absent in a pre-1.36 save, which yields an empty log: the player has not
  -- been told about sightings that happened before the system existed.
  self.presence = Presence.new(type(saved) == "table" and saved.presence or nil)
  self.pathSeed = type(saved) == "table" and tonumber(saved.pathSeed) or nil
  -- Absent in a pre-3.0 save, which yields an empty phone book: no contact is
  -- invented for a trainer the player beat before the network existed.
  self.comms = Comms.new(type(saved) == "table" and saved.comms or nil)
  self:syncRivalComms()
  self.radioStation = type(saved) == "table" and saved.radioStation or "POKEMON_MUSIC"
  self.radioEnabled = type(saved) == "table" and saved.radioEnabled == true or false
  self.customMusicFolder = type(saved) == "table" and saved.customMusicFolder or "custom_music"
  self.customMusicTrack = type(saved) == "table" and saved.customMusicTrack or nil
  self.customMusicSource = nil
  -- Custom audio is never auto-opened from an arbitrary host path. The user's selected folder is inside this mod so the sandbox remains authoritative.
  if self.radioStation == "CUSTOM_MUSIC" and not self.customMusicTrack then self.radioEnabled = false end
  self.challengeModes = type(saved) == "table" and type(saved.challengeModes) == "table"
    and Util.copy(saved.challengeModes) or {}
  if not self.tournaments then self.tournaments = Tournaments.new(self) end
  self.tournaments:restore(type(saved) == "table" and saved.tournaments or nil)
  self.seedValue = type(saved) == "table" and tonumber(saved.seedValue) or nil
  -- A pre-2.6 save has a pathSeed but no world seed. Adopt the one it has
  -- rather than minting a new one: its rivals were dealt their starters under
  -- the old scheme and its destiny was decided under that number.
  if not self.seedValue and self.pathSeed then self.seedValue = self.pathSeed end
  -- Numbers and contact state come back with the rivals themselves; the Gen 2
  -- registry does not survive a boot, so contacts are re-registered rather
  -- than regenerated -- regenerating would hand the player a new number for a
  -- contact they already have.
  if self.phone then
    Util.guard("phone", function()
      self.phone:bootstrapAll()
      self.phone:registerContacts()
    end)
  end
  self.eliteChampionId = type(saved) == "table" and saved.eliteChampionId or nil
  self.playerChampion = type(saved) == "table" and saved.playerChampion == true
  self.companionId = type(saved) == "table" and saved.companionId or nil
  if self.companionId and not self.byId[self.companionId] then
    self.companionId = nil
  end
  self.worldStartPending = type(saved) == "table" and saved.worldStartPending == true
  self.news = type(saved) == "table" and type(saved.news) == "table"
    and Util.copy(saved.news) or {}
  self.tickerQueue = {}
  self.ticker = { text = nil, age = 0, duration = 8, offset = 0 }
  self.pendingRivalMenu, self.pendingRivalAction = nil, nil
  self.rivalInteractionOpen = false
  for _, rival in ipairs(self.rivals) do
    local record = rivals and rivals[rival.id]
    if not (record and rival:restore(record)) then
      -- only seed an EMPTY party: a rival already holding its starter must
      -- not gain another when boot and New Game both walk this loop
      if #rival.party == 0 then self:seed(rival) end
    end
    -- Migrate saves made before canonical area gates existed. A rival already
    -- parked beyond its private badge/HM progress cannot legally route back
    -- because all adjoining maps may be gated too, so recover it to its first
    -- accessible home. This changes location only; badges, party, PC and goals
    -- remain private and intact.
    if rival.map and rival.canEnterMap and not rival:canEnterMap(rival.map) then
      local recovery
      for _, id in ipairs(homeMapsFor(rival.def)) do
        if self.graph:has(id) and rival:canEnterMap(id) then recovery = id break end
      end
      rival.map = recovery or rival.map
      rival.x, rival.y, rival.spawnedAt = nil, nil, nil
      rival.destination, rival.route, rival.routeIndex = nil, nil, 1
      rival.path, rival.hopClock = nil, nil
      rival:setState("IDLE", "returned behind progression gate")
    end
    -- Old saves and removed map packs can leave navigation pointing at maps
    -- that no longer exist. Preserve all progression, but return the rival to
    -- a valid home and discard only the impossible route/destination.
    if not (rival.map and self.graph:has(rival.map)) then
      local home
      for _, id in ipairs(homeMapsFor(rival.def)) do
        if self.graph:has(id) then home = id break end
      end
      rival.map = home or next(self.graph.nodes)
      rival.x, rival.y, rival.spawnedAt = nil, nil, nil
      rival.route, rival.routeIndex = nil, 1
      rival.destination = nil
      rival:setState("IDLE", "recovered from missing map")
    elseif rival.destination and not self.graph:has(rival.destination) then
      rival.destination, rival.route, rival.routeIndex = nil, nil, 1
      rival:setState("IDLE", "destination no longer exists")
    else
      local validRoute = type(rival.route) == "table"
      if validRoute then
        for _, id in ipairs(rival.route) do
          if not self.graph:has(id) then validRoute = false break end
        end
      end
      if not validRoute then
        rival.route, rival.routeIndex = nil, 1
        if rival.destination then
          pcall(function() rival:setDestination(rival.destination) end)
        end
      end
    end
  end
  self:seedAffectionGraph()
  -- the gauntlet restores its own bookkeeping; a bucket without one (an
  -- older save, or a playthrough past the intro) stays inactive
  -- Finished flag: explicit, durable, never guessed away on load.
  -- Backup key on mod.save in case the state blob was partial.
  local finished = false
  if type(saved) == "table" and saved.gauntletFinished == true then
    finished = true
  end
  pcall(function()
    if mod.save:get("gauntletFinished") == true
        or mod.save:get("gauntletMode") == "skip" then finished = true end
  end)
  -- Infer finished from progress if older saves omitted the flag
  if not finished then
    for _, rival in ipairs(self.rivals) do
      if rival:badgeCount() > 0 then finished = true break end
      if rival.map and rival.map ~= gauntletLabId()
         and rival.map ~= "PALLET_TOWN" and rival.map ~= "NEW_BARK_TOWN"
         and #rival.party > 0 and (rival.ticks or 0) > 20 then
        finished = true
        break
      end
    end
  end
  self.gauntletFinished = finished

  local g = type(saved) == "table" and saved.gauntlet or nil
  local order = {}
  if type(g) == "table" and type(g.order) == "table" then
    for _, id in ipairs(g.order) do
      if self.byId[id] then order[#order + 1] = id end
    end
  end
  local lab = resolveGauntletLab(self.graph)

  if finished then
    -- Never re-arm the intro gauntlet after it is done
    self.gauntlet = nil
  elseif type(g) == "table" and g.active and #order > 0 and lab then
    local restoredPhase = g.phase or "wait_blue"
    -- Dialogue callbacks and battle launcher closures are deliberately not
    -- serialized. A save made during either transient phase must resume at the
    -- safe one-shot challenge boundary instead of waiting for a callback that
    -- no longer exists.
    if restoredPhase == "dialogue" or restoredPhase == "launch_battle"
        or restoredPhase == "battling" then
      restoredPhase = "challenge"
    end
    self.gauntlet = {
      active = true,
      index = math.max(1, tonumber(g.index) or 1),
      order = order,
      lab = lab,
      phase = restoredPhase,
      phaseT = 0,
      challenging = false,
      lastResolvedIndex = tonumber(g.lastResolvedIndex),
    }
    for _, rival in ipairs(self.rivals) do
      if rival.map ~= lab then
        rival.map = lab
        rival.x, rival.y = nil, nil
        pcall(function() rival:setDestination(nil) end)
        if #rival.party == 0 then
          local species = Rival.firstAvailableStarter(rival.def, self.versionKey,
                                                      self.data and self.data.pokemon,
                                                      nil, self:starterOpts())
          if species then pcall(function() rival:addPokemon(species, 5) end) end
        end
        pcall(function() rival:setState("IDLE", "in the lab") end)
      end
    end
  else
    self.gauntlet = nil
  end
  self:syncGen2Parties()
end

-- GEN 2: the class records are the live-party seam.  Trainers.party builds the
-- battle mons out of the class member's `party` rows at battle start, so the
-- rows are written through every time the rival's team can have changed and
-- the party the player fights is always this rival's actual team.  Gen 1's
-- trainer.party hook does the same job on the other side of the build.
function M:gen2ClassId(rival)
  return GEN2_CLASS[rival and rival.id]
end

function M:syncGen2Party(rival)
  if not (rival and self.generation == 2) then return end
  local classes = self.data and self.data.gen2Trainers and self.data.gen2Trainers.classes
  -- the rival's own class when it registered one, or the story class it rides
  local class = classes and (classes[rival.def.trainerClass]
    or (rival.def.gen2Shadow and classes[rival.def.gen2Shadow]))
  local members = class and class.trainers
  if type(members) ~= "table" then return end
  local rows = {}
  for _, mon in ipairs(rival.party) do
    rows[#rows + 1] = { species = mon.species, level = mon.level,
      dvs = mon.dvs and Util.copy(mon.dvs) or nil,
      shiny = mon.shiny == true, ace = mon.ace == true }
  end
  if #rows == 0 then return end
  for _, row in ipairs(members) do
    if type(row) == "table" then row.party = Util.copy(rows) end
  end
end

function M:syncGen2Parties()
  for _, rival in ipairs(self.rivals) do
    self:syncGen2Party(rival)
  end
end

-- Version handling for future formats.  A bucket from a newer version than we
-- understand is left alone and the rivals re-seed, which loses their progress
-- but never corrupts the save; a bucket from an older one is migrated here.
mod.migrations:add("0.0.0", function(save)
  local bucket = save and save.modData and save.modData.ai_rivals
  if type(bucket) ~= "table" then return end
  local state = bucket.state
  if type(state) == "table" and state.version == nil then
    state.version = SAVE_VERSION
  end
end)

------------------------------------------------------------------------
-- Player progression
------------------------------------------------------------------------
-- AI rivals are allowed to keep pace with the player's gym journey, but they
-- cannot race several badges ahead while the player is still in Pewter. The
-- engine save exposes the player's badge case as save.badges; the fallback
-- shapes below keep this mod tolerant of compatible builds that wrap it.
function M:playerBadgeCount()
  local save = self.game and self.game.save
  if type(save) ~= "table" then return 0 end

  local candidates = {
    save.badges,
    save.inventory and save.inventory.badges,
    save.trainer and save.trainer.badges,
  }
  for _, badges in ipairs(candidates) do
    if type(badges) == "table" then
      local n = 0
      local order = self.gyms and self.gyms.order or {}
      for _, id in ipairs(order) do
        if badges[id] == true or badges[id] == 1 then n = n + 1 end
      end
      if n > 0 then return n end
      -- Some builds expose an ordered boolean array instead of badge ids.
      for i = 1, #order do
        if badges[i] == true or badges[i] == 1 then n = n + 1 end
      end
      if n > 0 then return n end
    elseif type(badges) == "number" then
      local n, value = 0, badges
      for _ = 1, #(self.gyms and self.gyms.order or {}) do
        if value % 2 == 1 then n = n + 1 end
        value = math.floor(value / 2)
      end
      return n
    end
  end
  return 0
end

-- The single gate for the whole relationship system.  Read into the world
-- view once per tick rather than probed at each call site, so turning bonds
-- off costs nothing and cannot leave one subsystem recording while another
-- has stopped.
function M:relationshipsEnabled()
  return mod.options:get("relationships") ~= false
end

-- The world's life-path seed (§3, §32).
--
-- Created ONCE, on first use, and saved. It is derived from data that already
-- differs between saves rather than from a clock, so two saves made in the
-- same second still diverge, and a given save always answers identically --
-- which is what makes eligibility unrerollable rather than merely hidden.
-- THE WORLD SEED (2.6.0).
--
-- One number, created ONCE per save and persisted, from which every
-- per-playthrough choice is derived: which rival is dealt which starter, and
-- which rival (if any) has an alternative destiny.
--
-- It replaces a derivation that had no entropy at all. The previous seed was
-- built from the generation, the rival ids and their starters -- all of them
-- fixed data -- so EVERY save produced the identical number, and therefore the
-- identical life-path eligibility. §3's 85/12/3 distribution was correct in
-- the model and unreachable in practice, because the roll never varied.
--
-- Creation may be random; only STABILITY is required (§32), and persistence is
-- what provides it. Entropy is gathered from several weak sources because no
-- single one is guaranteed present in every host: a sandbox may have no
-- `os`, and `math.random` may be unseeded.
function M:worldSeed()
  if self.seedValue then return self.seedValue end
  local parts = { tostring(self.generation or "?") }
  if type(os) == "table" then
    if type(os.time) == "function" then parts[#parts + 1] = tostring(os.time()) end
    if type(os.clock) == "function" then parts[#parts + 1] = tostring(os.clock()) end
  end
  if type(math.random) == "function" then
    parts[#parts + 1] = tostring(math.random(1, 2 ^ 30))
  end
  -- a fresh table's address differs per allocation on every host this runs on
  parts[#parts + 1] = tostring({})
  for _, rival in ipairs(self.rivals or {}) do
    parts[#parts + 1] = tostring(rival.id)
  end
  local text = table.concat(parts, ":")
  local seed = 0
  for i = 1, #text do seed = (seed * 33 + text:byte(i)) % 4294967296 end
  if seed == 0 then seed = 1 end
  self.seedValue = seed
  return seed
end

-- Existing saves keep the seed they were already playing under, so upgrading
-- never reassigns a destiny a player has already been living with.
function M:lifePathSeed()
  if self.pathSeed then return self.pathSeed end
  self.pathSeed = self:worldSeed()
  return self.pathSeed
end

-- The starter deal reads the same world seed, and the roster's pools.
function M:starterOpts(versionKey, pokemon, allows)
  return {
    seed = self:worldSeed(),
    roster = ROSTER,
    pokemon = pokemon,
    allows = allows,
  }
end

function M:lifePathsEnabled()
  return mod.options:get("life_paths") ~= false
end

function M:lifePathEligible(rival)
  if not self:lifePathsEnabled() then return false end
  local ids = {}
  for _, other in ipairs(self.rivals or {}) do ids[#ids + 1] = other.id end
  return LifePath.isEligible(self:lifePathSeed(), rival.id, ids)
end

-- The one door for a divergence. Every guard the brief asks for lives here so
-- no caller can skip one: the option, eligibility from the seed, the derived
-- pressure, and the model's own lock.
function M:considerLifePath(rival)
  if not rival or not rival.ensureLifePath then return false end
  local record = rival:ensureLifePath()
  if record.locked then return false end
  if not self:lifePathEligible(rival) then return false end
  local pressure = rival:lifePathPressure()
  if LifePath.stage(pressure, false) ~= "TRANSITIONING" then return false end
  local candidates = rival:lifePathCandidates(3)
  if #candidates == 0 then return false end
  -- WHICH of the plausible paths is decided by the seed, not by a live roll:
  -- §33 forbids a decision that can be rerolled by reloading. The candidate
  -- list comes from the rival's history, so the seed only breaks the tie
  -- between lives it has actually earned.
  local roll = LifePath.roll(self:lifePathSeed(), "choice:" .. rival.id)
  local total = 0
  for _, entry in ipairs(candidates) do total = total + entry.score end
  local pick, cursor = candidates[1].path, roll * total
  for _, entry in ipairs(candidates) do
    cursor = cursor - entry.score
    if cursor <= 0 then pick = entry.path break end
  end
  if not LifePath.commit(record, pick, self.sim and self.sim.tick or 0,
                         "pressure") then
    return false
  end
  self:addNews(rival, { kind = "life_path", path = pick })
  if rival.rememberEvent then
    rival:rememberEvent({ tick = self.sim and self.sim.tick or 0,
                          type = "LIFE_PATH", target = pick })
  end
  return true, pick
end

-- §19/§28/§29: the arcs that continue AFTER a divergence.
--
-- Checked on the same slow cadence as the divergence itself, and guarded the
-- same way: the edge must exist, the tenure must have been served, and the
-- doubt must be real. Nothing here can be reached by reloading.
function M:considerTransition(rival)
  if not rival or not rival.ensureLifePath then return false end
  if not self:lifePathsEnabled() then return false end
  local record = rival:ensureLifePath()
  local tick = self.sim and self.sim.tick or 0
  if not LifePath.mayTransition(record, tick) then return false end
  local facts = rival:lifePathFacts()
  facts.careerLevel = rival.careerLevel and rival:careerLevel() or 1
  facts.warmToPlayer = rival:relationshipTo("player") == "RESPECT"
    or rival:relationshipTo("player") == "FRIENDLY"
    or rival:relationshipTo("player") == "ALLIED"
  facts.careerFailures = (rival:ensureCareer() or {}).failures or 0
  if LifePath.doubt(record.path, facts) < LifePath.TRANSITION_PRESSURE then
    return false
  end
  local targets = LifePath.transitionTargets(record.path)
  if #targets == 0 then return false end
  -- Which life it lands in comes from the SEED, as the original choice did:
  -- §19 says redemption is not guaranteed and §33 says nothing may be
  -- rerolled, so the destination must be fixed for this save.
  local roll = LifePath.roll(self:lifePathSeed(), "transition:" .. rival.id)
  local from = record.path
  local pick = targets[math.min(#targets, math.floor(roll * #targets) + 1)]
  local to = LifePath.transition(record, pick, tick)
  if not to then return false end
  rival.career = Career.newProgress(to)
  rival.careerHomeMap, rival.careerHomeFor = nil, nil
  self:applyPathRelationships(rival, from, to)
  self:addNews(rival, { kind = "life_transition", from = from, to = to })
  if rival.rememberEvent then
    rival:rememberEvent({ tick = tick, type = "LIFE_PATH", target = to })
  end
  return true, to
end

-- §20: a life-path change moves how everyone feels about this rival -- the
-- other rivals AND the player. Routed through the 1.33 causes so the change is
-- an ordinary, explicable relationship event rather than a special case.
function M:applyPathRelationships(rival, from, to)
  local cause
  if to == "TEAM_ROCKET" then cause = "TURNED_ROCKET"
  elseif from == "TEAM_ROCKET" then cause = "LEFT_ROCKET"
  elseif to == LifePath.GYM_CHALLENGE then cause = "CAME_BACK"
  else cause = "CHANGED_PATH" end
  local tick = self.sim and self.sim.tick or 0
  for _, other in ipairs(self.rivals) do
    if other.id ~= rival.id then
      self:recordBond(other, rival.id, cause, { tick = tick })
    end
  end
  -- and the rival's own view of the player, which is the relationship the
  -- player will actually feel
  self:recordBond(rival, "player", cause, { tick = tick })
end

function M:sightingsEnabled()
  return mod.options:get("sightings") ~= false
end

-- 1.36.0 §13: what the player could plausibly have noticed, once per world
-- tick. This is an OBSERVER -- it reads rival state and writes only the
-- presence log -- so it can never change where a rival goes or what it does.
--
-- Adjacency is asked of the map graph rather than assumed, because "the next
-- route over" is a different set of maps in Kanto, in Johto, and in whatever
-- a total conversion ships.
function M:observePresence(playerMap, world)
  if not self:sightingsEnabled() then return nil end
  if not playerMap then return nil end
  self.presence = self.presence or Presence.new()
  local tick = self.sim and self.sim.tick or 0
  local adjacent = {}
  if self.graph and self.graph.neighbours then
    -- MapGraph:neighbours returns EDGE records, not map ids. Keying the set
    -- on the edge table would make every adjacency lookup miss silently.
    for _, edge in ipairs(self.graph:neighbours(playerMap) or {}) do
      local id = type(edge) == "table" and edge.to or edge
      if type(id) == "string" then adjacent[id] = true end
    end
  end
  -- Ask in LEAST-RECENTLY-SEEN order, not roster order.
  --
  -- The global cooldown means at most one rival is noticed per tick, so a
  -- fixed iteration order hands every sighting to whoever comes first in the
  -- roster: with four rivals parked on the player's map, the fourth was never
  -- noticed at all. Sorting by when each was last seen makes the choice fair
  -- and still deterministic (ties break on the id, never on table order), and
  -- it reads correctly too -- you notice the one you have not seen in a while.
  local order = {}
  for _, rival in ipairs(self.rivals) do
    local sameMap = rival.map == playerMap
    if sameMap or adjacent[rival.map] then order[#order + 1] = rival end
  end
  table.sort(order, function(a, b)
    local ta = self.presence.byRival[a.id] or -1
    local tb = self.presence.byRival[b.id] or -1
    if ta ~= tb then return ta < tb end
    return tostring(a.id) < tostring(b.id)
  end)

  for _, rival in ipairs(order) do
    local sameMap = rival.map == playerMap
    do
      local sighting = Presence.observe(self.presence, {
        id = rival.id,
        name = rival.name,
        map = rival.map,
        mapLabel = Util.spaced(rival.map or ""),
        state = rival.state,
        objective = rival.objective,
        camping = (rival.campTicks or 0) > 0,
        hunting = rival.huntTarget ~= nil,
        huntTarget = rival.huntTarget,
        travelling = rival.destination ~= nil and rival.destination ~= rival.map,
        direction = rival.lastDirection,
        sameMap = sameMap,
        adjacent = adjacent[rival.map] == true,
        -- a rival you are already talking to or fighting is not "spotted"
        engaged = (self.companionId == rival.id)
          or self.worldChallenge == true
          or self:gauntletActive(),
      }, tick)
      if sighting then
        self:addNews(rival, { kind = "sighting", note = sighting.note })
        return sighting
      end
    end
  end
  return nil
end

-- The map the player is actually standing on, or nil. Same probe worldView
-- uses; factored out so the menu can ask without building a whole world view.
function M:playerMapId()
  local where
  pcall(function()
    if self.game and mod.world and mod.world.current then
      where = mod.world:current()
    end
  end)
  return where and where.mapId or nil
end

function M:worldView()
  local where
  pcall(function()
    if self.game and mod.world and mod.world.current then
      where = mod.world:current()
    end
  end)
  local party
  pcall(function()
    party = self.game and self.game.save and self.game.save.party
  end)
  return {
    playerMap = where and where.mapId or nil,
    playerX = where and where.x, playerY = where and where.y,
    playerParty = party,
    playerBadges = self:playerBadgeCount(),
    compat = self.compat,
    rivals = self.rivals,
    companionId = self.companionId,
    relationships = self:relationshipsEnabled(),
    -- 4.6.0: a title held by the PLAYER is not something the simulation may
    -- settle on its own. Simulation.tryTitleMatch reads this and stands down,
    -- leaving the challenge to the in-person path the player can actually
    -- fight (M:startRivalChallenge's titleChallenge arm).
    playerChampion = self.playerChampion == true,
    tick = self.sim and self.sim.tick or 0,
    log = self.log,
  }
end

------------------------------------------------------------------------
-- Materialization
------------------------------------------------------------------------
-- Near the player a rival is a real NPC with real collision.  Far away it is
-- a table row.  This is the whole reason the mod is usable on a phone: at
-- most a handful of objects exist at once no matter how big the roster gets.

function M:despawnAll()
  for id, npcId in pairs(self.spawned) do
    Util.guard("removeNpc", function() mod.world:removeNpc(npcId) end)
    self.spawned[id] = nil
  end
end

function M:activeMap()
  local ow
  pcall(function()
    if mod.world and mod.world.overworld then ow = mod.world:overworld() end
  end)
  ow = ow or (self.game and self.game.overworld)
  return ow, ow and ow.map
end

-- FOLLOWERS_EX pattern: drive the already-live NPC entity directly. This is
-- the ordinary NPC update path (targetX/targetY/moving/progress), not the
-- shared script queue, so it animates without locking player input.
function M:liveRivalEntity(rival)
  if not rival then return nil end
  local ow = self:activeMap()
  local spawnedId = self.spawned and self.spawned[rival.id]
  local wantedName = "AIR_" .. tostring(rival.id)
  for _, list in ipairs({ (ow and ow.npcs) or {}, (ow and ow.entities) or {} }) do
    for _, npc in ipairs(list) do
      local id = npc.id or npc.index
      local name = npc.name or (npc.def and npc.def.name)
      if npc == spawnedId or id == spawnedId
         or tostring(id) == tostring(spawnedId)
         or name == wantedName then
        return npc
      end
    end
  end
  return nil
end

-- Authoritative terrain collision from the live Map. Unlike a visual tile or
-- a guessed coordinate, this is the same walkable-cell test used for walls,
-- trees and building facades by the player controller.
function M:liveTerrainWalkable(mapId, x, y)
  local ow, map = self:activeMap()
  if not (map and map.id == mapId and x and y) then return false end
  if map.inBounds and not map:inBounds(x, y) then return false end
  if type(map.isWalkableCell) ~= "function" then return false end
  local ok, walkable = pcall(map.isWalkableCell, map, x, y)
  return ok and walkable == true
end

function M:liveCellOccupied(mapId, x, y, exceptId)
  local ow, map = self:activeMap()
  if not (ow and map and map.id == mapId) then return true end
  local p = ow.player
  if p and p.cellX == x and p.cellY == y then return true end
  for _, npc in ipairs(ow.npcs or {}) do
    if npc.id ~= exceptId and npc.cellX == x and npc.cellY == y then return true end
  end
  return false
end

function M:validRivalCell(rival, overview, x, y, allowTransit)
  if not self:liveTerrainWalkable(rival.map, x, y) then return false end
  if not allowTransit and self:isTransitCell(rival.map, overview, x, y) then return false end
  local npcId = self.spawned and self.spawned[rival.id]
  if self:liveCellOccupied(rival.map, x, y, npcId) then return false end
  return true
end

-- Remove a bad live object and let the normal placement code rebuild it on a
-- proven-free tile. This is deliberately recoverable: the rival's party,
-- progress, destination and goal are untouched.
function M:repairRivalPosition(rival, reason)
  if not rival then return false, "No rival selected." end
  local npcId = self.spawned[rival.id]
  if npcId then pcall(function() mod.world:removeNpc(npcId) end) end
  self.spawned[rival.id] = nil
  rival.x, rival.y, rival.spawnedAt = nil, nil, nil
  rival.walking, rival.localWalkGoal = false, nil
  rival.blockedWalkPulses = 0
  self.walkMapCache = nil
  if self.perf then self.perf.recoveries = (self.perf.recoveries or 0) + 1 end
  local current = self:worldView()
  if current and rival.map == current.playerMap then
    pcall(function() self:spawnFor(rival.map) end)
  end
  return true, rival.name .. " moved to a safe tile" ..
    (reason and (" (" .. reason .. ").") or ".")
end

-- Where on this map the rival should stand.  A rival arriving from elsewhere
-- has no coordinates yet, so it materializes on a walkable cell that is not
-- the player's and not immediately adjacent to them -- a rival that appeared
-- in your face would read as a teleport, which is exactly the failure mode
-- the brief calls out.
function M:isTransitCell(mapId, overview, x, y)
  if not (x and y) then return false end
  for _, marker in ipairs((overview and overview.markers) or {}) do
    if marker.kind == "warp" and marker.x == x and marker.y == y then return true end
  end
  local maps = self.data and (self.data.maps or self.data.gen2Maps)
  local def = maps and maps[mapId]
  for _, warp in ipairs((def and def.warps) or {}) do
    if warp.x == x and warp.y == y then return true end
  end
  local w = overview and (overview.width or (overview.rows and #overview.rows[1]))
  local h = overview and overview.rows and #overview.rows
  return w and h and (x <= 0 or y <= 0 or x >= w - 1 or y >= h - 1) or false
end

function M:placementFor(rival, overview, world)
  local grid = Pathfinder.grid(overview)
  if not grid then return nil end
  local px, py = world.playerX, world.playerY
  -- Pathfinder.grid returns w/h (not width/height)
  local w = grid.w or grid.width or 0
  local h = grid.h or grid.height or 0
  if w < 1 or h < 1 then return nil end
  -- OAKS_LAB is only 5x6; the normal "3–14 tiles away" rule would leave
  -- every cell rejected.  On small maps (or during the gauntlet) accept any
  -- walkable cell that is not under the player's feet.
  local small = (w * h) <= 80 or self:gauntletActive()
  local minD, maxD = small and 1 or 3, small and 99 or 14
  local function acceptable(x, y)
    if not Pathfinder.walkable(grid, x, y) then return false end
    if not self:liveTerrainWalkable(rival.map, x, y) then return false end
    if self:isTransitCell(rival.map, overview, x, y) then return false end
    if self:liveCellOccupied(rival.map, x, y, self.spawned[rival.id]) then return false end
    if px and py then
      local d = math.abs(x - px) + math.abs(y - py)
      if d < minD or d > maxD then return false end
    end
    return true
  end
  if rival.x and rival.y and acceptable(rival.x, rival.y) then
    return rival.x, rival.y
  end
  -- deterministic scan from the rival's own RNG so two rivals on one map do
  -- not land on the same cell and the choice replays on reload
  local startX, startY = rival.rng:int(0, math.max(0, w - 1)),
                         rival.rng:int(0, math.max(0, h - 1))
  for dy = 0, h - 1 do
    for dx = 0, w - 1 do
      local x, y = (startX + dx) % w, (startY + dy) % h
      if acceptable(x, y) and not self:cellTaken(x, y) then return x, y end
    end
  end
  -- last resort on tiny maps: any walkable free cell, even adjacent
  if small then
    for dy = 0, h - 1 do
      for dx = 0, w - 1 do
        local x, y = (startX + dx) % w, (startY + dy) % h
        if Pathfinder.walkable(grid, x, y)
           and self:liveTerrainWalkable(rival.map, x, y)
           and not self:liveCellOccupied(rival.map, x, y, self.spawned[rival.id])
           and not self:cellTaken(x, y)
           and not (px == x and py == y) then
          return x, y
        end
      end
    end
  end
  -- Large-map recovery: distance preferences are presentation, collision is
  -- safety. If no nearby cell qualifies, use any proven free interior cell.
  for y = 1, h - 2 do
    for x = 1, w - 2 do
      if Pathfinder.walkable(grid, x, y)
         and self:liveTerrainWalkable(rival.map, x, y)
         and not self:isTransitCell(rival.map, overview, x, y)
         and not self:liveCellOccupied(rival.map, x, y, self.spawned[rival.id])
         and not self:cellTaken(x, y) then return x, y end
    end
  end
  return nil
end

function M:cellTaken(x, y)
  for _, rival in ipairs(self.rivals) do
    if rival.spawnedAt and rival.spawnedAt[1] == x and rival.spawnedAt[2] == y then
      return true
    end
  end
  return false
end

-- Fixed cells inside OAKS_LAB (5x6 interior). Used when mapOverview is
-- missing or the walkability scan finds nothing -- common on first enter.
-- Upper lab area near Oak / side tables -- NOT the south exit row.
-- Exit is typically along the bottom; keep rivals clear of it so Blue's
-- script and the player can move freely until the gauntlet starts.
local LAB_SLOTS = {
  { 2, 2 }, { 3, 2 }, { 4, 2 }, { 2, 3 }, { 4, 3 }, { 3, 4 },
}

-- Sprite ids are resolved against the CURRENT merged runtime data.  AI Rivals
-- never owns or rewrites the art behind those ids, so any player/trainer/NPC
-- sprite replacement mod remains authoritative regardless of load order.
M.GAUNTLET_MAX = 4

local RIVAL_SPRITE_PREFER = {
  chris   = { "SPRITE_BLUE", "SPRITE_COOLTRAINER_M", "SPRITE_RED", "SPRITE_CHRIS" },
  dyanari = { "SPRITE_LASS", "SPRITE_COOLTRAINER_F", "SPRITE_BRUNETTE_GIRL", "SPRITE_GIRL", "SPRITE_KRIS" },
  matt    = { "SPRITE_SUPER_NERD", "SPRITE_BUG_CATCHER", "SPRITE_YOUNGSTER", "SPRITE_ROCKER" },
  larissa = { "SPRITE_COOLTRAINER_F", "SPRITE_BRUNETTE_GIRL", "SPRITE_LASS", "SPRITE_GIRL", "SPRITE_KRIS" },
}

function M:spriteTable()
  -- Keep the explicit two-generation expression here as well as in Sprites.lua:
  -- several diagnostics use this accessor directly, and replacement mods patch
  -- these merged tables in place.
  local data = (self.game and self.game.data) or self.data
  if type(data) ~= "table" then return nil end
  return data.sprites or data.gen2Sprites
end

function M:safeSprite(preferred)
  local sprites = self:spriteTable()
  if not sprites then return nil end
  if preferred and sprites[preferred] then return preferred end
  if self.sprites then
    local resolved = self.sprites:semanticWalker("male", self.data, preferred)
    if resolved then return resolved end
  end
  -- Deterministic final fallback for diagnostics/total conversions.
  local ids = {}
  for id, rec in pairs(sprites) do
    if type(rec) == "table" and (rec.image or rec.walker or rec.hgssNativeImage) then
      ids[#ids + 1] = id
    end
  end
  table.sort(ids)
  return ids[1]
end

function M:spriteForRival(rival)
  if not (self.sprites and rival) then return nil end
  -- Preserve one LOGICAL walker id for the rival. We deliberately do not
  -- preserve/copy its image or palette: sprite replacement mods remain free
  -- to replace the live art behind this id, while hair/appearance no longer
  -- flips between e.g. COOLTRAINER_F and BRUNETTE_GIRL across refreshes.
  if rival.appearanceSprite and self.sprites:exists(rival.appearanceSprite, self.data) then
    return rival.appearanceSprite
  end
  local prefer = rival.id and RIVAL_SPRITE_PREFER[rival.id] or nil
  local resolved = self.sprites:walkerFor(rival.def, self.data, prefer)
  if resolved then rival.appearanceSprite = resolved end
  return resolved
end

function M:entryPlacement(rival, mapId, overview)
  if not (rival and rival.arrivedFrom and overview) then return nil end
  local grid = Pathfinder.grid(overview)
  local maps = self.data and (self.data.maps or self.data.gen2Maps)
  local def = maps and maps[mapId]
  if not (grid and def) then return nil end
  for _, warp in ipairs(def.warps or {}) do
    if warp.destMap == rival.arrivedFrom then
      for radius = 1, 3 do
        local candidates = {
          { warp.x, warp.y + radius }, { warp.x, warp.y - radius },
          { warp.x + radius, warp.y }, { warp.x - radius, warp.y },
        }
        for _, c in ipairs(candidates) do
          if Pathfinder.walkable(grid, c[1], c[2])
             and self:liveTerrainWalkable(mapId, c[1], c[2])
             and not self:isTransitCell(mapId, overview, c[1], c[2])
             and not self:liveCellOccupied(mapId, c[1], c[2])
             and not self:cellTaken(c[1], c[2]) then return c[1], c[2] end
        end
      end
    end
  end
  local side
  for dir, conn in pairs(def.connections or {}) do
    local other = type(conn) == "table" and conn.map or conn
    if other == rival.arrivedFrom then side = tostring(dir):lower() break end
  end
  local candidates = {}
  if side == "north" or side == "up" then
    for x = 1, grid.w - 2 do candidates[#candidates + 1] = { x, 1 } end
  elseif side == "south" or side == "down" then
    for x = 1, grid.w - 2 do candidates[#candidates + 1] = { x, grid.h - 2 } end
  elseif side == "west" or side == "left" then
    for y = 1, grid.h - 2 do candidates[#candidates + 1] = { 1, y } end
  elseif side == "east" or side == "right" then
    for y = 1, grid.h - 2 do candidates[#candidates + 1] = { grid.w - 2, y } end
  end
  for _, c in ipairs(candidates) do
    if Pathfinder.walkable(grid, c[1], c[2])
       and self:liveTerrainWalkable(mapId, c[1], c[2])
       and not self:liveCellOccupied(mapId, c[1], c[2])
       and not self:cellTaken(c[1], c[2]) then
      return c[1], c[2]
    end
  end
  return nil
end

-- Facing at spawn. `range` (spawn-time, engine schema) and `rival.facing`
-- (this mod's own live-entity field, set only transiently by moveRivalNpc
-- during a gauntlet/companion step) use different cases for the same four
-- directions -- "DOWN" vs "down" -- because they come from two different
-- systems. This table bridges them so a rival mid-step keeps the direction
-- it was already facing instead of spawning turned to face something else.
local SPAWN_FACINGS = { "DOWN", "UP", "LEFT", "RIGHT" }
local FACING_TO_RANGE = { down = "DOWN", up = "UP", left = "LEFT", right = "RIGHT" }

function M:spawnFor(mapId)
  if not mapId then return 0 end
  local world = self:worldView()
  local slotIdx = 0
  local spawned = 0

  -- Prefer the live overworld controller; fall back to mod.world facade.
  local function overworld()
    local game = self.game
    if game then
      if game.overworld and game.overworld.isOverworld and game.overworld.map then
        return game.overworld
      end
      local stack = game.stack and game.stack.states
      if stack then
        for i = #stack, 1, -1 do
          if stack[i].isOverworld then return stack[i] end
        end
      end
    end
    return nil
  end

  local ow = overworld()
  local overview
  pcall(function()
    if mod.world and mod.world.mapOverview then overview = mod.world:mapOverview() end
  end)

  for rivalIndex, rival in ipairs(self.rivals) do
    if #rival.party == 0 then
      local species = nil
      pcall(function()
        species = Rival.firstAvailableStarter(rival.def, self.versionKey,
                                              self.data and self.data.pokemon,
                                              nil, self:starterOpts())
      end)
      if not species and self.data and type(self.data.pokemon) == "table" then
        for id, _ in pairs(self.data.pokemon) do species = id break end
      end
      if species then
        pcall(function() rival:addPokemon(species, 5) end)
      end
    end

    -- Spawn even with empty party during lab intro so NPCs are visible
    if rival.map == mapId and not self.spawned[rival.id] then
      slotIdx = slotIdx + 1
      local cell = LAB_SLOTS[((slotIdx - 1) % #LAB_SLOTS) + 1]
      -- Prefer live coords so walk-up steps are not snapped back to slots
      local x = rival.x or cell[1]
      local y = rival.y or cell[2]
      -- OAKS_LAB stays a literal here and just below ON PURPOSE: both
      -- branches encode the KANTO lab's 5x6 interior geometry (LAB_SLOTS and
      -- the synthetic grid). Elm's lab is a different room, so Gold falls
      -- through to the proven entry/safe-placement path rather than being put
      -- on cells measured for somewhere else.
      if not rival.x and world and world.playerX and mapId ~= "OAKS_LAB" then
        x = (world.playerX or 4) + (slotIdx % 3)
        y = (world.playerY or 4)
      end
      if mapId ~= "OAKS_LAB" then
        local safeX, safeY = self:entryPlacement(rival, mapId, overview)
        if not safeX then safeX, safeY = self:placementFor(rival, overview, world) end
        if not (safeX and safeY) then
          -- Fail closed: remaining abstract is better than materialising in
          -- an unproven wall/tree cell. A later update/map entry retries.
          rival.x, rival.y = nil, nil
          return spawned
        end
        x, y = safeX, safeY
      end

      local sprite = self:spriteForRival(rival)
      if not sprite then
        -- No sprite this boot carries. Fail closed, exactly as an unproven
        -- tile does above: the rival stays abstract and a later map entry
        -- retries, rather than a spawn failing on an unknown sprite id.
        Util.lastError = string.format("spawn %s %s: no usable sprite",
          tostring(rival.id), tostring(mapId))
        rival.x, rival.y = nil, nil
        return spawned
      end

      local objDef = {
        index = 90 + rivalIndex,
        name = "AIR_" .. tostring(rival.id),
        sprite = sprite,
        x = x,
        y = y,
        movement = "STAY",
        -- Always DOWN before this fix -- every materialised rival faced
        -- south until something else moved it. rival.facing carries over
        -- when the rival is mid-step (a real, explicit direction); with no
        -- such state, this is a fresh materialisation and gets a random one
        -- off the rival's own seeded rng, so it is stable for THIS rival on
        -- THIS boot rather than reshuffling every despawn/respawn cycle.
        range = FACING_TO_RANGE[rival.facing]
          or SPAWN_FACINGS[rival.rng and rival.rng:int(1, 4) or math.random(1, 4)],
        solid = false, passable = true, through = true,
        -- A real text binding is what makes A-button interaction authoritative
        -- in Gen 1. world.interacted remains a secondary compatibility path.
        -- On Gold the text id is inert (nothing in the Gen 2 interact ladder
        -- reads it), so the press is served by the talkTo router keyed on the
        -- `name` above instead.
        text = self.generation == 1 and TALK_TEXT or nil,
      }

      -- Preferred: WorldAPI.spawnNpc (stable, owned, gen1+gen2).
      -- Fallback: OverworldState.addRuntimeObject (engine_internals).
      local npcId, err
      if mod.world and type(mod.world.spawnNpc) == "function" then
        local ok, a, b = pcall(function()
          return mod.world:spawnNpc(mapId, objDef)
        end)
        if ok and a then
          npcId = a
        else
          err = tostring(b or a or "spawnNpc failed")
        end
      end
      if not npcId and ow and type(ow.addRuntimeObject) == "function" then
        local ok, a, b = pcall(function()
          return ow:addRuntimeObject(mapId, objDef, mod.id or "ai_rivals")
        end)
        if ok and a then npcId = a else err = tostring(a or b or err) end
      end
      if not npcId and not err then err = "no spawn path" end

      if npcId then
        self.spawned[rival.id] = npcId
        rival.spawnedAt = { x, y }
        rival.x, rival.y = x, y
        rival.arrivedFrom = nil
        spawned = spawned + 1
      else
        Util.lastError = string.format(
          "spawn %s %s sp=%s: %s",
          tostring(rival.id), tostring(mapId), tostring(sprite),
          tostring(err or "nil"))
      end
    end
  end
  return spawned
end

-- Resolve the tile a rival must physically reach before its next map hop.
function M:mapExitTarget(rival, overview)
  if rival.destination and rival.map ~= rival.destination and not rival.route
     and self.graph then
    rival.route = self.graph:route(rival.map, rival.destination)
  end
  local nextMap = rival:nextHop()
  if not nextMap then return nil end
  local edge = self.graph and self.graph:edgeBetween(rival.map, nextMap)
  if edge and edge.x ~= nil and edge.y ~= nil then
    -- NPC script movement must never enter a warp tile. Some engine builds
    -- route any actor standing on a warp through the global transition/fade
    -- controller, which flashes the player's whole screen. Walk to a free
    -- tile beside the door, face it, then perform the rival-only abstract hop.
    local grid = Pathfinder.grid(overview)
    local candidates = {
      { edge.x, edge.y + 1 }, { edge.x - 1, edge.y },
      { edge.x + 1, edge.y }, { edge.x, edge.y - 1 },
    }
    local best, bestD
    for _, cell in ipairs(candidates) do
      if grid and Pathfinder.walkable(grid, cell[1], cell[2])
         and self:validRivalCell(rival, overview, cell[1], cell[2], false) then
        local d = math.abs((rival.x or cell[1]) - cell[1])
          + math.abs((rival.y or cell[2]) - cell[2])
        if not bestD or d < bestD then best, bestD = cell, d end
      end
    end
    if best then return best[1], best[2], nextMap end
    return nil
  end
  local maps = self.data and (self.data.maps or self.data.gen2Maps)
  local def = maps and maps[rival.map]
  local direction
  for dir, conn in pairs((def and def.connections) or {}) do
    local id = type(conn) == "table" and conn.map or conn
    if id == nextMap then direction = tostring(dir):lower() break end
  end
  local grid = Pathfinder.grid(overview)
  if not (grid and direction) then return nil end
  local candidates = {}
  if direction == "north" or direction == "up" then
    for x = 1, grid.w - 2 do candidates[#candidates + 1] = { x, 1 } end
  elseif direction == "south" or direction == "down" then
    for x = 1, grid.w - 2 do candidates[#candidates + 1] = { x, grid.h - 2 } end
  elseif direction == "west" or direction == "left" then
    for y = 1, grid.h - 2 do candidates[#candidates + 1] = { 1, y } end
  elseif direction == "east" or direction == "right" then
    for y = 1, grid.h - 2 do candidates[#candidates + 1] = { grid.w - 2, y } end
  end
  local best, bestD
  for _, c in ipairs(candidates) do
    if Pathfinder.walkable(grid, c[1], c[2])
       and self:liveTerrainWalkable(rival.map, c[1], c[2]) then
      local d = math.abs((rival.x or c[1]) - c[1]) + math.abs((rival.y or c[2]) - c[2])
      if not bestD or d < bestD then best, bestD = c, d end
    end
  end
  if best then return best[1], best[2], nextMap end
  return nil
end

-- Seconds a player must stand still, pressed against a spawned rival, before
-- that rival is nudged aside. Long enough that ordinary talking/menu use
-- next to a rival never triggers it; short enough to read as "give way", not
-- "wait forever".
local PATH_BLOCK_STALL_S = 2.5

-- self.pathNudgeDone debounces this to once per stall episode: it is cleared
-- the moment the player's cell changes (playerIdleSeconds resets to 0 in
-- RuntimePolicy), so leaving and returning to the same spot can trigger it
-- again, but standing there after the first nudge does not repeat it.
function M:relievePathBlock(world)
  local playerMap = world and world.playerMap
  local px, py = world and world.playerX, world and world.playerY
  if not (playerMap and px and py) then self.pathNudgeDone = false return end
  local idle = tonumber(self.playerIdleSeconds) or 0
  if idle < 0.5 then self.pathNudgeDone = false end
  if idle < PATH_BLOCK_STALL_S or self.pathNudgeDone then return end

  local blocker
  for _, rival in ipairs(self.rivals) do
    if rival.map == playerMap and self.spawned[rival.id] and rival.x and rival.y then
      if math.abs(rival.x - px) + math.abs(rival.y - py) == 1 then
        blocker = rival
        break
      end
    end
  end
  if not blocker then return end

  -- Reuse the walk director's cached grid for this map rather than rebuilding
  -- it (see docs/performance.md F4) -- this runs while the player is
  -- standing still on the SAME map that cache already describes.
  local cache = self.walkMapCache
  local overview, grid
  if cache and cache.mapId == playerMap then
    overview, grid = cache.overview, cache.grid
  else
    pcall(function() overview = mod.world and mod.world:mapOverview() end)
    grid = Pathfinder.grid(overview)
  end
  if not grid then return end

  local candidates = {
    { blocker.x, blocker.y - 1 }, { blocker.x, blocker.y + 1 },
    { blocker.x - 1, blocker.y }, { blocker.x + 1, blocker.y },
  }
  for _, c in ipairs(candidates) do
    local cx, cy = c[1], c[2]
    if (cx ~= px or cy ~= py) and Pathfinder.walkable(grid, cx, cy)
       and self:validRivalCell(blocker, overview, cx, cy, false) then
      local facing = math.abs(px - cx) >= math.abs(py - cy)
        and (px > cx and "right" or "left")
        or (py > cy and "down" or "up")
      -- moveRivalNpc is the proven instant-reposition path (handle:setPosition
      -- / :teleport, with rival.x/y/spawnedAt kept in sync) -- the same one
      -- the gauntlet already uses to place a rival without an animated walk.
      if self:moveRivalNpc(blocker, cx, cy, facing) then
        self.pathNudgeDone = true
      end
      return
    end
  end
end

-- Animate every visible rival one legal tile at a time. Strategic travel has
-- priority; a rival working at its destination paces within a safe area.
-- Rivals stop beside doors/seams and change only their own abstract map state;
-- they never enter a live transition tile or invoke the player's fade.
function M:worldWalkDirector(dt, world)
  self.walkAccumulator = (self.walkAccumulator or 0) + (tonumber(dt) or 0)
  local emergency = self.perf and (self.perf.autoLowSeconds or 0) > 0
  local performance = emergency and "emergency"
    or (mod.options:get("performance") or "balanced")
  local interval = performance == "emergency" and 0.60
    or performance == "low" and 0.48
    or (performance == "full" and 0.24 or 0.32)
  if self.walkAccumulator < interval then return end
  self.walkAccumulator = self.walkAccumulator - interval
  -- NPC:update owns interpolation. Commit its finished cell back into the
  -- persistent rival, matching FOLLOWERS_EX's separation of entity and trail.
  for _, rival in ipairs(self.rivals) do
    if rival.walking then
      rival.walkAge = (tonumber(rival.walkAge) or 0) + interval
      local entity = self:liveRivalEntity(rival)
      if entity and not entity.moving then
        rival.x, rival.y = entity.cellX or rival.x, entity.cellY or rival.y
        rival.spawnedAt = { rival.x, rival.y }
        local target = rival.walkTarget
        rival.walking, rival.walkAge, rival.walkTarget = false, 0, nil
        if target and target.onDone and rival.x == target.x and rival.y == target.y then
          pcall(target.onDone)
        end
      elseif rival.walkAge > 1.25 then
        if entity then
          entity.targetX, entity.targetY = nil, nil
          entity.moving, entity.progress = false, 0
          rival.x, rival.y = entity.cellX or rival.x, entity.cellY or rival.y
        end
        rival.walking, rival.walkAge = false, 0
        rival.walkTarget = nil
      end
    elseif self.spawned[rival.id] then
      -- Idle glance: a materialised, stationary rival occasionally turns to
      -- face a new direction, purely cosmetic -- entity.facing only, never
      -- entity.targetX/Y/moving, so this cannot fight the travel logic
      -- above over who owns the entity's position. Same field moveRivalNpc
      -- already writes mid-step; this just writes it while standing still.
      rival.idleGlanceAge = (tonumber(rival.idleGlanceAge) or 0) + interval
      if rival.idleGlanceAge >= (rival.idleGlanceNext or 0) then
        local rng = rival.rng
        rival.idleGlanceNext = rng and rng:int(2, 6) or (2 + math.random() * 4)
        rival.idleGlanceAge = 0
        local dir = SPAWN_FACINGS[rng and rng:int(1, 4) or math.random(1, 4)]:lower()
        if dir ~= rival.facing then
          local entity = self:liveRivalEntity(rival)
          if entity and not entity.moving then
            entity.facing, rival.facing = dir, dir
          end
        end
      end
    end
  end
  local mapId = world and world.playerMap
  local playerInMotion = world and world.playerMoving
  local hasVisible = false
  for _, rival in ipairs(self.rivals) do
    if rival.map == mapId and self.spawned[rival.id] then hasVisible = true break end
  end
  if self.companionYieldMap == mapId then hasVisible = true end
  if not hasVisible then return end
  -- Static terrain does not change while the player remains on a map. Cache
  -- its conversion instead of rebuilding the full collision grid each pulse.
  local cache = self.walkMapCache
  if not cache or cache.mapId ~= mapId then
    local overview
    pcall(function() overview = mod.world and mod.world:mapOverview() end)
    cache = { mapId = mapId, overview = overview,
              grid = Pathfinder.grid(overview) }
    self.walkMapCache = cache
  end
  local overview, grid = cache.overview, cache.grid
  if not grid then return end
  -- A solid follower must yield before the player steps onto a door or map
  -- seam. Remove only its live NPC; the persistent rival remains attached and
  -- is materialised safely on the destination map by map.entered.
  local companion = self.byId[self.companionId]
  local nearTransit = false
  if companion and world.playerX and world.playerY then
    local head = self.companionTrailHead
    if not head or head.map ~= mapId then
      self.companionTrailHead = {
        map = mapId, x = world.playerX, y = world.playerY,
      }
      self.companionTrailGoal = nil
    elseif head.x ~= world.playerX or head.y ~= world.playerY then
      -- One follower takes the player's previous committed cell. If several
      -- cells passed between pulses, A* catches up one animated tile at a time.
      self.companionTrailGoal = { x = head.x, y = head.y, map = mapId }
      head.x, head.y = world.playerX, world.playerY
    end
    for dy = -1, 1 do
      for dx = -1, 1 do
        if math.abs(dx) + math.abs(dy) <= 1
           and self:isTransitCell(mapId, overview, world.playerX + dx, world.playerY + dy) then
          nearTransit = true
        end
      end
    end
    local companionNpc = self.spawned[companion.id]
    if nearTransit and companionNpc then
      pcall(function() mod.world:removeNpc(companionNpc) end)
      self.spawned[companion.id] = nil
      companion.x, companion.y, companion.spawnedAt = nil, nil, nil
      companion.walking, companion.localWalkGoal, companion.walkTarget = false, nil, nil
      self.companionTrailHead, self.companionTrailGoal = nil, nil
      self.companionYieldMap = mapId
    elseif not nearTransit and self.companionYieldMap == mapId and not companionNpc then
      self.companionYieldMap = nil
      pcall(function() self:spawnFor(mapId) end)
    end
  end
  local repaired = false
  for _, rival in ipairs(self.rivals) do
    if rival.map == mapId and self.spawned[rival.id] and rival.x and rival.y
       and (not self:liveTerrainWalkable(mapId, rival.x, rival.y)
            or (not rival.walking and self:isTransitCell(mapId, overview,
                                                         rival.x, rival.y))) then
      self:repairRivalPosition(rival, "invalid or blocking tile")
      repaired = true
    end
  end
  if repaired then pcall(function() self:spawnFor(mapId) end) end
  -- Spread autonomous walking work across pulses. The companion remains
  -- responsive, but crowds no longer run several 500-node searches together.
  local autonomousId
  local count = #self.rivals
  local phaseCount = performance == "emergency" and 1000000
    or performance == "low" and 6
    or (performance == "full" and 1 or 3)
  self.autonomousWalkPhase = ((self.autonomousWalkPhase or 0) + 1) % phaseCount
  if not playerInMotion and self.autonomousWalkPhase == 0 then
    self.walkCursor = ((self.walkCursor or 0) % math.max(1, count)) + 1
    for offset = 0, count - 1 do
      local candidate = self.rivals[((self.walkCursor + offset - 1) % count) + 1]
      if candidate and candidate.id ~= self.companionId and candidate.map == mapId
         and self.spawned[candidate.id] then
        autonomousId = candidate.id
        self.walkCursor = ((self.walkCursor + offset) % count) + 1
        break
      end
    end
  end
  for _, rival in ipairs(self.rivals) do
    if rival.map == mapId and self.spawned[rival.id] and rival.x and rival.y
       and (rival.id == self.companionId or rival.id == autonomousId)
       and not rival.walking and rival.state ~= "CHALLENGING_PLAYER" then
      local isCompanion = self.companionId == rival.id
      local tx, ty, nextMap
      if isCompanion and world.playerX and world.playerY then
        local trail = self.companionTrailGoal
        if trail and trail.map == mapId
           and self:validRivalCell(rival, overview, trail.x, trail.y, false) then
          tx, ty = trail.x, trail.y
          if rival.x == tx and rival.y == ty then
            self.companionTrailGoal, tx, ty = nil, nil, nil
          end
        end
        if not tx then
          local followCells = {
            { world.playerX, world.playerY + 1 }, { world.playerX - 1, world.playerY },
            { world.playerX + 1, world.playerY }, { world.playerX, world.playerY - 1 },
          }
          local bestDistance
          for _, cell in ipairs(followCells) do
            if self:validRivalCell(rival, overview, cell[1], cell[2], false) then
              local distance = math.abs(rival.x - cell[1]) + math.abs(rival.y - cell[2])
              if not bestDistance or distance < bestDistance then
                tx, ty, bestDistance = cell[1], cell[2], distance
              end
            end
          end
        end
        if tx == rival.x and ty == rival.y then tx, ty = nil, nil end
      else
        tx, ty, nextMap = self:mapExitTarget(rival, overview)
      end
      if not tx and not isCompanion then
        local goal = rival.localWalkGoal
        if not goal or (goal[1] == rival.x and goal[2] == rival.y)
           or self:isTransitCell(mapId, overview, goal[1], goal[2]) then
          rival.localWalkGoal = nil
          local start = rival.rng:int(0, math.max(0, grid.w * grid.h - 1))
          for offset = 0, grid.w * grid.h - 1 do
            local cell = (start + offset) % (grid.w * grid.h)
            local gx, gy = cell % grid.w, math.floor(cell / grid.w)
            local d = math.abs(gx - rival.x) + math.abs(gy - rival.y)
            if d >= 2 and d <= 7 and Pathfinder.walkable(grid, gx, gy)
               and self:liveTerrainWalkable(mapId, gx, gy)
               and not self:isTransitCell(mapId, overview, gx, gy)
               and not self:liveCellOccupied(mapId, gx, gy, self.spawned[rival.id])
               and not self:cellTaken(gx, gy)
               and not (world.playerX == gx and world.playerY == gy) then
              rival.localWalkGoal = { gx, gy }
              break
            end
          end
        end
        goal = rival.localWalkGoal
        tx, ty = goal and goal[1], goal and goal[2]
      end
      if tx and ty then
        if nextMap and rival.x == tx and rival.y == ty then
          local oldNpc = self.spawned[rival.id]
          if oldNpc then pcall(function() mod.world:removeNpc(oldNpc) end) end
          self.spawned[rival.id] = nil
          rival.arrivedFrom = rival.map
          rival.map, rival.x, rival.y = nextMap, nil, nil
          if rival.useHMsForMap then rival:useHMsForMap(nextMap) end
          rival.spawnedAt, rival.localWalkGoal = nil, nil
          rival.hopClock = nil
          if rival.visitMap then rival:visitMap(nextMap) end
          if rival.map == rival.destination then AI.onArrive(rival, world) end
        else
        local blocked = {}
        if world.playerX and world.playerY then
          blocked[world.playerX .. "," .. world.playerY] = true
        end
        for _, other in ipairs(self.rivals) do
          if other ~= rival and other.map == mapId and other.x and other.y then
            blocked[other.x .. "," .. other.y] = true
          end
        end
        -- Include every live NPC in A* itself.  Checking only the immediate
        -- step made the planner repeatedly choose the same occupied tile and
        -- stall beside shopkeepers/trainers instead of walking around them.
        local activeOw = self:activeMap()
        local selfNpc = self.spawned[rival.id]
        for _, npc in ipairs((activeOw and activeOw.npcs) or {}) do
          if npc.id ~= selfNpc and npc.cellX ~= nil and npc.cellY ~= nil then
            blocked[npc.cellX .. "," .. npc.cellY] = true
          end
        end
        local path = Pathfinder.find(grid, rival.x, rival.y, tx, ty,
          { budget = isCompanion and 120 or 240, blocked = blocked })
        local step = type(path) == "table" and path[1]
        if step and self:liveTerrainWalkable(mapId, step.x, step.y)
           and not self:liveCellOccupied(mapId, step.x, step.y,
                                         self.spawned[rival.id]) then
          local leaving = nextMap and step.x == tx and step.y == ty
          self:moveRivalNpc(rival, step.x, step.y, step.dir, leaving and function()
            local oldNpc = self.spawned[rival.id]
            if oldNpc then pcall(function() mod.world:removeNpc(oldNpc) end) end
            self.spawned[rival.id] = nil
            rival.arrivedFrom = rival.map
            rival.map, rival.x, rival.y = nextMap, nil, nil
            if rival.useHMsForMap then rival:useHMsForMap(nextMap) end
            rival.spawnedAt, rival.localWalkGoal = nil, nil
            rival.hopClock = nil
            if rival.visitMap then rival:visitMap(nextMap) end
            if rival.map == rival.destination then AI.onArrive(rival, world) end
          end or nil)
          rival.blockedWalkPulses = 0
        else
          rival.blockedWalkPulses = (rival.blockedWalkPulses or 0) + 1
          if rival.blockedWalkPulses >= 6 then
            self:repairRivalPosition(rival, "path blocked")
          end
        end
        end
      end
    end
  end
end


function M:placementForGen2(rival, world)
  local where = mod.world:current()
  local px, py = where and where.x, where and where.y
  if not (px and py) then return nil end
  -- engine_internals: the facade has no collision query, the map does
  local walkable
  local ok, map = pcall(function()
    return self.game and self.game.world and self.game.world.map
  end)
  if ok and map and type(map.isWalkableCell) == "function" then
    local check = map.isWalkableCell
    walkable = function(x, y)
      local good, res = pcall(check, map, x, y)
      return good and res or nil
    end
  end
  local function acceptable(x, y)
    if walkable then
      local w = walkable(x, y)
      if w == nil or not w then return false end
    end
    local d = math.abs(x - px) + math.abs(y - py)
    if d < 3 or d > 14 then return false end
    return true
  end
  if rival.x and rival.y and acceptable(rival.x, rival.y) then
    return rival.x, rival.y
  end
  local candidates = {}
  for dy = -7, 7 do
    for dx = -7, 7 do
      local d = math.abs(dx) + math.abs(dy)
      if d >= 3 and d <= 7 then
        candidates[#candidates + 1] = { px + dx, py + dy }
      end
    end
  end
  -- shuffle from the rival's own RNG: two rivals do not land on one cell and
  -- the same spot replays on reload
  for i = #candidates, 2, -1 do
    local j = rival.rng:int(1, i)
    candidates[i], candidates[j] = candidates[j], candidates[i]
  end
  for _, c in ipairs(candidates) do
    if acceptable(c[1], c[2]) and not self:cellTaken(c[1], c[2]) then
      return c[1], c[2]
    end
  end
  -- last resort: the player's own cell is walkable by definition
  return px, py
end

------------------------------------------------------------------------
-- Talking and battling
------------------------------------------------------------------------

-- The Elite Four's final trainer is selected when its party is requested.
-- BLUE keeps the vanilla party; the four AI rivals bring their actual teams.
  -- Selection is deliberately persisted so a retry/reload cannot reroll the
  -- Champion mid-battle. A vacant title remains with vanilla Blue.
function M:selectEliteChampion()
  -- A reigning AI Champion owns the next title defence.
  for _, rival in ipairs(self.rivals) do
    if rival.champion == true then
      self.eliteChampionId = rival.id
      return rival
    end
  end
  -- A vacant title belongs to the game's vanilla Champion. An AI rival may
  -- replace that party only after it has actually won a simulated League run.
  self.eliteChampionId = "blue"
  return nil
end

function M:eliteChampion()
  if self.eliteChampionId ~= nil then
    if self.eliteChampionId == "blue" then return nil end
    return self.byId[self.eliteChampionId]
  end
  return self:selectEliteChampion()
end

-- Keep this narrow and defensive because engine revisions expose the player's
-- bag in slightly different shapes.  A failed grant leaves the rival's item
-- untouched rather than deleting a reward into thin air.
function M:givePlayerItem(item)
  local save = self.game and self.game.save
  local bag = save and save.inventory
  if type(bag) ~= "table" then return false end
  for _, method in ipairs({ "add", "addItem", "give" }) do
    if type(bag[method]) == "function" then
      local ok, result = pcall(bag[method], bag, item, 1)
      if ok then return result ~= false end
    end
  end
  local items = type(bag.items) == "table" and bag.items or bag
  if type(items[item]) == "number" then
    items[item] = items[item] + 1
    return true
  end
  -- Plain keyed bags commonly omit zero-count entries.  Only create a key
  -- for an item present in the live item registry.
  if self.data and self.data.items and self.data.items[item] then
    items[item] = 1
    return true
  end
  return false
end

function M:takePlayerItem(item)
  local save = self.game and self.game.save
  local bag = save and save.inventory
  if type(bag) ~= "table" then return false end
  for _, method in ipairs({ "remove", "removeItem", "take" }) do
    if type(bag[method]) == "function" then
      local ok, result = pcall(bag[method], bag, item, 1)
      if ok then return result ~= false end
    end
  end
  local items = type(bag.items) == "table" and bag.items or bag
  if type(items[item]) == "number" and items[item] > 0 then
    items[item] = items[item] - 1
    return true
  end
  return false
end

-- Every player-facing relationship cause goes through here: one option gate,
-- one tick source, one news path for a derived transition.  Callers name what
-- happened and nothing else.
function M:recordBond(rival, id, code, opts)
  if not (rival and rival.recordRelationship) then return false end
  if not self:relationshipsEnabled() then return false end
  opts = opts or {}
  opts.tick = opts.tick or (self.sim and self.sim.tick or 0)
  local _, _, after, changed = rival:recordRelationship(id, code, opts)
  if changed then
    self:addNews(rival, { kind = "relationship", with = id, state = after })
  end
  return changed == true, after
end

function M:recordBondBattle(rival, id, won, opts)
  if not (rival and rival.recordRelationshipBattle) then return false end
  if not self:relationshipsEnabled() then return false end
  opts = opts or {}
  opts.tick = opts.tick or (self.sim and self.sim.tick or 0)
  local _, _, after, changed = rival:recordRelationshipBattle(id, won, opts)
  if changed then
    self:addNews(rival, { kind = "relationship", with = id, state = after })
  end
  return changed == true, after
end

function M:helpRequest(rival)
  if not rival then return false, "No request." end
  local item = rival:itemCount("POKE_BALL") == 0 and "POKE_BALL"
    or (rival:healthFraction() < 0.55 and "POTION" or nil)
  if not item then return false, rival.name .. " does not need help right now." end
  if not self:takePlayerItem(item) then
    return false, "You do not have a " .. Util.spaced(item) .. "."
  end
  rival:addItem(item, 1)
  -- The item genuinely left the player's bag and entered the rival's, which
  -- is what makes this a cause rather than a gesture.
  self:recordBond(rival, "player", "HELPED")
  local line = "You helped " .. rival.name .. " with a " .. Util.spaced(item) .. "."
  self:addNews(rival, { kind = "news", text = line })
  return true, line
end

local function playerSlotData(mon)
  if type(mon) ~= "table" then return nil end
  local species = mon.species or mon.speciesId or mon.id
  if type(species) == "table" then species = species.id or species.name end
  if type(species) ~= "string" then return nil end
  local moves = {}
  for _, move in ipairs(mon.moves or {}) do
    local id = type(move) == "table" and (move.id or move.move or move.name) or move
    if type(id) == "string" then moves[#moves + 1] = id end
  end
  return { species = species, level = tonumber(mon.level) or 5, moves = moves }
end

-- Adapt persistent move IDs to whichever Pokémon move representation this
-- engine build uses. Desktop builds commonly store IDs; some iOS/revision
-- builds expose move records carrying their own PP.
local function applyPersistentMoves(mon, slot, data)
  if type(mon) ~= "table" or type(slot) ~= "table"
     or type(slot.moves) ~= "table" or #slot.moves == 0 then return end
  local current = type(mon.moves) == "table" and mon.moves or {}
  local recordShape = type(current[1]) == "table"
  if not recordShape then
    mon.moves = Util.copy(slot.moves)
    return
  end
  local byId = {}
  for _, move in ipairs(current) do
    local id = type(move) == "table" and (move.id or move.move or move.name)
    if type(id) == "string" then byId[id] = move end
  end
  local converted = {}
  for _, id in ipairs(slot.moves) do
    local record = byId[id] and Util.copy(byId[id])
      or (data and data.moves and data.moves[id] and Util.copy(data.moves[id]))
    if type(record) == "table" then
      record.id = record.id or id
      local pp = slot.movePp and slot.movePp[id]
      if tonumber(pp) then record.pp = tonumber(pp) end
      converted[#converted + 1] = record
    else
      converted[#converted + 1] = id
    end
  end
  mon.moves = converted
end

-- Build through the loaded engine and validate before touching either party.
function M:buildPlayerPokemon(slot)
  local ok, Pokemon = pcall(require, "src.pokemon.Pokemon")
  if not ok or type(Pokemon) ~= "table" or type(Pokemon.new) ~= "function" then return nil end
  local def = self.data and self.data.pokemon and self.data.pokemon[slot.species]
  local attempts = {
    function() return Pokemon.new(def, slot.level) end,
    function() return Pokemon.new(slot.species, slot.level) end,
    function() return Pokemon.new(self.data, slot.species, slot.level) end,
  }
  for _, make in ipairs(attempts) do
    local made, mon = pcall(make)
    local built = made and playerSlotData(mon) or nil
    if built and built.species == slot.species then
      return mon
    end
  end
  return nil
end

function M:tradeOffer(rival)
  local party = self.game and self.game.save and self.game.save.party
  if not (rival and type(party) == "table" and #party >= 2) then
    return false, "You need at least two Pokemon to trade."
  end
  local offered, offeredBox, offeredIndex
  local counts = {}
  for _, slot in ipairs(rival.party or {}) do counts[slot.species] = (counts[slot.species] or 0) + 1 end
  for _, box in ipairs(rival.pcBoxes or {}) do
    for _, slot in ipairs(box) do counts[slot.species] = (counts[slot.species] or 0) + 1 end
  end
  for _, box in ipairs(rival.pcBoxes or {}) do
    for i, slot in ipairs(box) do
      if (counts[slot.species] or 0) > 1 then
        offered, offeredBox, offeredIndex = slot, box, i
        break
      end
    end
    if offered then break end
  end
  if not offered then return false, rival.name .. " has no duplicate to offer." end
  local outgoing = playerSlotData(party[#party])
  if not outgoing or not rival:speciesDef(outgoing.species) then
    return false, "That Pokemon cannot be represented in the rival collection."
  end
  local incoming = self:buildPlayerPokemon(offered)
  if not incoming then return false, "Trading is unavailable in this game build." end
  -- Commit only after both sides have been validated and constructed.
  party[#party] = incoming
  table.remove(offeredBox, offeredIndex)
  rival:storePokemon(outgoing)
  rival:registerDex(outgoing.species)
  self:recordBond(rival, "player", "TRADED")
  local line = "You traded " .. Util.spaced(outgoing.species) .. " with "
    .. rival.name .. " for " .. Util.spaced(offered.species) .. "."
  self:addNews(rival, { kind = "news", text = line })
  return true, line
end

function M:startHmRecovery(rival, move)
  if not (rival and move) then return false end
  rival.hmGoal = move
  rival.hmGoalForced = true
  local species, mapId
  if rival.pickHmHuntTarget then species, mapId = rival:pickHmHuntTarget(move) end
  rival.objective = "TRAIN"
  if species and mapId then
    rival:setState("TRAVELLING", "finding an HM user")
    rival:setDestination(mapId)
    rival.travelReason = "Hunting " .. Util.spaced(species)
      .. " for " .. Util.spaced(move)
    self:addNews(rival, { kind = "hm_hunt", move = move, species = species })
  else
    rival:setState("TRAINING", "needs a compatible HM user")
    rival.destination, rival.route = nil, nil
    rival.travelReason = "Needs a Pokémon that can learn " .. Util.spaced(move)
  end
  return true
end

function M:setCompanion(rival)
  if rival and self.companionId ~= rival.id then
    local world = self:worldView()
    local missing = world and world.playerMap and rival.missingHMForMap
      and rival:missingHMForMap(world.playerMap)
    if missing then
      self:startHmRecovery(rival, missing)
      return false, rival.name .. " cannot join here without " .. Util.spaced(missing) .. "."
    end
    -- Switching companions dismisses the old one cleanly instead of leaving
    -- two rivals carrying an "accompanying" state while only one is registered
    -- as the battle ally.
    local previous = self.byId[self.companionId]
    if previous and previous ~= rival then
      previous.travelReason = "Resuming an independent journey"
      pcall(AI.evaluate, previous, self:worldView())
    end
    self.companionId = rival.id
    self.companionYieldMap = nil
    self.companionTrailHead, self.companionTrailGoal = nil, nil
    rival.destination, rival.route, rival.localWalkGoal = nil, nil, nil
    rival.walking, rival.blockedWalkPulses = false, 0
    rival:setState("IDLE", "accompanying the player")
    rival.travelReason = "Accompanying the player"
    if world and world.playerMap then
      rival.map, rival.x, rival.y = world.playerMap, nil, nil

      -- Materialise the companion immediately.  Previously this relied entirely
      -- on spawnFor() finding a valid tile after the NPC had been despawned.
      -- On maps with incomplete/strict collision data that could silently leave
      -- the companion abstract, making "ACCOMPANY" appear to do nothing.
      local overview
      pcall(function()
        if mod.world and mod.world.mapOverview then
          overview = mod.world:mapOverview()
        end
      end)
      if overview and world.playerX and world.playerY then
        local candidates = {
          { world.playerX, world.playerY + 1 },
          { world.playerX - 1, world.playerY },
          { world.playerX + 1, world.playerY },
          { world.playerX, world.playerY - 1 },
        }
        for _, cell in ipairs(candidates) do
          if self:validRivalCell(rival, overview, cell[1], cell[2], false)
             and not (cell[1] == world.playerX and cell[2] == world.playerY) then
            rival.x, rival.y = cell[1], cell[2]
            break
          end
        end
      end

      self:despawnAll()
      local spawned = 0
      local ok, result = pcall(function()
        return self:spawnFor(world.playerMap)
      end)
      if ok then spawned = tonumber(result) or 0 end

      -- If the preferred adjacent tile was not available, give the normal
      -- placement code one more chance from a clean coordinate state.
      if spawned == 0 and not self.spawned[rival.id] then
        rival.x, rival.y = nil, nil
        pcall(function() self:spawnFor(world.playerMap) end)
      end
    end
    self:addNews(rival, { kind = "news", text = rival.name .. " joined the player." })
    if self.spawned[rival.id] then
      return true, rival.name .. " is now accompanying you."
    end
    return true, rival.name .. " is now accompanying you. They will appear on the next map refresh."
  end
  local leaving = rival or self.byId[self.companionId]
  self.companionId = nil
  self.companionTrailHead, self.companionTrailGoal = nil, nil
  if leaving then
    leaving.travelReason = "Resuming an independent journey"
    pcall(AI.evaluate, leaving, self:worldView())
  end
  return true, leaving and (leaving.name .. " resumed travelling alone.")
    or "No rival is accompanying you."
end

mod.exports.registerAllySource({
  id = "ai_rivals_companion",
  priority = 1,
  provide = function(game, battle)
    local rival = M.byId[M.companionId]
    if not rival then return nil end
    local slot
    for _, candidate in ipairs(rival.party or {}) do
      if (tonumber(candidate.hp) or rival:maxHpOf(candidate)) > 0 then slot = candidate break end
    end
    if not slot then return nil end
    local mon = M:buildPlayerPokemon(slot)
    if not mon then return nil end
    -- Carry the rival's actual persistent battle state into the temporary
    -- engine Pokémon instead of reverting to constructor-default moves.
    applyPersistentMoves(mon, slot, M.data)
    if tonumber(slot.exp) then mon.exp = tonumber(slot.exp) end
    if slot.status ~= nil then mon.status = slot.status end
    if type(slot.pp) == "table" then mon.pp = Util.copy(slot.pp) end
    if type(slot.movePp) == "table" then mon.movePp = Util.copy(slot.movePp) end
    if mon.stats and mon.stats.hp then
      mon.hp = math.min(mon.stats.hp, tonumber(slot.hp) or mon.stats.hp)
    end
    M.companionBattleSlot, M.companionBattleMon = slot, mon
    return mon, true
  end,
})
mod.exports.companionActive = function()
  local rival = M.byId[M.companionId]
  if not rival then return false end
  for _, slot in ipairs(rival.party or {}) do
    if (tonumber(slot.hp) or rival:maxHpOf(slot)) > 0 then return true end
  end
  return false
end

function M:restoreCompanionBattle(battle)
  local slot, mon = M.companionBattleSlot, M.companionBattleMon
  if not (slot and mon) then return false end
  if battle and not battle.__dbExternalAlly then
    -- The provider was queried but the battle refused/failed to construct the
    -- external battler. Discard the untouched temporary object immediately.
    M.companionBattleSlot, M.companionBattleMon = nil, nil
    return false
  end
  M.companionBattleSlot, M.companionBattleMon = nil, nil
  slot.hp = math.max(0, tonumber(mon.hp) or slot.hp or 0)
  local snapshot = playerSlotData(mon)
  if snapshot then
    slot.species = snapshot.species or slot.species
    slot.level = snapshot.level or slot.level
    if snapshot.moves and #snapshot.moves > 0 then slot.moves = snapshot.moves end
  else
    slot.level = tonumber(mon.level) or slot.level
  end
  slot.exp = tonumber(mon.exp) or slot.exp
  slot.status = mon.status
  if type(mon.pp) == "table" then slot.pp = Util.copy(mon.pp) end
  if type(mon.movePp) == "table" then slot.movePp = Util.copy(mon.movePp) end
  local movePp = {}
  for _, move in ipairs(mon.moves or {}) do
    if type(move) == "table" then
      local id = move.id or move.move or move.name
      if type(id) == "string" and tonumber(move.pp) then movePp[id] = tonumber(move.pp) end
    end
  end
  slot.movePp = next(movePp) and movePp or slot.movePp
  local rival = M.byId[M.companionId]
  if rival and rival:isFainted() then
    -- A wiped companion blacks out like every other rival. Dismiss first so
    -- the follow director cannot pull them straight back onto the player map.
    M.companionId = nil
    local npcId = M.spawned[rival.id]
    if npcId then pcall(function() mod.world:removeNpc(npcId) end) end
    M.spawned[rival.id] = nil
    if not (rival.warpToLastPokemonCenter and rival:warpToLastPokemonCenter()) then
      rival.travelReason = "Companion team fainted; needs healing"
    end
    pcall(function() M:save() end)
  end
  return true
end

mod.events:on("battle.ended", function(ev)
  M:restoreCompanionBattle(ev and ev.battle)
end)

mod.events:on("world.blacked_out", function(ev)
  -- Some builds emit blackout before (or instead of) battle.ended. The
  -- restore function consumes its snapshot once, so both events are safe.
  M:restoreCompanionBattle(ev and ev.battle)
end)

function M:awardRivalLoot(rival)
  if not rival or not rival.ensureInventory then return nil end
  rival:ensureInventory()

  -- The Master Ball is a League-completion reward, not ordinary rival
  -- inventory. Roll exactly once per player victory and never debit the
  -- rival when it succeeds.
  local badges = self:playerBadgeCount()
  if badges >= 8 and rival.rng:chance(0.15) then
    if self:givePlayerItem("MASTER_BALL") then return "MASTER_BALL" end
  end

  local choices = {}
  for item, count in pairs(rival.inventory or {}) do
    if tonumber(count) and count > 0 and self:rivalGiftAllowed(item, badges) then
      choices[#choices + 1] = item
    end
  end
  if #choices == 0 then return nil end
  local item = choices[rival.rng:int(1, #choices)]
  if self:givePlayerItem(item) and rival:takeItem(item) then return item end
  return nil
end

-- Rival gifts unlock alongside the player's badge case. Before Brock is
-- defeated the only possible gifts are Potions and ordinary Poké Balls.
-- MASTER_BALL is deliberately absent: awardRivalLoot owns its single 15%
-- post-eight-badge roll.
local RIVAL_GIFT_BADGES = {
  POTION = 0, POKE_BALL = 0,
  ANTIDOTE = 1, PARLYZ_HEAL = 1, AWAKENING = 1,
  BURN_HEAL = 1, ICE_HEAL = 1, REPEL = 1,
  GREAT_BALL = 2, SUPER_POTION = 2,
  ULTRA_BALL = 3, HYPER_POTION = 3,
  RARE_CANDY = 5,
}

function M:rivalGiftAllowed(item, badgeCount)
  local required = RIVAL_GIFT_BADGES[tostring(item or "")]
  return required ~= nil and math.max(0, tonumber(badgeCount) or 0) >= required
end

function M:rivalAtNpc(npcId)
  for id, spawnedId in pairs(self.spawned) do
    local rival = self.byId[id]
    local spawnedKey = spawnedId
    if type(spawnedId) == "table" then
      spawnedKey = spawnedId.id or spawnedId.name
        or (spawnedId.def and spawnedId.def.name)
    end
    if spawnedId == npcId or spawnedKey == npcId
       or tostring(spawnedKey) == tostring(npcId)
       or tostring(npcId) == "AIR_" .. tostring(id) then return rival end
  end
  return nil
end

function M:rivalDetailItems(rival)
  if not rival then return {} end
  local battleMode = self:rivalBattleMode(rival, (self.challengeModes or {})[rival.id])
  return {
    { label = "CHALLENGE", right = battleMode == "DOUBLE" and "2V2" or "1V1", value = "_challenge" },
    { label = M.companionId == rival.id and "STOP FOLLOW" or "ACCOMPANY",
      right = M.companionId == rival.id and "ON" or "JOIN", value = "_accompany" },
    { label = "TRADE", value = "_trade" },
    { label = "GIVE HELP", right = rival:itemCount("POKE_BALL") == 0 and "BALL"
        or (rival:healthFraction() < 0.55 and "POTION" or "--"), value = "_help" },
    { label = "RIVAL INFO", value = "_info" },
    { label = "GOODBYE", value = "_goodbye" },
  }
end

function M:rivalInfoItems(rival)
  if not rival then return {} end
  local detail = {
    { label = "MOVE TO SAFE TILE", right = "MOVE", value = "_repair" },
  }
  do
    if rival.moodLabel then
      detail[#detail + 1] = {
        label = "MOOD", right = rival:moodLabel():upper():sub(1, 18), value = "_line" }
      detail[#detail + 1] = {
        label = "CHAPTER", right = rival:chapterLabel():upper():sub(1, 18), value = "_line" }
      local story = rival:ensureStory()
      detail[#detail + 1] = {
        label = "MILESTONES",
        right = Story.unlockedCount(story) .. "/" .. Story.milestoneCount(),
        value = "_story",
      }
    end
    local ace = rival.favouriteSpecies and rival:favouriteSpecies()
    detail[#detail + 1] = {
      label = "TEAM STYLE",
      right = (rival.teamStyleLabel and rival:teamStyleLabel() or "?"):upper():sub(1, 18),
      value = "_line",
    }
    detail[#detail + 1] = {
      label = "BATTLE STYLE",
      right = (rival.battleStyle and rival:battleStyle() or "?"):upper():sub(1, 18),
      value = "_line",
    }
    -- §22: the player is shown WHAT a rival is doing, never the machinery.
    -- A rival still on the Gym Challenge shows nothing at all here, so the
    -- screen cannot leak who has an alternative destiny waiting.
    if rival.onGymChallenge and not rival:onGymChallenge() then
      detail[#detail + 1] = {
        label = "NOW",
        right = LifePath.label(rival:lifePathId()):upper():sub(1, 18),
        value = "_line",
      }
      local rank = rival.careerRank and rival:careerRank()
      if rank then
        detail[#detail + 1] = {
          label = "RANK", right = rank:upper():sub(1, 18), value = "_line" }
      end
    end
    if rival.spendingProfile then
      local profile = rival:spendingProfile()
      local best, bestShare = nil, 0
      for _, category in ipairs(Economy.CATEGORIES) do
        if (profile[category] or 0) > bestShare then
          best, bestShare = category, profile[category]
        end
      end
      if best then
        detail[#detail + 1] = {
          label = "SPENDS ON",
          right = (best:lower() .. " " .. math.floor(bestShare * 100 + 0.5) .. "%"):upper(),
          value = "_line",
        }
      end
    end
    local sky = rival.currentWeatherId and rival:currentWeatherId()
    if sky then
      detail[#detail + 1] = {
        label = "SKY", right = Weather.label(sky):upper():sub(1, 18), value = "_line" }
      local focus = rival:weatherFocusType()
      if focus then
        detail[#detail + 1] = {
          label = "SKY FAVOURS", right = tostring(focus):sub(1, 18), value = "_line" }
      end
    end
    local preferred = rival.preferredTypes and rival:preferredTypes(2) or {}
    if #preferred > 0 then
      detail[#detail + 1] = {
        label = "PREFERRED TYPE",
        right = table.concat(preferred, "/"):sub(1, 18),
        value = "_line",
      }
    end
    if ace then
      detail[#detail + 1] = {
        label = "FAVOURITE",
        right = Util.spaced(ace):sub(1, 18),
        value = "_line",
      }
    end
  end
  if self:relationshipsEnabled() then
    local tick = self.sim and self.sim.tick or 0
    local bond = rival:bondWith("player", tick)
    detail[#detail + 1] = {
      label = "TOWARD YOU",
      right = (Relationships.label(Relationships.state(bond)):upper()
        .. " " .. tostring(bond.wins or 0) .. "-" .. tostring(bond.losses or 0)):sub(1, 18),
      value = "_line",
    }
    for _, other in ipairs(self.rivals) do
      if other.id ~= rival.id then
        detail[#detail + 1] = {
          label = ("TOWARD " .. tostring(other.name)):sub(1, 16),
          right = Relationships.label(rival:relationshipTo(other.id, tick)):upper(),
          value = "_line",
        }
      end
    end
  end
  return detail
end

function M:rivalBattleMode(rival, requested)
  if not rival or rival.id == self.companionId then return "UNAVAILABLE" end
  local ow = self:getOverworld()
  local canQueue = ow and type(ow.queueScript) == "function"
  local canRun = ow and ow.runner and type(ow.runner.run) == "function"
  if not (canQueue or canRun) then return "UNAVAILABLE" end
  local playerParty = self.game and self.game.save and self.game.save.party
  if type(playerParty) ~= "table" or #playerParty == 0 then return "UNAVAILABLE" end
  local rivalHealthy, playerHealthy = 0, 0
  for _, slot in ipairs(rival.party or {}) do
    if (tonumber(slot.hp) or rival:maxHpOf(slot)) > 0 then rivalHealthy = rivalHealthy + 1 end
  end
  for _, slot in ipairs(playerParty) do
    if (tonumber(slot.hp) or 1) > 0 then playerHealthy = playerHealthy + 1 end
  end
  if rivalHealthy == 0 then return "FAINTED" end
  local wanted = requested or (self.challengeModes and self.challengeModes[rival.id]) or "SINGLE"
  if wanted == "DOUBLE" and rivalHealthy >= 2 and playerHealthy >= 2 then return "DOUBLE" end
  return "SINGLE"
end

-- Phone menus sit above the overworld, so the normal rivalBattleMode() cannot
-- truthfully test queueScript/runner availability until the Pokégear closes.
-- This checks only the conditions that are meaningful while actually on the
-- call; queueRivalAction stages the launch for the next idle overworld frame.
function M:phoneRivalBattleMode(rival, requested)
  if not rival or rival.id == self.companionId then return "UNAVAILABLE" end
  local playerParty = self.game and self.game.save and self.game.save.party
  if type(playerParty) ~= "table" or #playerParty == 0 then return "UNAVAILABLE" end
  local rh, ph = 0, 0
  for _, slot in ipairs(rival.party or {}) do
    if (tonumber(slot.hp) or rival:maxHpOf(slot)) > 0 then rh = rh + 1 end
  end
  for _, slot in ipairs(playerParty) do
    if (tonumber(slot.hp) or 1) > 0 then ph = ph + 1 end
  end
  if rh == 0 then return "FAINTED" end
  local wanted = requested or (self.challengeModes and self.challengeModes[rival.id]) or "SINGLE"
  if wanted == "DOUBLE" and rh >= 2 and ph >= 2 then return "DOUBLE" end
  return "SINGLE"
end

function M:canToggleChallengeDouble(rival)
  if not rival then return false end
  local rh, ph = 0, 0
  for _, slot in ipairs(rival.party or {}) do
    if (tonumber(slot.hp) or rival:maxHpOf(slot)) > 0 then rh = rh + 1 end
  end
  for _, slot in ipairs((self.game and self.game.save and self.game.save.party) or {}) do
    if (tonumber(slot.hp) or 1) > 0 then ph = ph + 1 end
  end
  return rh >= 2 and ph >= 2
end

-- Construct and push a manual Gen 1 rival battle without relying on the
-- queued script `start_battle` verb. Some Android builds accept that queue
-- but never drain the battle row, producing a truthful-looking acceptance
-- message followed by nothing. The pending rival is already set, so the
-- trainer.party hook below supplies its live team during construction.
-- 3.1.0 -- GOLD TRAINER BATTLES, ENTIRELY INSIDE THE MOD.
--
-- We shipped patches/0001-gen2-mod-trainer-battle.patch for this. An engine
-- patch is not acceptable: a mod has to work on a stock install, and a player
-- who cannot patch their engine had a feature that silently did nothing.
--
-- The supported route was there the whole time, and the engine's own source
-- names it twice:
--
--   * src/mods/Gen2Compat.lua marks BattleState.newTrainer ABSENT with the
--     reason "Gold has no factory that returns an unpushed battle, and
--     World:startBattle constructs and pushes in one call." So the Gen 1 path
--     below cannot work on Gold -- but startBattle can.
--   * src/world/gen2/WorldAPI.lua refuses `start_battle "trainer"` because
--     "the trainer arm needs a party out of the extracted trainer table and an
--     OPP_CLASS the mod cannot name". That is a limit of the SCRIPT VERB, not
--     of World:startBattle, which takes `opts.trainer` directly
--     (src/world/gen2/World.lua:5822).
--   * src/battle/gen2/Battle.lua:273-288 then calls the `trainer.party` hook
--     with the class and member id, and says outright: "a mod that hands back
--     rows it built itself keeps them, because nothing here rewrites what the
--     hook returned."
--
-- That hook is the one our rivals have fought through since 1.1. So Gold needs
-- no party out of the extracted table and no OPP_CLASS we cannot name: we pass
-- the trainer shell, our own hook answers with the rival's real live team, and
-- the battle is ours.
function M:pushGen2RivalBattle(rival)
  if not rival then return false, "no rival" end
  local world = mod.world
  if not (world and type(world.overworld) == "function") then
    return false, "no Gen 2 world facade"
  end
  local ok, result = pcall(function()
    local ow = world:overworld()
    if not (ow and type(ow.startBattle) == "function") then
      error("this world cannot start battles directly")
    end
    local classId = rival.def and rival.def.trainerClass
    if not classId then error("rival has no trainer class") end
    -- The shell only. `party = {}` is deliberate: an empty roster is what
    -- makes the trainer.party hook the single source of the team, so a Gold
    -- battle and a Gen 1 battle fight the SAME persistent party rather than
    -- two rosters that can drift apart.
    ow:startBattle({
      trainer = {
        name = rival.name,
        class = classId,
        classId = classId,
        index = 1,
        memberId = 1,
        party = {},
      },
    }, function()
      -- No completion work here on purpose. The mod already settles a rival
      -- battle from the `battle.ended` event (see the handler that records the
      -- result, the relationship, the service credit and the story beat), and
      -- Gold raises that event under the same name. Doing it again in this
      -- callback would double-count every battle -- two memory rows, two
      -- relationship swings, two career credits.
      --
      -- An earlier draft called M:onRivalBattleFinished here. No such function
      -- exists; it would have raised inside a pcall on every Gold battle and
      -- silently eaten the outcome.
    end)
    return true
  end)
  if ok and result == true then return true end
  Util.lastError = "gen2 rival battle: " .. tostring(result)
  return false, Util.lastError
end

function M:pushManualRivalBattle(rival, ow)
  -- Gold first: its BattleState facade marks newTrainer absent, so the Gen 1
  -- construction below cannot succeed there and trying it first would only
  -- produce a misleading error.
  if self.versionKey == "gen2" then
    local done, line = self:pushGen2RivalBattle(rival)
    if done then return true end
    Util.lastError = line or Util.lastError
    return false, Util.lastError
  end
  local ok, result = pcall(function()
    local Game = self.game
    if not Game then error("game unavailable") end
    local controller = (Game and Game.overworld) or ow
    if not (controller and type(controller.pushBattle) == "function") then
      error("overworld cannot push battles")
    end
    local BattleState = require("src.battle.BattleState")
    local classId = rival and rival.def and rival.def.trainerClass
    if not classId then error("rival has no trainer class") end
    local battle = BattleState.newTrainer(Game, classId, 1)
    if not battle or battle.dead then error("trainer battle was refused") end
    if not battle.onFinish then
      battle.onFinish = function(value)
        if controller.afterBattle then controller:afterBattle(value, battle) end
      end
    end
    controller:pushBattle(battle)
    return true
  end)
  if ok and result == true then return true end
  Util.lastError = "manual rival battle launch: " .. tostring(result)
  return false, Util.lastError
end

function M:updatePendingRivalBattle(dt)
  local launch = self.pendingRivalBattleLaunch
  if not launch then return false end
  launch.age = (tonumber(launch.age) or 0) + (tonumber(dt) or 0)
  -- Let the dialogue screen leave the stack before pushing BattleState.
  local ready = self:overworldIdle()
    or (launch.age >= 0.35 and self:overworldRunnerIdle())
  if launch.age < 0.08 or not ready then return true end
  self.pendingRivalBattleLaunch = nil
  -- A stale delayed callback must never resurrect an old battle after another
  -- sequence has begun.
  if not self.rivalBattleSequenceActive
      or self.rivalBattleActiveRivalId ~= launch.rivalId then
    return true
  end
  local rival = self.byId[launch.rivalId]
  local ow = self:getOverworld()
  local ok, line = self:pushManualRivalBattle(rival, ow)
  if not ok then
    -- Last-resort engine-owned execution for an iOS revision that refuses
    -- direct BattleState construction. Unlike the broken queueScript path,
    -- runner:run executes this single row immediately at an idle boundary.
    local ran, accepted = false, false
    if ow and ow.runner and type(ow.runner.run) == "function" and rival then
      ran, accepted = pcall(function()
        return ow.runner:run({ { "start_battle", "trainer",
          rival.def.trainerClass, 1 } }, {})
      end)
    end
    if ran and accepted ~= false then return true end
    self.pending, self.pendingChampion = nil, nil
    -- A failed launch must release the lock, or the mod is wedged for the rest
    -- of the session.
    self.rivalBattleSequenceActive = false
    self.rivalBattleActiveRivalId = nil
    self.worldChallenge = false
    if rival then pcall(function() rival:setState("IDLE", "challenge launch failed") end) end
    self.ticker = { text = "NOTICE  •  " .. tostring(line), age = 0,
      duration = 8, offset = 0 }
  end
  return true
end

-- One exit for the complete challenge transaction. The old release lived only
-- in world.blacked_out, so an ordinary win/clean loss left this lock set for
-- the rest of the session and every later challenge reported "already in
-- progress".
function M:releaseRivalBattleSequence(rivalId)
  return BattleFlow.release(self, rivalId)
end

function M:startRivalChallenge(rival, requestedMode, tournamentMatch)
  -- Checked BEFORE any state mutation: a refused second request must leave the
  -- first transaction exactly as it found it.
  if self.rivalBattleSequenceActive then
    return false, "A rival battle is already in progress."
  end
  if self.pendingRivalBattleLaunch then
    return false, "A rival battle is already being prepared."
  end
  local mode = self:rivalBattleMode(rival, requestedMode)
  if mode == "UNAVAILABLE" then
    if rival and rival.id == self.companionId then
      return false, "Stop accompanying before challenging this rival."
    end
    return false, "A battle is unavailable right now."
  end
  if mode == "FAINTED" then return false, rival.name .. " has no healthy Pokémon." end
  local ow = self:getOverworld()
  if not ow then
    return false, "Battle cannot start on this screen."
  end
  -- A direct player challenge is immediate: never withdraw from the PC, teach
  -- a TM or walk away to prepare after the player has pressed CHALLENGE.
  self.pending = rival
  self.pendingTournamentMatch = tournamentMatch == true
  self.tournamentExpActive = tournamentMatch == true
  self.rivalBattleSequenceId = (tonumber(self.rivalBattleSequenceId) or 0) + 1
  self.rivalBattleSequenceActive = true
  self.rivalBattleActiveRivalId = rival.id
  rival._rivalBattleSequenceId = self.rivalBattleSequenceId
  rival:setState("CHALLENGING_PLAYER", "accepted a direct challenge")
  if mode == "DOUBLE" and type(mod.exports.allowNextScriptedDouble) == "function" then
    pcall(mod.exports.allowNextScriptedDouble)
  end
  -- 1.39.0 §30: a title shot is EARNED, not owed.
  --
  -- This used to fire on eight badges alone, so a rival could challenge the
  -- player for the Championship without ever having beaten the Elite Four --
  -- an entitlement the player does not have, and §38 requires the AI to play
  -- by the same rules. It now additionally requires a qualifying run: the
  -- rival must have CLEARED the Elite Four since it last held the title.
  local titleChallenge = self.playerChampion == true
    and rival.nextBadge and rival:nextBadge() == nil and rival.champion ~= true
    and rival.mayChallengeTitle and rival:mayChallengeTitle()
  if titleChallenge then self.pendingChampion = rival end
  local line = titleChallenge and self.dialogue:championChallenge(rival)
    or self.dialogue:challenge(rival)
  local rows = {
    { "show_text", line },
    { "start_battle", "trainer", rival.def.trainerClass, 1 },
  }
  local ok, accepted
  -- Every Gen 1 host, including iOS: run dialogue only, then push BattleState
  -- after its completion callback. iOS was previously left on queueScript,
  -- but field reports confirm that it too can accept start_battle without
  -- ever executing it. The delayed push happens only after the text/UI stack
  -- is clear, which is the portability condition the old iOS branch lacked.
  if self.generation ~= 2
      and ow.runner and type(ow.runner.run) == "function" then
    ok, accepted = pcall(function()
      return ow.runner:run({ { "show_text", line } }, {
        onDone = function()
          self.pendingRivalBattleLaunch = { rivalId = rival.id, age = 0 }
        end,
      })
    end)
  elseif type(ow.queueScript) == "function" then
    ok, accepted = pcall(function() return ow:queueScript(rows) end)
  elseif ow.runner and type(ow.runner.run) == "function" then
    ok, accepted = pcall(function() return ow.runner:run(rows, {}) end)
  else
    ok, accepted = false, "no trainer script path"
  end
  if not ok or accepted == false then
    self.pending, self.pendingChampion, self.pendingRivalBattleLaunch = nil, nil, nil
    self.tournamentExpActive = false
    self.rivalBattleSequenceActive = false
    self.rivalBattleActiveRivalId = nil
    self.worldChallenge = false
    rival:setState("IDLE", "challenge could not start")
    return false, "Battle queue failed: " .. tostring(accepted)
  end
  return true, mode .. " battle accepted."
end

-- Execute choices after the menu closes, when the overworld is active again.
function M:queueRivalAction(rival, value)
  if type(value) == "table" then value = value.value or value.id end
  if value == "_story" and rival and self.game then
    mod.ui.push(self.game, SCREEN .. "Story", { rival = rival })
    return true
  end
  -- Touch/iOS list menus may return the selected row rather than its value.
  -- Normalise both forms here so every caller gets the same behaviour.
  if type(value) == "table" then value = value.value or value.id end
  local valid = value == "_help" or value == "_trade" or value == "_repair"
    or value == "_accompany" or value == "_challenge"
  if not (rival and rival.id and valid) then return false end
  self.pendingRivalAction = { rivalId = rival.id, value = value, age = 0 }
  return true
end

function M:performRivalAction(rival, value)
  if not rival then return false, "That rival is no longer available." end
  if value == "_help" then return self:helpRequest(rival)
  elseif value == "_trade" then return self:tradeOffer(rival)
  elseif value == "_repair" then return self:repairRivalPosition(rival, "manual repair")
  elseif value == "_accompany" then
    if self.companionId == rival.id then return self:setCompanion(nil) end
    return self:setCompanion(rival)
  elseif value == "_challenge" then return self:startRivalChallenge(rival, (self.challengeModes or {})[rival.id])
  end
  return false, "Unknown rival action."
end

-- ------------------------------------------------------------------
-- The Pokegear conversation (4.5.0)
-- ------------------------------------------------------------------

-- Which rival is on the other end of this contact?  syncRivalComms stamps
-- record.rivalId, but a save written before that did not, so fall back to the
-- contact id the rival contacts have always been keyed by rather than
-- returning nil and telling the player their rival is an ordinary trainer.
function M:rivalForContact(record)
  if type(record) ~= "table" or record.kind ~= "RIVAL" then return nil end
  local rival = record.rivalId and self.byId and self.byId[record.rivalId]
  if rival then return rival end
  for _, r in ipairs(self.rivals or {}) do
    if ("PHONE_AIR_" .. string.upper(tostring(r.id))) == tostring(record.id) then
      return r
    end
  end
  return nil
end

-- What this caller can honestly say about that rival.  The model is in
-- src/Scout.lua and is derived on every open: a report is never stored, so it
-- cannot contradict the world it describes.  A nil caller is an ordinary
-- trainer, who holds no head-to-head record and answers at rumour level.
function M:scoutReport(caller, subject)
  if not subject then return nil end
  local tick = self.sim and self.sim.tick or 0
  local ok, report = pcall(Scout.report, caller, subject, tick)
  if ok and type(report) == "table" then return report end
  return { level = "NONE", headline = "NO ANSWER", rows = {},
    line = "I can't help with that." }
end

-- ------------------------------------------------------------------
-- Trainer rankings and records (4.6.0)
-- ------------------------------------------------------------------
-- The rankings table and every trainer record are DERIVED on open. Nothing
-- about an achievement is stored: "Defeated Brock" is the badge case joined to
-- the gym table, the Elite Four line is the League record, the rivalries are
-- the bonds. A screen built this way cannot drift from the world, and a save
-- edit that removes a badge removes the sentence about it too.

function M:playerFacts()
  local name
  pcall(function()
    local save = self.game and self.game.save
    name = save and (save.playerName or (save.trainer and save.trainer.name))
  end)
  if type(name) ~= "string" or name == "" then name = "Player" end
  local party = {}
  pcall(function()
    party = (self.game and self.game.save and self.game.save.party) or {}
  end)
  return {
    name = name,
    badges = self:playerBadgeCount(),
    caught = #party,
    champion = self.playerChampion == true,
  }
end

function M:trainerRankings()
  local ok, rows = pcall(Rankings.build, self.rivals, self:playerFacts())
  if ok and type(rows) == "table" then return rows end
  return {}
end

-- The names the record screen needs to say who a rivalry is WITH. Built from
-- the live roster rather than stored with the bond: a bond holds an id, and
-- the id resolves to whatever that rival is called now.
function M:rivalNames()
  local names = {}
  for _, rival in ipairs(self.rivals or {}) do
    if rival and rival.id then names[rival.id] = rival.name end
  end
  return names
end

function M:trainerRecord(rivalId, isPlayer)
  if isPlayer then
    -- The player's own row. The mod knows the badge case and the title and
    -- nothing else about them, and it says so rather than inventing a career:
    -- the player's Pokemon, rivalries and history are the GAME's business, not
    -- this mod's, and a screen that guessed at them would be making things up.
    local facts = self:playerFacts()
    return {
      name = facts.name, badges = facts.badges,
      eliteFour = facts.champion and "Defeated" or "Not yet",
      champion = facts.champion, defences = 0,
      career = facts.champion and "Trainer -> Champion" or "Trainer",
      rivalries = {}, highlights = {},
    }
  end
  local rival = rivalId and self.byId and self.byId[rivalId] or nil
  if not rival then return nil end
  local ok, record = pcall(Achievements.record, rival, {
    gyms = self.gyms,
    notable = NOTABLE,
    names = self:rivalNames(),
    playerName = self:playerFacts().name,
    tick = self.sim and self.sim.tick or 0,
    -- Rival has no label accessor of its own; LifePath owns the vocabulary,
    -- so ask it rather than writing a second copy of the mapping here.
    lifePathLabel = rival.lifePathId and LifePath.label(rival:lifePathId()) or nil,
    careerRank = rival.careerRank and rival:careerRank() or nil,
  })
  if not (ok and type(record) == "table") then return nil end
  -- The relationship LABEL is presentation, so it is resolved here rather than
  -- in the pure module: Relationships owns the vocabulary and nothing else
  -- restates it (lesson 19).
  for _, row in ipairs(record.rivalries or {}) do
    row.label = Relationships.label(row.state)
  end
  return record
end

-- A call the player placed is still a call: it belongs in the history the
-- CALL HISTORY screen reads.  Comms.record refuses any reason outside its
-- closed set, so an unknown reason is dropped rather than invented.
function M:noteCall(contactId, reason)
  if not (self.comms and contactId) then return false end
  local entry = Comms.record(self.comms, contactId, reason,
    self.sim and self.sim.tick or 0, { incoming = false })
  if entry then pcall(function() self:save() end) end
  return entry ~= nil
end

function M:tournamentLimits(mode)
  if not self.tournaments then return 0 end
  return self.tournaments:maxPlayerRivals(mode == "DOUBLE" and "DOUBLE" or "SINGLE")
end

function M:arrangeTournament(hostRivalId, count, mode, venueMap)
  if not self.tournaments then self.tournaments = Tournaments.new(self) end
  local world = self:worldView() or {}
  venueMap = venueMap or world.playerMap
  if not venueMap then return false, "You cannot arrange a tournament here." end
  local ok, line = self.tournaments:startPlayer(hostRivalId, count, mode, venueMap)
  if ok and hostRivalId then
    self:noteCall("PHONE_AIR_" .. string.upper(tostring(hostRivalId)), "TOURNAMENT")
  end
  return ok, line
end

function M:openRivalMenu(rival)
  if not (rival and self.game) then return false end
  mod.ui.push(self.game, SCREEN .. "Detail", {
    rival = rival, items = self:rivalDetailItems(rival),
  })
  return true
end

function M:interactWithRival(rival, npc)
  -- Primary path is now rivalTalkHandler (show_text → menu). This remains as
  -- a safe fallback for any direct callers: flatten the greeting onto the
  -- ticker and schedule the menu for the next idle overworld frame.
  if not rival or self.rivalInteractionOpen then return false end
  self.rivalInteractionOpen = true
  local line = self.pendingLine or (self.dialogue and self.dialogue:greeting(rival)) or (rival.name .. ".")
  self.pendingLine = nil
  local flat = tostring(line):gsub("[\n\r\v\f]+", " "):gsub("%s+", " "):match("^%s*(.-)%s*$") or ""
  self.ticker = { text = flat, age = 0, duration = 6, offset = 0 }
  self.pendingRivalMenu = rival.id
  return true
end

-- Which rival is the player facing?  The talk script runs with the overworld's
-- own notion of the talked-to object, so we resolve by position: the rival
-- standing on the cell the player is facing.
function M:facedRival()
  local where
  pcall(function()
    where = mod.world and mod.world.current and mod.world:current()
  end)
  if not where then return nil end
  local dx, dy = 0, 0
  local facing = where.facing
  if facing == "up" then dy = -1
  elseif facing == "down" then dy = 1
  elseif facing == "left" then dx = -1
  elseif facing == "right" then dx = 1 end
  local fx, fy = (where.x or 0) + dx, (where.y or 0) + dy
  local best, bestDist
  for _, rival in ipairs(self.rivals) do
    if rival.map == where.mapId then
      local rx, ry = rival.x, rival.y
      if rx == fx and ry == fy then return rival end
      if rx and ry then
        local d = math.abs(rx - fx) + math.abs(ry - fy)
        if d <= 1 and (not bestDist or d < bestDist) then
          best, bestDist = rival, d
        end
      end
    end
  end
  if best then return best end
  -- Fallback: any rival on this map (lab gauntlet)
  if where.mapId == gauntletLabId() then
    for _, rival in ipairs(self.rivals) do
      if rival.map == where.mapId then return rival end
    end
  end
  return nil
end

-- The script verb our talk rows call.  Registered through mod.commands, which
-- is the one script extension point that works on BOTH generations.
mod.commands:register("ai_rivals:talk", function(ctx)
  local rival = M:facedRival()
  if not rival then return end
  -- the intro gauntlet owns talking while it is active
  if M:gauntletActive() then
    return M:talkGauntlet(rival)
  end
  -- Talking is allowed during a battle sequence -- refusing it would leave a
  -- rival unresponsive for the whole transaction -- but it must never launch a
  -- second battle from the same frame or from an intro callback.
  if M.rivalBattleSequenceActive or M.pendingRivalBattleLaunch then
    return { { "show_text", M.dialogue:greeting(rival) } }
  end
  local wantsFight = mod.options:get("encounters")
    and AI.wantsToChallenge(rival, M:worldView())

  if wantsFight then
    M.rivalBattleSequenceId = (tonumber(M.rivalBattleSequenceId) or 0) + 1
    M.rivalBattleSequenceActive = true
    M.rivalBattleActiveRivalId = rival.id
    rival._rivalBattleSequenceId = M.rivalBattleSequenceId
    M.pending = rival
    local titleChallenge = M.playerChampion == true
      and rival.nextBadge and rival:nextBadge() == nil
      and rival.champion ~= true
    if titleChallenge then M.pendingChampion = rival end
    rival:setState("CHALLENGING_PLAYER", "talked to")
    return {
      { "show_text", titleChallenge and M.dialogue:championChallenge(rival)
          or M.dialogue:challenge(rival) },
      { "start_battle", "trainer", rival.def.trainerClass, 1 },
    }
  end
  return { { "show_text", M.dialogue:greeting(rival) } }
end)

-- THE PARTY SWAP.  This is what makes a rival battle real: the registry
-- record is a placeholder, and this hook replaces it with the rival's live
-- team the instant a battle against that class is built.  Everything the
-- engine does downstream -- stats, DVs, AI class, exp award, the payout --
-- is the vanilla trainer path, untouched.
--
-- GEN 2 passes the class NAME (or its numeric constant) and the member id;
-- the rival matches its own class, the story class it shadows, or the class
-- constant its overworld object carries.  The battle mons are built from the
-- class member's `party` rows (M:syncGen2Party keeps them live), so the
-- vanilla roster already IS the rival's team and the hook returns it after
-- refreshing the rows.

function M:contactForTrainerBattle(oppClass, partyIndex)
  if not oppClass then return nil end
  local world = self:worldView() or {}
  local mapId = world.playerMap
  if not mapId or Comms.isGymMap(mapId) then return nil end
  if not Comms.isOrdinaryTrainer(oppClass, nil, mapId) then return nil end
  local memberKey = "MEMBER_" .. tostring(tonumber(partyIndex) or 1)
  local key = Comms.contactIdForTrainer(mapId, oppClass, memberKey)
  local def = self:phoneTrainerForContact(key)
  if def then return def end
  for _, candidate in pairs((self.byTrainerClass and self.byTrainerClass[oppClass]) or {}) do
    if candidate.map == mapId then return candidate end
  end
  -- A scripted trainer with no discoverable object can still join the network.
  return {
    id = key,
    name = Comms.trainerDisplayName(oppClass),
    trainerClass = oppClass,
    partyIndex = tonumber(partyIndex) or 1,
    map = mapId,
    synthetic = true,
  }
end

mod.hooks:wrap("trainer.party", function(next, oppClass, partyIndex, party)
  local vanilla = next(oppClass, partyIndex, party)
  -- Capture a fallback contact for scripted trainer battles that do not emit
  -- world.interacted. The exact NPC identity is used when available; otherwise
  -- class+map remains stable and deterministic.
  if not M.byTrainerClass or not M.byTrainerClass[oppClass] then
    local contact = M:contactForTrainerBattle(oppClass, partyIndex)
    if contact then M.pendingTrainerContact = contact end
  end
  -- The final Gen 1 League rival is normally OPP_RIVAL3. Replace only its
  -- party; its vanilla map/script still starts the battle safely.
  if oppClass == "OPP_RIVAL3" then
    local champion = M:eliteChampion()
    if champion then
      M.pending = champion
      M.pendingChampion = champion
      if champion.prepareForBattle then champion:prepareForBattle() end
      return champion:battleParty()
    end
  end
  for _, rival in ipairs(M.rivals) do
    local match = rival.def.trainerClass == oppClass
      or (rival.def.gen2Shadow and rival.def.gen2Shadow == oppClass)
      or (type(oppClass) == "number" and M:gen2ClassId(rival) == oppClass)
    if match then
      M.pending = rival
      if M.generation == 2 then
        M:syncGen2Party(rival)
        return vanilla
      end
      return rival:battleParty()
    end
  end
  return vanilla
end)

-- GEN 2's engagement seam: fires the moment a trainer's sight cone or an A
-- press picks a trainer object, BEFORE the battle script builds its party, so
-- the class rows are fresh for this fight.  Gen 1 has no single equivalent;
-- its bookkeeping happens in trainer.party and battle.ended instead.

-- ------------------------------------------------------------------------
-- Pokégear trainer network
-- ------------------------------------------------------------------------

function M:phoneTrainerForContact(id)
  local hit = self.phoneTrainerDefs and self.phoneTrainerDefs[id]
  if hit then return hit end
  local record = self.comms and Comms.get(self.comms, id)
  local classId = record and record.trainerId
  if classId and self.byTrainerClass and self.byTrainerClass[classId] then
    for _, def in pairs(self.byTrainerClass[classId]) do return def end
  end
  return nil
end

function M:offerTrainerPhone(contact)
  if not contact or not self.comms then return false end
  local id = contact.id
  if not Comms.shouldOfferTrainer(self.seedValue or self.pathSeed or self:worldSeed(), id) then
    return false
  end
  local record = Comms.offer(self.comms, id, {
    name = contact.name,
    kind = "TRAINER",
    trainerId = contact.trainerClass,
    personality = contact.personality,
  }, self.seedValue or self.pathSeed or 0)
  if not record then return false end
  -- Trainer numbers are offered after the battle, mirroring Gold/Silver's
  -- progression instead of filling the Pokegear with strangers immediately.
  if not record.accepted and not record.declined then
    record.offered = true
    self.pendingPhoneOffer = record
    self.ticker = {
      text = tostring(contact.name) .. " wants to exchange phone numbers.",
      age = 0, duration = 6, offset = 0
    }
  end
  return true
end

function M:acceptPendingPhoneOffer(recordOrId)
  -- The offer screen receives the contact record before pendingPhoneOffer is
  -- cleared to stop the screen reopening every update frame.  Accept the
  -- screen-bound record/id first, while retaining the pending slot as a
  -- compatibility fallback for older callers.
  local record = type(recordOrId) == "table" and recordOrId
    or self.pendingPhoneOffer
  local id = type(recordOrId) == "string" and recordOrId
    or (record and record.id)
  if not id then return false end
  local ok = Comms.accept(self.comms, id)
  self.pendingPhoneOffer = nil
  return ok
end

function M:declinePendingPhoneOffer(recordOrId)
  local record = type(recordOrId) == "table" and recordOrId
    or self.pendingPhoneOffer
  local id = type(recordOrId) == "string" and recordOrId
    or (record and record.id)
  if not id then return false end
  local ok = Comms.decline(self.comms, id)
  self.pendingPhoneOffer = nil
  return ok
end

function M:trainerPhoneLine(record, tick)
  local choices = { "REMATCH", "CHAT", "GOSSIP", "WEATHER" }
  local slot = ((tonumber(tick) or 0) + #(record.id or "") + (tonumber(self.seedValue) or 0)) % #choices + 1
  local kind = choices[slot]
  if kind == "WEATHER" and self.compat and type(self.compat.weatherMap) == "function" then
    local ok, rows = pcall(self.compat.weatherMap, self.compat)
    if ok and type(rows) == "table" and #rows > 0 then
      local row = rows[((tonumber(tick) or 0) % #rows) + 1]
      return "WEATHER", ("%s called: Weather report - %s around %s."):format(
        record.name, tostring(row.weather or "CLEAR"):gsub("_", " "), tostring(row.label or row.id or "the region"))
    end
  end
  if kind == "GOSSIP" and #(self.rivals or {}) > 0 then
    local rival = self.rivals[((tonumber(tick) or 0) % #self.rivals) + 1]
    local where = rival.map and tostring(rival.map):gsub("_", " ") or "somewhere on the road"
    local badges = rival.badgeCount and rival:badgeCount() or 0
    return "CHAT", ("%s called: I heard %s is around %s with %d badge%s."):format(
      record.name, rival.name, where, badges, badges == 1 and "" or "s")
  end
  if kind == "REMATCH" then
    return "REMATCH", record.name .. " called: Want another battle sometime? Give me a call."
  end
  return "CHAT", record.name .. " called for a bit of trainer gossip and to see how your journey is going."
end

function M:updateTrainerPhoneCalls()
  if not (self.comms and self.sim) then return end
  local tick = tonumber(self.sim.tick) or 0
  if tick <= 0 or tick % 720 ~= 0 then return end
  local trainers = {}
  for _, record in ipairs(Comms.listed(self.comms)) do
    if record.kind == "TRAINER" then trainers[#trainers + 1] = record end
  end
  if #trainers == 0 then return end
  local record = trainers[((tick + (tonumber(self.seedValue) or 0)) % #trainers) + 1]
  if not Comms.mayCall(self.comms, record.id, tick, self:worldView()) then return end
  local reason, text = self:trainerPhoneLine(record, tick)
  if reason == "WEATHER" and not (self.compat and self.compat:present("weather")) then
    reason, text = "CHAT", record.name .. " called with some route gossip."
  end
  Comms.record(self.comms, record.id, reason, tick, { incoming = true })
  self.tickerQueue = self.tickerQueue or {}
  local headline = "PHONE  •  " .. text
  if self.ticker and not self.ticker.text then
    self.ticker = { text = headline, age = 0, duration = 8, offset = 0 }
  else
    self.tickerQueue[#self.tickerQueue + 1] = headline
  end
end

function M:callRival(rival)
  if not (rival and self.comms) then return false, "Rival not found." end
  local id = "PHONE_AIR_" .. string.upper(tostring(rival.id))
  local contact = Comms.get(self.comms, id)
  if not contact or not contact.accepted then
    return false, "You don't have " .. tostring(rival.name) .. "'s number."
  end
  local world = self:worldView() or {}
  local map = world.playerMap
  if not map then return false, "You can't make a call here." end
  if rival.id == self.companionId then
    return false, rival.name .. " is already accompanying you."
  end
  rival.phoneSummon = {
    map = map,
    requestedAt = self.sim and self.sim.tick or 0,
    previousObjective = rival.objective,
    previousDestination = rival.destination,
  }
  rival:setDestination(map)
  rival.objective = "PHONE_SUMMON"
  rival:setState("TRAVELLING", "called by the player")
  Comms.record(self.comms, id, "SUMMON_REPLY",
    self.sim and self.sim.tick or 0, { incoming = false })
  self:save()
  self.ticker = {
    text = rival.name .. " is on the way to " .. tostring(map) .. "!",
    age = 0, duration = 8, offset = 0
  }
  return true, rival.name .. " is coming to you."
end

function M:callContact(contactId)
  local record = self.comms and Comms.get(self.comms, contactId)
  if not record or not record.accepted then
    return false, "That number is not in your Pokegear."
  end
  local tick = self.sim and self.sim.tick or 0
  -- Player-initiated calls must not use Comms.mayCall().  That predicate is
  -- deliberately for *incoming* NPC calls and rejects any world marked busy;
  -- an open Pokegear menu is itself busy, which made CALL RIVAL impossible.
  -- Outgoing calls are staged safely (rivals travel to the player; ordinary
  -- trainers queue a rematch) and Comms.record() below still updates the
  -- shared call timestamps so NPCs cannot immediately ring back.
  if record.kind == "RIVAL" then
    local rival = self.byId[record.rivalId]
    if not rival then
      -- Older saves predate the explicit rivalId field.
      for _, r in ipairs(self.rivals or {}) do
        if ("PHONE_AIR_" .. string.upper(tostring(r.id))) == contactId then
          rival = r
          break
        end
      end
    end
    if not rival then return false, "That rival is unavailable." end
    return self:callRival(rival)
  end

  local def = self:phoneTrainerForContact(contactId)
  if not def then return false, "That trainer cannot be reached." end
  local world = self:worldView() or {}
  local map = world.playerMap
  if not map then return false, "You can't make a call here." end

  self.pendingPhoneTrainer = {
    id = contactId,
    trainerClass = def.trainerClass,
    name = def.name,
    rematches = (record.rematch or 0) + 1,
  }
  Comms.record(self.comms, contactId, "REMATCH", tick, { incoming = false })
  record.rematch = (record.rematch or 0) + 1
  self:save()
  -- Trainers are not teleported into battle. A called rematch is staged at
  -- the player's current location, using the same safe overworld battle seam
  -- as the AI rivals. The call itself never interrupts an active battle.
  self.pendingPhoneTrainer.map = map
  self.pendingPhoneTrainer.ready = true
  self.ticker = {
    text = tostring(def.name) .. " is ready for a rematch!",
    age = 0, duration = 8, offset = 0
  }
  return true, tostring(def.name) .. " is ready for a rematch."
end

function M:pushPhoneTrainerBattle(contact)
  local world = mod.world
  local def = self:phoneTrainerForContact(contact and contact.id)
  if not def then return false, "trainer definition unavailable" end
  local ow = self:getOverworld()
  if self.generation == 2 then
    if not (world and type(world.overworld) == "function") then
      return false, "no Gen 2 world facade"
    end
    local ok, err = pcall(function()
      local w = world:overworld()
      w:startBattle({
        trainer = {
          name = def.name,
          class = def.trainerClass,
          classId = def.trainerClass,
          index = def.partyIndex or 1,
          memberId = def.partyIndex or 1,
          party = {},
        },
      }, function() end)
    end)
    if ok then return true end
    return false, tostring(err)
  end
  local ok, result = pcall(function()
    local Game = self.game
    local controller = (Game and Game.overworld) or ow
    if not (controller and type(controller.pushBattle) == "function") then
      error("overworld cannot push battles")
    end
    local BattleState = require("src.battle.BattleState")
    local battle = BattleState.newTrainer(Game, def.trainerClass, def.partyIndex or 1)
    if not battle or battle.dead then error("trainer battle was refused") end
    controller:pushBattle(battle)
    return true
  end)
  if ok and result == true then return true end
  return false, tostring(result)
end

function M:resolvePhoneTrainerBattle(ev)
  local pending = self.pendingPhoneTrainer
  if not pending then return false end
  local battle = ev and ev.battle
  local oppClass = battle and (battle.oppClass or (battle.trainer and battle.trainer.classId))
  if oppClass and tostring(oppClass) ~= tostring(pending.trainerClass) then return false end
  self.pendingPhoneTrainer = nil
  return true
end

-- A Gen 1 trainer battle does not have one universal "trainer engaged" event,
-- so remember the most recent trainer object the player interacted with. The
-- battle-ended path then turns that exact NPC into a phone contact.
mod.events:on("world.interacted", function(ev)
  if not ev or ev.kind ~= "trainer" or not ev.target then return end
  local mapId = ev.mapId
  if Comms.isGymMap(mapId) then return end
  local contact = Comms.trainerFromObject(ev.target, mapId)
  if contact then
    M.pendingTrainerContact = contact
  end
end)

mod.events:on("world.trainer_engaged", function(ev)
  -- Engagement events can be emitted again while the first battle's intro is
  -- still unwinding. Ignore them until the active transaction ends.
  if M.rivalBattleSequenceActive then return end
  if M.generation ~= 2 then return end
  if not ev or not ev.trainerClass then return end
  -- the payload's trainerClass is the numeric class constant the overworld
  -- object carried (record.class), so match against the stored one
  local engaged = tonumber(ev.trainerClass) or ev.trainerClass
  local ordinary = M:contactForTrainerBattle(engaged, ev.memberId or ev.partyIndex or ev.index)
  if ordinary and Comms.isOrdinaryTrainer(ordinary.trainerClass, ordinary.name, ordinary.map) then
    M.pendingTrainerContact = ordinary
  end
  for _, rival in ipairs(M.rivals) do
    if M:gen2ClassId(rival) == engaged then
      M.pendingTrainerContact = nil
      M.pending = rival
      M:syncGen2Party(rival)
      return
    end
  end
end)

mod.events:on("battle.started", function(ev)
  M.playerMovesSeen = {}
  local party = M.game and M.game.save and M.game.save.party or {}
  local lead = party[1] and (party[1].species or party[1].speciesId)
  M.playerBattleObservation = { lead = lead, location = M:worldView().playerMap }
end)

-- The absorbed double engine can identify moves the player actually selected.
-- Single-battle builds that expose no equivalent event simply reveal no move;
-- they never fall back to reading the complete save-party moveset.
mod.events:on("mod.ai_rivals.player_move_revealed", function(ev)
  local species, move = ev and ev.species, ev and ev.move
  if type(species) ~= "string" or type(move) ~= "string" then return end
  M.playerMovesSeen = M.playerMovesSeen or {}
  M.playerMovesSeen[species] = M.playerMovesSeen[species] or {}
  M.playerMovesSeen[species][move] = true
end)

local function applyRevealedPlayerMoves(rival)
  if not (rival and rival.rememberRevealedMove) then return end
  for species, moves in pairs(M.playerMovesSeen or {}) do
    for move in pairs(moves) do
      rival:rememberRevealedMove("player", species, move)
    end
  end
end

mod.events:on("battle.ended", function(ev)
  M.worldChallenge = nil
  -- Ordinary Kanto trainers outside gyms join the phone network after a
  -- successful battle. The contact is created once and never duplicated.
  local trainerContact = M.pendingTrainerContact
  local phoneBattle = M.pendingPhoneTrainer
  if trainerContact and not phoneBattle then
    local playerWon = (ev and ev.result) == "win"
    if playerWon and not Comms.isGymMap(trainerContact.map) then
      M:offerTrainerPhone(trainerContact)
    end
  end
  M.pendingTrainerContact = nil
  M._gauntletStarting = false
  M._gauntletQueued = false
  local battle = ev and ev.battle
  local oppClass = battle and (battle.oppClass
    or (battle.trainer and battle.trainer.classId))
  if M.pendingPhoneTrainer and
     (not oppClass or tostring(oppClass) == tostring(M.pendingPhoneTrainer.trainerClass)) then
    M.pendingPhoneTrainer = nil
  end
  -- Vanilla lab rival (Blue / OPP_RIVAL1): unlock the AI gauntlet walk-up
  if oppClass == "OPP_RIVAL1" or oppClass == "RIVAL1"
     or oppClass == "OPP_RIVAL" or tostring(oppClass):match("RIVAL1") then
    M.blueBattled = true
    -- Kick the AI gauntlet the moment Blue's fight ends
    if M.gauntlet and M.gauntlet.active and not M:gauntletDone() then
      M.gauntlet.phase = "approach"
      M.gauntlet.phaseT = 0
      M.gauntlet.approachAge = 0
      M.gauntlet.challenging = false
    end
  end
  -- Also accept the flag if the engine set it during the battle script
  pcall(function()
    if M:blueLabBattled() then M.blueBattled = true end
  end)

  local rival, activeId = BattleFlow.endedRival(M)
  if not rival then
    -- A completed locked battle with a lost pending pointer must still unlock.
    if activeId then M:releaseRivalBattleSequence(activeId) end
    return
  end
  local championBattle = M.pendingChampion == rival
  if oppClass then
    local matched = BattleFlow.matches(M, rival, activeId, oppClass,
                                       championBattle)
    if not matched then return end
  end
  M.pending = nil
  M.pendingChampion = nil
  if championBattle then M.eliteChampionId = nil end

  -- ev.result is from the PLAYER's side, so a player win is a rival loss
  local playerWon = (ev and ev.result) == "win"
  Util.guard("battle.ended", function()
    rival:recordPlayerBattle(not playerWon, M.sim and M.sim.tick or 0)
    if rival.rememberOpponent then
      local playerParty = M.game and M.game.save and M.game.save.party
      rival:rememberOpponent("player", playerParty, not playerWon,
        M.sim and M.sim.tick or 0, false)
      applyRevealedPlayerMoves(rival)
    end
    -- 1.33.0: the battle the player just fought is the strongest cause there
    -- is.  Recorded from the RIVAL's side (it won or it lost), with the badge
    -- gap so a rival far ahead of the player can become a MENTOR rather than
    -- simply a repeated winner.
    M:recordBondBattle(rival, "player", not playerWon,
      { lead = rival:badgeCount() - M:playerBadgeCount() })
    -- 1.34.0: a battle the player fought counts toward the rival's team
    -- service record exactly as a simulated one does, and repeated defeats at
    -- the player's hands are evidence for building specifically against them.
    if rival.creditLeadBattle then rival:creditLeadBattle(not playerWon) end
    -- 1.35.0: §4's arc begins here. Losing to the player opens a setback the
    -- rival has to answer; beating the player later closes it, and the chapter
    -- turns from SETBACK through REBUILDING to RESURGENT as it does.
    if playerWon and rival.noteDefeat then
      rival:noteDefeat("player", M.sim and M.sim.tick or 0)
    elseif not playerWon and rival.noteVictory then
      rival:noteVictory("player", M.sim and M.sim.tick or 0)
    end
    if rival.advanceStory then
      local ok, gained, chapter, chapterChanged, _, notable =
        pcall(rival.advanceStory, rival, M.sim and M.sim.tick or 0)
      if ok then
        for _, milestone in ipairs(gained or {}) do
          M:addNews(rival, { kind = "milestone", milestone = milestone.id,
                             notable = milestone.news == true })
        end
        if chapterChanged and notable then
          M:addNews(rival, { kind = "chapter", chapter = chapter })
        end
      end
    end
    if playerWon and rival.observeTeamEvidence then
      rival:observeTeamEvidence("PLAYER_PROBLEM")
      local _, after, changed = rival:observeTeamEvidence("BEATEN_BADLY")
      if changed then
        M:addNews(rival, { kind = "team_style", style = after })
      end
    elseif not playerWon and rival.observeTeamEvidence then
      local _, after, changed = rival:observeTeamEvidence("WON_QUICKLY")
      if changed then
        M:addNews(rival, { kind = "team_style", style = after })
      end
    end
    if rival.rememberPlayerBattle then
      local observation = M.playerBattleObservation or {}
      observation.rivalWon = not playerWon
      observation.tick = M.sim and M.sim.tick or 0
      observation.species, observation.moves = {}, {}
      for _, slot in ipairs((M.game and M.game.save and M.game.save.party) or {}) do
        local species = slot and (slot.species or slot.speciesId)
        if type(species) == "string" then observation.species[#observation.species + 1] = species end
      end
      for _, moves in pairs(M.playerMovesSeen or {}) do
        for move in pairs(moves) do observation.moves[#observation.moves + 1] = move end
      end
      rival:rememberPlayerBattle(observation)
    end
    if championBattle and playerWon then
      rival.champion = false
      M.playerChampion = true
      M.eliteChampionId = "blue"
      M:recordBond(rival, "player", "TITLE_LOST")
      M:addNews(rival, { kind = "news",
        text = "The player dethroned " .. tostring(rival.name) .. "." })
    elseif championBattle and not playerWon and M.playerChampion then
      for _, other in ipairs(M.rivals) do other.champion = false end
      rival.champion = true
      M.playerChampion = false
      M.eliteChampionId = rival.id
      M:recordBond(rival, "player", "TITLE_TAKEN")
      rival.newsPending = "CHAMPION"
      M:addNews(rival, { kind = "news",
        text = tostring(rival.name) .. " dethroned the player." })
    end
    if playerWon then
      -- Engine trainer battles use a defensive party copy, so the rival's
      -- saved HP was previously still full here and AI.evaluate could never
      -- detect a blackout. A player victory is a full defeat: faint the saved
      -- party, warp to the nearest Center, then let the normal HEALING tick
      -- restore it.
      rival:setState("DEFEATED", "lost to the player")
      if rival.blackoutToNearestPokemonCenter then
        rival:blackoutToNearestPokemonCenter("lost to the player", true)
      else
        for _, slot in ipairs(rival.party or {}) do slot.hp = 0 end
        AI.evaluate(rival, M:worldView())
      end
      local loot = M:awardRivalLoot(rival)
      if loot then
        M.pendingLootLine = string.format("%s handed over\na %s!", rival.name, tostring(loot):gsub("_", " "))
      end
      -- 1.15.0: a beaten rival may also part with a small healing item as a
      -- consolation.  It is a real item out of its bag, into the player's.
      if rival.pickGiftItem and rival.rng:chance(0.4) then
        -- Transfer first and debit last: a full/unknown player bag must not
        -- delete an item from the rival's persistent inventory.
        rival:ensureInventory()
        local gifts = {}
        local badges = M:playerBadgeCount()
        for item, count in pairs(rival.inventory or {}) do
          if tonumber(count) and count > 0
             and M:rivalGiftAllowed(item, badges) then
            gifts[#gifts + 1] = item
          end
        end
        local gift = #gifts > 0 and gifts[rival.rng:int(1, #gifts)] or nil
        if gift and M:givePlayerItem(gift) and rival:takeItem(gift) then
          local text = string.format("%s gives you a %s.", rival.name,
                                     tostring(gift):gsub("_", " "))
          M.pendingGiftLine = text
          M:addNews(rival, { kind = "news", text = text })
        end
      end
    end
    local line = championBattle and M.dialogue:championChallenge(rival)
      or M.dialogue:afterBattle(rival, not playerWon)
    if M.pendingLootLine then
      line = (line or "") .. "\f" .. M.pendingLootLine
      M.pendingLootLine = nil
    end
    if M.pendingGiftLine then
      line = (line or "") .. "\f" .. M.pendingGiftLine
      M.pendingGiftLine = nil
    end
    if line then M.pendingLine = line end
  end)

  -- the intro gauntlet: win OR loss -- advance the turn / leave the lab
  M:endGauntletBattle(rival)
  -- If the player blacked out mid-sequence, ensure rivals still depart
  if M.gauntlet and M.gauntlet.active and M.gauntlet.index > #(M.gauntlet.order or {}) then
    M:finishGauntlet()
  end
  if M.pendingTournamentMatch and M.tournaments then
    M.pendingTournamentMatch = nil
    pcall(function() M.tournaments:onPlayerBattleResult(rival.id, playerWon) end)
  end
  M.tournamentExpActive = false
  -- Release after bookkeeping and gauntlet progression, on every normal
  -- battle result (not only blackout).
  M:releaseRivalBattleSequence(rival.id)
end)

-- The post-battle line rides the next talk rather than fighting the engine's
-- own victory text for the same box.

-- Player blackout (loss): still end the gauntlet fight turn and, if that was
-- the last rival (or any lab fight), release them into the world the same as
-- a win.  win/loss is already recorded on battle.ended when it fires; on pure
-- blackout without a clean battle.ended we still finish the lab sequence.
mod.events:on("world.blacked_out", function(ev)
  local blackoutRival = M.pending
    or (M.rivalBattleActiveRivalId and M.byId[M.rivalBattleActiveRivalId])
  pcall(function()
    if not M:gauntletActive() then return end
    local rival = blackoutRival or M:gauntletRival()
    if rival then
      -- Rival won this bout
      pcall(function()
        rival:recordPlayerBattle(true, M.sim and M.sim.tick or 0)
        if rival.rememberOpponent then
          local playerParty = M.game and M.game.save and M.game.save.party
          rival:rememberOpponent("player", playerParty, true,
            M.sim and M.sim.tick or 0, false)
          applyRevealedPlayerMoves(rival)
        end
      end)
      M:endGauntletBattle(rival)
    else
      -- No current rival pointer -- still release the lab
      M:finishGauntlet()
    end
    -- Force full release if somehow still stuck in lab after a loss
    if M:gauntletActive() then
      M:finishGauntlet()
    end
  end)

  -- Release only after ALL battle bookkeeping and gauntlet progression have
  -- completed. Releasing earlier is what left the re-entrancy window open: an
  -- intro callback or a nearby rival could start the same battle again while
  -- the first was still settling its memory, relationship and career credit.
  --
  -- Guarded on identity so a battle that is NOT the locked one cannot release
  -- somebody else's transaction.
  M:releaseRivalBattleSequence(blackoutRival and blackoutRival.id or nil)
end)

mod.events:on("world.interacted", function(ev)
  if not ev then M.pendingLine = nil return end
  local kind = ev.kind and tostring(ev.kind):lower() or nil
  if kind and kind ~= "npc" then M.pendingLine = nil return end
  if M:gauntletActive() then return end -- opening lab talk owns progression
  local npc = ev.npc or ev.target or ev.object
  local npcId = ev.npcId or ev.id
  if not npcId and npc then
    pcall(function() npcId = npc.id or npc.name or (npc.def and npc.def.name) end)
  end
  local npcName
  pcall(function() npcName = npc and (npc.name or (npc.def and npc.def.name)) end)
  local rival = M:rivalAtNpc(npcId) or M:rivalAtNpc(npcName) or M:facedRival()
  if not rival then return end
  -- Mark handled for event buses that support cancellation; harmless on buses
  -- where world.interacted is notification-only.
  ev.handled, ev.cancelled = true, true
  Util.guard("interact:" .. tostring(rival.id), function()
    M:interactWithRival(rival, npc)
  end)
end)

------------------------------------------------------------------------
-- Engine seams
------------------------------------------------------------------------

-- Boot order in gen1recomp (src/core/Game.lua):
--   first load:  save.created  →  game.ready
--   title NEW GAME:  game.ready already happened  →  save.created
-- So save.created can fire BOTH before ready (boot skeleton) and after
-- (actual New Game).  We defer the first case and always run the second.

local function startOrSeedRivals()
  if not M.ready then
    M.pendingGauntlet = true
    return
  end
  M.pendingGauntlet = false
  -- Restore first so a finished playthrough is not treated as New Game
  pcall(function() M:load() end)
  if M:gauntletDone() then
    -- Already completed intro: keep restored world positions
    for _, rival in ipairs(M.rivals) do
      if not rival.map or rival.map == "" then
        pcall(function() M:seed(rival) end)
      end
    end
  elseif not M:gauntletActive() then
    if not M:beginGauntlet() then
      for _, rival in ipairs(M.rivals) do M:seed(rival) end
    end
  end
  M:syncGen2Parties()
  M.sprites:resolve(M.data, true)
  local world = M:worldView()
  if world and world.playerMap then
    Util.guard("spawn:start", function() M:spawnFor(world.playerMap) end)
  end
end

mod.events:on("game.ready", function(ev)
  M.game = ev.game
  Util.guard("compat:kanto-potion", function()
    if KantoCompat.install(M.compat) then
      mod.log:info("AI Rivals installed Kanto Reforged Potion compatibility")
    end
  end)
  M:build(ev.game.data)
  M:load()
  -- Re-register trainers/talk/onEnter against the REAL merged data.  The
  -- entry-chunk registration often sees nil boot data and skips maps.
  Util.guard("register:ready", function()
    registerTrainers(ev.game.data)
    registerTalkScripts(ev.game.data)
  end)
  pcall(function() M.sprites:resolve(M.data, true) end)
  if M.pendingGauntlet then
    startOrSeedRivals()
  end
end)

mod.events:on("save.loaded", function()
  if not M.ready then return end
  M:load()
  M.sprites:resolve(M.data, true)
  M:despawnAll()
end)

mod.events:on("save.created", function()
  startOrSeedRivals()
end)

-- save.write is a veto hook: capture our state into the bucket BEFORE the
-- engine serializes, then always call next so a normal save proceeds.
mod.hooks:wrap("save.write", function(next, game)
  Util.guard("save", function() M:save() end)
  return next(game)
end)

mod.events:on("map.entered", function(ev)
  if not M.ready then return end
  M.walkMapCache = nil
  local mapId = ev and ev.mapId
  -- Prefer the live overworld id when the event is sparse
  if not mapId and mod.world and mod.world.current then
    local ok, cur = pcall(function() return mod.world:current() end)
    if ok and cur then mapId = cur.mapId end
  end
  if not mapId then return end
  M.companionTrailHead, M.companionTrailGoal = nil, nil

  local companion = M.byId[M.companionId]
  if companion and M:gauntletDone() then
    local missing = companion.missingHMForMap
      and companion:missingHMForMap(mapId)
    if missing then
      -- Do not teleport a companion through a field obstacle it cannot clear.
      -- It remains on its previous map and resumes its own HM recovery goal.
      M.companionId = nil
      M.companionYieldMap = nil
      local line = companion.name .. " stayed behind to find a Pokémon for "
        .. Util.spaced(missing) .. "."
      M:addNews(companion, { kind = "news", text = line })
      M:startHmRecovery(companion, missing)
    else
      if companion.useHMsForMap then companion:useHMsForMap(mapId) end
      companion.map, companion.x, companion.y = mapId, nil, nil
      if companion.visitMap then companion:visitMap(mapId) end
      companion.destination, companion.route = nil, nil
      companion.travelReason = "Accompanying the player"
      M.companionYieldMap = nil
    end
  end

  local lab = resolveGauntletLab(M.graph)
  -- Entering the lab: force the gauntlet ONLY if it has never been completed.
  -- Once gauntletFinished is set the sequence is permanently closed.
  if lab and mapId == lab and not M:gauntletDone() then
    Util.guard("gauntlet:enter", function()
      M:beginGauntlet()
      for _, r in ipairs(M.rivals) do
        r.map = mapId
        if #r.party == 0 then
          local species = Rival.firstAvailableStarter(r.def, M.versionKey,
                                                      M.data and M.data.pokemon,
                                                      nil, M:starterOpts())
          if species then r:addPokemon(species, 5) end
        end
      end
    end)
  end

  M:despawnAll()
  local n = 0
  local ok, result = pcall(function() return M:spawnFor(mapId) end)
  if ok then n = result or 0 end
  -- Retry once with safe sprites only if nothing appeared on the lab map
  if lab and mapId == lab and n == 0 then
    for _, r in ipairs(M.rivals) do
      r.map = mapId
      M.spawned[r.id] = nil
    end
    pcall(function() M:spawnFor(mapId) end)
  end
end)

-- The Choose Your Hero answers arrive here (now from our own intro steps) as
-- the player gives them; this is the authoritative signal for which
-- character-creation walkers are going spare.
mod.events:on("intro.oak_speech.answered", function(ev)
  Util.guard("intro.answer", function()
    if not (ev and ev.saveKey) then return end
    if ev.saveKey == "ai_rivals_count" then
      -- Clamped to the ROSTER, not to four: the gauntlet cap and the number
      -- of rivals in the world are separate numbers as of 3.3.
      local count = math.max(1,
        math.min(#ROSTER, math.floor(tonumber(ev.value) or #ROSTER)))
      mod.save:set("aiRivalCount", count)
      M:setRivalCount(count)
      return
    end
    if ev.saveKey == "ai_rivals_gauntlet" then
      if ev.value == "skip" then
        M:skipGauntlet("chosen at character creation")
      else
        pcall(function() mod.save:set("gauntletMode", "play") end)
      end
      return
    end
  end)
end)

-- THE TICK.  One accumulator, gated inside Simulation:update, bounded per
-- tick.  next() is always called: a mod that skipped it would pause the game.
mod.hooks:wrap("core.update", function(next, game, dt)
  local result = next(game, dt)
  -- Never touch rival logic during Oak speech / naming / title.
  if not M.ready then return result end
  -- Whole-body timer for the FRAME row (PERFORMANCE screen). SIM/WALK below
  -- only see their own regions; this is the one number that sees F1/F2/F4-F7
  -- from docs/performance.md too. Every branch below funnels back to the
  -- unconditional `return result` after the pcall (an early `return result`
  -- inside just ends the pcall'd closure -- pcall still returns normally and
  -- execution reaches the same place), so one measurement here covers them
  -- all without instrumenting each branch.
  local frameStarted = performanceClockMs()
  local ok, err = pcall(function()
  if M.perf and (M.perf.autoLowSeconds or 0) > 0 then
    M.perf.autoLowSeconds = math.max(0,
      M.perf.autoLowSeconds - (tonumber(dt) or 0))
  end
  local world = M:worldView()
  local playerMap = world and world.playerMap
  -- A simulation tick can include route planning, PC management and a full
  -- headless battle. Running that synchronously every 1.5 seconds produced a
  -- regular hitch after roughly four player steps. Detect tile motion and let
  -- simulation time advance only after the player has naturally paused.
  RuntimePolicy.trackPlayerMotion(M, world, dt)
  if M.ticker and M.ticker.text then
    M.ticker.age = (M.ticker.age or 0) + (tonumber(dt) or 0)
    M.ticker.offset = (M.ticker.offset or 0) + 32 * (tonumber(dt) or 0)
    if M.ticker.age >= (M.ticker.duration or 8) then
      local nextHeadline = M.tickerQueue and table.remove(M.tickerQueue, 1)
      if nextHeadline then
        M.ticker = { text = nextHeadline, age = 0, duration = 8, offset = 0 }
      else
        M.ticker.text = nil
      end
    end
  end
  -- No overworld yet (naming / intro, etc.)
  if not playerMap then return end

  -- Dialogue-complete manual challenges own this frame. Launching before
  -- background simulation prevents the rival from walking away or changing
  -- state between accepting the fight and BattleState construction.
  if M:updatePendingRivalBattle(dt) then return result end

  if M.pendingPhoneOffer and M:overworldIdle() then
    mod.ui.push(game, "AIR_PokegearOffer", { contact = M.pendingPhoneOffer })
    M.pendingPhoneOffer = nil
    return result
  end

  if M.pendingPhoneTrainer and M.pendingPhoneTrainer.ready and M:overworldIdle() then
    local contact = M.pendingPhoneTrainer
    M.pendingPhoneTrainer.ready = false
    local ok, err = M:pushPhoneTrainerBattle(contact)
    if not ok then
      M.pendingPhoneTrainer = nil
      M.ticker = { text = "NOTICE  • " .. tostring(err),
        age = 0, duration = 8, offset = 0 }
    end
    return result
  end

  -- Close the menu before changing overworld state. This keeps all choices
  -- responsive on desktop and touch builds and prevents actions targeting the
  -- menu screen instead of the active map.
  if M.pendingRivalAction then
    local action = M.pendingRivalAction
    action.age = (tonumber(action.age) or 0) + (tonumber(dt) or 0)
    local strict = M:overworldIdle()
    local fallback = M:overworldRunnerIdle() and (
      (action.value ~= "_challenge" and action.age >= 0.08)
      or action.age >= 0.35)
    if strict or fallback then
      M.pendingRivalAction = nil
      local rival = M.byId[action.rivalId]
      local called, ok, line = pcall(M.performRivalAction, M, rival, action.value)
      if not called then
        ok, line = false, "Rival action failed: " .. tostring(ok)
        Util.lastError = tostring(line)
      end
      M.ticker = { text = (ok and "RIVAL LINK  •  " or "NOTICE  •  ")
        .. tostring(line or "Nothing happened."), age = 0, duration = 8, offset = 0 }
    end
    return result
  end

  -- Defer the menu push until an idle overworld frame. Always return while it
  -- is pending so background simulation cannot race the UI handoff.
  if M.pendingRivalMenu then
    local pending = M.pendingRivalMenu
    if type(pending) ~= "table" then pending = { rivalId = pending, age = 0 } end
    pending.age = (tonumber(pending.age) or 0) + (tonumber(dt) or 0)
    M.pendingRivalMenu = pending
    if M:overworldIdle() or (pending.age >= 0.25 and M:overworldRunnerIdle()) then
      local rival = M.byId[pending.rivalId]
      M.pendingRivalMenu = nil
      M.rivalInteractionOpen = false
      if rival then
        local opened, err = pcall(function() return M:openRivalMenu(rival) end)
        if not opened then Util.lastError = "rival menu: " .. tostring(err) end
      end
    end
    return result
  end

  -- Intro lock: until the lab gauntlet is finished, keep everyone in the lab
  -- and pause world simulation so they cannot wander to Pewter/Viridian.
  -- Safety: if gauntlet is finished but anyone is still marked in the lab,
  -- push them out once so the world sim can take over.
  if M:gauntletDone() then
    local stuck = false
    for _, r in ipairs(M.rivals) do
      if r.map == gauntletLabId() then stuck = true break end
    end
    if stuck then
      pcall(function() M:finishGauntlet() end)
      -- finish is no-op if already finished; force scatter
      for i, r in ipairs(M.rivals) do
        if r.map == gauntletLabId() then
          -- 2.10.0: same reasoning as postLabStarts -- a Gold rescue must not
          -- drop a stuck rival into Kanto.
          local starts = postLabStarts()
          local start = (starts[i] and starts[i].map)
            or (starts[1] and starts[1].map) or "ROUTE_1"
          r.map = start
          r.x, r.y = nil, nil
          r.destination = "PEWTER_CITY"
          pcall(function() r:setState("TRAVELLING", "forced leave") end)
          pcall(function() AI.evaluate(r, M:worldView()) end)
        end
      end
      pcall(function() M:despawnAll() end)
    end
  end

  -- SKIP releases positions immediately but not simulation time. Oak's intro
  -- contains long idle dialogue stretches that previously let every rival
  -- grind to Lv13-14 before the player could leave the lab.
  if M.worldStartPending then
    local party = M.game and M.game.save and M.game.save.party
    local hasStarter = type(party) == "table" and #party > 0
    if hasStarter and M:blueLabBattled() then
      M.worldStartPending = false
      pcall(function() M:save() end)
    else
      return result
    end
  end

  if not M:gauntletDone() then
    if playerMap == gauntletLabId() then
      for _, r in ipairs(M.rivals) do
        r.map = playerMap
        r.destination = nil
        r.route = nil
      end
      if not M:gauntletDone() and (not M.gauntlet or not M.gauntlet.active) then
        local ok, err = pcall(function() return M:beginGauntlet() end)
        if not ok then
          Util.lastError = "beginGauntlet: " .. tostring(err)
        end
        -- Do NOT invent an active gauntlet that clears gauntletFinished
      end
      local need = false
      for _, r in ipairs(M.rivals) do
        if not M.spawned[r.id] then need = true break end
      end
      if need then
        pcall(function() M:despawnAll() end)
        local ok, err = pcall(function() return M:spawnFor(playerMap) end)
        if not ok then
          Util.lastError = "spawn: " .. tostring(err)
        end
      end
      -- Auto walk-up + challenge in roster order, but never spend an A* search
      -- in the same frame as player movement.
      if not (world and world.playerMoving) then
        pcall(function() M:gauntletDirector(dt) end)
      end
    end
    return result
  end

  -- Simulation time belongs to the world, not to the player's feet. Visible
  -- rivals are already protected by ctx.near inside Simulation.tickRival, so
  -- keep off-screen rivals moving/healing while the player walks.
  if M.sim then
    Util.guard("tick", function()
      -- Options may be changed from the Mods menu during an existing save;
      -- apply the selected profile without requiring a restart.
      local performance = mod.options:get("performance") or "balanced"
      RuntimePolicy.configure(M.sim, performance,
        PACE[mod.options:get("pace")] or PACE.normal)
      if M.rivalContext then
        M.rivalContext.relationships = M:relationshipsEnabled()
      end
      local ran = false
      local alreadyHere = {}
      if playerMap then
        for _, rival in ipairs(M.rivals) do
          if rival.map == playerMap then alreadyHere[rival.id] = true end
        end
      end
      local perfStarted = performanceClockMs()
      local ok, err = pcall(function()
        ran = M.sim:update(dt, M.rivals, world)
      end)
      M:recordPerformance("simulation", perfStarted)
      if not ok then
        Util.lastError = "tick:" .. tostring(err):gsub("%s+", " "):sub(1, 80)
      end
      if ran and M.tournaments then
        pcall(function() M.tournaments:maybeAutonomous(M.sim and M.sim.tick or 0) end)
      end
      if ran and playerMap then
        -- Training, evolution and headless battles alter only rival data. Do
        -- not re-run runtime-NPC materialisation after every world tick: on
        -- some engine builds rebuilding the live object layer invokes the
        -- screen transition/fade. Materialise only a rival that genuinely
        -- crossed onto the player's map during this tick.
        local arrived = false
        for _, rival in ipairs(M.rivals) do
          if rival.map == playerMap and not alreadyHere[rival.id]
             and not M.spawned[rival.id] then arrived = true break end
        end
        if arrived then pcall(function() M:spawnFor(playerMap) end) end
      end
    end)
  end

  -- 4.5.0: the same door every other overworld effect goes through. A
  -- tournament is arranged from inside the Pokegear, so without this gate the
  -- first match could construct itself while four menus were still stacked
  -- over the map -- dialogue running under a list the player is still reading.
  if M.tournaments and not (world and world.playerMoving) and M:overworldIdle() then
    pcall(function() M.tournaments:updatePending() end)
  end

  -- 1.36.0 §13: what the player noticed this tick. Read-only with respect to
  -- every rival, and rate-limited inside Presence, so it costs a handful of
  -- comparisons per tick and cannot spam the news channel.
  if playerMap and not (world and world.playerMoving) then
    Util.guard("presence", function() M:observePresence(playerMap, world) end)
  end

  if M.phone then
    Util.guard("phone", function() M.phone:update(dt, M.rivals, world) end)
  end
  Util.guard("trainer phone", function() M:updateTrainerPhoneCalls() end)

  -- 2.1.0: a life-path decision is checked rarely and only for the rival whose
  -- turn it is, because at most two rivals in a save can ever take one and the
  -- pressure that drives it moves over hours, not ticks. One rival per sweep
  -- keeps this off the per-tick budget entirely (§34).
  if M.sim and M.lifePathsEnabled and M:lifePathsEnabled()
     and (M.sim.tick or 0) % 240 == 0 and #M.rivals > 0 then
    Util.guard("lifepath", function()
      local index = ((M.sim.tick / 240) % #M.rivals) + 1
      local rival = M.rivals[math.floor(index)]
      -- A rival still on the Gym Challenge may diverge; one already living
      -- another life may move ALONG its arc. Never both in the same sweep.
      if rival and rival.onGymChallenge and rival:onGymChallenge() then
        M:considerLifePath(rival)
      else
        M:considerTransition(rival)
      end
    end)
  end

  -- Autonomous presentation stays idle during player motion; the companion's
  -- lightweight entity trail is allowed to advance alongside the player.
  local walkingStarted = performanceClockMs()
  pcall(function() M:worldWalkDirector(dt, world) end)
  M:recordPerformance("walking", walkingStarted)

  -- Rivals already spawn passable/through (see the objDef in spawnFor), but
  -- a rival occasionally still ends up somewhere the player cannot get past
  -- it -- a doorway, a one-tile corridor. Rather than depend on understanding
  -- exactly which case that is, relieve it directly: standing still, pressed
  -- against a spawned rival, for a few real seconds nudges that ONE rival to
  -- a free neighbouring tile instead of leaving the player stuck.
  pcall(function() M:relievePathBlock(world) end)

  -- World duels: sometimes a nearby rival walks up and challenges you.
  if mod.options:get("encounters") and playerMap and world
     and not M:gauntletActive() and not M.worldChallenge then
    Util.guard("worldDuel", function()
      local px, py = world.playerX, world.playerY
      if not px then return end
      for _, rival in ipairs(M.rivals) do
        if rival.map == playerMap and rival.x and rival.y
           and #rival.party > 0 then
          local dist = math.abs(rival.x - px) + math.abs(rival.y - py)
          if dist <= 2 and AI.wantsToChallenge(rival, world) then
            local accepted = M:startRivalChallenge(rival)
            if accepted then
              M.worldChallenge = true
              rival.stateReason = "world duel"
              break
            end
          end
        end
      end
    end)
  end
  end) -- pcall core.update body
  if not ok then
    Util.lastError = "tick: " .. tostring(err)
  end
  -- Deliberately not M:recordPerformance -- that function feeds slowStrikes /
  -- autoLowSeconds, and adding a measurement must not change when the mod
  -- decides it is struggling. Same average/maximum math, no side effects.
  local frameFinished = performanceClockMs()
  if frameStarted and frameFinished and M.perf and M.perf.frame then
    local row = M.perf.frame
    local elapsed = math.max(0, frameFinished - frameStarted)
    row.samples = (row.samples or 0) + 1
    row.average = row.samples == 1 and elapsed
      or (row.average * 0.9 + elapsed * 0.1)
    row.maximum = math.max(row.maximum or 0, elapsed)
  end
  return result
end)

-- Screen-space world-news ticker. render.hud runs after the completed game
-- frame, so the headline remains readable without pausing or opening a menu.
mod.hooks:wrap("render.hud", function(next, game, viewport)
  local result = next(game, viewport)
  if mod.options:get("news_ticker") == false then return result end
  local ticker = M.ticker
  local top = game and game.stack and game.stack.top and game.stack:top()
  if not (ticker and ticker.text and top and top.isOverworld
          and love and love.graphics) then return result end
  local g = love.graphics
  local ww = g.getWidth and g.getWidth() or 160
  local font = g.getFont and g.getFont()
  local fh = font and font:getHeight() or 8
  local h = math.max(18, fh + 8)
  local alpha = 0.88
  local left = math.max(0, (ticker.duration or 8) - (ticker.age or 0))
  if left < 1 then alpha = alpha * left end
  -- love.graphics state is global.  push()/pop() without the "all" argument
  -- preserves only the transform on older LÖVE builds, so the ticker's fading
  -- alpha used to leak into the next game frame and fade the entire screen.
  -- Save and restore every state value changed here explicitly for compatibility
  -- with both the original engine and newer runtimes.
  local oldR, oldG, oldB, oldA = g.getColor()
  local oldSX, oldSY, oldSW, oldSH = g.getScissor()
  g.push()
  g.setColor(0.02, 0.04, 0.08, alpha)
  g.rectangle("fill", 0, 0, ww, h)
  g.setColor(0.25, 0.75, 1.0, alpha)
  g.rectangle("fill", 0, h - 2, ww, 2)
  g.setScissor(5, 0, math.max(1, ww - 10), h)
  local textW = font and font:getWidth(ticker.text) or #ticker.text * 6
  local x = 8
  if textW > ww - 16 then
    local cycle = textW + ww
    x = ww - ((ticker.offset or 0) % cycle)
  end
  g.setColor(1, 1, 1, alpha)
  g.print(ticker.text, math.floor(x), math.floor((h - fh) / 2))
  g.pop()
  if oldSX ~= nil then
    g.setScissor(oldSX, oldSY, oldSW, oldSH)
  else
    g.setScissor()
  end
  g.setColor(oldR, oldG, oldB, oldA)
  return result
end)

------------------------------------------------------------------------
-- Status screens and debug verbs
------------------------------------------------------------------------
-- Both were extracted in 4.6.1: ~760 lines of presentation and console verbs
-- that only ever read the manager through its public methods. They install
-- HERE, not at the bottom of the file, because hook registration order is
-- observable -- Status installs a `ui.start_menu.items` wrap that must still
-- run before the one Pokegear installs from installIntro() below.

Status.install(mod, M, SCREEN)
Commands.install(mod, M)
------------------------------------------------------------------------
-- Load-time work
------------------------------------------------------------------------
-- Order matters: capture the vanilla walkers BEFORE the Choose Your Hero
-- intro swap rewrites SPRITE_RED/SPRITE_BLUE at game.ready, or the art the
-- rivals borrow would be whatever the player picked rather than what they
-- did not.

-- Trainers/talk/sprites registered on game.ready only (avoids New Game crashes)
--
-- NO INFORMATION MUST MEAN ZERO, NOT A DEFAULT.  At the entry chunk `mod.game`
-- is frequently not up yet, so `bootData` is nil -- and `detectGeneration(nil)`
-- answers 1, because its question is "does this dataset look like Gold" and an
-- absent dataset does not.  Registering on that answer put Gen 1 map_scripts
-- onto a Gold boot, which the loader reports as "the map_scripts registry has
-- no Gen 2 target" in the mod manager's error feed on every single launch.
--
-- An unknown generation is not Gen 1; it is unknown.  Skip, and let game.ready
-- register against the REAL merged data, which it already does unconditionally
-- a few lines further down.  Nothing is lost by waiting: the comment above has
-- always said game.ready is the authoritative registration.
local bootData = mod.game and mod.game.data
local bootKnown = bootData ~= nil
  and (bootData.maps ~= nil or bootData.gen2Maps ~= nil
       or bootData.gen2Trainers ~= nil)
if bootKnown then
  pcall(function() registerTrainers(bootData) end)
  pcall(function() registerTalkScripts(bootData) end)
else
  mod.log:info("boot data not up yet; trainers/talk register at game.ready")
end

-- Character selection is intentionally not installed. The vanilla rival naming
-- screen remains, and sprite selection is derived from the chosen rival name.
local compat = Compat.new(mod)
M.compat = compat
pcall(function() WonderTrade.install(mod, M) end)




------------------------------------------------------------------------
-- Intro additions. Character/gender/sprite selection is intentionally absent.
-- The vanilla rival naming screen remains untouched; AI Rivals only adds the
-- optional rival-count and opening-gauntlet choices.
------------------------------------------------------------------------
do
  local function installIntro()
    if not (mod.hooks and mod.hooks.wrap) then
      print("[ai_rivals] no mod.hooks.wrap")
      return
    end
    if not (mod.ui and mod.ui.insertStepBefore and mod.ui.insertStepAfter) then
      print("[ai_rivals] no mod.ui step helpers")
      return
    end
    mod.hooks:wrap("intro.oak_speech.build", function(next, steps, speech)
      steps = next(steps, speech)
      if type(steps) ~= "table" then return steps end

      local choices, values = RosterPolicy.creationChoices(#ROSTER)
      local anchor = "ask_player_name"
      if #choices > 1 then
        mod.ui.insertStepAfter(steps, anchor, {
          id = "choose_ai_rivals_count",
          kind = "choice",
          text = "How many AI\nrivals?",
          saveKey = "ai_rivals_count",
          choices = choices,
          values = values,
          tx = 4, ty = 3, tw = 12,
        })
        anchor = "choose_ai_rivals_count"
      end

      local labId = M:gauntletLab()
      if labId then
        mod.ui.insertStepAfter(steps, anchor, {
          id = "choose_ai_rivals_gauntlet",
          kind = "choice",
          text = "Battle the AI rivals\nin " .. M:labLabel(labId) .. "?",
          saveKey = "ai_rivals_gauntlet",
          choices = { "PLAY", "SKIP" },
          values = { "play", "skip" },
          tx = 5, ty = 5, tw = 10,
        })
      end
      return steps
    end, 100)
    print("[ai_rivals] intro.oak_speech.build wrapped")
  end

  Pokegear.init(mod, M, Comms)
  installIntro()
end


------------------------------------------------------------------------
-- Exports, for tests and for other mods
------------------------------------------------------------------------

mod.exports.manager = M
mod.exports.compat = compat
mod.exports.modules = {
  Util = Util, MapGraph = MapGraph, Pathfinder = Pathfinder,
  BattleSim = BattleSim, Rival = Rival, AI = AI,
  Simulation = Simulation, Sprites = Sprites, Dialogue = Dialogue,
  Version = Version, Compat = Compat,
  Relationships = Relationships, TeamPlan = TeamPlan, Story = Story,
  Presence = Presence, Weather = Weather, Economy = Economy,
  League = League, LifePath = LifePath, Career = Career, Phone = Phone,
  Comms = Comms, Scout = Scout,
  Pokegear = Pokegear,
  WonderTrade = WonderTrade,
  KantoCompat = KantoCompat,
  Memory = Memory,
  BattleFlow = BattleFlow, RuntimePolicy = RuntimePolicy,
  Gen2Talk = Gen2Talk,
  RosterPolicy = RosterPolicy,
}
mod.exports.data = { roster = ROSTER, personalities = PERSONALITIES,
                     gyms = GYMS, dialogue = LINES }
mod.exports.rivals = function() return M.rivals end

end