main.lua

-- Better Buildings -- FireRed-styled exteriors for Kanto's shops, gyms,
-- landmarks and ordinary town buildings.
--
-- These buildings are drawn from tiles the whole overworld shares: the roof
-- diamond (tile $12) is in eight blocks, the brick course (tile $0A) in
-- nineteen, and every gym in Kanto is the same three facade blocks repeated
-- -- which is why the four-wide gyms read "GYM GYM".  Repainting any of it
-- in place would re-skin every house in Kanto, so this mod takes the
-- surgical route instead:
--
--   1. transforms.lua grows the player's own extracted atlas downward and
--      paints original drawings into it (ids 96 and up).
--   2. New blocks are appended to the OVERWORLD tileset, fitted to the exact
--      vanilla arrangements each drawing stands in for.
--   3. Maps are repointed only after a complete chassis and, for landmarks,
--      its destination warp match.  Unrelated lookalikes such as Saffron's
--      Fighting Dojo keep the art they always had.
--
-- Footprint, collision and the warp cell are preserved to the pixel: each
-- doorway still sits in the cell it always did and its bottom-left tile is
-- still the tile the engine reads for the warp, so every map's warp table
-- keeps working untouched.  That covers the doors; the route gates and the
-- back entrances are opened by the tile in FRONT of the player instead, so
-- the new tiles inherit that facing too -- see CARPET_DIRS below.
--
-- Voxel mode reads the atlas through Assets.resolve, so it sees the grown
-- image.  The drawings normally keep the voxel detector's natural curved
-- roof profiles.  Only Fuchsia Gym and Fuchsia's Center need exact templates:
-- they touch solid scenery and would otherwise be flood-filled into it.

local mod = ...

local ATLAS_W, ATLAS_H = 128, 48         -- the vanilla overworld atlas
local PER_ROW = 16
local BASE_TILES = (ATLAS_W / 8) * (ATLAS_H / 8)   -- 96
local BAND_ROWS = 8                       -- one drawing band, in tile rows
local SHOP_ROW = ATLAS_H / 8              -- 6: the Center/Mart band

-- The gym roster, in the SAME ORDER as draw_gyms.GYMS -- band i of the
-- sheet holds gym i, so reordering one list without the other paints
-- Cerulean's roof on Pewter's gym.  tools/emit_transform.py checks the two
-- agree at authoring time.
--
-- `blocks` is the building's width in map blocks; `mirror` marks the one gym
-- (Fuchsia) whose vanilla building puts the doorway at the building's LEFT
-- edge, in the second cell of that block rather than the first.
local GYMS = {
  { warp = "PEWTER_GYM",    blocks = 3, mirror = false },
  { warp = "CERULEAN_GYM",  blocks = 4, mirror = false },
  { warp = "VERMILION_GYM", blocks = 3, mirror = false },
  { warp = "CELADON_GYM",   blocks = 4, mirror = false },
  { warp = "FUCHSIA_GYM",   blocks = 3, mirror = true },
  { warp = "SAFFRON_GYM",   blocks = 4, mirror = false },
  { warp = "CINNABAR_GYM",  blocks = 3, mirror = false },
  { warp = "VIRIDIAN_GYM",  blocks = 3, mirror = false },
}

local GYM_BAND = SHOP_ROW + BAND_ROWS     -- 14: the first gym band

-- ------- the ordinary buildings
--
-- Three chassis carry every house, shop and gate in Kanto, and the towns just
-- repeat them: a one-block-tall cottage terrace (blocks 2/48 + 9* + 3), a
-- gabled house (56/57 over 60/61 with a door, or 16/0 without) and the
-- flat-roofed civic block (32/13*/33 over 124 or 55, 58 or 125, and 126).
-- That last one is the SAME chassis the Center and the Mart are built from,
-- which is why re-skinning those two left everything beside them looking
-- wrong.
--
-- Because the game assembles those at any width, this mod ships KITS rather
-- than buildings: interchangeable one-block modules that tile into a run.
-- That is also the only way per-town styles fit.  A map's block ids are
-- capped at 255 (src/mods/Schemas.lua), the landmarks above already reach
-- 193, and one drawing per building would want more than a hundred ids.
-- Module reuse, borrowed kit parts and painting the regional defaults into
-- their vanilla slots keep the expanded roster inside the limit.
--
-- ORDER MATCHES draw_houses.py.  Band positions are computed from a style's
-- index in these lists, so reordering one list without the other hands
-- Lavender's slate to Viridian's cottages; tools/emit_transform.py checks the
-- two agree at authoring time.  `parts` is the subset of a kit the towns on
-- that style actually place -- drawing a module nobody places is free, but
-- APPENDING one is not.
local COTTAGES = {
  { key = "viridian", parts = "door right" },
  { key = "pewter",   parts = "door right" },
  { key = "cerulean", parts = "door plain mid right" },
  { key = "lavender", parts = "door right" },
  { key = "fuchsia",  parts = "door plain right" },
  { key = "celadon",  parts = "plain mid right" },
  { key = "kanto",    parts = "door plain mid right" },
}

-- one entry per DRAWING, two to a band.  A "plain" entry is the doorless
-- scenery variant of the style named before the `_plain` suffix and shares
-- its roof blocks -- vanilla draws both variants under the same roof pair.
--
-- `base` is the other direction: a style that claims only some of the kit and
-- borrows the rest from the style named.  Pallet's two houses are one drawing
-- in two paints -- the player's roof red, the rival's blue -- and are
-- identical below the eave, so the rival appends a roof and nothing else.
local HOUSES = {
  { key = "pallet",        parts = "roof door" },
  { key = "fuchsia",       parts = "roof door" },
  { key = "saffron",       parts = "roof door" },
  { key = "saffron_plain", parts = "plain" },
  { key = "kanto",         parts = "roof door" },
  { key = "pallet_rival",  parts = "roof", base = "pallet" },
}

-- `base` works here exactly as it does for the houses above: a style that
-- claims only some of the kit and takes the rest from the style named.  It is
-- what makes Celadon's named buildings affordable.  Most claim one doorway
-- bay and borrow the neighbours' roof.  The Game Corner and Mansion each
-- claim repeating roof and wall bays too.  Hotel and Diner use Celadon's
-- standard entrance, and the residential row repeats one sealed section, to
-- keep both landmarks under the block ceiling.
local FLATS = {
  { key = "town",    parts = "section door_r door_l" },
  { key = "port",    parts = "plain door_r right" },
  { key = "celadon", parts = "plain door_r door_l right" },
  -- Saffron never puts a doorway in a bay's LEFT cell
  { key = "saffron", parts = "section door_r" },
  { key = "celadon_row",     parts = "section" },
  { key = "celadon_corner",  parts = "roof facade door_l", base = "celadon" },
  { key = "celadon_hotel",   parts = "", base = "celadon" },
  { key = "celadon_diner",   parts = "", base = "celadon" },
  { key = "celadon_mansion", parts = "roof facade door_l", base = "celadon" },
  -- Kanto's route gates.  Same chassis as everything above, which is the
  -- whole problem: in a town's shopfront kit the one building you WALK
  -- THROUGH comes out as a sealed shop.  `gate_ends` carries the two cap
  -- modules that put the stepped entrance in the OUTER cell -- the end the player
  -- actually steps in at -- in a band of its own because the kit above
  -- already spends all four columns.
  { key = "gate",       parts = "section door_r door_l" },
  { key = "gate_ends",  parts = "end_w end_e", base = "gate" },
  { key = "vermilion",       parts = "roof", base = "port" },
}

local COT_ROWS, HOUSE_ROWS, FLAT_ROWS = 4, 6, 8   -- one band, in tile rows
local COT_BAND = GYM_BAND + BAND_ROWS * #GYMS                  -- 78
local HOUSE_BAND = COT_BAND + COT_ROWS * #COTTAGES             -- 106
local FLAT_BAND = HOUSE_BAND
  + HOUSE_ROWS * math.ceil(#HOUSES / 2)                        -- 124
local DEPT_ROWS = 4
local DEPT_BAND = FLAT_BAND + FLAT_ROWS * #FLATS               -- 204
local OAK_ROWS = 4
local OAK_BAND = DEPT_BAND + DEPT_ROWS                         -- 208
-- One dormant row belongs to the Better Paths and Grass companion.  This
-- mod owns the resolved OVERWORLD atlas, so the terrain art has to live here
-- to keep a second whole-atlas override from hiding the building bands.  No
-- Better Buildings block uses these ids on its own.
local TERRAIN_ROWS = 1
local TERRAIN_BAND = OAK_BAND + OAK_ROWS
local GROWN_H = (TERRAIN_BAND + TERRAIN_ROWS) * 8

-- which tile column of a band each module is drawn in
local COT_COL = { door = 0, plain = 4, mid = 8, right = 12 }
-- the two cap modules live in a band of their own, so they take the first
-- two columns rather than colliding with the doorways they never share a
-- band with
local FLAT_COL = { plain = 0, door_r = 4, door_l = 8, right = 12,
                   end_w = 0, end_e = 4 }
local DEPT_COL = { roof = 0, upper = 4, ground = 8, door = 12 }
local OAK_COL = { roof = 0, side = 4, door = 8 }

-- Kanto's towns, and the style each one builds in.  Anything not listed --
-- the route houses, Celadon's terrace, Cinnabar's civic pair -- takes the
-- regional default.
local COTTAGE_STYLE = {
  VIRIDIAN_CITY = "viridian", PEWTER_CITY = "pewter",
  CERULEAN_CITY = "cerulean", LAVENDER_TOWN = "lavender",
  FUCHSIA_CITY = "fuchsia", CELADON_CITY = "celadon",
}
local HOUSE_STYLE = {
  PALLET_TOWN = "pallet", FUCHSIA_CITY = "fuchsia", SAFFRON_CITY = "saffron",
}
-- A house that overrides its town's style, keyed by what is behind its door.
-- Pallet Town places the same gabled house twice, and the only thing that
-- tells the player's from the rival's is which one you can walk into and find
-- your mother in -- so the warp is what this reads, exactly the way the gyms
-- are found by their `*_GYM` warps rather than by their blocks.
local HOUSE_STYLE_BY_WARP = {
  REDS_HOUSE_1F = "pallet",         -- the player's own: a red roof
  BLUES_HOUSE = "pallet_rival",     -- the rival's, across the street: blue
}
local FLAT_STYLE = {
  CELADON_CITY = "celadon", SAFFRON_CITY = "saffron",
  VERMILION_CITY = "vermilion", CERULEAN_CITY = "port",
}
-- The style a town's civic kit switches to for a run with no doorway in it.
--
-- Celadon is nineteen buildings on one chassis, and thirteen of them cannot
-- be entered at all -- so drawing every one as retail frontage turned the
-- whole city into the department store repeated down both sides of the
-- street.  A run with a doorway module is somewhere you can go in; a run
-- without is where people live.  That is a distinction the vanilla map
-- already draws, so it needs no per-building list to read it.
local FLAT_RESIDENTIAL = { celadon = "celadon_row" }
-- A civic run that takes a style of its own, keyed by what is behind its
-- door -- the same way the gyms are found by their `*_GYM` warps and
-- Pallet's two houses are told apart.  The Game Corner owns both its doorway
-- plus repeating roof and wall panels; Mansion does the same.  Hotel and
-- Diner use the standard Celadon doorway, and residential buildings repeat
-- one sealed section; every remaining module is borrowed rather than added.
local FLAT_STYLE_BY_WARP = {
  GAME_CORNER = "celadon_corner",
  CELADON_HOTEL = "celadon_hotel",
  CELADON_DINER = "celadon_diner",
  CELADON_MANSION_1F = "celadon_mansion",
}
local DEFAULT_COTTAGE, DEFAULT_HOUSE, DEFAULT_FLAT = "kanto", "kanto", "town"

-- the vanilla blocks each chassis is assembled from
local COT_LEFT = { [2] = "door", [48] = "plain" }
local COT_MID, COT_RIGHT = 9, 3
local HOUSE_ROOF_L, HOUSE_ROOF_R = 56, 57
local HOUSE_FACE = { [60] = "door", [16] = "plain" }   -- keyed by left block
local HOUSE_FACE_R = { door = 61, plain = 0 }
local FLAT_LEFT = { [124] = "door_r", [55] = "plain" }
local FLAT_MID = { [58] = "door_l", [125] = "plain" }
local FLAT_RIGHT = 126
local FLAT_STOREY_L, FLAT_STOREY_M, FLAT_STOREY_R = 104, 127, 105
local FLAT_ROOF_L, FLAT_ROOF_M, FLAT_ROOF_R = 32, 13, 33

-- Where the DEFAULT style's modules are painted: straight onto the vanilla
-- blocks they stand in for, rather than into ids of their own.
--
-- Every Kanto map that places one of these chassis is converted above, so
-- once this mod has run not one map in the region still points at 2/48/9/3,
-- 56/57/60/61 or 124 -- which makes appending a copy of each pure waste of
-- the scarcest thing the mod has.  Painting the default kit in place costs
-- nine ids less, and is the more correct answer besides: a map that places a
-- vanilla cottage gets the improved art without this mod having to have
-- known about that map.
--
-- Only the DEFAULT styles may do this.  A town style painted onto a shared
-- vanilla block would put Lavender's slate on every route house in Kanto.
-- And only blocks nothing else reads: 16 and 0 carry the doorless house but
-- also the gyms and the grass, so `kanto`'s house claims neither.
local COT_REUSE = { kanto = { door = 2, plain = 48, mid = 9, right = 3 } }
local HOUSE_REUSE = {
  kanto = { roofL = 56, roofR = 57, doorL = 60, doorR = 61 },
}
local FLAT_REUSE = { town = { doorR = 124 } }

-- The gate kit is painted the same way, but onto ids DISCOVERED rather than
-- named -- because by the time it was written there were none left to name.
-- The landmark and town layers spend every id up to the 255 ceiling, so a
-- gate style that appended its six modules would push the ordinary-building
-- layer over the edge and cost Kanto every house kit it has.
--
-- What is left is the blockset's own slack: Kanto's OVERWORLD tileset ships
-- 128 blocks and the region's maps place only 121 of them.  The remaining
-- seven have no placement anywhere to disturb, so the gate kit paints into
-- them.  Discovered from the MERGED maps rather than hard-coded, so a map
-- mod that starts placing one of those blocks simply leaves fewer spares and
-- the gates keep the civic art they have today.
local GATE_PARTS = { "roofA", "facA", "doorR", "doorL", "endW", "endE" }

-- Kanto's gates, found the way every other building here is found: by what
-- is behind the door.  Every one of the fourteen leads to a map named for
-- it, and nothing else in the region is.
local function isGateMap(id)
  return type(id) == "string"
    and (id:match("_GATE$") ~= nil or id:match("_GATE_[12]F$") ~= nil)
end

-- A map block id is validated as a byte, so 255 is the last id this mod can
-- hand a map.  Vanilla spends 128 and the landmarks 70; the kits use all 58
-- slots that remain, so a tileset mod loaded ahead of this one can leave the
-- ordinary-building layer without room.
local BLOCK_CEILING = 256

-- the vanilla shop pair this mod stands in for: a 2x2 arrangement of blocks
-- whose south-east corner carries the POKe (114) or MART (115) sign
local SHOPS = {
  center = { se = 114, sw = 124, nw = 32, ne = 33 },
  mart   = { se = 115, sw = 124, nw = 32, ne = 33 },
}

-- where each shop drawing sits in its band: the Center in tile columns 0-7,
-- the Mart in columns 8-15
local SHOP_COLUMN = { center = 0, mart = 8 }

-- The vanilla gym, left to right along its facade row: a left cap, one or
-- more sign blocks, a right cap.  The plain caps (16/18) carry the doorway
-- on the right; the house-style caps (124/126) carry it on the left, which
-- is how Fuchsia's gym is built.
local GYM_LEFT = { [16] = true, [124] = true }
local GYM_MID = { [17] = true }
local GYM_RIGHT = { [18] = true, [126] = true }
-- and the roof row above it
local GYM_ROOF_LEFT = { [12] = true, [32] = true }
local GYM_ROOF_MID = { [13] = true }
local GYM_ROOF_RIGHT = { [14] = true, [33] = true }

local function tileId(row, col) return row * PER_ROW + col end

-- Stable inter-mod seam for Better Paths and Grass.  Four variants are
-- available per floor material; tall grass intentionally keeps one canonical
-- id so the engine's grassTile contract, encounter overlay and voxel tuft
-- classifier continue to agree.
local terrainTiles = {
  lawn = {}, grass = {}, path = {}, tall = tileId(TERRAIN_BAND, 12),
}
for col = 0, 3 do
  terrainTiles.lawn[#terrainTiles.lawn + 1] = tileId(TERRAIN_BAND, col)
  terrainTiles.grass[#terrainTiles.grass + 1] = tileId(TERRAIN_BAND, 4 + col)
  terrainTiles.path[#terrainTiles.path + 1] = tileId(TERRAIN_BAND, 8 + col)
end

-- Fuchsia's Center touches the city's solid scenery, so voxel mode needs a
-- tile grid unique to that one placement.  One copied south-west block is
-- enough to make the complete 8x8-tile grid unique; its pixels are identical
-- to the normal Center and only its tile ids differ.  The other three blocks
-- are shared with every Center, reclaiming exactly the three byte-sized block
-- ids Professor Oak's fixed landmark needs below.
local FUCHSIA_CENTER_PAD = 12
local FUCHSIA_CENTER_LEFT_TOP = GYM_BAND

local function fuchsiaCenterTile(row, col)
  return tileId(FUCHSIA_CENTER_LEFT_TOP + row, FUCHSIA_CENTER_PAD + col)
end

local function fuchsiaCenterBlock(row, col)
  local out = {}
  for r = 0, 3 do
    for c = 0, 3 do
      out[#out + 1] = fuchsiaCenterTile(row + r, col + c)
    end
  end
  return out
end

-- the 16 tile ids of one 4x4 block, reading rows then columns
local function blockAt(row, col)
  local out = {}
  for r = 0, 3 do
    for c = 0, 3 do out[#out + 1] = tileId(row + r, col + c) end
  end
  return out
end

-- The doorway's collision tile: the bottom-left 8x8 tile of the doorway
-- cell, which is what pokered (and this engine) reads for walkability, the
-- door animation and the warp.  It is the last row of the facade block row,
-- so seven tile rows down from the band's top.
local function doorTile(top, col) return tileId(top + 7, col) end

-- ------- 1. grow the tileset

local tileset = mod.content.tilesets:get("OVERWORLD")
if not tileset then
  mod.log:warn("the OVERWORLD tileset is not in the merged view -- is a "
    .. "total conversion loaded ahead of this mod? nothing re-skinned")
  return
end
if tileset.imageWidth ~= ATLAS_W or tileset.imageHeight ~= ATLAS_H then
  mod.log:warn("the OVERWORLD atlas is %sx%s, not the %dx%d layout these "
    .. "drawings were authored against -- another tileset mod is probably "
    .. "loaded ahead of this one; nothing re-skinned",
    tostring(tileset.imageWidth), tostring(tileset.imageHeight),
    ATLAS_W, ATLAS_H)
  return
end
if type(tileset.blocks) ~= "table" or #tileset.blocks == 0 then
  mod.log:warn("the OVERWORLD tileset carries no blocks -- nothing re-skinned")
  return
end

-- block ids are 0-based indices into `blocks`, so the first id we append is
-- the current length.  Reading it here (rather than hard-coding 128) keeps
-- us correct behind another mod that already appended blocks of its own.
--
-- The list is copied rather than extended through `__append`, because the
-- default kits are painted over blocks that already exist (see *_REUSE) and
-- a wrapper can only reach the end.  Building on the merged view we just
-- read leaves every block another mod contributed exactly where it put it.
local blocksOut = {}
for i = 1, #tileset.blocks do blocksOut[i] = tileset.blocks[i] end
local firstBlockId = #blocksOut

-- Collision is a property of a tile id, but maps are assembled from blocks.
-- Every generated block therefore inherits the four cell roles of the
-- vanilla block it replaces.  This matters for more than visible doors: a
-- few exterior blocks carry walk-behind / edge passage cells, and another
-- supported ROM or an earlier tileset mod may put those roles on a different
-- tile id.  Registering only the doorway drawn by this mod silently turns
-- such a passage into a wall even though the map footprint never changed.
local roleAdds = { walkable = {}, doorTiles = {}, warpTiles = {} }
local roleSeen = { walkable = {}, doorTiles = {}, warpTiles = {} }
local sourceRoles = { walkable = {}, doorTiles = {}, warpTiles = {} }
for name, set in pairs(sourceRoles) do
  for _, tile in ipairs(tileset[name] or {}) do set[tile] = true end
end

local function addRole(name, tile)
  if type(tile) == "number" and not roleSeen[name][tile] then
    roleSeen[name][tile] = true
    roleAdds[name][#roleAdds[name] + 1] = tile
  end
end

-- A second, quieter kind of collision role, and the one that seals a route
-- gate if it is missed.  ExtraWarpCheck (pokered IsWarpTileInFrontOfPlayer,
-- src/world/Warp.lua) fires a warp the player is STANDING on from the tile
-- in FRONT of them, matched against field.warpCarpets.tiles for the facing
-- direction -- so the tile that opens the door is one the player never
-- steps on and no tileset role names.  Every Kanto route gate is entered
-- that way (they have no door cell at all: you walk into the building's
-- side), and so is every back entrance -- Cerulean's two cut-through
-- houses, Celadon Mansion's rear stair, Fuchsia's Good Rod house.  Repaint
-- such a bay and its collision, its footprint and its warp table are all
-- still correct while the building has quietly become unenterable.
--
-- The fix is the role rule again, one level out: a new tile drawn where a
-- vanilla carpet tile stood inherits that tile's direction.
local CARPET_DIRS = { "up", "down", "left", "right" }
local warpCarpets = mod.content.field and mod.content.field:get("warpCarpets")
local carpetAdds, carpetSeen, sourceCarpets = {}, {}, {}
local anyCarpet = false
for _, dir in ipairs(CARPET_DIRS) do
  carpetAdds[dir], carpetSeen[dir], sourceCarpets[dir] = {}, {}, {}
  local tiles = type(warpCarpets) == "table" and warpCarpets.tiles or nil
  for _, tile in ipairs(type(tiles) == "table" and tiles[dir] or {}) do
    sourceCarpets[dir][tile] = true
  end
end

local function addCarpet(dir, tile)
  if type(tile) == "number" and not carpetSeen[dir][tile] then
    carpetSeen[dir][tile] = true
    carpetAdds[dir][#carpetAdds[dir] + 1] = tile
    anyCarpet = true
  end
end

-- The engine reads the bottom-left tile of each 2x2-tile cell.  Accepting a
-- list of source blocks lets a repeated kit module preserve the union of the
-- compatible vanilla positions it replaces (for example a civic middle bay
-- on either the ground floor or the storey above it).
local CELL_TILES = { 5, 7, 13, 15 }
local function inheritRoles(block, sources)
  if type(sources) == "number" then sources = { sources } end
  for _, sourceId in ipairs(sources or {}) do
    local source = tileset.blocks[sourceId + 1]
    if type(source) == "table" then
      for _, pos in ipairs(CELL_TILES) do
        local oldTile, newTile = source[pos], block[pos]
        for name, set in pairs(sourceRoles) do
          if set[oldTile] then addRole(name, newTile) end
        end
        for _, dir in ipairs(CARPET_DIRS) do
          if sourceCarpets[dir][oldTile] then addCarpet(dir, newTile) end
        end
      end
    end
  end
  return block
end

local function addDoor(tile)
  addRole("walkable", tile)
  addRole("doorTiles", tile)
  addRole("warpTiles", tile)
end

local function append(block, sources)
  inheritRoles(block, sources)
  blocksOut[#blocksOut + 1] = block
  return #blocksOut - 1
end

-- `id` is the vanilla block this drawing stands in for, or nil to append
local function put(id, block, sources)
  sources = sources or id
  if id == nil then return append(block, sources) end
  inheritRoles(block, sources)
  blocksOut[id + 1] = block
  return id
end

-- how many ids each layer will spend, so the ceiling can be checked before
-- any of it is written rather than discovered as a schema error on patch.
-- A module the style paints onto a vanilla block spends none.
local function partCount(roster, cost, reuse)
  local n = 0
  for _, entry in ipairs(roster) do
    local reused = (reuse or {})[entry.key] or {}
    for part in entry.parts:gmatch("%S+") do
      for _, slot in ipairs(cost[part] or { part }) do
        if reused[slot] == nil then n = n + 1 end
      end
    end
  end
  return n
end

-- ------- the gate kit's ids: the blockset's own unplaced slack
--
-- Run before the budget below, because a gate module that finds a spare id
-- costs the accounting nothing: `partCount` skips a part the *_REUSE table
-- already answers for.  Ids below `firstBlockId` only -- the appended range
-- is this mod's own and every id in it is spoken for.
local placedIds = {}
for _, map in mod.content.maps:each() do
  if map.tileset == "OVERWORLD" then
    for _, id in ipairs(map.blocks or {}) do placedIds[id] = true end
    if type(map.borderBlock) == "number" then placedIds[map.borderBlock] = true end
  end
end
-- a spare this mod is about to paint for another style is not spare
for _, reuse in pairs(FLAT_REUSE) do
  for _, id in pairs(reuse) do placedIds[id] = true end
end
for _, reuse in pairs(COT_REUSE) do
  for _, id in pairs(reuse) do placedIds[id] = true end
end
for _, reuse in pairs(HOUSE_REUSE) do
  for _, id in pairs(reuse) do placedIds[id] = true end
end

local spareIds = {}
for id = 0, firstBlockId - 1 do
  if not placedIds[id] then spareIds[#spareIds + 1] = id end
end

local gateReuse = nil
if #spareIds >= #GATE_PARTS then
  gateReuse = {}
  for i, part in ipairs(GATE_PARTS) do gateReuse[part] = spareIds[i] end
  FLAT_REUSE.gate = { roofA = gateReuse.roofA, facA = gateReuse.facA,
                      doorR = gateReuse.doorR, doorL = gateReuse.doorL }
  FLAT_REUSE.gate_ends = { endW = gateReuse.endW, endE = gateReuse.endE }
else
  -- No slack: the gates keep the civic art of the town they stand outside.
  -- They are still enterable -- the passage is what is missing, not the way
  -- in -- so this is a look, not a regression.
  mod.log:info("the blockset has %d unplaced ids and the gate kit wants %d "
    .. "-- Kanto's gates keep their town's civic art", #spareIds, #GATE_PARTS)
end

-- shops, Fuchsia's one unique Center block, Department Store and Oak's Lab
local landmarkBlocks = 4 * 2 + 1 + 4 + 3
for _, gym in ipairs(GYMS) do landmarkBlocks = landmarkBlocks + 2 * gym.blocks end
-- each part, and the id slots it spends -- the same names the *_REUSE tables
-- and the kit tables below are keyed by
local houseBlocks = partCount(COTTAGES, {}, COT_REUSE)
  + partCount(HOUSES, { roof = { "roofL", "roofR" },
                        door = { "doorL", "doorR" },
                        plain = { "plainL", "plainR" } }, HOUSE_REUSE)
  + partCount(FLATS, { plain = { "roofA", "facA" },
                       right = { "roofR", "facR" },
                       section = { "roofA", "facA" },
                       roof = { "roofA" },
                       facade = { "facA" },
                       end_w = { "endW" }, end_e = { "endE" },
                       door_r = { "doorR" }, door_l = { "doorL" } },
              FLAT_REUSE)

if firstBlockId + landmarkBlocks > BLOCK_CEILING then
  mod.log:warn("the OVERWORLD tileset already carries %d blocks, and a map "
    .. "block id is validated as a byte -- there is no room left to append "
    .. "the %d this mod needs; nothing re-skinned",
    firstBlockId, landmarkBlocks)
  return
end
-- The houses are the part that goes if the room runs out: the landmarks are
-- what the mod is for, and half a town re-skinned still beats none of it.
local roomForHouses =
  firstBlockId + landmarkBlocks + houseBlocks <= BLOCK_CEILING
if not roomForHouses then
  mod.log:warn("no room under the 255-block id cap for the house kits (%d "
    .. "ids wanted, %d free) -- the Centers, Marts and gyms are re-skinned "
    .. "and every other building keeps its vanilla art",
    houseBlocks, BLOCK_CEILING - firstBlockId - landmarkBlocks)
end

-- the shop pair: four blocks each, laid out like the vanilla 2x2
local shopIds = {}
for _, kind in ipairs({ "center", "mart" }) do
  local col = SHOP_COLUMN[kind]
  local vanilla = SHOPS[kind]
  shopIds[kind] = {
    nw = append(blockAt(SHOP_ROW, col), vanilla.nw),
    ne = append(blockAt(SHOP_ROW, col + 4), vanilla.ne),
    sw = append(blockAt(SHOP_ROW + 4, col), vanilla.sw),
    se = append(blockAt(SHOP_ROW + 4, col + 4), vanilla.se),
  }
  addDoor(doorTile(SHOP_ROW, col + 2))
end

-- the gyms: two rows of `blocks` blocks each, from that gym's own band
local gymIds, gymByWarp = {}, {}
for i, gym in ipairs(GYMS) do
  local top = GYM_BAND + (i - 1) * BAND_ROWS
  local ids = { [0] = {}, [1] = {} }
  for r = 0, 1 do
    for c = 0, gym.blocks - 1 do
      local source
      if r == 0 then
        source = (c == 0) and (gym.mirror and 32 or 12)
          or (c == gym.blocks - 1) and (gym.mirror and 33 or 14) or 13
      else
        source = (c == 0) and (gym.mirror and 124 or 16)
          or (c == gym.blocks - 1) and (gym.mirror and 126 or 18) or 17
      end
      ids[r][c] = append(blockAt(top + r * 4, c * 4), source)
    end
  end
  gymIds[gym.warp] = ids
  gymByWarp[gym.warp] = gym
  -- the doorway is the last block's first cell, or -- mirrored -- the first
  -- block's second cell
  addDoor(doorTile(top, gym.mirror and 2 or (gym.blocks - 1) * 4))
end

-- One block used only by the Center placement on FUCHSIA_CITY.  A single
-- unique quarter makes the complete tile grid unambiguous to the voxel
-- profile without spending four ids on pixel-identical copies.
local fuchsiaCenterIds = {
  nw = shopIds.center.nw,
  ne = shopIds.center.ne,
  sw = append(fuchsiaCenterBlock(4, 0), SHOPS.center.sw),
  se = shopIds.center.se,
}
addDoor(fuchsiaCenterTile(7, 2))

-- Celadon's fixed four-wide, four-row Department Store.  The source map
-- repeats one middle roof, upper-storey and doorway block, so four authored
-- blocks are enough for a complete landmark: roof, upper bay, outer display
-- and entrance.  Each of the two entrance placements keeps its own warp.
local departmentIds = {
  roof = append(blockAt(DEPT_BAND, DEPT_COL.roof),
    { FLAT_ROOF_L, FLAT_ROOF_M, FLAT_ROOF_R }),
  upper = append(blockAt(DEPT_BAND, DEPT_COL.upper),
    { FLAT_STOREY_L, FLAT_STOREY_M, FLAT_STOREY_R }),
  ground = append(blockAt(DEPT_BAND, DEPT_COL.ground), { 55, 115 }),
  door = append(blockAt(DEPT_BAND, DEPT_COL.door), 58),
}
addDoor(tileId(DEPT_BAND + 3, DEPT_COL.door))

-- Professor Oak's fixed three-wide, two-row Pallet Town landmark: a grey
-- research block under a clean flat grey-tiled roof.  One roof bay repeats
-- across the front, matching dark-glazed window bays flank the entrance, and
-- the original OAKS_LAB warp remains in the left cell of the middle facade
-- block.
local oakLabIds = {
  roof = append(blockAt(OAK_BAND, OAK_COL.roof), { 12, 13, 14 }),
  side = append(blockAt(OAK_BAND, OAK_COL.side), { 16, 0 }),
  door = append(blockAt(OAK_BAND, OAK_COL.door), 58),
}
addDoor(tileId(OAK_BAND + 3, OAK_COL.door))

-- the cottage kits: four interchangeable modules across one 32px band
local cottageIds = {}
local COT_SOURCE = { door = 2, plain = 48, mid = COT_MID, right = COT_RIGHT }
if roomForHouses then
  for i, st in ipairs(COTTAGES) do
    local top = COT_BAND + (i - 1) * COT_ROWS
    local ids, reuse = {}, COT_REUSE[st.key] or {}
    for part in st.parts:gmatch("%S+") do
      ids[part] = put(reuse[part], blockAt(top, COT_COL[part]), COT_SOURCE[part])
      if part == "door" then
        -- one block tall, so the doorway cell is the block's own second
        -- row rather than a facade row four rows down
        addDoor(tileId(top + 3, COT_COL[part] + 2))
      end
    end
    cottageIds[st.key] = ids
  end
end

-- The gabled house.  Its roof block's TOP HALF is walkable in vanilla -- the
-- player walks behind the building along there -- so those two tile rows are
-- copied from the vanilla block rather than painted: new art there would both
-- wall the player out and stamp one town's ground across every other's.
local function houseRoofBlock(row, col, vanillaId)
  local src = tileset.blocks[vanillaId + 1]
  if type(src) ~= "table" or #src < 16 then return nil end
  local out = {}
  for i = 1, 8 do out[i] = src[i] end
  for r = 0, 1 do
    for c = 0, 3 do out[#out + 1] = tileId(row + r, col + c) end
  end
  return out
end

local houseIds = {}
if roomForHouses then
  for i, st in ipairs(HOUSES) do
    local row = HOUSE_BAND + math.floor((i - 1) / 2) * HOUSE_ROWS
    local col = ((i - 1) % 2) * 8
    local style = st.key:match("^(.-)_plain$") or st.key
    local ids = houseIds[style] or {}
    local reuse = HOUSE_REUSE[style] or {}
    houseIds[style] = ids
    for part in st.parts:gmatch("%S+") do
      if part == "roof" then
        ids.roofL = houseRoofBlock(row, col, HOUSE_ROOF_L)
        ids.roofR = houseRoofBlock(row, col + 4, HOUSE_ROOF_R)
        ids.roofL = ids.roofL and put(reuse.roofL, ids.roofL, HOUSE_ROOF_L)
        ids.roofR = ids.roofR and put(reuse.roofR, ids.roofR, HOUSE_ROOF_R)
      else
        -- the drawing's rows 2..5 are the facade block row
        local sourceL = (part == "door") and 60 or 16
        local sourceR = (part == "door") and 61 or 0
        ids[part .. "L"] = put(reuse[part .. "L"],
          blockAt(row + 2, col), sourceL)
        ids[part .. "R"] = put(reuse[part .. "R"],
          blockAt(row + 2, col + 4), sourceR)
        if part == "door" then
          addDoor(tileId(row + 5, col + 2))
        end
      end
    end
  end
  -- and the borrowed halves: a style with a `base` claimed only part of the
  -- kit, and takes the rest -- ids, not new blocks -- from the style it is a
  -- repaint of.  The doorway tile comes with them, so the rival's door still
  -- warps from the cell it always did.
  for _, st in ipairs(HOUSES) do
    local ids, from = houseIds[st.key], st.base and houseIds[st.base]
    if ids and from then
      for part, id in pairs(from) do
        if ids[part] == nil then ids[part] = id end
      end
    end
  end
end

-- the flat-roofed civic kits.  A doored module borrows its roof from the
-- plain one beside it, so a bay with a door and a bay without share a roof
-- and the kit costs six ids rather than eight.
local flatIds = {}
if roomForHouses then
  for i, st in ipairs(FLATS) do
    local top = FLAT_BAND + (i - 1) * FLAT_ROWS
    local ids, reuse = {}, FLAT_REUSE[st.key] or {}
    for part in st.parts:gmatch("%S+") do
      if part == "plain" then
        ids.roofA = put(reuse.roofA, blockAt(top, FLAT_COL.plain),
          { FLAT_ROOF_L, FLAT_ROOF_M })
        ids.facA = put(reuse.facA, blockAt(top + 4, FLAT_COL.plain),
          { 55, 125, FLAT_STOREY_L, FLAT_STOREY_M })
      elseif part == "right" then
        ids.roofR = put(reuse.roofR, blockAt(top, FLAT_COL.right), FLAT_ROOF_R)
        ids.facR = put(reuse.facR, blockAt(top + 4, FLAT_COL.right),
          { FLAT_RIGHT, FLAT_STOREY_R })
      elseif part == "section" then
        -- One sealed bay repeats as field and right cap.  Residential
        -- Celadon, regional civic buildings and Saffron each use this compact
        -- form to preserve their material identity while reserving scarce
        -- block ids for fixed landmarks.
        ids.roofA = put(reuse.roofA, blockAt(top, FLAT_COL.plain),
          { FLAT_ROOF_L, FLAT_ROOF_M, FLAT_ROOF_R })
        ids.roofR = ids.roofA
        ids.facA = put(reuse.facA, blockAt(top + 4, FLAT_COL.plain),
          { 55, 125, FLAT_STOREY_L, FLAT_STOREY_M,
            FLAT_RIGHT, FLAT_STOREY_R })
        ids.facR = ids.facA
      elseif part == "end_w" or part == "end_e" then
        -- A cap that carries the gate's stepped door in its OUTER cell, which is
        -- the cell the player steps into off the path.  Facade only: the roof
        -- over it is the same panel the rest of the run carries, so the
        -- canopy runs unbroken from one end of the gate to the other.
        local slot = (part == "end_w") and "endW" or "endE"
        ids[slot] = put(reuse[slot], blockAt(top + 4, FLAT_COL[part]),
          (part == "end_w") and 55 or FLAT_RIGHT)
      elseif part == "door_r" then
        ids.doorR = put(reuse.doorR,
          blockAt(top + 4, FLAT_COL.door_r), 124)
        addDoor(doorTile(top, FLAT_COL.door_r + 2))
      elseif part == "door_l" then
        ids.doorL = put(reuse.doorL,
          blockAt(top + 4, FLAT_COL.door_l), 58)
        addDoor(doorTile(top, FLAT_COL.door_l))
      elseif part == "roof" then
        -- A sectional industrial roof: the same sealed panel repeats across
        -- the whole run and also serves as its right cap, costing one id.
        ids.roofA = append(blockAt(top, FLAT_COL.plain),
          { FLAT_ROOF_L, FLAT_ROOF_M, FLAT_ROOF_R })
        ids.roofR = ids.roofA
      elseif part == "facade" then
        -- A sealed casino wall bay repeats on both sides of the entrance.
        -- One block serving as field and right cap is what makes a full
        -- Game Corner facade affordable under the 255-id ceiling.
        ids.facA = append(blockAt(top + 4, FLAT_COL.plain),
          { 55, 125, FLAT_STOREY_L, FLAT_STOREY_M,
            FLAT_RIGHT, FLAT_STOREY_R })
        ids.facR = ids.facA
      end
    end
    flatIds[st.key] = ids
  end
  -- and the borrowed modules, exactly as the houses do it: a venue claimed
  -- its doorway bay and takes roof, walls and right-hand cap from the style
  -- it is a repaint of
  for _, st in ipairs(FLATS) do
    local ids, from = flatIds[st.key], st.base and flatIds[st.base]
    if ids and from then
      for part, id in pairs(from) do
        if ids[part] == nil then ids[part] = id end
      end
    end
  end

end

mod.content.tilesets:patch("OVERWORLD", {
  -- the rows transforms.lua paints; the width is unchanged
  imageHeight = GROWN_H,
  blocks = blocksOut,
  -- the new doorway tiles inherit every role tile $1B held: standable,
  -- door-animated, and the cell a warp fires from
  walkable = { __append = roleAdds.walkable },
  doorTiles = { __append = roleAdds.doorTiles },
  warpTiles = { __append = roleAdds.warpTiles },
})

-- and the same for the tiles ExtraWarpCheck reads in front of the player,
-- which live in field rather than in the tileset.  Appending leaves every
-- vanilla id in place, so a gate keeps working whether the player faces the
-- vanilla wall or the new one; a base with no warpCarpets at all has nothing
-- to inherit and needs none -- extraCheck falls back to the map-edge test
-- when the table is absent, which no tile id can break.
if anyCarpet then
  local tiles = {}
  for _, dir in ipairs(CARPET_DIRS) do
    if #carpetAdds[dir] > 0 then tiles[dir] = { __append = carpetAdds[dir] } end
  end
  mod.content.field:patch("warpCarpets", { tiles = tiles })
end

-- ------- 2. full-colour art: opt the new tiles out of the RED++ bake
--
-- Under COLORS=RED++ the renderer bakes one of eight four-colour palettes
-- onto every tile GRAPHIC (TileRenderer.getGbcAtlas, and the voxel mod's
-- mirror of it).  A tile with no group would be left alone -- but
-- worldGroupAt floors unknown ids at group 7 (TEXT), which would drag these
-- drawings through a four-shade remap and lose them.  Returning nil for our
-- own ids instead is the "leave it alone" answer the bake already knows how
-- to take, and it is what makes the Center red, the Mart blue and each gym
-- its leader's type colour in every town rather than town-palette coloured.
-- Vanilla ids are untouched.
local okFx, PaletteFX = pcall(require, "src.render.PaletteFX")
if okFx and type(PaletteFX) == "table" and PaletteFX.worldGroupAt
    and not PaletteFX.__betterBuildingsTrueColor then
  local inner = PaletteFX.worldGroupAt
  PaletteFX.worldGroupAt = function(tilesetId, mapId, tile)
    if tilesetId == "OVERWORLD" and type(tile) == "number"
        and tile >= BASE_TILES then
      return nil
    end
    return inner(tilesetId, mapId, tile)
  end
  PaletteFX.__betterBuildingsTrueColor = true
else
  mod.log:warn("could not reach the palette bake -- the new tiles will be "
    .. "shade-remapped with the rest of the atlas under COLORS=RED++; every "
    .. "other COLORS mode is unaffected")
end

-- ------- 3. repoint the maps

local converted = { center = 0, mart = 0, gym = 0, department = 0, lab = 0,
                    cottage = 0, house = 0, flat = 0, gate = 0, ends = 0, skipped = 0 }

-- every gate this pass rebuilt, so the voxel diorama below can be handed the
-- grids it actually placed rather than a guess at Kanto's gate arrangements
local gates = {}

-- Every pitched building this pass actually rebuilt.  The voxel companion's
-- generic detector sees the new full-colour tile ids but not the architectural
-- bands they depict, so it otherwise raises the roof and the facade as two
-- unrelated volumes.  That is the triangular daylight gap visible under the
-- eaves.  Keep exact block grids here and register them through the companion's
-- public building profile below. A narrowly scoped in-memory adapter retains
-- the detector's 16-voxel gable rise for these rectangular roof drawings and
-- extends the facade to its underside, closing the gap without flattening it.
local slopedVoxelGrids = {}
local function rememberSloped(kind, grid, options)
  slopedVoxelGrids[#slopedVoxelGrids + 1] = {
    kind = kind, grid = grid, options = options or {},
  }
end

-- the vanilla shop pair, anchored on its sign block at (x, y)
local function shopMatches(at, x, y, kind)
  if x < 1 or y < 1 then return false end
  local v = SHOPS[kind]
  return at(x - 1, y - 1) == v.nw and at(x, y - 1) == v.ne
     and at(x - 1, y) == v.sw
end

-- The Department Store's exact vanilla footprint, anchored on the first
-- ground-floor block.  The full pattern check prevents the shared MART sign
-- block 115 from turning another structure into this landmark.
local function departmentMatches(at, w, h, x0, by)
  if x0 < 0 or x0 + 3 >= w or by < 3 or by >= h then return false end
  local rows = {
    { 32, 13, 13, 33 },
    { 104, 127, 127, 105 },
    { 104, 127, 127, 105 },
    { 55, 58, 58, 115 },
  }
  for r = 0, 3 do
    for c = 0, 3 do
      if at(x0 + c, by - 3 + r) ~= rows[r + 1][c + 1] then return false end
    end
  end
  return true
end

-- Oak's Lab is the one 3x2 placement of the gym-like chassis whose doorway
-- warp leads to OAKS_LAB.  Checking both complete rows keeps unrelated uses
-- of these heavily shared vanilla blocks untouched.
local function oakLabMatches(at, w, h, x0, by)
  if x0 < 0 or x0 + 2 >= w or by < 1 or by >= h then return false end
  local roof, face = { 12, 13, 14 }, { 16, 58, 0 }
  for c = 0, 2 do
    if at(x0 + c, by - 1) ~= roof[c + 1]
        or at(x0 + c, by) ~= face[c + 1] then return false end
  end
  return true
end

-- The vanilla gym around the block a `*_GYM` warp fires from.  Anchoring on
-- the warp rather than on the block pattern is what keeps the Fighting Dojo
-- -- built from the identical blocks, flush against Saffron's gym -- out of
-- the rewrite.  Returns the facade row's first and last block columns.
local function gymExtent(at, w, bx, by, gym)
  if by < 1 or bx < 0 or bx >= w then return nil end
  local x0 = bx
  if not GYM_LEFT[at(x0, by)] then
    repeat x0 = x0 - 1 until x0 < 0 or not GYM_MID[at(x0, by)]
  end
  local x1 = bx
  if not GYM_RIGHT[at(x1, by)] then
    repeat x1 = x1 + 1 until x1 >= w or not GYM_MID[at(x1, by)]
  end
  if x0 < 0 or x1 >= w then return nil end
  if not (GYM_LEFT[at(x0, by)] and GYM_RIGHT[at(x1, by)]) then return nil end
  if x1 - x0 + 1 ~= gym.blocks then return nil end
  -- the doorway has to sit in the cap this gym's drawing puts it in
  if bx ~= (gym.mirror and x0 or x1) then return nil end
  -- and the roof above has to be the vanilla one
  if not (GYM_ROOF_LEFT[at(x0, by - 1)] and GYM_ROOF_RIGHT[at(x1, by - 1)]) then
    return nil
  end
  for c = x0 + 1, x1 - 1 do
    if not (GYM_MID[at(c, by)] and GYM_ROOF_MID[at(c, by - 1)]) then
      return nil
    end
  end
  return x0, x1
end

local pending = {}
for mapId, map in mod.content.maps:each() do
  if map.tileset == "OVERWORLD" and type(map.blocks) == "table"
      and map.width and map.height then
    local w, h = map.width, map.height
    local blocks, dirty = nil, false
    local function at(bx, by)
      if bx < 0 or by < 0 or bx >= w or by >= h then return nil end
      return (blocks or map.blocks)[by * w + bx + 1]
    end
    -- copy-on-write: an untouched map is left as the record the merge built.
    -- A default-styled building is painted onto the very blocks it already
    -- names (see *_REUSE), so writing it back changes nothing and must not
    -- be what marks the map dirty.
    local function edit(bx, by, id)
      if at(bx, by) == id then return end
      if not blocks then
        blocks = {}
        for j = 1, #map.blocks do blocks[j] = map.blocks[j] end
      end
      blocks[by * w + bx + 1] = id
      dirty = true
    end

    -- the shop pair, found by its sign block
    for i = 1, #map.blocks do
      local value = map.blocks[i]
      for kind, v in pairs(SHOPS) do
        if value == v.se then
          local x, y = (i - 1) % w, math.floor((i - 1) / w)
          if shopMatches(at, x, y, kind) then
            local new = (mapId == "FUCHSIA_CITY" and kind == "center")
              and fuchsiaCenterIds or shopIds[kind]
            edit(x - 1, y - 1, new.nw)
            edit(x, y - 1, new.ne)
            edit(x - 1, y, new.sw)
            edit(x, y, new.se)
            rememberSloped("shop_" .. kind,
              { { new.nw, new.ne }, { new.sw, new.se } })
            converted[kind] = converted[kind] + 1
          end
        end
      end
    end

    -- the gyms, found by their warps
    for _, warp in ipairs(map.warps or {}) do
      local gym = gymByWarp[warp.destMap]
      local ids = gym and gymIds[warp.destMap]
      if gym and type(warp.x) == "number" and type(warp.y) == "number" then
        local bx, by = math.floor(warp.x / 2), math.floor(warp.y / 2)
        -- the doorway is always the bottom cell of the facade block row, and
        -- the mirrored gym puts it in the block's second column
        local cellX, cellY = warp.x % 2, warp.y % 2
        if cellY == 1 and cellX == (gym.mirror and 1 or 0) then
          local x0, x1 = gymExtent(at, w, bx, by, gym)
          if x0 then
            for r = 0, 1 do
              for c = x0, x1 do edit(c, by - 1 + r, ids[r][c - x0]) end
            end
            local roof, face = {}, {}
            for c = x0, x1 do
              roof[#roof + 1] = ids[0][c - x0]
              face[#face + 1] = ids[1][c - x0]
            end
            rememberSloped("gym", { roof, face })
            converted.gym = converted.gym + 1
          end
        end
      end
    end

    -- Celadon Department Store, found by its two adjacent entrance warps.
    -- It runs before the civic matcher because its ground row deliberately
    -- uses the same blocks, stacked into a taller landmark chassis.
    local storeDoors = {}
    for _, warp in ipairs(map.warps or {}) do
      if warp.destMap == "CELADON_MART_1F" and type(warp.x) == "number"
          and type(warp.y) == "number" and warp.x % 2 == 0
          and warp.y % 2 == 1 then
        storeDoors[#storeDoors + 1] = {
          bx = math.floor(warp.x / 2), by = math.floor(warp.y / 2)
        }
      end
    end
    if #storeDoors == 2 then
      if storeDoors[1].bx > storeDoors[2].bx then
        storeDoors[1], storeDoors[2] = storeDoors[2], storeDoors[1]
      end
      local left, right = storeDoors[1], storeDoors[2]
      local x0 = left.bx - 1
      if left.by == right.by and right.bx == left.bx + 1
          and departmentMatches(at, w, h, x0, left.by) then
        for c = 0, 3 do edit(x0 + c, left.by - 3, departmentIds.roof) end
        for r = 1, 2 do
          for c = 0, 3 do
            edit(x0 + c, left.by - 3 + r, departmentIds.upper)
          end
        end
        edit(x0, left.by, departmentIds.ground)
        edit(x0 + 1, left.by, departmentIds.door)
        edit(x0 + 2, left.by, departmentIds.door)
        edit(x0 + 3, left.by, departmentIds.ground)
        converted.department = converted.department + 1
      end
    end

    -- Oak's Lab, found by its destination warp just like a gym.  It runs
    -- before the ordinary-building passes so its shared vanilla ids cannot
    -- be mistaken for pieces of another chassis after the replacement.
    for _, warp in ipairs(map.warps or {}) do
      if warp.destMap == "OAKS_LAB" and type(warp.x) == "number"
          and type(warp.y) == "number" and warp.x % 2 == 0
          and warp.y % 2 == 1 then
        local bx, by = math.floor(warp.x / 2), math.floor(warp.y / 2)
        local x0 = bx - 1
        if oakLabMatches(at, w, h, x0, by) then
          for c = 0, 2 do edit(x0 + c, by - 1, oakLabIds.roof) end
          edit(x0, by, oakLabIds.side)
          edit(x0 + 1, by, oakLabIds.door)
          edit(x0 + 2, by, oakLabIds.side)
          converted.lab = converted.lab + 1
        end
      end
    end

    -- ------- the ordinary buildings
    --
    -- These run after the landmarks on purpose.  A converted Center or gym
    -- no longer carries a vanilla id, so it cannot be matched twice, and the
    -- flat chassis is close enough to the Center's that anchoring on the
    -- vanilla ids is what keeps the two apart.
    if roomForHouses then
      local cotKit = cottageIds[COTTAGE_STYLE[mapId] or DEFAULT_COTTAGE]
      local houseKit = houseIds[HOUSE_STYLE[mapId] or DEFAULT_HOUSE]
      local flatStyle = FLAT_STYLE[mapId] or DEFAULT_FLAT
      local flatKit = flatIds[flatStyle]
      local homeKit = flatIds[FLAT_RESIDENTIAL[flatStyle] or ""]
      local gateKit = gateReuse and flatIds.gate_ends

      -- every block a gate warp fires from or into, so a run can ask both
      -- whether it IS a gate and which of its ends the player walks in at
      local gateWarps = {}
      for _, warp in ipairs(map.warps or {}) do
        if isGateMap(warp.destMap) and type(warp.x) == "number"
            and type(warp.y) == "number" then
          gateWarps[#gateWarps + 1] =
            { bx = math.floor(warp.x / 2), by = math.floor(warp.y / 2),
              cx = warp.x % 2, cy = warp.y % 2 }
        end
      end

      -- the cottage terrace: a left end, any number of middles, a right end
      if cotKit then
        for by = 0, h - 1 do
          local bx = 0
          while bx < w do
            local part = COT_LEFT[at(bx, by)]
            if part then
              local x1 = bx + 1
              while x1 < w and at(x1, by) == COT_MID do x1 = x1 + 1 end
              if x1 < w and at(x1, by) == COT_RIGHT
                  and cotKit[part] and cotKit.right
                  and (x1 == bx + 1 or cotKit.mid) then
                edit(bx, by, cotKit[part])
                for c = bx + 1, x1 - 1 do edit(c, by, cotKit.mid) end
                edit(x1, by, cotKit.right)
                local row = {}
                for c = bx, x1 do row[#row + 1] = at(c, by) end
                rememberSloped("cottage", { row }, {
                  roofRows = 16, roofBack = 7, roofFront = 9,
                  roofCycle = { 5, 8 },
                })
                converted.cottage = converted.cottage + 1
                bx = x1
              elseif x1 < w and at(x1, by) == COT_RIGHT then
                converted.skipped = converted.skipped + 1
                bx = x1
              end
            end
            bx = bx + 1
          end
        end
      end

      -- Houses that take a style of their own rather than their town's,
      -- keyed by the facade block their doorway sits in.  The doorway is
      -- always the left block's right cell, so a warp at tile (x, y) belongs
      -- to the house whose facade starts at block (x // 2, y // 2).
      local byDoor = {}
      for _, warp in ipairs(map.warps or {}) do
        local style = HOUSE_STYLE_BY_WARP[warp.destMap]
        if style and houseIds[style] and type(warp.x) == "number"
            and type(warp.y) == "number" then
          local bx, by = math.floor(warp.x / 2), math.floor(warp.y / 2)
          byDoor[by * w + bx] = houseIds[style]
        end
      end

      -- and the same lookup for the civic runs, keyed by the block the
      -- doorway module sits in.  Either cell of that block can carry it --
      -- door_r puts the leaf in the right cell and door_l in the left -- so
      -- only the block matters, not which half of it the warp is in.
      local venueByDoor = {}
      for _, warp in ipairs(map.warps or {}) do
        local style = FLAT_STYLE_BY_WARP[warp.destMap]
        if style and flatIds[style] and type(warp.x) == "number"
            and type(warp.y) == "number" then
          venueByDoor[math.floor(warp.y / 2) * w + math.floor(warp.x / 2)] =
            flatIds[style]
        end
      end

      -- the gabled house: always two blocks square, doored or scenery
      if houseKit and houseKit.roofL then
        for by = 1, h - 1 do
          for bx = 0, w - 2 do
            local variant = HOUSE_FACE[at(bx, by)]
            if variant and at(bx, by - 1) == HOUSE_ROOF_L
                and at(bx + 1, by - 1) == HOUSE_ROOF_R
                and at(bx + 1, by) == HOUSE_FACE_R[variant] then
              local kit = byDoor[by * w + bx] or houseKit
              if kit[variant .. "L"] then
                edit(bx, by - 1, kit.roofL)
                edit(bx + 1, by - 1, kit.roofR)
                edit(bx, by, kit[variant .. "L"])
                edit(bx + 1, by, kit[variant .. "R"])
                local houseOptions = {
                  -- The first two tile rows of the roof blocks are the
                  -- walk-behind ground copied from vanilla, not building art.
                  cropTop = 2,
                  roofRows = 16, roofBack = 7, roofFront = 9,
                  roofCycle = { 5, 8 },
                }
                -- Saffron's concrete-and-glass house is much lighter than
                -- the other gabled drawings.  After the walk-behind rows are
                -- cropped, the companion's light-pixel silhouette flood can
                -- classify its wall as exterior air and leave only floating
                -- window boxes and dark frame pieces.  The drawing occupies
                -- the complete cropped rectangle, so seal every read edge
                -- and retain its real texels on the outer facade plane.
                if kit == houseIds.saffron then
                  houseOptions.seal = "nsew"
                  houseOptions._betterBuildingsOpaqueFront = true
                end
                rememberSloped("house", {
                  { kit.roofL, kit.roofR },
                  { kit[variant .. "L"], kit[variant .. "R"] },
                }, houseOptions)
                converted.house = converted.house + 1
              else
                converted.skipped = converted.skipped + 1
              end
            end
          end
        end
      end

      -- The flat-roofed civic block: a facade row, an optional storey over
      -- it, and the roof over that.  One storey only -- Silph Co stacks four
      -- and is a landmark in its own right, so it keeps its vanilla art
      -- rather than being re-skinned as a very tall shop.
      if flatKit and flatKit.roofA and flatKit.facR then
        for by = 1, h - 1 do
          local bx = 0
          while bx < w do
            local part = FLAT_LEFT[at(bx, by)]
            if part then
              local x1 = bx + 1
              while x1 < w and FLAT_MID[at(x1, by)] do x1 = x1 + 1 end
              if x1 < w and at(x1, by) == FLAT_RIGHT then
                -- how far up the building goes, and whether the top of it is
                -- the vanilla roof
                local roofY = by - 1
                local storeyY = nil
                local function rowIs(y, l, m, r)
                  if y < 0 or at(bx, y) ~= l or at(x1, y) ~= r then
                    return false
                  end
                  for c = bx + 1, x1 - 1 do
                    if at(c, y) ~= m then return false end
                  end
                  return true
                end
                if rowIs(roofY, FLAT_STOREY_L, FLAT_STOREY_M, FLAT_STOREY_R) then
                  storeyY, roofY = roofY, roofY - 1
                end

                -- every module this run needs has to be in the town's kit
                local need, doored = {}, false
                for c = bx, x1 - 1 do
                  local kind = (c == bx) and part or FLAT_MID[at(c, by)]
                  need[c] = (kind == "door_r" and "doorR")
                    or (kind == "door_l" and "doorL") or "facA"
                  if need[c] ~= "facA" then doored = true end
                end

                -- which kit this particular run builds from: a named
                -- building's own, the town's residential one if nobody can
                -- get in, or the town's ordinary civic kit
                local kit = flatKit
                for c = bx, x1 - 1 do
                  kit = venueByDoor[by * w + c] or kit
                end
                if kit == flatKit and homeKit and not doored then
                  kit = homeKit
                end

                -- A gate outranks both: it is a building of the region, not
                -- of the town it stands outside, and a doorless one is the
                -- opposite of somewhere nobody can go in.  `endW`/`endE`
                -- are claimed only for an end a warp actually fires from --
                -- Route 5's gate is entered by its door and from the north,
                -- and doorwaying its sides would invent a way in the map has
                -- no path to.
                local endW, endE = false, false
                local endWCell, endECell = nil, nil
                if gateKit then
                  local isGate = false
                  for _, g in ipairs(gateWarps) do
                    if g.by >= roofY - 1 and g.by <= by
                        and g.bx >= bx - 1 and g.bx <= x1 + 1 then
                      isGate = true
                      if g.by == by and g.bx == bx - 1 then
                        endW, endWCell = true, g.cy
                      end
                      if g.by == by and g.bx == x1 + 1 then
                        endE, endECell = true, g.cy
                      end
                    end
                  end
                  if isGate then kit = gateKit end
                end
                endW = endW and kit.endW ~= nil and need[bx] == "facA"
                endE = endE and kit.endE ~= nil
                -- Two different reasons not to convert, and only one of them
                -- is this mod's business.  A run whose roof is not the
                -- vanilla one is simply not this chassis -- Pewter's Museum,
                -- the Pokemon Tower and Silph Co all end in `126` over
                -- something else entirely -- and is passed over in silence.
                -- A run that IS this chassis but wants a module the town's
                -- kit does not carry is worth saying out loud.
                local structure =
                  rowIs(roofY, FLAT_ROOF_L, FLAT_ROOF_M, FLAT_ROOF_R)
                local complete = structure and kit.roofA ~= nil
                  and kit.facR ~= nil
                for c = bx, x1 - 1 do
                  if not kit[need[c]] then complete = false end
                end

                if complete then
                  for c = bx, x1 - 1 do
                    edit(c, roofY, kit.roofA)
                    if storeyY then edit(c, storeyY, kit.facA) end
                    edit(c, by,
                      (c == bx and endW and kit.endW) or kit[need[c]])
                  end
                  edit(x1, roofY, kit.roofR)
                  if storeyY then edit(x1, storeyY, kit.facR) end
                  edit(x1, by, (endE and kit.endE) or kit.facR)
                  converted.flat = converted.flat + 1
                  -- Keep the complete assembled grid for voxel mode. The
                  -- civic chassis can be two or three block rows deep and
                  -- any width, so the placement is the authoritative model
                  -- template just as it is for the route gates below.
                  local voxelGrid = {}
                  for y = roofY, by do
                    local row = {}
                    for c = bx, x1 do row[#row + 1] = at(c, y) end
                    voxelGrid[#voxelGrid + 1] = row
                  end
                  if kit == gateKit then
                    -- keep the grid this run just became, not its
                    -- coordinates: the voxel diorama below models the
                    -- gates from what was actually placed
                    local grid = voxelGrid
                    -- A side warp enters the short wall, not the facade.
                    -- Preserve which 16px half of the final depth block it
                    -- addresses so the voxel companion can rotate that
                    -- entrance onto the west/east elevation.
                    grid.endWCell = endW and endWCell or nil
                    grid.endECell = endE and endECell or nil
                    converted.gate = converted.gate + 1
                    if endW then converted.ends = converted.ends + 1 end
                    if endE then converted.ends = converted.ends + 1 end
                    gates[#gates + 1] = grid
                  else
                    -- Despite this kit's historical "flat" chassis name,
                    -- the automatic voxel detector pitches these distinct
                    -- roof rows. Register that same slope with the exact
                    -- facade grid so Vermilion and Celadon do not retain the
                    -- old wall/roof separation.
                    -- The glass door leaf reaches the drawing's south edge.
                    -- Without this seal the profile's light-pixel silhouette
                    -- flood enters through its threshold and classifies the
                    -- whole doorway as exterior air. Other edges carry their
                    -- own dark outline, so only south needs closing.
                    local civicOptions = { seal = "s" }
                    -- Saffron's curtain-wall drawing is intentionally much
                    -- lighter than the other civic fronts.  The companion's
                    -- pane rule recesses every framed light region by
                    -- removing its outer voxel; on these broad glass bays
                    -- that can expose characters and scenery through the
                    -- facade at an oblique camera angle.  Mark only this
                    -- city's civic models for the opaque-front pass below.
                    -- The real glass texels and lighting remain in place;
                    -- they simply occupy the facade plane instead of being
                    -- represented by an opening in it.
                    if flatStyle == "saffron" then
                      civicOptions._betterBuildingsOpaqueFront = true
                    end
                    rememberSloped("civic", voxelGrid, civicOptions)
                  end
                elseif structure then
                  converted.skipped = converted.skipped + 1
                end
                bx = x1
              end
            end
            bx = bx + 1
          end
        end
      end
    end

    if dirty then pending[#pending + 1] = { id = mapId, blocks = blocks } end
  end
end

for _, entry in ipairs(pending) do
  mod.content.maps:patch(entry.id, { blocks = entry.blocks })
end

if converted.center + converted.mart + converted.gym == 0 then
  mod.log:warn("found no vanilla Center, Mart or gym to re-skin -- the new "
    .. "tiles and blocks are installed but nothing places them; another map "
    .. "mod has probably rearranged the towns already")
else
  mod.log:info("re-skinned %d Pokemon Centers, %d Poke Marts and %d gyms "
    .. "across %d maps", converted.center, converted.mart, converted.gym,
    #pending)
  if converted.department > 0 then
    mod.log:info("re-skinned Celadon Department Store as a restrained "
      .. "flagship Poke Mart")
  end
  if converted.lab > 0 then
    mod.log:info("re-skinned Professor Oak's Lab as Pallet Town's grey "
      .. "research block under a flat tiled roof")
  end
  if converted.gym < #GYMS then
    mod.log:info("%d of the %d Kanto gyms were not in their vanilla "
      .. "arrangement and keep their old art", #GYMS - converted.gym, #GYMS)
  end
  if roomForHouses then
    mod.log:info("re-skinned %d cottages, %d houses and %d flat-roofed "
      .. "civic buildings in their towns' own styles",
      converted.cottage, converted.house, converted.flat)
    if converted.gate > 0 then
      mod.log:info("%d of those are route gates, rebuilt as FireRed-style "
        .. "checkpoints, with %d warp-facing end stair base(s)",
        converted.gate, converted.ends)
    end
    if converted.skipped > 0 then
      mod.log:info("%d ordinary buildings stand in an arrangement their "
        .. "town's kit has no module for and keep their vanilla art",
        converted.skipped)
    end
  end
end

-- ------- 4. the voxel diorama, when it is installed
--
-- The voxel detector normally flood-fills touching solid tiles into one
-- structure. Every pitched Better Buildings drawing needs an exact grid too:
-- without its roof/facade band split the detector makes two volumes and leaves
-- daylight between them. The Department Store needs its complete 16x16 grid
-- so repeated upper storeys stay vertical rather than becoming separate
-- roofs. Its full 128px matched depth keeps the visible facade on the same
-- front row as the two doorway, collision and warp cells.
--
-- Battle Arts' public building profile can register exact drawings, but its
-- stock model always treats that drawing as the south facade, mirrors it on
-- the back and fills each short wall with a generic interior shade. Better
-- Buildings owns the extra meaning
-- its gate templates need: this adapter wraps the model lookup in memory and
-- only for entries carrying `_betterBuildingsSideDoors` or
-- `_betterBuildingsPitch`, plus the overworld templates marked for proper
-- rear and side elevations below. No Battle Arts file, shipped data table or
-- version is changed; the scoped geometry and texture choices exist only in
-- memory while Better Buildings is loaded.
local function installGateSideDoorAdapter(V)
  if type(V) ~= "table" or type(V.require) ~= "function" then
    return false, "voxel namespace has no module loader"
  end
  local ok, Buildings = pcall(V.require, "Buildings")
  if not ok or type(Buildings) ~= "table"
      or type(Buildings.build) ~= "function" then
    return false, "voxel Buildings module is unavailable"
  end
  if type(debug) ~= "table" or type(debug.getupvalue) ~= "function"
      or type(debug.setupvalue) ~= "function" then
    return false, "Lua debug upvalue access is unavailable"
  end

  local slot, originalModel = nil, nil
  for i = 1, 32 do
    local name, value = debug.getupvalue(Buildings.build, i)
    if not name then break end
    if name == "model" and type(value) == "function" then
      slot, originalModel = i, value
      break
    end
  end
  if not slot then return false, "voxel building model seam was not found" end

  local adapterTag = "better_buildings_voxel_adapter_v5"
  for i = 1, 16 do
    local name, value = debug.getupvalue(originalModel, i)
    if not name then break end
    if name == "adapterTag" and value == adapterTag then return true end
  end

  local function remap(v, a0, a1, b0, b1, reverse)
    if a1 <= a0 then return b0 end
    local n = math.floor((v - a0) * (b1 - b0) / (a1 - a0) + 0.5)
    return reverse and (b1 - n) or (b0 + n)
  end

  local function adaptedModel(sp, pr, template)
    -- Retaining this tag as an upvalue makes development hot reloads
    -- idempotent without writing a marker onto Battle Arts' module table.
    if adapterTag == "" then return originalModel(sp, pr, template) end
    local m = originalModel(sp, pr, template)
    if type(m) ~= "table" or type(m.at) ~= "function" then return m end

    -- Buildings' authored profile derives lateral roof shape from a sprite's
    -- transparent silhouette. Better Buildings' module drawings deliberately
    -- seal their rectangular edges, so that measurement is level even though
    -- the generic detector previously gave these structures a 16-voxel gable.
    -- Lift only the roof slab into that same gable and grow the wall beneath
    -- it. Sampling the stock model means every surface keeps its real texels;
    -- this adapter changes geometry, never invents or repaints artwork.
    local rise = type(template) == "table"
      and template._betterBuildingsPitch
    if type(rise) == "number" and rise > 0 then
      local flatAt = m.at
      local flatTop = m.ytop
      local slab = template.slab or 4
      local wallTop = flatTop - slab
      local z0 = 0
      local z1 = pr.D - 1 + (template.frontEave or 0)
      local middle = (z0 + z1) / 2
      local half = math.max(0.5, (z1 - z0) / 2)
      local function roofLift(z)
        if z < z0 or z > z1 then return 0 end
        local t = 1 - math.abs(z - middle) / half
        return math.floor(rise * math.max(0, math.min(1, t)) + 0.5)
      end
      m.ytop = flatTop + rise
      m.at = function(x, y, z)
        local lift = roofLift(z)
        if lift > 0 then
          local flatY = y - lift
          -- The shifted stock roof, including its top, fascia and underside.
          if flatY > wallTop and flatY <= flatTop then
            return flatAt(x, flatY, z)
          end
          -- The upright material continues until the shifted underside. Only
          -- the real footprint grows a wall; the front eave remains overhang.
          if z >= 0 and z < pr.D and y > wallTop
              and y <= wallTop + lift then
            return flatAt(x, wallTop, z)
          end
          if y > wallTop then return nil end
        end
        return flatAt(x, y, z)
      end
    end

    -- The stock model puts the south facade on z=D-1 and the SAME source
    -- pixels on z=0. Face winding then mirrors that copy, so doors, signs and
    -- storefronts appear backward on the rear wall. Replace only the exposed
    -- north wall with a quiet elevation sampled from the drawing's own plain
    -- left-edge material. Dark posts at the 32px module rhythm keep long
    -- buildings articulated without copying any front-facing feature.
    local backDonor = type(template) == "table"
      and template._betterBuildingsBack
    if type(backDonor) == "number" then
      local surfacedAt = m.at
      local roofRows = template.roofRows or 0
      local W, ground = sp.W, pr.ground
      m.at = function(x, y, z)
        local i = surfacedAt(x, y, z)
        if i == nil or z ~= 0 or type(x) ~= "number"
            or type(y) ~= "number" then return i end
        local sy = ground - 1 - y
        if sy < roofRows or sy >= sp.H then return i end
        local phase = x % 32
        local sx = (phase == 0 and 0) or (phase == 1 and 1)
          or (phase == 31 and 0) or backDonor
        sx = math.max(0, math.min(W - 1, sx))
        local donor = sy * W + sx
        if not sp.inside[donor] then
          sx = math.max(0, math.min(W - 1, backDonor))
          donor = sy * W + sx
        end
        return sp.inside[donor] and donor or i
      end
    end

    -- Stock side faces use `pr.interior`, which is deliberately only a safe
    -- fallback colour. On full-colour buildings that turns whole gable ends
    -- and long walls into the same grey-purple slab. Continue a plain course
    -- from the drawing's own nearest facade edge instead. Repeating the edge
    -- outline at the 32px module rhythm gives long sides real corner/bay
    -- framing, while the side-door wrapper below remains the final authority
    -- wherever a map is actually entered through one of these elevations.
    local sideInset = type(template) == "table"
      and template._betterBuildingsSides
    if type(sideInset) == "number" then
      local surfacedAt = m.at
      local roofRows = template.roofRows or 0
      local W, H, D, ground = sp.W, sp.H, pr.D, pr.ground
      sideInset = math.max(0, math.floor(sideInset))
      m.at = function(x, y, z)
        local i = surfacedAt(x, y, z)
        if i == nil or type(x) ~= "number" or type(y) ~= "number"
            or type(z) ~= "number" or z <= 0 or z >= D - 1
            or (x ~= 0 and x ~= W - 1) then return i end

        -- A pitched adapter can raise wall material into screen rows that
        -- belonged to the roof drawing. Prefer the returned source texel's
        -- row when it identifies facade material; otherwise use the direct
        -- ground-relative row. Synthesised roof rims consequently keep their
        -- dark roof trim rather than being mistaken for wall.
        local sy = ground - 1 - y
        local sourceRow = type(i) == "number" and i >= 0 and i < W * H
          and math.floor(i / W) or nil
        local wallRow = sourceRow and sourceRow >= roofRows and sourceRow
          or (sy >= roofRows and sy < H and sy)
        if not wallRow then return i end

        local phase = z % 32
        local inset = (phase == 0 or phase == 31) and 0
          or (phase == 1 and 1) or sideInset
        local west = x == 0
        local sx = west and inset or (W - 1 - inset)
        sx = math.max(0, math.min(W - 1, sx))
        local donor = wallRow * W + sx
        if sp.inside[donor] then return donor end

        -- Flush-cropped and tapered drawings occasionally leave that exact
        -- inset transparent. Walk inward on the same painted course so the
        -- fallback still belongs to this building and this elevation row.
        for d = 0, W - 1 do
          sx = west and d or (W - 1 - d)
          donor = wallRow * W + sx
          if sp.inside[donor] then return donor end
        end
        return i
      end
    end

    -- Saffron's broad glazed civic bays must remain a visible surface, not
    -- holes in the front shell.  The stock pane treatment models a recess by
    -- omitting the outermost voxel.  That is convincing for a small window,
    -- but across these curtain walls it gives an oblique view a clear ray to
    -- characters and scenery behind the building.  Restore only missing
    -- facade voxels from the drawing itself; frames and every already-solid
    -- texel are untouched, as are all other towns and all roof geometry.
    local opaqueFront = type(template) == "table"
      and template._betterBuildingsOpaqueFront
    if opaqueFront then
      local surfacedAt = m.at
      local W, H, D, ground = sp.W, sp.H, pr.D, pr.ground
      local roofRows = template.roofRows or 0
      m.at = function(x, y, z)
        local i = surfacedAt(x, y, z)
        if i ~= nil or type(x) ~= "number" or type(y) ~= "number"
            or x < 0 or x >= W or z ~= D - 1 then return i end
        local sy = ground - 1 - y
        if sy >= roofRows and sy < H then return sy * W + x end
        return i
      end
    end

    local doors = type(template) == "table"
      and template._betterBuildingsSideDoors
    if type(doors) ~= "table" then return m end

    local baseAt = m.at
    local W, D, ground = sp.W, pr.D, pr.ground
    m.at = function(x, y, z)
      if type(x) ~= "number" or type(y) ~= "number" or type(z) ~= "number"
          or x < 0 or x >= W or y < 0 or y > m.ytop
          or z < m.zmin or z > m.zmax then
        return baseAt(x, y, z)
      end
      local sy = ground - 1 - y
      if sy >= 0 and sy < sp.H then
        for _, door in ipairs(doors) do
          local zr, sr = door.z, door.source
          local wr, yr = door.wallSource, door.rows
          if type(zr) == "table" and type(sr) == "table"
              and type(wr) == "table" and type(yr) == "table"
              and sy >= yr[1] and sy <= yr[2] then
            -- Replace the south-facing copy first. At the one corner voxel
            -- shared by two elevations this gives the long wall the clean
            -- cream edge; the side door still keeps its other fifteen pixels.
            if z == D - 1 and x >= sr[1] and x <= sr[2] then
              local sx = remap(x, sr[1], sr[2], wr[1], wr[2], false)
              return sy * W + sx
            end
            local edge = (door.side == "west" and x == 0)
              or (door.side == "east" and x == W - 1)
            if edge and z >= zr[1] and z <= zr[2]
                and sp.inside[sy * W + x] then
              local sx = remap(z, zr[1], zr[2], sr[1], sr[2],
                door.side == "east")
              return sy * W + sx
            end
          end
        end
      end
      return baseAt(x, y, z)
    end
    return m
  end

  debug.setupvalue(Buildings.build, slot, adaptedModel)
  return true
end

-- The diorama ships as a FAMILY of forks -- Battle Art Voxel, the original
-- DramaticShape, its Dramaless successor and PotatoVoxel -- and they declare
-- each other as conflicts, so at most one is ever loaded.  What matters here
-- is that they all still expose the same namespace this section is written
-- against: `exports.lib` with `require`/`data`, a `Buildings.build` closing
-- over the `model` upvalue the adapter wraps, and the same `voxel_heights`
-- building profile with the same template vocabulary.  So the work below is
-- identical whichever one is installed, and the only fork-specific thing is
-- the id.  Look for each in turn and take the first that is actually present
-- AND carries that namespace: a fork that has been trimmed to something this
-- adapter cannot drive is skipped rather than left to mask a later one.
local VOXEL_COMPANIONS = {
  "BATTLE_ART_VOXEL_FORK", "DRAMATIC_SHAPE", "DRAMALESS_SHAPE", "potato_voxel",
}
local voxel
for _, id in ipairs(VOXEL_COMPANIONS) do
  local found = mod.find(id)
  local lib = found and found.exports and found.exports.lib
  if type(lib) == "table" and type(lib.require) == "function"
      and type(lib.data) == "function" then
    voxel = found
    break
  end
end
if voxel then
  local V = voxel.exports.lib
  local sideDoorOk, sideDoorWhy = installGateSideDoorAdapter(V)
  if not sideDoorOk then
    mod.log:warn("could not orient route-gate end entrances in voxel mode: %s",
      sideDoorWhy)
  end
  local okProfile, profile = pcall(V.data, "voxel_heights")
  local list = okProfile and type(profile) == "table" and profile.buildings
    and profile.buildings.OVERWORLD

  if type(list) == "table" then
    -- Idempotent across a development hot reload: the voxel namespace keeps
    -- its data cache, so discard this mod's previous registrations first.
    for i = #list, 1, -1 do
      local id = list[i] and list[i].id
      if type(id) == "string" and id:sub(1, 17) == "better_buildings_" then
        table.remove(list, i)
      end
    end

    -- The mirrored-back bug belongs to the stock overworld templates too --
    -- the Museum, Pokemon Tower, Silph Co and any vanilla building this mod
    -- deliberately leaves alone. Mark those existing profile entries for the
    -- same in-memory rear-elevation treatment before appending our own.
    local nativeBacks = 0
    for _, entry in ipairs(list) do
      if type(entry) == "table" and type(entry.tiles) == "table"
          and not entry.claimOnly then
        entry._betterBuildingsBack = 2
        entry._betterBuildingsSides = 2
        nativeBacks = nativeBacks + 1
      end
    end

    local function addTemplate(id, rows, options)
      local entry = {
        id = "better_buildings_" .. id,
        tiles = rows,
        roofRows = 32,
        roofBack = 7,
        roofFront = 8,
        roofCycle = { 5, 12 },
        slab = 4,
        frontEave = 4,
        ledge = nil,
        _betterBuildingsBack = 2,
        _betterBuildingsSides = 2,
      }
      for key, value in pairs(options or {}) do entry[key] = value end
      list[#list + 1] = entry
    end

    local function blockRowsToTiles(grid, cropTop)
      local rows = {}
      for _, blockRow in ipairs(grid) do
        for r = 0, 3 do
          local row = {}
          for _, blockId in ipairs(blockRow) do
            local block = blocksOut[blockId + 1]
            if type(block) ~= "table" then return nil end
            for c = 1, 4 do row[#row + 1] = block[r * 4 + c] end
          end
          rows[#rows + 1] = row
        end
      end
      for _ = 1, cropTop or 0 do table.remove(rows, 1) end
      return rows
    end

    -- Exact models for every converted shop, gym, cottage, gabled house and
    -- pitched civic-house arrangement.
    -- Their rectangular drawings need the explicit rise below: without it the
    -- authored-profile path correctly finds the roof/facade boundary but has
    -- no transparent taper from which to recover the old detector's gable.
    table.sort(slopedVoxelGrids, function(a, b)
      local aa = #a.grid * #(a.grid[1] or {})
      local ba = #b.grid * #(b.grid[1] or {})
      return aa > ba
    end)
    local slopedSeen, slopedShapes = {}, 0
    for _, spec in ipairs(slopedVoxelGrids) do
      local rows = blockRowsToTiles(spec.grid, spec.options.cropTop)
      if rows and #rows > 0 then
        local keyParts = {}
        for _, row in ipairs(rows) do
          keyParts[#keyParts + 1] = table.concat(row, ",")
        end
        local key = table.concat(keyParts, ";")
        if not slopedSeen[key] then
          slopedSeen[key] = true
          slopedShapes = slopedShapes + 1
          local options = {}
          for name, value in pairs(spec.options) do
            if name ~= "cropTop" then options[name] = value end
          end
          options._betterBuildingsPitch = 16
          addTemplate("pitched_" .. slopedShapes, rows, options)
        end
      end
    end
    if slopedShapes > 0 then
      mod.log:info("modelled %d pitched landmark, cottage, house and civic "
        .. "arrangement(s) with walls joined to their 16-voxel roof slopes "
        .. "for %s", slopedShapes, voxel.id)
    end

    local storeRows = {}
    local function repeatBlockRow(row, col, count, out)
      for _ = 1, count do
        for c = 0, 3 do out[#out + 1] = tileId(row, col + c) end
      end
    end
    -- one roof block repeated four times
    for r = 0, 3 do
      local row = {}
      repeatBlockRow(DEPT_BAND + r, DEPT_COL.roof, 4, row)
      storeRows[#storeRows + 1] = row
    end
    -- one upper-storey block repeated across two complete floors
    for _ = 1, 2 do
      for r = 0, 3 do
        local row = {}
        repeatBlockRow(DEPT_BAND + r, DEPT_COL.upper, 4, row)
        storeRows[#storeRows + 1] = row
      end
    end
    -- outer display, two entrances, outer display
    for r = 0, 3 do
      local row = {}
      repeatBlockRow(DEPT_BAND + r, DEPT_COL.ground, 1, row)
      repeatBlockRow(DEPT_BAND + r, DEPT_COL.door, 2, row)
      repeatBlockRow(DEPT_BAND + r, DEPT_COL.ground, 1, row)
      storeRows[#storeRows + 1] = row
    end
    addTemplate("celadon_department_store", storeRows)

    -- ------- Professor Oak's Lab
    --
    -- Registered FLAT, which is the one thing this drawing insists on.  Left
    -- to the generic detector the lab came out as a ramp: that path reads a
    -- structure's top two tile rows as a pitched roof unless they repeat
    -- pixel for pixel, and the parapet means these two do not -- so it tilted
    -- a slope over the building whose whole point is that it has none.  A
    -- template settles it without a special case, because the roof band is
    -- drawn from straight above with no taper: the measured elevation profile
    -- is level across every column, and the model comes out as the low
    -- research block the elevation depicts.
    --
    -- `seal = "we"` is not optional here.  The lab is a module kit and its
    -- bays carry no end treatment (the drawing says so itself), so the left
    -- and right columns are bare tile face and bare concrete rather than
    -- outline; unsealed, the silhouette flood walks in from both borders and
    -- hollows out the roof field and the whole frontage.  North and south
    -- need nothing -- the parapet's top row and the threshold under the
    -- plinth are black across the full width -- and with the flood shut out
    -- the drawing reads solid, which is what it depicts.
    --
    -- The band split follows the bay. Rows 0-3 lay the north parapet, rows
    -- 4-9 provide one complete clean tile course for the repeating deck, and
    -- the four eave rows close the south rim. The roof remains uninterrupted
    -- in both the flat overworld and the voxel diorama.
    --
    -- The frontage takes `panes = false` and stays flush: its lights are dark
    -- glass in WHITE frames, the inverse of the polarity the recess rule
    -- reads, and it is already right as drawn.
    --
    -- The blocks stay exported (mod.exports.oakLabBlocks) so a companion mod
    -- can find the placement without re-deriving it from the warp.
    local labRows = {}
    for r = 0, 3 do
      local row = {}
      repeatBlockRow(OAK_BAND + r, OAK_COL.roof, 3, row)
      labRows[#labRows + 1] = row
    end
    for r = 0, 3 do
      local row = {}
      repeatBlockRow(OAK_BAND + r, OAK_COL.side, 1, row)
      repeatBlockRow(OAK_BAND + r, OAK_COL.door, 1, row)
      repeatBlockRow(OAK_BAND + r, OAK_COL.side, 1, row)
      labRows[#labRows + 1] = row
    end
    addTemplate("oak_lab", labRows, {
      roofBack = 4, roofFront = 4, roofCycle = { 4, 9 },
      seal = "we", panes = false,
    })

    -- ------- the gates
    --
    -- A gate is registered as its own model so the diorama builds it from the
    -- drawing rather than from the generic detector's guess at a box: the
    -- standing-seam roof, opaque doors, clerestory and projecting stair base
    -- all come from the art this mod painted, at the width the map actually
    -- drew the building. Side-entry metadata turns a cap entrance onto its
    -- real west/east elevation instead of leaving it painted on the south.
    --
    -- The door and stairs are opaque on purpose.  A dark ground line seals
    -- the drawing from the silhouette flood, so light roof, clerestory, wall
    -- and step pixels all remain solid.  The five-row stair-base band is the
    -- one part that projects past the facade, giving its three painted treads
    -- a real foundation lip without moving the map's collision or warp cell.
    --
    -- The grids come from the placements the map pass actually made rather
    -- than from a list of Kanto's gate arrangements, so a gate this mod
    -- rebuilt is a gate this mod can model, whatever width the map drew it.
    local seen, shapes = {}, 0
    for _, grid in ipairs(gates) do
      local key = {}
      for _, blockRow in ipairs(grid) do
        key[#key + 1] = table.concat(blockRow, ",")
      end
      key[#key + 1] = "w=" .. tostring(grid.endWCell)
      key[#key + 1] = "e=" .. tostring(grid.endECell)
      key = table.concat(key, ";")
      if not seen[key] then
        seen[key] = true
        local rows = blockRowsToTiles(grid)
        if rows then
          shapes = shapes + 1
          local options = { ledge = { 58, 62 } }
          local sideDoors = {}
          local widthPx, depthPx = #grid[1] * 32, #grid * 32
          if grid.endWCell ~= nil then
            local z0 = depthPx - 32 + grid.endWCell * 16
            sideDoors[#sideDoors + 1] = {
              side = "west", z = { z0, z0 + 15 },
              source = { 0, 15 }, wallSource = { 16, 31 },
              rows = { 45, 62 },
            }
          end
          if grid.endECell ~= nil then
            local z0 = depthPx - 32 + grid.endECell * 16
            sideDoors[#sideDoors + 1] = {
              side = "east", z = { z0, z0 + 15 },
              source = { widthPx - 16, widthPx - 1 },
              wallSource = { widthPx - 32, widthPx - 17 },
              rows = { 45, 62 },
            }
          end
          if #sideDoors > 0 then
            options._betterBuildingsSideDoors = sideDoors
          end
          addTemplate("gate_" .. shapes, rows, options)
        end
      end
    end
    if shapes > 0 then
      mod.log:info("modelled %d opaque gate arrangement(s) with projecting "
        .. "stair bases and oriented side entrances for %s", shapes, voxel.id)
    end

    -- TileShape owns tile classification; ChunkMesher owns both map meshes
    -- and Structures' connected-region cache; Buildings caches one prebuilt
    -- model per template INDEX, which the removal above shifts.  Drop all
    -- three after extending the profile so an already visited Pallet Town or
    -- Fuchsia City rebuilds correctly too.
    local okShape, TileShape = pcall(V.require, "TileShape")
    if okShape and type(TileShape) == "table" and TileShape.invalidate then
      TileShape.invalidate()
    end
    local okBuild, Buildings = pcall(V.require, "Buildings")
    if okBuild and type(Buildings) == "table" and Buildings.invalidate then
      Buildings.invalidate()
    end
    local okMesh, ChunkMesher = pcall(V.require, "ChunkMesher")
    if okMesh and type(ChunkMesher) == "table" and ChunkMesher.invalidate then
      ChunkMesher.invalidate()
    end
    mod.log:info("registered the pitched building set, Celadon Department "
      .. "Store, Professor Oak's Lab and route gates as standalone buildings "
      .. "with %s", voxel.id)
    mod.log:info("replaced mirrored front copies on %d native overworld "
      .. "building back(s) with plain rear elevations", nativeBacks)
    mod.log:info("replaced generic grey fill on %d native overworld "
      .. "building side-wall profile(s) with material-matched elevations",
      nativeBacks)
  else
    -- Older DramaticShape builds do not expose the building profile.  They
    -- still need the original tile-shape cache drop to see the grown atlas.
    local okShape, TileShape = pcall(V.require, "TileShape")
    if okShape and type(TileShape) == "table" and TileShape.invalidate then
      TileShape.invalidate()
      mod.log:info("dropped %s's tile-shape cache so it re-resolves OVERWORLD",
        voxel.id)
    end
  end
end

mod.exports.version = "1.8.2"
mod.exports.installGateSideDoorAdapter = installGateSideDoorAdapter
-- which fork of the voxel diorama this load bound to, or nil in flat mode
mod.exports.voxelCompanion = voxel and voxel.id
-- the ids a companion mod may use to identify these buildings
mod.exports.blocks = shopIds
mod.exports.gymBlocks = gymIds
mod.exports.cottageBlocks = cottageIds
mod.exports.houseBlocks = houseIds
mod.exports.flatBlocks = flatIds
mod.exports.departmentStoreBlocks = departmentIds
mod.exports.oakLabBlocks = oakLabIds
mod.exports.firstTile = BASE_TILES
mod.exports.terrainTiles = terrainTiles