main.lua

-- Dramatic Shape Voxel Mod: a full 3D diorama overworld, shipped as a
-- rendering pipeline mod.
--
-- The engine's render_pipelines registry (src/mods/Schemas.lua) lets a mod
-- own part of the frame.  This mod registers two:
--
--   voxel      a drawWorld pipeline.  Instead of the flat tile blit, the
--              overworld's terrain is extruded into real geometry, walked
--              by a depth-buffered 3D camera, with characters as leaning
--              sprite slabs and a shadow map throwing real cast shadows
--              across whatever they land on.  Occlusion is the depth
--              buffer, not a y-sort: walk behind a building and the
--              building is simply in front.
--
--   tiltshift  a worldPresent pipeline -- the stage that post-processes
--              the finished world BEFORE the UI composites over it.  A
--              tilt-shift blur that sells the miniature-model look, on the
--              diorama only, leaving text boxes and menus crisp.
--
-- Everything a display mode needs beyond the two draw functions -- the
-- OFF/15/35/50 ladder, the options rows, the hotkeys, persistence in
-- save.options.pipelines, the free-roam gate, the mutual exclusion with
-- the engine's TILT mode -- is engine plumbing driven by the records
-- below.  This file declares; lib/ draws.
--
-- Voxel mode is presentational: it changes what the world LOOKS like and
-- nothing about what it IS.  TWO rungs are the deliberate exception. 1ST
-- (the camera in the player's own eyes) and 3RD (the same rig, boomed back
-- behind their shoulder) replace the grid WALK with a free,
-- camera-relative one while either is selected (lib/FreeMove.lua), because
-- a camera you can steer with a mouse demands feet that go where it looks.
-- Even there the game is untouched: the walk asks the engine's own
-- collision the same questions a grid step asks, keeps the player's
-- logical cell synced, and fires the engine's own landing pipeline per
-- cell crossed -- warps, encounters, ledges, gates and scripts all run
-- exactly as themselves. Step off the rung and the grid walk is back.

local mod = ...

-- ------- the mod namespace
--
-- lib/ modules require each other through V rather than package.path: a
-- mod directory is not on it, and may live inside a mounted .love archive
-- that plain require cannot reach.  Each module is loaded once, with V
-- passed in as its vararg (`local V = ...`).

local V = { mod = mod, path = mod.path }

function V.game()
  return mod.game or require("src.core.Game")
end

function V.generation()
  local ok, GameVersion = pcall(require, "src.core.GameVersion")
  if ok and GameVersion and type(GameVersion.generation) == "function" then
    return tonumber(GameVersion.generation()) or 1
  end
  return 1
end

-- Crash capture for the render pipelines: the engine's guardRender swallows
-- any throw in drawWorld and silently falls back to the flat 2D path, which
-- reads on screen as "voxel broke" with no trace. Capture the error, persist
-- it through mod.storage (playthrough-scoped), and surface it once through
-- the LOVE error handler so it lands in lua-error.log.
local crashReported = nil
local worldProbe = { updates = 0, draws = 0, wrote = {} } -- plus voxelStuck below
local voxelStuck = 0
-- Fresh-install Gen2 default for the VOXEL pipeline. Levels follow
-- Voxel.ANGLE_LABELS = { OFF, FULL, 15, 35, 50, 75, 1ST(EXP), 3RD(EXP) },
-- so 1 = FULL (the diorama preset). 1ST/3RD are OFF by default: a free-cam
-- rung is a deliberate player choice, not something a fresh save should
-- boot into. (Literal 1: VoxelState loads below, so Voxel.FULL_LEVEL is not
-- in scope yet here.)
local GEN2_DEFAULT_VOXEL = 1

-- Gold/Silver loads display settings from options.lua's nested `gold` block.
-- Older Battle Art builds wrote the ladder at the file root, which Gen2
-- intentionally ignores. Seed only a MISSING Gen2 value; an explicit 0 is a
-- player's OFF choice and must remain off.
local function gen2PipelineOptions(game)
  local opts = game and (game.options
    or (game.save and game.save.options)) or nil
  if type(opts) ~= "table" then return nil end
  if type(opts.pipelines) ~= "table" then opts.pipelines = {} end
  if V.generation() == 2 and opts.pipelines.voxel == nil then
    opts.pipelines.voxel = GEN2_DEFAULT_VOXEL
    if game and type(game.persistOptions) == "function" then
      pcall(game.persistOptions, game)
    elseif game and type(game.writeOptions) == "function" then
      pcall(game.writeOptions, game)
    end
  end
  return opts
end

local function writeWorldProbe(key, text)
  if worldProbe.wrote[key] then return end
  worldProbe.wrote[key] = true
  local okCache, cache = pcall(function() return mod.cache end)
  if okCache and cache and type(cache.write) == "function" then
    pcall(cache.write, cache, "world_probe_" .. key .. ".txt", text)
  end
end

local function captureRenderCrash(body)
  local ok, result = xpcall(body, function(err)
    err = tostring(err)
    if err:find("crashcapture", 1, true) then return err end
    local trace = debug and debug.traceback and debug.traceback("", 2) or ""
    local okDate, at = pcall(os.date, "!%Y-%m-%d %H:%M:%S UTC")
    crashReported = { message = err, traceback = trace,
                      at = okDate and at or "unknown" }
    local okCache, cache = pcall(function() return mod.cache end)
    if okCache and cache and type(cache.write) == "function" then
      pcall(cache.write, cache, "render_crash.txt",
            crashReported.at .. "\n" .. err .. "\n" .. trace)
    end
    local okStorage, storage = pcall(function() return mod.storage end)
    if okStorage and storage then
      for _, game in ipairs({ V.game(), nil }) do
        local okW = pcall(storage.write, storage, game,
                          "render_crash", { crashReported })
        if okW then break end
      end
    end
    return "crashcapture: " .. err .. "\n" .. trace
  end)
  if not ok then
    -- one loud surfacing: the LOVE error handler writes lua-error.log
    error(result, 0)
  end
  return result
end

local function chunkFor(rel)
  local source = mod:read(rel)
  if not source then
    error(("BATTLE_ART_VOXEL_GEN2: %s is missing -- reinstall the mod"):format(rel), 0)
  end
  local chunk, err = load(source, "@" .. mod.path .. "/" .. rel)
  if not chunk then
    error(("BATTLE_ART_VOXEL_GEN2: %s did not compile: %s"):format(rel, tostring(err)), 0)
  end
  return chunk
end

local modules = {}
function V.require(name)
  local hit = modules[name]
  if hit ~= nil then return hit end
  local value = chunkFor("lib/" .. name .. ".lua")(V)
  modules[name] = value
  return value
end

local dataFiles = {}
function V.data(name)
  local hit = dataFiles[name]
  if hit ~= nil then return hit end
  local value = chunkFor("data/" .. name .. ".lua")(V)
  dataFiles[name] = value
  return value
end

-- ------- pipelines

local Voxel = V.require("VoxelState")
local Voxel3D = V.require("Voxel3D")
local VoxelScene = V.require("VoxelScene")
local RenderDistance = V.require("RenderDistance")
local TiltShift = V.require("TiltShift")
local ChunkMesher = V.require("ChunkMesher")
local VoxelPrecache = V.require("VoxelPrecache")
local VoxelPrecacheScreen = V.require("VoxelPrecacheScreen")
local VoxelCacheRamScreen = V.require("VoxelCacheRamScreen")
local VoxelMeshDisk = V.require("VoxelMeshDisk")
local Shadows = V.require("Shadows")
local StaticGeometry = V.require("StaticGeometry")
local ModSetting = V.require("ModSetting")
local RamPrecacheSetting = ModSetting.new(
  "ramPrecacheMb", "RAM PRECACHE MB",
  { 3072, false, 0 },
  { "3072", "OFF", "FULL" },
  1)
local PipelineCanvas = V.require("PipelineCanvas")
local WorldCanvasOrientation = V.require("WorldCanvasOrientation")
local VoxelGrid = V.require("VoxelGrid")
local WorldCurve = V.require("WorldCurve")
local OverworldBattle = V.require("OverworldBattle")
local StadiumBackground = V.require("StadiumBackground")
local BattleExit = V.require("BattleExit")
local BattleArt = V.require("BattleArt")
local AnimatedBattleArt = V.require("AnimatedBattleArt")
local InterfaceSprites = V.require("InterfaceSprites")
local WorldUnderlay = V.require("WorldUnderlay")
local UiBackplates = V.require("UiBackplates")
local BattleStage = V.require("BattleStage")
local BattlePresentation = V.require("BattlePresentation")
local DayNight = V.require("DayNight")
local DayTint = V.require("DayTint")
local Water = V.require("Water")
local AntiAlias = V.require("AntiAlias")
local FirstPerson = V.require("FirstPerson")
local FreeMove = V.require("FreeMove")
local CamControl = V.require("CamControl")
local VR = V.require("VR")
-- HORDE MODE: the konami code's minigame. Horde owns the state machine and
-- every hook; the other four are the gun, the crowd, the readout and the
-- chip-synthesized sounds it fires. See lib/Horde.lua for the whole design.
local Horde = V.require("Horde")
local HordeGun = V.require("HordeGun")
local HordeHud = V.require("HordeHud")
local HordeSfx = V.require("HordeSfx")

-- Freeze the final modded registries before saves begin mutating live maps.
-- Persistent geometry is always fingerprinted from this immutable source.
mod.events:on("mods.loaded", function(payload)
  StaticGeometry.capture(payload and payload.data)
end)

-- Forward declaration: the voxel pipeline's update hook (registered below)
-- calls this, and it is defined further down with the settings it drives.
-- Declared rather than left global -- a mod writing to _G would leak into
-- every other mod's namespace.
local applyFull

-- The last VOID FILL the terrain was meshed under; see the update hook.
-- The scene canvas size required by the active host compositor.
--
-- `ctx.width/height` are the window measured in LOVE UNITS
-- (love.graphics.getDimensions), but the engine composites a pipeline's
-- returned canvas with `draw(canvas, 0, 0, 0, 1/dpiX, 1/dpiY)` -- a scale
-- that only covers the window when the canvas is at PIXEL resolution.
-- Sizing it in units costs the DPI scale TWICE: the canvas is that much
-- smaller, then it is drawn that much smaller again, so the diorama lands
-- in the top-left corner at 1/dpi of the screen.  Desktop never sees it --
-- units and pixels are the same thing there -- but on Android the DPI scale
-- is the display density (2.625 on a 420dpi panel), and the world came out
-- a third of the size in each direction.
--
-- That contract applies to Gen 1. Gold/Silver/Crystal's Gen 2 World instead
-- draws the returned canvas directly at scale 1, so framebuffer dimensions
-- there create a DPI-factor crop. PipelineCanvas keeps the two contracts
-- explicit instead of guessing from the dimensions themselves.
local function sceneSize(ctx)
  return PipelineCanvas.sceneSize(ctx, V.generation())
end

local voidFill = { last = nil }
function voidFill.check()
  local TileRenderer = require("src.render.TileRenderer")
  local now = TileRenderer.voidFill
  if voidFill.last ~= nil and now ~= voidFill.last then
    ChunkMesher.invalidate()   -- no map id: every ring on every map is stale
  end
  voidFill.last = now
end

mod.content.render_pipelines:register("voxel", {
  label = "VOXEL",
  levels = Voxel.ANGLE_LABELS,
  -- 3 is the engine's TILT key, which this mode supersedes -- see the
  -- hotkey block near the bottom of this file for how it is claimed
  hotkey = "3",
  -- above tiltshift, so the two sort together in the options list with the
  -- mode first and its post-process under it
  priority = 20,

  -- Headless runs and drivers without a depth canvas or shader support
  -- answer false here, and the engine keeps the vanilla 2D path -- which
  -- is why no caller ever has to guard for a missing 3D pass.
  available = function()
    return Voxel3D.available()
  end,

  -- the engine hands over the live level; we ease the camera toward it.
  -- pump() advances queued mesh builds inside a few-millisecond budget,
  -- so entering voxel mode (and streaming neighbours while walking)
  -- costs frames nothing visible -- the old synchronous build froze the
  -- first frame for seconds. prefetch() runs here as well as in the
  -- draw, because update ticks even while a warp's Transition covers
  -- the screen: the destination's meshes start building the moment the
  -- map swaps behind the fade, and the fade-covered frames get a wider
  -- pump slice -- so stepping out of a door lands on terrain that is
  -- already there instead of a flat flash.
  update = function(dt, level)
    worldProbe.updates = worldProbe.updates + 1
    -- FULL is a preset, so it is applied ON THE PRESS rather than held every
    -- frame: it SETS the other rows and then leaves them alone. Holding them
    -- would make the zoom keys and the wheel dead while the mode was on, and
    -- would fight anyone who changed one deliberately.
    applyFull(level)
    Voxel.update(dt, level)
    -- the first-person head, on the same tick: its blend in and out of the
    -- orbit, the mouse capture lifecycle, and the frame's stick-rate look.
    -- Unconditional like Voxel.update, because the blend has to keep easing
    -- OUT after the rung is left
    FirstPerson.update(dt)
    -- the day/night clock, on the same always-running tick: Pipelines.update
    -- runs whatever the level, so time passes with the mode off, through
    -- battles and menus, and a CYCLE evening falls mid-fight exactly as it
    -- would mid-walk
    DayNight.update(dt)
    -- The overworld battle rides this hook rather than owning a pipeline of
    -- its own, because it owns no pass of the FRAME: it draws under a battle
    -- screen the engine composites, which is not a stage the registry has.
    -- What it needs is a tick that keeps running once the overworld stops
    -- being the top state, and this is one -- Game:update calls
    -- Pipelines.update unconditionally, so it survives the transition wipe
    -- and the whole battle. Ahead of the active() gate below, because a 3D
    -- battle does not require the free-roam mode to be switched on.
    OverworldBattle.update(dt)
    -- The horde, on the same always-running tick and for the same reason:
    -- it owns no pass of the frame, it is a MODE over the overworld, and
    -- it has to keep thinking while a warp's wipe covers the screen (the
    -- crowd follows the player through the door) and under the GAME OVER
    -- card, which is a pushed state that stops everything below it.
    Horde.update(dt)
    -- VOID FILL picks the block the border ring is made of, and in this
    -- mode that ring is BAKED INTO THE MESH rather than drawn each frame.
    -- So the option has to reach the cache or nothing happens on screen
    -- until the meshes are dropped for some other reason -- which reads
    -- exactly like the option doing nothing at all. Polled rather than
    -- hooked because the engine changes it from three places (the options
    -- row, applyOptions on load, TileRenderer.setVoidFill) and none of
    -- them announces it. Ahead of the active() gate, so switching it
    -- while voxel mode is OFF still invalidates what is cached.
    voidFill.check()
    -- The whole VR frame -- session lifecycle, xrWaitFrame's pacing, both
    -- eye renders, the layer submit -- rides this hook, because it is the
    -- one tick that runs through menus, dialogs and battles, which is
    -- what a headset needs the world (or at least the UI panel) to do.
    -- Ahead of the active() gate: with the mode off, the headset still
    -- shows the flat screen on the floating panel.
    VR.update(dt)
    local Game = V.game()
    local ow = Game and (Game.overworld or Game.world)
    local Pipelines = require("src.render.Pipelines")
    local opts = gen2PipelineOptions(Game) or { pipelines = {} }
    -- Sample every ~10s and OVERWRITE: the first samples land on the title
    -- screen before Game2 builds its world, so a one-shot probe only ever
    -- recorded world=false. The latest sample is the interesting one.
    -- Belt-and-braces restore: the game.ready listener can miss its window
    -- (options may load after our chunk registers), so watch for the stuck
    -- state directly -- stored level > 0 while the runtime sits at 0. Two
    -- consecutive samples past boot before acting, so a deliberate OFF by
    -- the player is respected once they have had a chance to choose it.
    if Pipelines.level("voxel") <= 0 and (opts.pipelines.voxel or 0) > 0 then
      voxelStuck = voxelStuck + 1
      if voxelStuck == 2 then
        Pipelines.setLevel("voxel", math.min(opts.pipelines.voxel,
                                             Pipelines.maxLevel("voxel")))
        Voxel.setLevel(Pipelines.level("voxel"))
        writeWorldProbe("restore",
          "restored at update " .. tostring(worldProbe.updates)
          .. " -> level " .. tostring(Pipelines.level("voxel")))
      end
    else
      voxelStuck = 0
    end
    if worldProbe.updates % 600 == 0 then
      local top = Game and Game.stack and Game.stack.top
                and Game.stack:top() or nil
      writeWorldProbe("update", table.concat({
        "at_update=" .. tostring(worldProbe.updates),
        "top=" .. tostring(top and top.name or top),
        "level=" .. tostring(level),
        "voxelLevel=" .. tostring(Voxel.level),
        "angle=" .. tostring(Voxel.angle),
        "ready=" .. tostring(Voxel.ready),
        "active=" .. tostring(Voxel.active()),
        "world=" .. tostring(ow ~= nil),
        "map=" .. tostring(ow and ow.map and ow.map.id),
        "camera=" .. tostring(ow and ow.camera ~= nil),
        "pending=" .. tostring(ChunkMesher.pending()),
      }, "\n"))
    end
    if not Voxel.active() then return end
    if ow and ow.map and ow.camera then
      pcall(VoxelScene.prefetch, ow)
      -- Complement nearby cache misses in RAM. Persistence remains explicit
      -- through CACHE / SAVE so ordinary play never performs surprise I/O.
      pcall(VoxelPrecache.update, Game)
    end
    ChunkMesher.pump(Game and Game.stack
                     and Game.stack:top() ~= ow)
  end,

  drawWorld = function(ctx)
    worldProbe.draws = worldProbe.draws + 1
    -- the palette closure, stashed for the VR frame: it renders from the
    -- update hook, where no ctx exists to carry one
    VR.paletteFor = ctx.paletteFor
    return captureRenderCrash(function()
    -- With a headset running, the window's world pass becomes the MIRROR
    -- -- the left eye, fitted to the window -- rather than a third full
    -- render of the scene. Everything else about the frame (the UI the
    -- engine composites over this) is unchanged, which is exactly what
    -- the headset's floating panel photographs.
    if VR.active() then
      local sw, sh = sceneSize(ctx)
      local m = VR.mirror(sw, sh)
      if m then return m end
    end
    -- Terrain and characters are geometry; the field FX stay ordinary 2D
    -- draws composited on top, anchored through the same camera the 3D
    -- pass used (ctx.drawFx below).  The scene renders at the window's
    -- PIXEL resolution (see sceneSize) so the 3D pass is crisp rather than
    -- a magnified low-res image, while the FX closures keep drawing in
    -- world-pixel units.
    local sw, sh = sceneSize(ctx)
    -- With AA on, the whole pass runs into a canvas BIGGER than the window
    -- and is folded back down at the end (see AntiAlias).  Nothing between
    -- these two lines knows: every pass in the frame measures itself in the
    -- canvas it was handed, so the sky's dither, the water's march and the
    -- camera itself all come out the same picture at a higher sample rate.
    local rw, rh = AntiAlias.expand(sw, sh)
    local canvas = VoxelScene.render(ctx.state, rw, rh,
                                     ctx.vw, ctx.vh, ctx.paletteFor)
    if not canvas then
      if worldProbe.draws == 1 or worldProbe.draws % 120 == 0 then
        local map = ctx.state and ctx.state.map
        writeWorldProbe("decline_" .. tostring(worldProbe.draws),
          table.concat({
            "draws=" .. tostring(worldProbe.draws),
            "map=" .. tostring(map and map.id),
            "renderer=" .. tostring(map and map.renderer ~= nil),
            "atlas=" .. tostring(map and map.renderer
                                  and map.renderer.image ~= nil),
            "tileset=" .. tostring(map and map.tileset ~= nil),
            "terrain=" .. tostring(map and ChunkMesher.pair(map, false)
                                    ~= nil),
            "body=" .. tostring(map and ChunkMesher.pair(map, true)
                                 ~= nil),
            "pending=" .. tostring(ChunkMesher.pending()),
            "voxelLevel=" .. tostring(Voxel.level),
            "angle=" .. tostring(Voxel.angle),
            "ready=" .. tostring(Voxel.ready),
          }, "\n"))
      end
      -- Battle teardown can reveal the world before its streamed terrain is
      -- ready. Keep the clean arena backdrop for that short handoff instead
      -- of exposing Silver's flat world between the two composites.
      return WorldCanvasOrientation.present(
        OverworldBattle.handoff(), "overworld-handoff", V.generation())
    end
    writeWorldProbe("success", "draws=" .. tostring(worldProbe.draws)
      .. "\nmap=" .. tostring(ctx.state and ctx.state.map
                              and ctx.state.map.id))
    if Voxel3D.beginOverlay() then
      -- the FX closures are ordinary 2D draws sized in DISPLAY pixels, and
      -- they are drawing into the supersampled canvas alongside everything
      -- else -- so the scale goes up with it, or the "!" bubble lands the
      -- right place at half the size.  project() already answers in canvas
      -- pixels, so only the scale needs saying.
      ctx.drawFx(function(wx, wy) return Voxel3D.project(wx, 0, wy) end,
                 ctx.scale * AntiAlias.factor())
      -- the horde's readout rides the same overlay, over the FX: health,
      -- ammunition, the crosshair and the banners, sized in the same
      -- supersampled canvas pixels everything else here is drawn in. A
      -- headset never reaches this line (drawWorld returns the mirror
      -- above) -- lib/VR draws the same HUD onto each eye instead.
      HordeHud.drawFlat(rw, rh, ctx.scale * AntiAlias.factor())
      Voxel3D.endOverlay()
    end
    -- and back to the window's own size, which is what the engine composites
    -- one canvas pixel to one display pixel.  A pass-through when AA is off.
      local resolved = AntiAlias.resolve(canvas, sw, sh, "world")
      if resolved then OverworldBattle.worldReady() end
      return WorldCanvasOrientation.present(
        resolved, "overworld", V.generation())
    end)
  end,

  invalidate = function()
    Voxel3D.invalidate()
    OverworldBattle.invalidate()
    AntiAlias.invalidate()
    WorldCanvasOrientation.invalidate()
    ChunkMesher.invalidate()   -- no map id = every cached mesh
    VR.invalidate()            -- the mirror, and FBO ids of dead canvases
  end,
})

mod.content.render_pipelines:register("tiltshift", {
  label = "T-SHIFT",
  levels = TiltShift.LABELS,
  -- 6 is free: no engine branch claims it, so this one alone reaches the
  -- registry by the documented route
  hotkey = "6",
  priority = 10,

  update = function(dt, level)
    TiltShift.update(dt, level)
  end,

  -- worldPresent, not present: the blur belongs on the diorama, not on the
  -- dialog box in front of it.  A pass-through when the level is 0 or the
  -- shader is unavailable, so the frame is untouched in every other case.
  worldPresent = function(canvas)
    return TiltShift.apply(canvas)
  end,

  invalidate = function()
    TiltShift.invalidate()
  end,
})

-- ------- this mod's own settings
--
-- Neither of these is a pipeline: they own no pass of the frame, they
-- PARAMETERISE the voxel one, so they have nothing to put in drawWorld or
-- present and the registry would rightly reject them.  Plain mod settings
-- instead -- see ModSetting for where they persist and how the two rows
-- each ends up on stay in step.

-- ------- the FULL preset
--
-- Everything the mode wants switched to at once. Applied when the VOXEL row
-- ARRIVES at FULL and not again, so the player can still move the camera or
-- the zoom afterwards -- it is a starting point, not a lock.
--
-- Leaving FULL deliberately does NOT undo any of it. A preset that reverted
-- would throw away whatever the player had changed since, and "put it back
-- how it was" is not a thing this can know.
local fullWas = nil

applyFull = function(level)
  local isFull = Voxel.isFull(level)
  local was = fullWas
  fullWas = isFull
  if not isFull or was == true or was == nil then return end

  local Game = require("src.core.Game")
  local Pipelines = require("src.render.Pipelines")
  local Zoom = require("src.render.Zoom")
  local opts = Game.save and Game.save.options
  if not opts then return end

  -- the miniature blur at its strongest: FULL is the diorama look, and the
  -- tilt-shift is most of what makes it read as a model. A fresh Gen2 install
  -- arrives at FULL through GEN2_DEFAULT_VOXEL (which wants the diorama with
  -- T-SHIFT off), so only a player who steps onto FULL by hand gets the blur;
  -- the default boot keeps the preset's other rows but not the tilt-shift.
  local freshDefault = level == GEN2_DEFAULT_VOXEL
  if not freshDefault then
    -- Tilt-shift is opt-in: FULL must not force the blur on (and persist it),
    -- which previously snapped every manual FULL arrival to max and stuck.
    -- Leave it OFF / at its stored value; the player turns T-SHIFT on from
    -- the OPTIONS row if they want the diorama blur.
  end
  Pipelines.syncOptions(opts)
  -- the horizon flat. The curve bends the world away from a walking player,
  -- which fights a fixed diorama framing
  WorldCurve.setting:setIndex(1, Game)
  -- and the water reflecting everything it can: FULL is the diorama at its
  -- most photographed, and a lake with the sky and the shoreline in it is
  -- most of what makes the model read as being outdoors
  Water.setting:setIndex(1, Game)
  -- and the view fitted to the window
  opts.zoom = 0
  Zoom.applyOptions(opts)
  -- battles on the map too: FULL means the whole mode, and a fight is where
  -- half of it is spent. Set and then LET GO of -- unlike the rows above, both
  -- battle rows stay on the menu under FULL (see the rows hook), so this is
  -- where the preset puts them and not where they are held.
  OverworldBattle.setting:setIndex(1, Game)
  -- with both mons out there on it: BACK SPRITES keeps the player's own on the
  -- menu, which is the one part of the old screen FULL is least about. Set the
  -- same way, and changed back on the same row a keypress later.
  OverworldBattle.backSetting:setIndex(1, Game)
  -- and the battle screen the staged fight is composed for. WIDE re-lays that
  -- screen out on a 304x144 surface, which moves every anchor the arena camera
  -- is solved against (OverworldBattle.forceOG); FULL has just switched staged
  -- fights on, so the layout follows them.
  OverworldBattle.forceOG(Game)
  -- and the sky on the clock on the wall: FULL sets DAYTIME to SYNC. Set and
  -- then LET GO of, like the battle rows above -- the row stays on the menu
  -- under FULL, because holding it there left a player who booted after dark
  -- with no way to ask for daylight.
  DayNight.forceSync(Game)
  if Game.writeOptions then pcall(Game.writeOptions, Game) end
end

-- Whether a fight can be staged on the map, as far as the OPTIONS menu is
-- concerned: the 3D-BTL row, and nothing else.
--
-- It used to answer yes under FULL as well, on the grounds that FULL owned
-- that row and switched it on. FULL no longer owns it -- the row stays on the
-- menu under FULL and can be switched off there (see the rows hook) -- so that
-- clause would now claim staged battles for a preset the player had just
-- turned them off inside, pinning BATTLE LAYOUT to OG for a fight that is
-- never staged. The row is the only thing that decides, which is what every
-- other reader of this setting already believed: OverworldBattle.begin and
-- wantsFront both gate on enabled() alone.
--
-- Deliberately NOT gated on Voxel3D.available(): the engine offers a
-- pipeline's row whether or not the hardware can run it (Pipelines.rows), so
-- this mode's rows say ON on a machine without a depth buffer too, and a menu
-- that claims 3D battles are on must not also offer the layout they cannot be
-- drawn in.
local function stagedBattles()
  return OverworldBattle.enabled()
end

local function applyRamPrecacheBudget()
  local value = RamPrecacheSetting:get()
  if value == false then
    -- OFF: disable precache entirely, no preload, no RAM limit
    VoxelMeshDisk.setRamPrecacheEnabled(false)
    return false
  end
  VoxelMeshDisk.setRamPrecacheEnabled(true)
  if value == 0 then
    -- FULL: no RAM budget cap, eager whole-world load
    VoxelMeshDisk.setRamBudget(0)
  else
    VoxelMeshDisk.setRamBudget(tonumber(value) * 1024 * 1024)
  end
  return true
end

-- Gen 2 does not build render-pipeline rows for either of its options
-- screens. Keep one small bridge for those surfaces: the in-game row still
-- edits Pipelines directly, while the mod manager stores this mirror key and
-- the options-changed event below applies it to the same live level.
local VOXEL_OPTION_KEY = "voxelLevel"
local VOXEL_HELP = "Choose the voxel camera: OFF, the FULL diorama preset, "
  .. "or an orbit/free-camera rung. This is the touch-accessible equivalent "
  .. "of the keyboard's 3 display-mode key."

local function mirrorVoxelOption(game, level)
  game = game or V.game()
  level = math.max(0, math.min(Voxel.MAX_LEVEL,
                               math.floor(tonumber(level) or 0)))
  local changed = false
  local opts = game and game.save and game.save.options
  if opts then
    opts.modOptions = opts.modOptions or {}
    opts.modOptions[mod.id] = opts.modOptions[mod.id] or {}
    changed = opts.modOptions[mod.id][VOXEL_OPTION_KEY] ~= level
    opts.modOptions[mod.id][VOXEL_OPTION_KEY] = level
  end
  local loader = game and game.mods
  if loader then
    loader.modOptions = loader.modOptions or {}
    loader.modOptions[mod.id] = loader.modOptions[mod.id] or {}
    loader.modOptions[mod.id][VOXEL_OPTION_KEY] = level
  end
  return changed
end

local function setVoxelOption(game, level)
  game = game or V.game()
  local Pipelines = require("src.render.Pipelines")
  level = Pipelines.setLevel("voxel", level)
  Voxel.setLevel(level)
  local opts = gen2PipelineOptions(game)
  if opts then
    Pipelines.syncOptions(opts)
    opts.tilt, opts.gbcfx = 0, 0
  end
  mirrorVoxelOption(game, level)
  applyFull(level)
  local okTilt, Tilt = pcall(require, "src.render.Tilt")
  if okTilt and Tilt and Tilt.setLevel then pcall(Tilt.setLevel, 0) end
  local okGbc, GBCFX = pcall(require, "src.render.GBCFX")
  if okGbc and GBCFX and GBCFX.setLevel then pcall(GBCFX.setLevel, 0) end
  if game and game.writeOptions then pcall(game.writeOptions, game)
  elseif game and game.persistOptions then pcall(game.persistOptions, game) end
  return level
end

local SETTINGS = {
  { RenderDistance.setting,
    "Limit connected-map terrain, water, figures and distant characters. "
    .. "SHORT/MEDIUM/FAR cover 16/32/64 movement cells. MEDIUM is the default; "
    .. "FULL restores uncapped rendering. The current map always stays visible.",
    full = true },
  { RamPrecacheSetting,
    "Compressed voxel cache retained for CONTINUE and nearby-area loading. "
    .. "Choose FULL to retain every precached record; larger values use more "
    .. "system RAM but reduce first-entry disk reads on mobile.",
    full = true },
  { VoxelGrid.setting, "One-pixel wireframe along every voxel edge." },
  { VoxelScene.silhouetteSetting,
    "Draw silhouettes for characters hidden behind voxel geometry. "
    .. "OFF disables the silhouette pass completely." },
  { WorldCurve.setting,
    "Bend the world down over the horizon, Animal Crossing style." },
  { Water.setting,
    "Reflections on water. FULL adds screen-space reflections of the "
    .. "shoreline, the trees and the buildings behind it; SKY is the sky, "
    .. "the sun and the moon alone, which is most of the look for a "
    .. "fraction of the cost." },
  { Shadows.setting,
    "Enable shadows. OFF removes both the real cast-shadow map and its flat "
    .. "fallback from free roam and staged battles; UNLIT battle cards also "
    .. "decline shadows even while this global switch is ON.",
    full = true },
  -- `full` marks a row FULL does not take away. FULL owns the diorama's own
  -- knobs; what a battle is drawn over, and how it is framed, are not that.
  -- Off the OPTIONS menu while VR is on: the headset REQUIRES staged
  -- battles (OverworldBattle.enabled answers true regardless of this row)
  -- and forbids back sprites (backPinned answers false), so both rows
  -- decide nothing there and a dead switch on the menu reads as broken.
  { OverworldBattle.setting,
    "Fight on the map: the battle draws over the nearest clear ground, "
    .. "shot over the shoulder with a slow parallax drift.",
    when = function() return not VR.enabled() end, full = true },
  -- Advanced compatibility control, kept off the in-game menu because it
  -- pins the player pic to the UI camera and applies the world's night tint,
  -- overriding the staged camera and SPRITE LIGHT presentation controls.
  { OverworldBattle.backSetting,
    "Keep your own Pokemon on the battle menu, seen from behind in its "
    .. "original slot, instead of standing it on the map facing the foe. "
    .. "The foe is still out there on its own tile.",
    when = function() return stagedBattles() and not VR.enabled() end,
    full = true, managerOnly = true },
  -- Battle Art rows (ported from the Gen1 fork). Only offered while a fight
  -- can actually be staged on the map.
  { BattleArt.setting,
    "Use optional PNGs from assets/battle in fights. Missing art falls "
    .. "back to the ROM. ANIMATED is the tested fresh-install default.",
    when = function() return stagedBattles() end, full = true },
  { BattleArt.trainerSetting,
    "Use the ROM opponent trainers, or choose an optional static collection. "
    .. "A class missing from that collection falls back to its ROM portrait.",
    when = function()
      return stagedBattles() and BattleArt.setting:get() ~= "rom"
    end, full = true, managerOnly = true },
  { BattleArt.playerArtSetting,
    "Choose the player trainer's static battle-intro portrait. A missing "
    .. "named choice tries player.png, then ROM. PNG uses player.png "
    .. "directly. BATTLE ART: ROM pins this row to ROM.",
    when = function()
      return stagedBattles() and BattleArt.setting:get() == "static"
    end, full = true },
  { BattleArt.playerAnimationSetting,
    "Choose the player trainer's battle-intro art under ANIMATED. PNG uses "
    .. "player.png as a static portrait; named sets play their authored "
    .. "slide poses once. Missing art and ROM retain the engine portrait.",
    when = function()
      return stagedBattles() and BattleArt.setting:get() == "animated"
    end, full = true },
  { BattleArt.frontAnimationSetting,
    "Choose the front generation used by BATTLE ART: ANIMATED. GEN 1 reads "
    .. "single-frame PNGs; GEN 2-5 read atlases. STATIC ignores this row. "
    .. "Missing art falls directly back to ROM.",
    when = function()
      return stagedBattles() and BattleArt.setting:get() == "animated"
    end, full = true },
  { BattleArt.backAnimationSetting,
    "Choose the player back-art generation. STATIC reads only a PNG from "
    .. "back-static/GEN for every choice. ANIMATED reads static GEN 1, 2, "
    .. "and 4 PNGs, or animated GEN 3 and 5 atlases. Missing art falls "
    .. "back to the ROM.",
    when = function() return stagedBattles() and BattleArt.setting:get() ~= "rom"
    end, full = true },
  { BattleArt.duplicateSetting,
    "Choose who owns Pokemon pictures when another sprite mod is installed. "
    .. "BATTLE ART keeps this mod's selected front and back collections on "
    .. "top, including its DV-routed shiny collections. MODDED installs no "
    .. "Pokemon art and captures the pictures chosen by another sprite mod "
    .. "or the ROM on both sides.",
    when = function() return stagedBattles() end, full = true },
  { BattleArt.viewSetting,
    "Show the player's Pokemon from the front or back. Supplied art stays "
    .. "world-placed; a missing selected back falls back to the ROM UI pic.",
    when = function() return stagedBattles() end, full = true },
  { BattleArt.frontFlipSetting,
    "Orient the player-side FRONT SPRITES card. BATTLE ART mirrors ordinary "
    .. "front art so it faces the opponent. DEFAULT preserves the image's "
    .. "authored direction, for sprite mods that already supply a flipped "
    .. "player picture such as Crystal Animated Sprites.",
    when = function()
      return stagedBattles() and BattleArt.playerSide() == "front"
    end, full = true },
  { UiBackplates.spriteLight,
    "SHADED lets the mons receive the world's day tint and cast shadows; "
    .. "UNLIT draws them flat and full bright. UNLIT is what the OG "
    .. "battle's sprites look like.",
    when = function() return stagedBattles() end, full = true },
  { UiBackplates.hudColor,
    "INVERTED uses bright white HUD ink over the arena; COLOR keeps the "
    .. "engine's black ink. HP and EXP bars retain their native colors.",
    when = function() return stagedBattles() end, full = true },
  { UiBackplates.arenaFill,
    "Choose the staged battle background: the voxel world, a flat white "
    .. "field, assets/battle/front-static/bosses/arena.png, or Stadium 2's "
    .. "live field and models when its importer is ready. STADIUM2 falls "
    .. "back to OFF's voxel battlefield when unavailable.",
    when = function() return stagedBattles() end, full = true },
  { UiBackplates.stadiumCircle,
    "Control Stadium's ground circles independently of ARENA FILL. ON uses "
    .. "the full circle, HALF uses a smaller circle, and OFF hides it while "
    .. "an invisible plane still receives model shadows.",
    when = function() return StadiumBackground.installed() end, full = true },
  { UiBackplates.backdropOffset,
    "Crop the selected PNG arena downward in source-image pixels.",
    when = function()
      return stagedBattles() and UiBackplates.arenaPng()
    end, full = true },
  { UiBackplates.bossBg,
    "Allow encounter-specific boss artwork to override an illustrated arena.",
    full = true, managerOnly = true },
  { UiBackplates.textboxFill,
    "Choose opaque white, translucent dark, opaque black, or paperless "
    .. "battle text boxes.",
    when = function() return stagedBattles() end, full = true },
  { InterfaceSprites.setting,
    "INTERFACE SPRITES: show BATTLE ART's regular-form FRONT outside battle. "
    .. "Title and status support timed atlas animation; other hook-aware "
    .. "screens use single-image sets or retain ROM art, independent of "
    .. "DUPLICATE FIX (which owns only battle pictures). "
    .. "MODDED leaves the interfaces to another sprite mod or the ROM.",
    full = true },
  { InterfaceSprites.scalingSetting,
    "FIT keeps Summary and Dex artwork within 56x56. FULL keeps native pixels "
    .. "and can overlap the UI. Summary aligns the first pose at the bottom; "
    .. "Dex centers it. Animation timing and movement are preserved.",
    full = true },
  { WorldUnderlay.setting,
    "Choose the solid outdoor world beneath terrain holes and beyond map edges: "
    .. "CYAN or BLACK. OFF/KFP leaves the underlay to Kanto First Person. "
    .. "NATURE uses a black underlay and continues each biome beyond loaded "
    .. "ROM cells with stable random-sized tree or rock billboards. "
    .. "Indoor horizons automatically match "
    .. "the room's own border/void material so the finite map ring cannot reveal "
    .. "a differently coloured infinite fill behind it.",
    full = true, managerOnly = true },
  -- Marked `full` on the battle rows' reasoning, and then some. FULL SETS this
  -- to SYNC on arrival (applyFull) because the diorama's sky should follow the
  -- clock on the wall; it used to HOLD it there and take the row away, which
  -- meant a player who started the game after dark had the whole world
  -- multiplied by DayNight.TINTS.night with no row anywhere to say otherwise.
  -- A preset that hides the one row deciding whether you can see is a lock,
  -- not a preset.
  { DayNight.setting,
    "What time it is outdoors: pin the sky to DAY, NIGHT, DUSK or DAWN, "
    .. "let CYCLE run it -- ten minutes of sun, ten of moon, with the "
    .. "shadows, the sky and the light following -- or SYNC it to the "
    .. "clock on the wall, so Kanto's evening falls when yours does.",
    full = true },
  -- Marked `full` for the opposite reason the battle rows are: this is not a
  -- knob on the look at all, it is what the look COSTS. FULL is a preset for
  -- the diorama, not a licence to spend four times the fill rate on the
  -- machine it happens to be running on, so it neither sets this nor takes
  -- the row away -- the player decides what their hardware can carry, from
  -- inside FULL like anywhere else.
  { AntiAlias.setting,
    "Smooth the stair-stepped edges of the 3D world -- roof ridges, ledge "
    .. "lips, a tree against the sky -- by rendering the diorama larger than "
    .. "the window and folding it back down. Every edge in the picture "
    .. "softens with them, the tileset's own texels included, so the diorama "
    .. "reads smoother rather than sharper. 2X costs half again as many "
    .. "pixels in each direction and 4X twice, which makes this the most "
    .. "expensive row in the mod.",
    full = true },
  -- `full` for the same reason as AA: not a knob on the look, a question
  -- about the hardware on the desk.
  { VR.setting,
    "PCVR through OpenXR (SteamVR, Oculus, WMR). The diorama becomes a "
    .. "tabletop model your head moves around; the 1ST rung stands you "
    .. "inside the world at life size, looking where the headset looks. "
    .. "Menus and dialogs float on a panel. Needs a Windows OpenXR runtime "
    .. "and the mod running from a real folder; without them the row stays "
    .. "and the game stays flat, with the reason on the console.",
    -- on Windows the row stays even when a runtime is missing (the console
    -- says why); off Windows -- mobile above all -- there is no VR to have
    -- and the row does not exist
    when = function() return VR.supported() end, full = true },
  -- Under the VR row and only while it is ON: a comfort setting for a
  -- device that is not plugged in decides nothing, and this one is read
  -- exclusively by the headset's right stick.
  { VR.smoothTurn,
    "Turn smoothly with the right stick instead of snapping 45 degrees a "
    .. "flick. OFF by default, and deliberately: a software turn moves the "
    .. "world past a head that did not move, which is the most reliable way "
    .. "to make somebody ill in a headset. Turn it on if you have your sea "
    .. "legs and want the continuity.",
    when = function() return VR.enabled() end, full = true },
}

local voxelChoices = {}
for level, label in ipairs(Voxel.ANGLE_LABELS) do
  voxelChoices[#voxelChoices + 1] = { label, level - 1 }
end
local schema = {
  { key = VOXEL_OPTION_KEY, type = "choice", label = "VOXEL",
    choices = voxelChoices, default = GEN2_DEFAULT_VOXEL, help = VOXEL_HELP },
}
for _, entry in ipairs(SETTINGS) do
  -- the VR rows are absent from the mod manager's page too where the
  -- platform cannot do VR at all -- the OPTIONS menu's `when` gates are
  -- situational (a row hidden for now), this one is existential
  local vrOnly = entry[1] == VR.setting or entry[1] == VR.smoothTurn
  if not vrOnly or VR.supported() then
    schema[#schema + 1] = entry[1]:schema(entry[2])
  end
end
mod.options:define(schema)

-- ------- this mod's hotkeys
--
--   3  VOXEL    cycle the camera ladder      (was 6; skips FULL)
--   5  V-GRID   toggle the wireframe         (new)
--   6  T-SHIFT  cycle the blur ladder        (was 9)
--   7  V-CURVE  cycle the horizon bend       (new)
--   8  3D-BTL   toggle overworld battles     (new)
--   9  WATER    cycle the water reflections  (new; 9 was T-SHIFT's old key)
--
-- Only 6 arrives by the documented route. Game:keypressed answers the
-- engine's own display keys FIRST and returns -- 2 COLORS, 3 TILT, 4 ZOOM,
-- 5 GBC FX -- and only then offers the key to Pipelines.hotkey, expressly
-- so "a pipeline can never shadow one" (Schemas, render_pipelines.hotkey).
-- 3 and 5 are two of those, and 7 and 8 belong to plain mod settings that
-- own no pass and so have no registry to claim a key from at all.
--
-- So this wraps Game:keypressed. It is the invasive option and it is the
-- only one: polling the keyboard in update() would fire alongside the
-- engine's handler rather than instead of it, so 3 would cycle this mode
-- AND the engine's TILT on the same press.
--
-- Consequences worth being explicit about: while this mod is enabled, TILT
-- (3) and GBC FX (5) are unreachable by key -- and unreachable on the OPTIONS
-- menu too, where both rows are taken away and both values held at zero (see
-- pinEngineFx). Nothing is being hidden that still does something: TILT is the
-- flat fake of what this mode does for real, the registry already forces it
-- off whenever a world pipeline takes the pass, and GBC FX is a full-screen
-- present pass over the top of the diorama. Uninstalling puts both back.
--
-- Everything the engine does around a pipeline hotkey has to happen here
-- too, so the work is DELEGATED rather than reimplemented: Pipelines.hotkey
-- applies its own gate and ladder, and the three lines after it are the
-- engine's own (syncOptions, the tilt exclusion, writeOptions).

local HOTKEYS = {
  ["3"] = "pipeline",           -- voxel, by its declared hotkey
  ["6"] = "pipeline",           -- tiltshift, likewise
  ["5"] = VoxelGrid.setting,
  ["7"] = WorldCurve.setting,
  ["8"] = OverworldBattle.setting,
  ["9"] = Water.setting,
}

-- One step of the VOXEL angle ladder: everything a "3" press does, named
-- so the pad's SELECT button (below) can make exactly the same step. The
-- gate is the registry's own; the tilt/GBC FX clearing is the engine work
-- the key has always delegated (see the wrap below for why).
local function cycleVoxel(game)
  local Pipelines = require("src.render.Pipelines")
  -- HORDE MODE holds the rung at 1ST for as long as it runs. Refused HERE
  -- rather than at each caller because this one function IS every way a
  -- player can step the ladder: the "3" key, the pad's SELECT, and the VR
  -- left-stick click all come through it.
  if Horde.viewLocked() then return false end
  local top, world
  if type(game.pipelineGate) == "function" then
    top, world = game:pipelineGate()
  else
    top = game.stack and game.stack:top()
    world = game.overworld or game.world
  end
  if not Pipelines.canToggle("voxel", top, world) then return false end
  setVoxelOption(game, Voxel.nextHotkeyLevel(Pipelines.level("voxel")))
  local options = game.options or (game.save and game.save.options) or {}
  -- 3 is the key that used to turn TILT on and sits next to the one that
  -- used to turn GBC FX on, and this mod has taken both away. A player who
  -- left either running before enabling the mod would otherwise have no
  -- way back to off, and both fight the diorama -- so the VOXEL step
  -- clears them on EVERY press, not just the press that switches on.
  options.tilt = 0
  options.gbcfx = 0
  -- Silver has the option keys and native display hotkeys, but does not ship
  -- Gen1's standalone GBCFX module. Clear whichever optional renderer modules
  -- this engine lineage actually exposes without making the voxel key depend
  -- on either one existing.
  local okGbc, GBCFX = pcall(require, "src.render.GBCFX")
  if okGbc and GBCFX and GBCFX.setLevel then pcall(GBCFX.setLevel, 0) end
  local okTilt, Tilt = pcall(require, "src.render.Tilt")
  if okTilt and Tilt and Tilt.setLevel then
    pcall(Tilt.setLevel, options.tilt or 0)
  end
  return true
end

-- The VR stick click makes this same step (VR.stepView): the function is
-- a local of this file, so the handoff is explicit rather than a
-- reimplementation drifting out of date in lib/VR.lua.
VR.cycleVoxel = cycleVoxel

if V.generation() ~= 2 then
  local Game = require("src.core.Game")
  local Pipelines = require("src.render.Pipelines")
  local inner = Game.keypressed

  function Game:keypressed(key)
    -- HORDE MODE owns the keyboard's spare keys while it runs: R reloads,
    -- and the mode keys are swallowed rather than left to change the rung
    -- or the post-processing out from under a locked camera.
    if Horde.active then
      if key == "r" then
        HordeGun.reload()
        return
      end
      if HOTKEYS[key] then return end
    end
    local claim = HOTKEYS[key]
    local top = self.stack and self.stack:top()
    -- Q and E work whichever camera is in front of the player -- the
    -- battle's lens, the third-person boom, or the engine's own survey
    -- zoom on an orbit rung. CamControl answers which, and answers "none"
    -- for 1ST and for every screen with no camera of ours behind it, in
    -- which case the key falls through untouched. Ahead of the hotkey
    -- table because unlike those it is NOT free-roam only: a staged battle
    -- is exactly where the zoom is most wanted.
    if (key == "q" or key == "e")
       and not (top and top.onKeyPressed) then
      if CamControl.zoomBy(key == "q" and 1 or -1) then return end
    end
    -- A screen with its own key handler gets the key first, exactly as the
    -- engine's first branch does: typing a nickname must not toggle a
    -- render mode. Only free-roam presses are ours to take.
    if claim and not (top and top.onKeyPressed) then
      if claim == "pipeline" then
        -- 3 walks the ANGLE rungs and steps over FULL (Voxel.HOTKEY_ORDER),
        -- so the registry's plain "advance one and wrap" is not what it
        -- wants; 6 still is. The gate is the registry's own either way.
        -- The whole of 3's step lives in cycleVoxel, because the pad's
        -- SELECT button makes the same step (see the handleInput wrap).
        if key == "3" then
          if cycleVoxel(self) then return end
        elseif Pipelines.hotkey(key, top, self.overworld) then
          Pipelines.syncOptions(self.save.options)
          require("src.render.Tilt").setLevel(self.save.options.tilt or 0)
          self:writeOptions()
          return
        end
      elseif Pipelines.canToggle("voxel", top, self.overworld) then
        -- All four answer to the voxel pass's own free-roam gate --
        -- borrowed from the registry rather than restated, so a press
        -- mid-warp or mid-cutscene is refused for the wireframe exactly when
        -- it would be for the mode itself. Three of them parameterise that
        -- pass; the fourth (3D-BTL) decides what a battle is drawn over, and
        -- wants the same gate for a different reason: the answer is read
        -- when the fight starts, so flipping it from inside one would be a
        -- switch that appeared to do nothing.
        claim:cycle(self)
        -- 8 is one of the two ways staged battles get switched on, and they
        -- pin BATTLE LAYOUT to OG (see the rows hook). The other keys
        -- parameterise the pass and leave the layout alone; the guard answers
        -- for all of them, so nothing here has to know which key it was.
        if stagedBattles() then OverworldBattle.forceOG(self) end
        return
      end
    end
    return inner(self, key)
  end
else
  -- Gold/Silver reserves 3 for its flat TILT before pipeline hotkeys are
  -- offered. Claim it at that same display-hotkey layer so the voxel camera
  -- ladder wins while this mod is installed, exactly as on Gen1.
  local Game = require("src.core.Game")
  if type(Game.hotkey) == "function" and not Game.battleArtVoxelGen2Hotkey then
    local innerHotkey = Game.hotkey
    function Game:hotkey(key)
      if key == "3" and cycleVoxel(self) then return true end
      return innerHotkey(self, key)
    end
    Game.battleArtVoxelGen2Hotkey = true
  end
end

-- ------- the mode's rows, kept together
--
-- The engine splices a pipeline's row in beside TILT, because a display mode
-- belongs with the other display modes; a mod's own ui.options.rows
-- additions land at the END of the list. That left this mod's four rows in
-- two places with unrelated engine rows between them, which reads as two
-- unrelated features rather than one mode with settings.
--
-- So the plain settings are inserted directly after the last of this mod's
-- PIPELINE rows instead of appended. Nothing else moves: the block lands
-- where the engine already decided display modes go.
local function insertGrouped(out, extra)
  local anchor = nil
  for i, row in ipairs(out) do
    local id = type(row) == "table" and row.id
    if id == "pipeline:voxel" or id == "pipeline:tiltshift" then anchor = i end
  end
  -- Gold/Silver has no native pipeline rows. Put the block at its display
  -- controls instead of appending it after CANCEL, where the preceding row
  -- exits the screen and makes every appended mod setting look absent.
  if not anchor then
    for i, row in ipairs(out) do
      if type(row) == "table" and row.id == "zoom" then anchor = i end
    end
  end
  if not anchor then
    local at = #out + 1
    for i, row in ipairs(out) do
      if type(row) == "table" and (row.cancel or row.id == "cancel") then
        at = i
        break
      end
    end
    for i, row in ipairs(extra) do table.insert(out, at + i - 1, row) end
    return out
  end
  for i, row in ipairs(extra) do table.insert(out, anchor + i, row) end
  return out
end

-- FULL owns the settings that describe the LOOK, so while it is selected those
-- are taken off the menu rather than left to be changed under it -- including
-- T-SHIFT, which is a pipeline row the engine put there. A row that no longer
-- decides anything is worse than no row.
--
-- The battle rows are the exception and they stay; see the rows hook.
local function dropRow(out, id)
  for i = #out, 1, -1 do
    if type(out[i]) == "table" and out[i].id == id then table.remove(out, i) end
  end
  return out
end

-- ------- TILT and GBC FX are gone while this mod is installed
--
-- Both fight the diorama, and both were already half-taken: the mode's own key
-- (3) forces them off on every press, and the registry switches TILT off
-- whenever a world pipeline takes the pass. What was left was two rows the
-- player could set and watch get reverted -- TILT is the flat fake of what
-- this mode does for real, and GBC FX is a full-screen present pass over the
-- top of the whole thing.
--
-- So they come OFF the menu, and are HELD at zero rather than merely dropped.
-- Hiding a live setting is a trap: a save written before the mod was installed
-- can carry TILT 3, and a row that is not there is a row that cannot turn it
-- back off. Pinned wherever the value could have arrived from -- the menu
-- opening, a save being loaded or begun -- so there is no route by which one
-- of them is on and unreachable.
--
-- Everything they did is still reachable: uninstall the mod and both rows are
-- back, at whatever they were last set to.
-- BATTLE BG rides the same reasoning, and comes off for a reason of its own.
-- The row picks what fills the screen AROUND the battle's 160x144 field --
-- WHITE paper, BLACK bars, or the frozen overworld dimmed behind it -- and
-- all three were answers to the same question: what to do with the voids,
-- given the battle is a small picture in the middle of a big window.
--
-- This mod answers that question differently and permanently. A staged fight
-- fills the whole window with the map the fight is standing on, and the
-- flat battle screen it composites over it is drawn on the mode's own
-- surface; there are no voids left for the row to fill. WORLD is the worst
-- of the three under it -- it makes the battle non-opaque so the engine
-- draws the overworld underneath, which is a SECOND copy of the world drawn
-- under the one the arena pass already put there, dimmed and at a different
-- camera. BLACK bars over a diorama read as a letterboxed screenshot.
--
-- So the value is pinned at WHITE, which is the one the mode was composed
-- against, and the row comes off the menu on the same reasoning as TILT and
-- GBC FX: a row that no longer decides anything is worse than no row.
-- Uninstall the mod and it is back, at whatever it was last set to.
local function pinEngineFx(game)
  game = game or require("src.core.Game")
  local opts = game and (game.options or (game.save and game.save.options))
  local okTilt, Tilt = pcall(require, "src.render.Tilt")
  local okGbc, GBCFX = pcall(require, "src.render.GBCFX")
  local changed = false
  if opts then
    changed = (opts.tilt or 0) ~= 0 or (opts.gbcfx or 0) ~= 0
                or (opts.battleBg or "white") ~= "white"
    opts.tilt, opts.gbcfx = 0, 0
    opts.battleBg = "white"
  end
  if okTilt and Tilt and Tilt.setLevel then pcall(Tilt.setLevel, 0) end
  if okGbc and GBCFX and GBCFX.setLevel then pcall(GBCFX.setLevel, 0) end
  if changed and game.writeOptions then pcall(game.writeOptions, game) end
end

-- The staged composition is authored against ADVANCED (RED++) and the original
-- centered 160x144 furniture. Apply that presentation when a journey starts,
-- then leave both engine rows live so the player can change either afterward.
local function applyPresentationDefaults(game)
  game = game or require("src.core.Game")
  local opts = game and game.save and game.save.options
  if not opts then return end
  local changed = opts.colors ~= "redpp" or opts.uiLayout ~= "centered"
  opts.colors = "redpp"
  opts.uiLayout = "centered"
  pcall(require("src.render.PaletteFX").setMode, "redpp")
  -- Restore defaults also resets the diorama blur to OFF. Tilt-shift is
  -- opt-in and must not survive a "restore defaults" press (or a save that
  -- arrived with it forced on by an older FULL preset).
  local Pipelines = require("src.render.Pipelines")
  Pipelines.setLevel("tiltshift", 0)
  Pipelines.syncOptions(opts)
  if changed and game.writeOptions then pcall(game.writeOptions, game) end
end

-- call next() first and decorate what comes back, so every other mod's
-- rows survive this one
mod.hooks:wrap("ui.options.rows", function(next, game, rows)
  local out = next(game, rows)
  if type(out) ~= "table" then return out end
  local Pipelines = require("src.render.Pipelines")
  -- ahead of every branch below, including FULL's early return: these two are
  -- off the menu whatever else this mod is or is not doing
  pinEngineFx(game)
  dropRow(out, "tilt")
  dropRow(out, "gbcfx")
  -- and BATTLE BG with them: this mode fills the window with the map, so
  -- the row's whole question -- what to put in the voids around the battle
  -- -- no longer has voids to be about (see pinEngineFx)
  dropRow(out, "battleBg")
  -- BATTLE LAYOUT is the ENGINE's row, and this is the one place the mod takes
  -- one away. While a fight can be staged on the map, OG is the only layout it
  -- can be composed in (OverworldBattle.forceOG), so the value is pinned there
  -- and the row comes off the list on the same reasoning as the rows FULL owns:
  -- a row that no longer decides anything is worse than no row. Nothing is
  -- lost by switching 3D-BTL off -- the row is back, WIDE and all, on the same
  -- keypress.
  if stagedBattles() then
    OverworldBattle.forceOG(game)
    dropRow(out, "battleLayout")
  end
  local full = Voxel.isFull(Pipelines.level("voxel"))
  if full then
    -- FULL owns the rows that PARAMETERISE the diorama -- the wireframe, the
    -- horizon bend, the blur. DAYTIME is no longer among them: FULL sets it
    -- to SYNC on arrival and then lets go, like the battle rows.
    -- TILT-SHIFT is intentionally KEPT on the menu at FULL: the player may
    -- want to tune the blur even on the preset look, so do not drop it here.
  end
  local extra = {}
  for _, entry in ipairs(SETTINGS) do
    -- Two things decide whether a row is offered.
    --
    -- FULL: a preset that owns the look, so the rows that describe the look go
    -- with it. The BATTLE rows are not that -- 3D-BTL decides what a fight is
    -- drawn OVER and BACK SPRITES how it is framed, and neither is a knob on
    -- the diorama FULL is a preset for. FULL still SETS them on arrival (see
    -- applyFull); it does not hold them, so leaving them on the menu is the
    -- difference between a preset and a lock.
    --
    -- And a row whose own switch is off the table this frame (BACK SPRITES,
    -- which needs a staged fight to be about) is left off with it. The mod
    -- manager's page carries every one of them either way.
    local offered = not entry.managerOnly
                    and (entry.full or not full)
                    and (not entry.when or entry.when())
    if offered then
      local row = entry[1]:row()
      if entry[1] == RamPrecacheSetting then
        local step = row.step
        row.step = function(g, dir)
          local changed = step(g, dir)
          applyRamPrecacheBudget()
          return changed
        end
      end
      extra[#extra + 1] = row
    end
  end
  -- Gold/Silver's OPTION screen never splices render-pipeline rows (only
  -- Gen 1's menu does), so without this the VOXEL row cannot exist here no
  -- matter what registers. Offer it beside the mod's own rows.
  local hasVoxelRow = false
  for _, row in ipairs(out) do
    if row.id == "pipeline:voxel" then hasVoxelRow = true break end
  end
  if not hasVoxelRow then
    -- The keyboard shortcut deliberately skips FULL and only advances. An
    -- options row must expose the complete ladder and honor left and right.
    table.insert(extra, 1, {
      id = "pipeline:voxel",
      label = "VOXEL",
      value = function() return Pipelines.levelLabel("voxel") end,
      step = function(g, dir)
        local span = Pipelines.maxLevel("voxel") + 1
        local target = (Pipelines.level("voxel") + (dir or 1)) % span
        setVoxelOption(g, target)
        return true
      end,
    })
  end
  -- Tilt-shift is a render pipeline (the diorama blur) that Gen2's OPTIONS
  -- menu never splices in on its own (only Gen 1's menu does), the same gap
  -- the VOXEL row above works around. Inject it unconditionally so the blur
  -- is tunable from the in-game OPTIONS menu at any voxel level.
  table.insert(extra, {
    id = "pipeline:tiltshift",
    label = "T-SHIFT",
    value = function() return Pipelines.levelLabel("tiltshift") end,
    step = function(g, dir)
      local span = Pipelines.maxLevel("tiltshift") + 1
      local target = (Pipelines.level("tiltshift") + (dir or 1)) % span
      Pipelines.setLevel("tiltshift", target)
      -- Persist: setLevel only touches the live ladder. Mirror cycleVoxel's
      -- save path so the choice survives a menu exit (previously it reverted
      -- to the stored level on exit).
      local opts = g and g.save and g.save.options
      if opts then
        Pipelines.syncOptions(opts)
        if g.writeOptions then pcall(g.writeOptions, g) end
      end
      return true
    end,
  })
  return insertGrouped(out, extra)
end)

-- Gen 1's title Menu executes an injected row's onSelect directly. The Gen 2
-- Chrome list (used by this port for Gold/Silver) passes only `value` into a
-- closed vanilla switch, so a label + onSelect row is visible but inert. Add
-- the same callback seam Gen 2's StartMenu already provides.
do
  local ok, MainMenu = pcall(require, "src.ui.gen2.MainMenu")
  if ok and MainMenu and not MainMenu.bavcInjectedRowHook then
    local choose = MainMenu.choose
    function MainMenu:choose(value)
      local item = self.list and self.list.items
        and self.list.items[self.list.index or 1] or nil
      if value == nil and item and type(item.onSelect) == "function" then
        return item.onSelect(self.game, self)
      end
      return choose(self, value)
    end
    MainMenu.bavcInjectedRowHook = true
  end
end

-- Generate the whole selected version only when the player explicitly asks.
-- CONTINUE merely inflates existing compressed records into RAM, then invokes
-- the engine's original action; missing records remain lazy runtime misses.
mod.hooks:wrap("ui.title_menu.items", function(next, game, items)
  local out = next(game, items)
  if type(out) ~= "table" then return out end
  VoxelMeshDisk.bind(game, true)
  local cacheAvailable = VoxelMeshDisk.available()
  for _, item in ipairs(out) do
    if tostring(item and item.label or "") == "CONTINUE" and cacheAvailable then
      local continue
      if type(item.onSelect) == "function" then
        continue = item.onSelect
      elseif item.value == "continue" then
        item.value = nil
        continue = function(_, menu) menu:choose("continue") end
      end
      if continue then item.onSelect = function(_, menu)
        VoxelMeshDisk.beginSession()
        -- OFF disables precache entirely: no preload, no RAM limit
        local preload = applyRamPrecacheBudget()
        if not preload then
          continue(game, menu)
          return
        end
        -- Mobile RAM budgets are smaller than a complete Gen2 cache. Start
        -- with the saved area and its connected neighbours so CONTINUE enters
        -- the 3D world immediately instead of spending the budget on an
        -- alphabetical, unrelated portion of the cache.
        local priorityMaps = VoxelPrecache.startupMapIds(game.data, game.save)
        -- Desktop-class builds may hold the whole compressed cache resident
        -- (eager preload). Consoles, mobiles and handhelds stream per-map from
        -- disk under a RAM budget and evict the oldest, so a long session
        -- cannot OOM the way a 4 GiB Switch did loading the full world.
        if VoxelMeshDisk.eagerLoadAllowed() then
          VoxelMeshDisk.setRamBudget(0)
          local names = select(1, VoxelMeshDisk.ramPlan(priorityMaps))
          local resume = function() continue(game, menu) end
          if not names or #names == 0 or VoxelMeshDisk.ramReady(names) then
            resume()
          else
            game.stack:push(VoxelCacheRamScreen.new(game, resume, priorityMaps))
          end
        else
          -- Streaming platform: retain the user's selected compressed-cache
          -- budget. The loader screen fills that budget before continuing so
          -- the first visible area does not pay the disk-read cost.
          local names = select(1, VoxelMeshDisk.ramPlan(priorityMaps))
          local resume = function() continue(game, menu) end
          if not names or #names == 0 or VoxelMeshDisk.ramReady(names) then
            resume()
          else
            game.stack:push(VoxelCacheRamScreen.new(game, resume, priorityMaps))
          end
        end
      end end
    elseif tostring(item and item.label or "") == "NEW GAME" then
      local newGame
      if type(item.onSelect) == "function" then
        newGame = item.onSelect
      elseif item.value == "new" then
        item.value = nil
        newGame = function(_, menu) menu:choose("new") end
      end
      if newGame then item.onSelect = function(_, menu)
        newGame(game, menu)
        VoxelMeshDisk.bind(game, false)
        VoxelMeshDisk.beginSession()
        local preload = applyRamPrecacheBudget()
        if preload and VoxelMeshDisk.eagerLoadAllowed() then
          VoxelMeshDisk.setRamBudget(0)
        end
      end end
    end
  end
  if not VoxelMeshDisk.precacheAvailable() then return out end
  local entry = {
    label = "PRECACHE",
    onSelect = function()
      VoxelMeshDisk.beginPrecache()
      game.stack:push(VoxelPrecacheScreen.new(game))
    end,
  }
  local at = #out + 1
  for i, item in ipairs(out) do
    if tostring(item and item.label or "") == "EXIT GAME" then at = i break end
  end
  table.insert(out, at, entry)
  return out
end)

-- Runtime misses stay in RAM until the pause-menu CACHE action. SAVE writes
-- only dirty records; DROP clears this Gold/Silver namespace and GPU meshes.
mod.hooks:wrap("ui.start_menu.items", function(next, game, items)
  local out = next(game, items)
  if type(out) ~= "table" then return out end
  VoxelMeshDisk.bind(game, false)
  for _, item in ipairs(out) do
    if tostring(item and item.label or "") == "CACHE" then return out end
  end
  local entry = {
    label = "CACHE",
    onSelect = function()
      if VoxelMeshDisk.cacheReadOnly() then
        game.stack:push(VoxelPrecacheScreen.new(game))
        return
      end
      local Menu = require("src.ui.Menu")
      local Screens = require("src.ui.Screens")
      local TextBox = require("src.render.TextBox")
      local function reopen() Screens.push(game, "StartMenu") end
      game.stack:push(Menu.new(game, {
        { label = "SAVE", onSelect = function()
          local before = VoxelMeshDisk.ramStats()
          local ok, saved, failed, errors = VoxelMeshDisk.saveRamToDisk()
          if not ok then
            local Logger = require("src.core.Logger")
            for _, err in ipairs(errors or {}) do
              Logger.error("voxel cache save: %s", tostring(err))
            end
            game.stack:push(TextBox.new(game,
              ("CACHE SAVE FAILED\n%d FILE%s NOT WRITTEN\fTRY SAVE AGAIN")
                :format(failed, failed == 1 and "" or "S")))
          elseif saved == 0 then
            game.stack:push(TextBox.new(game,
              ("CACHE ALREADY SAVED\nRAM %s")
                :format(VoxelMeshDisk.sizeText(before.bytes))))
          else
            local after = VoxelMeshDisk.ramStats()
            game.stack:push(TextBox.new(game,
              ("CACHE SAVED\n%d FILE%s\nRAM %s\n%d IN RAM")
                :format(saved, saved == 1 and "" or "S",
                        VoxelMeshDisk.sizeText(after.bytes), before.files)))
          end
        end },
        { label = "DROP", onSelect = function()
          ChunkMesher.purgeCache()
          game.stack:push(TextBox.new(game,
            "MESH CACHE DROPPED\nAREAS REBUILD CLEAN"))
        end },
      }, { tx = 10, ty = 0, tw = 10, onCancel = reopen }))
    end,
  }
  local at = #out + 1
  for i, item in ipairs(out) do
    if tostring(item and item.label or "") == "SAVE" then at = i break end
  end
  table.insert(out, at, entry)
  return out
end)


-- Game2 applies saved pipeline levels (Pipelines.applyOptions, Game2.lua:1984)
-- while its options load -- which can run BEFORE this mod's entry chunk
-- registers the voxel pipeline on the Gold/Silver boot path. A stored level
-- then restores into a registry without us and is dropped; the probe caught
-- exactly that: map=ROUTE_30, world+camera live, level=0. Re-apply once the
-- game is up: whatever the stored option says wins, unless the player has
-- already stepped the ladder themselves.
local voxelRestoreDone = false
mod.events:on("game.ready", function(payload)
  if voxelRestoreDone then return end
  voxelRestoreDone = true
  local game = payload and payload.game or V.game()
  StaticGeometry.configure(game)
  -- Seed the player art/anim rows from the save's gender when the player has
  -- made no explicit choice: a girl opens on the BYO player.png, a boy on
  -- gen2. An explicit pick (or a stored value) always wins.
  pcall(BattleArt.seedPlayerDefaults, game)
  local opts = gen2PipelineOptions(game)
  local stored = type(opts) == "table" and type(opts.pipelines) == "table"
    and tonumber(opts.pipelines.voxel) or nil
  local Pipelines = require("src.render.Pipelines")
  if stored and Pipelines.level("voxel") <= 0 and math.floor(stored) > 0 then
    Pipelines.setLevel("voxel", math.min(math.floor(stored),
                                         Pipelines.maxLevel("voxel")))
    Voxel.setLevel(Pipelines.level("voxel"))
    Pipelines.syncOptions(opts)
    writeWorldProbe("restore",
      "restored voxel level " .. tostring(Pipelines.level("voxel"))
      .. " from saved options at game.ready")
  end
  if mirrorVoxelOption(game, Pipelines.level("voxel"))
      and game and game.writeOptions then
    pcall(game.writeOptions, game)
  end
end)

-- The mod manager writes and persists on its own, so the only thing left
-- to do is move our cached index and pick the new value up.
mod.events:on("mod.options_changed", function(payload)
  if not (payload and payload.mod == mod.id) then return end
  if payload.key == VOXEL_OPTION_KEY then
    setVoxelOption(V.game(), payload.value)
    return
  end
  for _, entry in ipairs(SETTINGS) do
    if payload.key == entry[1].key then entry[1]:sync(payload.value) end
  end
  if payload.key == RamPrecacheSetting.key then
    applyRamPrecacheBudget()
  end
  -- 3D-BTL switched on from the manager's page pins BATTLE LAYOUT exactly as
  -- the OPTIONS row does. The manager persists its own value; this is the one
  -- that has to follow it.
  if stagedBattles() then OverworldBattle.forceOG() end
end)

-- ------- keeping the geometry in step with the world
--
-- Terrain meshes are derived from a map's block layer, so anything that
-- rewrites a block (a cut tree, a smashed rock, a script's replaceBlock)
-- has to drop that map's cached mesh or the 3D world keeps showing the
-- tree that is no longer there.  The 2D tile renderer invalidates its own
-- caches off the same edit.

-- Keep the current terrain drawable and drop only changed props immediately.
V.require("BlockMeshRefresh").install(ChunkMesher, mod.events)

-- A reloaded map is rebuilt from scratch (warps that re-enter the same map,
-- hot reload), so its mesh is stale for the same reason -- with one
-- exception, and it is the common one.
--
-- A palette switch reloads the map ONLY to rebuild its atlas
-- (PaletteFX.setMode -> reloadMap(id, "colors")). The geometry that comes
-- back is identical: this mesher reads block layout and tile ids and never
-- reads colour, and the palette lives entirely in the texture TerrainAtlas
-- hands back per frame -- which is keyed BY palette, so the new colours are
-- already built by the time the next frame draws.
--
-- Dropping the mesh anyway cost a visible flash of the flat 2D world on
-- every palette toggle. Mesh builds are asynchronous, so the frames between
-- the drop and the first finished mesh have no terrain to draw, and
-- drawWorld returning nil IS the 2D fallback. Keeping the geometry lets the
-- new colours land on the diorama already on screen, in one frame, which is
-- what a palette toggle should look like from inside voxel mode.
mod.events:on("map.reloaded", function(payload)
  if payload and payload.reason == "colors" then return end
  local mapId = payload and (payload.mapId or (payload.map and payload.map.id))
  if mapId then ChunkMesher.invalidate(mapId) end
end)

-- ------- rows come and go, so the menu has to notice
--
-- OptionsMenu builds its row list ONCE, when it is opened, and then reads
-- that list every frame. So stepping the VOXEL row onto or off FULL changed
-- which rows the hook would return but not which rows were on screen -- the
-- settings FULL owns stayed visible until the menu was closed and reopened,
-- and a player who stepped off FULL could not see the rows come back.
--
-- Rebuilt in place, and only on a step that changes the LIST: crossing FULL,
-- toggling 3D-BTL, or switching the player's selected sprite side.
-- Every other rung returns the same list, and rebuilding on all of them would
-- rerun every mod's ui.options.rows hook once per keypress. The cursor is
-- clamped rather than reset, so it stays on the row it was just used on
-- instead of jumping to the top when the list below it shortens.
do
  local OptionsMenu = require("src.ui.OptionsMenu")
  if not OptionsMenu.dramaticShapeFullHook then
    local Pipelines = require("src.render.Pipelines")
    local inner = OptionsMenu.update

    local function idAt(menu, index)
      local row = menu.rows and menu.rows[index or 1]
      return type(row) == "table" and row.id or nil
    end

    function OptionsMenu:update(dt)
      local before = Pipelines.level("voxel")
      local hadBattles = OverworldBattle.enabled()
      -- the VR row hides the two battle rows while it is on, so stepping
      -- it changes the LIST exactly the way 3D-BTL does
      local hadVR = VR.enabled()
      local hadPlayerSide = BattleArt.playerSide()
      local wasOn = idAt(self, self.index)
      inner(self, dt)
      local after = Pipelines.level("voxel")
      local crossedFull = after ~= before
                          and (Voxel.isFull(before) or Voxel.isFull(after))
      if crossedFull or OverworldBattle.enabled() ~= hadBattles
         or VR.enabled() ~= hadVR
         or BattleArt.playerSide() ~= hadPlayerSide then
        local rebuilt = OptionsMenu.new(self.game)
        self.rows = rebuilt.rows
        -- Follow the row the cursor was ON rather than the slot it was in:
        -- 3D-BTL takes BATTLE LAYOUT off the list ABOVE itself, which would
        -- otherwise slide the cursor onto the row under the one just used.
        for i = 1, #self.rows do
          if wasOn and idAt(self, i) == wasOn then self.index = i; break end
        end
        local cancel = #self.rows + 1
        if (self.index or 1) > cancel then self.index = cancel end
      end
    end

    OptionsMenu.dramaticShapeFullHook = true
  end
end

-- ------- battles on the map
--
-- The wraps this needs -- OverworldState:pushBattle, BattleState:draw and
-- BattleState:drawHUDs -- all live in lib/OverworldBattle.lua, which is
-- where the reasoning for each one is written down. Installed once, here,
-- so this file keeps naming every engine seam the mod touches.
OverworldBattle.install()
StadiumBackground.install()

-- ------- the free-roam rungs' inputs and their walk
--
-- 1ST and 3RD need two things no other rung does, and each is a named seam.
-- Both rungs are one rig -- the boom behind the shoulder is a number inside
-- it (lib/ThirdPerson.lua) -- so both are installed by the same two calls:
--
-- FirstPerson.install claims the LOOK inputs the engine ignores: the right
-- stick's axes (Game:gamepadaxis passes them to Input, which returns early
-- on anything but the left pair), relative mouse motion (through the public
-- input.pointer hook), the mouse buttons
-- while the cursor is captured (A and B -- there is no cursor to click UI
-- with), and any touch that lands off the overlay's controls (a drag on
-- open screen is the look; the d-pad and buttons still go to
-- TouchControls, whose own d-pad finger is also read back analog as the
-- move vector). Every wrap forwards whatever it does not claim, and claims
-- only while one of the two rungs is actually driving.
--
-- Movement is generation-specific. Gen1FreeMove wraps
-- OverworldState:handleInput; Gen2FreeMove instead wraps Gold/Silver's
-- World:pollInput and World:stepBody. Both keep a continuous camera-relative
-- body while synchronising the logical cell and handing warps, encounters,
-- ledges, boulders, map connections and forced movement back to the native
-- generation's own machinery.
FirstPerson.install()
if V.generation() == 2 then
  local Gen2FreeMove = V.require("Gen2FreeMove")
  local ok, why = Gen2FreeMove.install()
  if not ok then
    error("BATTLE_ART_VOXEL_GEN2: Silver free movement unavailable: "
      .. tostring(why), 0)
  end
else
  FreeMove.install()
end

-- ------- the zooms, and the battle camera the player can steer
--
-- CamControl claims the wheel, Q/E, the mouse and the touch screen for
-- whichever camera is actually in front of the player -- the staged
-- battle's, the third-person boom, or the engine's own survey zoom -- and
-- forwards everything else. Installed AFTER the two above deliberately: a
-- wrap installed later is the OUTER one, so a fight gets first refusal on
-- the mouse and the fingers, which is right, because while one is staged
-- the free-roam look is not driving.
CamControl.install()

-- ------- SELECT walks the angle ladder
--
-- The same step the "3" key makes, on the pad's own button: a phone (and
-- a controller) has no number row, and SELECT has no overworld job in
-- Gen 1 -- its work is all in-menu, which this wrap never sees. The seam
-- is OverworldState:handleInput, the same choke point the free walk
-- replaced: every gate above it -- menus, dialogs, scripted moves,
-- transitions -- already decided the overworld owns the buttons, so a
-- SELECT here is free-roam by construction, exactly like the key. When
-- the step is refused (mid-warp, no 3D pass) the press falls through to
-- the engine's own handling, which is a no-op, as ever.
--
-- Gen 2 is the exception: CheckRegisteredItem gives SELECT a real
-- overworld job there, so a live registration wins and the ladder is left
-- to the key, the pad's own binding and the OPTIONS row.  With nothing
-- registered SELECT is idle exactly as in Gen 1, and still steps.
--
-- Installed after the movement bridge. On Gen1 its wrap must sit outside
-- FreeMove's handleInput replacement or 1ST would eat SELECT. Silver's bridge
-- lives on World instead, so the compatibility OverworldController wrap does
-- not compete with continuous movement there.
do
  local OverworldState = require("src.world.OverworldController")
  local GameVersion = require("src.core.GameVersion")
  local function registeredItemOwnsSelect(Game)
    if not GameVersion.isGen2() then return false end
    local save = Game and Game.save
    local id = save and save.registeredItem
    if not id then return false end
    local def = Game.data and Game.data.items and Game.data.items[id]
    return (def and def.registerable and save.inventory
            and save.inventory[id]) and true or false
  end
  if not OverworldState.dramaticShapeSelectHook then
    local inner = OverworldState.handleInput
    function OverworldState:handleInput(...)
      local Game = require("src.core.Game")
      local input = Game.input
      if input and input.wasPressed and input:wasPressed("select")
         and not registeredItemOwnsSelect(Game) then
        if cycleVoxel(Game) then return end
      end
      return inner(self, ...)
    end
    OverworldState.dramaticShapeSelectHook = true
  end
end

-- ------- the konami code, and everything it turns on
--
-- Installed last of the input seams so its handleInput reasoning sits
-- outside FreeMove's and SELECT's. The detector itself does not live on
-- handleInput at all -- it reads the fixed step's own press queue, which
-- is where keyboard, pad, touch and the VR controllers have all already
-- become the same eight buttons. See lib/Horde.lua.
Horde.install()

-- ------- edge-anchored menus stay in the GB frame while a headset is live
--
-- The engine's zoom-aware anchoring (Renderer:setUIAnchor) docks the START
-- menu to the WINDOW's top-right edge. Both VR screens -- the floating
-- panel and the Pokedex -- crop the window to the GB frame, so a menu at
-- the window's edge is cropped away with the border it docked to. The
-- engine's own answer to "a state composes its screen, keep every element
-- inside it" is uiAnchorHold, computed per frame from this predicate; a
-- live headset is exactly that situation for the WHOLE window, so the
-- predicate answers yes for as long as one is. Held menus blit where they
-- were drawn in the 160x144 canvas -- the START menu's 9,0 x 11 slot is
-- already flush with the frame's right edge, which is the right edge of
-- what the headset sees. Off-headset frames fall through untouched. Gold's
-- Game2 compositor already keeps its screen stack inside the GB frame.
if V.generation() ~= 2 then
  local Game = require("src.core.Game")
  if not Game.dramaticShapeAnchorHold then
    local inner = Game.uiAnchorsHeldInStack
    function Game.uiAnchorsHeldInStack(stack)
      if VR.active() then return true end
      return inner(stack)
    end
    Game.dramaticShapeAnchorHold = true
  end
end

-- The overworld's own pushBattle is the choke point for a wild encounter or
-- a trainer, and it is wrapped. A battle that arrives some other way -- a
-- link battle, a script pushing a BattleState directly -- reaches this
-- instead, which stages the arena from wherever the player is standing.
-- Nothing visible is lost by being late: the cull only has to beat the
-- battle screen, and the wipe those battles skip is where it would have
-- shown.
mod.events:on("battle.started", function(payload)
  OverworldBattle.ensure(payload and payload.battle)
end)

-- Both mons face the camera, so the player's side wants its FRONT pic where
-- the battle screen would have used the back one. The engine's own
-- pokemon.sprite hook is the seam for exactly this: it is asked for every
-- battle pic with the side it is resolving, so swapping one side's answer
-- needs no battle code at all -- and every path that builds a battler goes
-- through it, including a Transform mid-fight.
--
-- next() first, so a sprite-replacing mod loaded before this one still gets
-- the last word on WHICH art is used; this only changes which SIDE is asked
-- for.
mod.hooks:wrap("pokemon.sprite", function(next, path, ctx)
  local out = next(path, ctx)
  if not (ctx and ctx.kind == "battle" and ctx.side == "back") then
    return out
  end
  if BattleArt.playerSide() ~= "front" then return out end
  if not OverworldBattle.wantsFront() then return out end
  local def = ctx.data and ctx.data.pokemon and ctx.data.pokemon[ctx.species]
  return (def and def.spriteFront) or out
end)

-- Every ending path emits this, including a battle skipped before it drew,
-- so this is where the map's cast comes back.
-- Gold/Silver raises battle.ended the moment the OUTCOME is decided --
-- while the defeat/exp dialogue is still queued and on screen -- so a full
-- teardown here froze the staged arena mid-conversation. Mark the session
-- ending and let OverworldBattle.update finish it when the battle screen
-- actually leaves the stack.
mod.events:on("battle.ended", function()
  OverworldBattle.retire()
end)

-- ------- and the way back out
--
-- The engine wipes INTO a battle with one of the original's eight transitions
-- and cuts straight OUT of it. That cut is between two very different cameras
-- in this mode, so while voxel mode is on the battle fades out, closes behind
-- the black, and the map fades up. The two seams it needs -- BattleState:finish
-- and Renderer:endFrame -- and the reasoning for each live in lib/BattleExit.lua.
--
-- Declared as a transitions record rather than a constant in that file, so the
-- fade is retunable in data exactly like the eight wipes it answers, and a total
-- conversion can make it as long or as short as its own pacing wants.
if V.generation() ~= 2 then
  mod.content.transitions:register(BattleExit.ID, {
    frames = BattleExit.FRAMES,
  })
  BattleExit.install()
end

-- ------- and the hour on the flat world
--
-- The clock reaches the diorama through the voxel shader's own tint uniform,
-- which the 2D tile path never runs -- so with the mode off, the same evening
-- that fell on the diorama left the flat world at permanent noon. One clock,
-- two worlds, one of them ignoring it. DayTint paints the same multiply over
-- the composited flat world, between the world blit and the UI blit; the
-- reasoning for that exact instant is in the file.
DayTint.install()

-- ------- what time it is
--
-- The cycle's clock rides the SAVE SLOT (save.modData, via mod.save): what
-- time it is in Kanto is a fact about that journey, like where the player is
-- standing. Written on the engine's save.writing event -- the moment before
-- the bytes hit disk -- and read back whenever a save is opened or begun. A
-- save with no clock in it starts at day; that is DayNight.restore's
-- fallback, and also the DAYTIME row's own default.
mod.events:on("save.writing", function()
  DayNight.store()
end)

mod.events:on("save.loaded", function()
  DayNight.restore()
  -- a save written before this mod was installed can carry TILT or GBC FX
  -- switched on, and their rows are not there to switch them back off (see
  -- pinEngineFx). Answered here rather than only when the menu opens, so a
  -- player who never opens it is not left playing under one.
  pinEngineFx()
  applyPresentationDefaults()
end)

mod.events:on("save.created", function()
  DayNight.restore()
  pinEngineFx()
  applyPresentationDefaults()
end)

-- The engine's own time-of-day seam. OverworldState:timeOfDay() is an
-- eternal "DAY" until a mod answers here; answering it hands the period to
-- the map.palette hook (ctx.tod) and music.select, so a palette or music
-- pack keyed to night works with this mod's clock for free. next() first: a
-- mod loaded before this one that already moved the time keeps its answer.
mod.hooks:wrap("world.tod", function(next, tod, ctx)
  local out = next(tod, ctx)
  if out ~= tod then return out end
  return DayNight.tod()
end)

mod.exports.version = "2.1.2"
mod.exports.battleStage = BattleStage.export(OverworldBattle)
mod.exports.battlePresentation = BattlePresentation.export()
-- Species art ownership + metrics, so companion mods (Stadium 2 importer,
-- effects mods) read the same battler identity Battle Art staged.
mod.exports.battleArt = BattleArt
-- Hook-aware screens (title, summary, dex entry) pick up BATTLE ART fronts
-- outside battle; every hook pcalls its screen module and skips on mismatch.
InterfaceSprites.install()

-- Player back pic in a normal (non-staged) gen2 battle. The engine resolves
-- the player's back through Sprites.playerPic -> the "player.sprite" hook, and
-- BATTLE ART's override otherwise only runs inside the staged voxel renderer.
-- Wrap that seam so the selected STATIC back-static PNG replaces the back for
-- ANY player (boy or girl, Gold or Kris) without touching fronts, intros or
-- the engine's own generation/ROM backs when the option is ROM.
mod.hooks:wrap("player.sprite", function(next, path, ctx)
  local out, trueColor = next(path, ctx)
  if out == nil then return nil end
  -- Only the in-battle BACK slot is ours; fronts/intros stay engine-owned.
  if not ctx or ctx.side ~= "back"
     or (ctx.kind and ctx.kind ~= "battle") then
    return out, trueColor
  end
  local png = BattleArt.playerBackPathForOptions()
  if png then return png, true end
  return out, trueColor
end)

-- exposed so a companion mod can pin its own tiles' shapes or read the
-- camera without reaching into this mod's file layout
mod.exports.lib = V