mobile spin fix

add first person mode
fix water again on android
2026-08-02 01:20:39 -04:00 · 2026-08-02 01:16:42 -04:00 · 2026-08-02 00:53:38 -04:00 · 2026-08-02 00:14:13 -04:00 · 2026-08-02 00:01:39 -04:00 · 2026-08-01 23:48:23 -04:00
54 changed files with 14564 additions and 548 deletions
@@ -0,0 +1,200 @@
 name: Release
 # Packs the mod into an installable .zip and publishes it as a GitHub Release,
 # once per push to main.
 #
 # Archive layout: every mod file at the archive root, manifest.json included.
 # That is one of the two shapes the game accepts on MODS > Import mod .zip
 # (src/mods/LauncherMods.lua locateRoot: manifest at the root, or inside a
 # single top-level folder). Nothing else is added, so the archive stays
 # installable by hand too.
 #
 # Versioning, first rule that applies wins:
 #   1. the "version" input of a manual run,
 #   2. "[release X.Y.Z]" anywhere in the commit message,
 #   3. manifest.json's own version, when it is ahead of every existing tag,
 #      so bumping the manifest is the normal way to cut a release,
 #   4. otherwise the newest vX.Y.Z tag with its patch incremented
 #      (0.2.99 rolls over to 0.3.0).
 # Whichever wins is written into the manifest.json inside the archive, so a
 # shipped mod never reports a different version than the release it came from.
 #
 # Generated by: python3 tools/modkit.py add-release-workflow <mod-id>
 # MOD_ID below is stamped to this mod's id when the file is copied.
 on:
  push:
    branches: [master]
    paths-ignore:
      - '.github/**'
      - '**.md'
  workflow_dispatch:
    inputs:
      version:
        description: "Exact version to release (e.g. 0.3.0). Leave blank to auto-resolve."
        required: false
        default: ""
 permissions:
  contents: write
 concurrency:
  group: release
  cancel-in-progress: false
 jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Determine version
        id: ver
        env:
          DISPATCH_VERSION: ${{ github.event.inputs.version }}
        run: |
          set -euo pipefail
          python3 - <<'PY' >> "$GITHUB_OUTPUT"
          import json, os, re, subprocess, sys
          SEMVER = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
          def sh(*args):
              return subprocess.run(args, capture_output=True, text=True).stdout.strip()
          def parse(text):
              m = SEMVER.match(text)
              return tuple(int(p) for p in m.groups()) if m else None
          def die(msg):
              print(f"::error::{msg}", file=sys.stderr)
              raise SystemExit(1)
          with open("manifest.json", encoding="utf-8") as fh:
              manifest_version = str(json.load(fh).get("version", ""))
          released = sorted(
              v for v in (parse(tag[1:]) for tag in sh("git", "tag", "-l", "v*").splitlines()) if v
          )
          latest = released[-1] if released else None
          override = os.environ.get("DISPATCH_VERSION", "").strip()
          if not override:
              found = re.search(r"\[release\s+(\d+\.\d+\.\d+)\]", sh("git", "log", "-1", "--pretty=%B"))
              override = found.group(1) if found else ""
          manifest_ver = parse(manifest_version)
          if override:
              version = parse(override) or die(f"invalid version override {override!r} (expected X.Y.Z)")
              source = "the override"
          elif manifest_ver and (latest is None or manifest_ver > latest):
              version = manifest_ver
              source = "manifest.json"
          elif latest:
              major, minor, patch = latest
              patch += 1
              if patch > 99:
                  minor, patch = minor + 1, 0
              version = (major, minor, patch)
              source = "a patch bump on v%d.%d.%d" % latest
          else:
              die(f"manifest.json version {manifest_version!r} is not X.Y.Z "
                  "and there is no vX.Y.Z tag to count from")
          text = "%d.%d.%d" % version
          print(f"Releasing {text}, from {source}.", file=sys.stderr)
          print(f"version={text}")
          print(f"tag=v{text}")
          PY
      - name: Refuse to clobber an existing release
        env:
          GH_TOKEN: ${{ github.token }}
          TAG: ${{ steps.ver.outputs.tag }}
        run: |
          set -euo pipefail
          if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
            echo "::error::Tag $TAG already exists. Pick a different version."
            exit 1
          fi
          if gh release view "$TAG" >/dev/null 2>&1; then
            echo "::error::Release $TAG already exists. Pick a different version."
            exit 1
          fi
      - name: Build the mod .zip
        env:
          VERSION: ${{ steps.ver.outputs.version }}
          MOD_ID: "DRAMATIC_SHAPE"
        run: |
          set -euo pipefail
          staging="$RUNNER_TEMP/pkg"
          out="$GITHUB_WORKSPACE/dist"
          rm -rf "$staging" "$out"
          mkdir -p "$staging" "$out"
          git archive HEAD | tar -x -C "$staging"
          rm -rf "$staging/.github" "$staging/.gitattributes" \
                 "$staging/.gitignore" "$staging/.luarc.json"
          python3 - "$staging/manifest.json" "$VERSION" <<'PY'
          import json, sys
          path, version = sys.argv[1], sys.argv[2]
          with open(path, encoding="utf-8") as fh:
              manifest = json.load(fh)
          manifest["version"] = version
          with open(path, "w", encoding="utf-8") as fh:
              json.dump(manifest, fh, indent=2, ensure_ascii=False)
              fh.write("\n")
          PY
          zip_path="$out/${MOD_ID}-${VERSION}.zip"
          (cd "$staging" && zip -qr "$zip_path" .)
          unzip -l "$zip_path"
          unzip -p "$zip_path" manifest.json > "$RUNNER_TEMP/packed-manifest.json"
          python3 - "$RUNNER_TEMP/packed-manifest.json" "$VERSION" <<'PY'
          import json, sys
          path, expected = sys.argv[1], sys.argv[2]
          with open(path, encoding="utf-8") as fh:
              version = json.load(fh)["version"]
          if version != expected:
              raise SystemExit(f"::error::packed manifest says {version}, expected {expected}")
          print(f"manifest.json is at the archive root and reports {version}")
          PY
          (cd "$out" && sha256sum "${MOD_ID}"-*.zip > sha256sums.txt)
          cat "$out/sha256sums.txt"
      - name: Publish GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
          VERSION: ${{ steps.ver.outputs.version }}
          TAG: ${{ steps.ver.outputs.tag }}
          MOD_ID: "DRAMATIC_SHAPE"
        run: |
          set -euo pipefail
          prev="$(git tag -l 'v*' --sort=-v:refname | grep -v "^${TAG}$" | head -1 || true)"
          range="${prev:+${prev}..}$GITHUB_SHA"
          changes="$(git log --no-merges --pretty='- %s' "$range" | head -50 || true)"
          notes=$'Download the .zip and install it from the game: MODS > Import mod .zip.'
          if [ -n "$changes" ]; then
            notes+=$'\n\n## Changes\n\n'"$changes"
          fi
          printf 'Release notes:\n%s\n' "$notes"
          gh release create "$TAG" \
            --target "$GITHUB_SHA" \
            --title "$VERSION" \
            --notes "$notes" \
            "dist/${MOD_ID}-${VERSION}.zip" \
            "dist/sha256sums.txt"
          echo "Published release $TAG"
@@ -1,5 +1,852 @@
 # Changelog
 ## 1.5.0
 ### Added
 - **1ST: a first-person camera, played like a modern one.** A seventh
  rung on the VOXEL ladder (hotkey 3 walks it; the OPTIONS row carries
  it). Stepping onto it dives the camera from wherever the orbit was
  into the player's own head over half a second, and stepping off flies
  it back out. The rig rides the same placed-camera seam the staged
  battle proved out, so the sky's bands meet the horizon, the sun and
  moon hang where their shadows say, and the water reflects at eye
  level -- all through math that was already there.
  - **Free look.** Relative mouse motion (the cursor is captured while
    the rung is on; left click is A, right click is B), the right
    stick at a rate with a squared response curve, or a touch dragged
    across any open screen -- the overlay's d-pad and buttons still
    work, and a second finger can drag the view while the first
    walks. Pitch clamps short of straight up and straight down.
  - **Free movement.** While 1ST drives, the grid walk is replaced by
    a continuous, camera-relative one: push forward and you go where
    you look, at any angle, sliding along whatever you graze. The left
    stick's raw deflection, the touch d-pad's true vector, or the held
    keys (forward / backpedal / strafe) all steer it. The grid is
    still the game: the walk asks the engine's own collision the same
    per-cell questions a grid step asks, the logical cell tracks the
    body, and every cell crossed runs the engine's own landing
    pipeline -- warps, encounters, spinners, gates, poison, repel, the
    step counters. Walking off the map edge, into a ledge or into a
    boulder hands the push to the engine's own handlers, so
    connections cross, ledges hop and boulders shove exactly as
    themselves. Speed is the grid walker's own (bike included), so
    distance per second and encounters per tile are unchanged.
  - **Billboards seen from inside the world.** Character cards stop
    leaning and start turning: upright, yawed about their feet to face
    the eye, wearing the frame their pose shows *this* viewer -- walk
    behind an NPC and you see their back, circle to a flank and you
    get the profile, exactly the four frames Gen 1 drew. The authored
    figures (the couch sitters) turn the same way, about their own
    middle. The sun pass swaps frames in step, so a card never reads
    its own shadow through a mirror-flipped record of itself. The
    player's own card is left out of the camera draw -- the eye stands
    in it -- but still casts its shadow on the ground ahead.
  - The shadow map's box follows the look (the orbit's fit reaches far
    north and barely south, which is wrong for a head facing south);
    the world curve is declined outright while the head owns the
    camera; and the whole rung falls back to the 75-degree orbit on
    hardware without the 3D pass.
 ## 1.4.3
 ### Added
 - **The furniture of the whole game goes through the building
  pipeline.** 1.4.1 put four drawings through it; this is the rest of
  the rooms. Every one of them is the same read -- the drawing's own
  bands say what is a top seen from above, what is a face seen head-on,
  and where the thing ends on the floor -- and every one of them
  replaces a pinned box that wore its drawing as a decal. The pins all
  stay as the degradation path, neutralized wherever a template stamps.
  - **The bookcase, the commonest piece of furniture in the game** --
    58 placements across two drawings on the town-house atlas (books
    and a bowl on each shelf at the west end of eighteen homes, books
    on both at the east), plus Red's and the Copycat's pair. Pinned
    `desk` it was a 24px box with the books painted on its flat front.
    Modelled it is 23 voxels of cabinet with its top seen from above,
    and every book, bowl and door panel sunk a voxel behind the frame
    the drawing seals it in.
  - **Celadon's display cabinets** -- the tall one with the trophy
    behind its glass and the short one beside it, band for band the
    same object as the town house's on another atlas, which is what
    makes the pair read as one line of furniture: 23 voxels and 15,
    exactly the 8 rows of drawing between them.
  - **The dining table, everywhere it is drawn** -- the generic town
    house's at 18 placements, Red's and the Copycat's, and the chief's
    long table at four cells wide. All of them the lab table's read at
    a different width, all of them 6 voxels, all of them standing on
    the ground line their legs are drawn stopping at rather than on
    the grid's floor.
  - **The stool at every one of those tables** -- 94 placements on the
    house atlas alone, ten more in Red's and the Copycat's, and the Fan
    Club's four members' chairs, a different drawing that is
    pixel-identical from the seat down. The first template with no base
    piece at all: a stool is drawn mid-cell over its own floor, so it
    is a desk-set of exactly one part, seat lid over legs with the
    floor showing between them.
  - **The Pokemon Center's healing machine** -- two variants, 24
    placements, plus the Indigo Plateau lobby's pair. A wall-height
    cabinet with its monitor perched on the front of its top face,
    drawn across two map rows because it towers over the 16px band
    behind it, which the volume path could only read as more wall. The
    hoses leaving its side are modelled as hoses, at the elevation and
    the depth the two stacked motifs put them; the west machine's
    keyboard is a shelf at counter height wearing its own top-view art.
  - **Bill's desk, and the Silph president's** -- the same drawing in
    both rooms. Its terminal is drawn in 2:1 isometric, turned 45
    degrees to the map, and builds as a cube rather than the slab a 2:1
    reading gives; the kinked dark run between keyboard and computer is
    raised to the keyboard's height and reads as the cable it is. The
    desk stops at its own two cells because the artist drew its apron
    into the walkable cell in front, sharing tiles with the chair
    pushed up to it -- so the chair is modelled as a part of the desk.
  - **The Bike Shop's open toolbox.** The drawing looks down INTO the
    tray, which is why every solid treatment failed it -- as a
    `billboard` the whole cell went up as one 10-voxel slab wearing the
    drawing as a decal. `tray` builds four walls, a floor and air
    between them, with the lid standing open on its hinge.
  What the template language grew to carry them: `tray`; a `desk` band
  that lays its top face flat as a lid; the `box`, `flat` and `iso`
  part kinds; `stretch` for a band mapped over a deeper plot than it
  was drawn on; `inset` for a pane sunk by hand; `panes = false` where
  the global recess pass has the polarity backwards; a `wall` element
  so a template can keep the band behind it solid; `plane` for a height
  the drawing states elsewhere; and `scrub`/`keep`/`support`, which let
  a template model a surface while leaving an object standing on it to
  its own standee -- Red's potted plant on the dining table.
 - **Round bins: the `can` class.** Vermilion Gym's switch puzzle stands
  fifteen galvanised trash cans in a row, and the S.S. Anne redraws the
  same object pixel for pixel as its galley barrels. Left to the thin
  standee pool they were flat discs on edge -- fifteen coins standing
  in a row; pinned a plain `cylinder` the drawing's base arc revolves
  too and they came out as barrels balanced on a three-voxel stem.
  `can` is the round hull cut at both ends, hollowed and tapered: the
  drawn mouth ellipse projects across the top and down the well so you
  look into the bin, the drawn base ellipse is ground contact rather
  than body, and the plan narrows toward the floor. The two ellipses
  are measured off the pixels; the height, the well and the taper are
  authored, and the entry says why.
 - **The rock gyms' boulders are round.** 87 placements over Pewter's
  walls and maze and Bruno's clusters, and every one of them was a
  square bar wearing a boulder texture in relief -- the repeat-aware
  scenery path extruding the whole drawing as one course. Each cell is
  now a hull whose plan is its own drawn width profile turned in depth:
  a dome full-width from the drawn shoulder down, tapering over the top
  five rows exactly where the art tapers, with the floor's corner
  diamonds opening between them the way the drawing has them. Still
  16px, so nothing standing on or beside a rock moves.
 - **The potted plant stands as a plant.** The most repeated interior
  prop in the game -- 78 placements over 13 maps, six per Pokemon
  Center -- and its urn was rendering as a hollow black frame, because
  the drawing's foot lies flush on the block's bottom edge and the
  background vote took the plant's own darks away with the floor. Named
  outright as light and white instead, it stands as one organic
  silhouette 32px tall over its two stacked cells, crown overhanging
  the stem. `planter` carries the same reading for a round drawing
  stacked two cells high on one cell of plot.
 - **Bicycles, in both places the Bike Shop draws them.** The six on the
  showroom floor get their own pool at two voxels rather than the thin
  pool's five: a bike is a line drawing, and at five voxels every
  stroke closes the gap to its neighbour with its own side faces, so
  from any angle but dead-on the air inside the frames filled in and
  the six came out as one dark lump. And the two against the north wall
  get `mounted`, a new authored-mask escape for a thing drawn INTO a
  wall band: it holds the wall's plane as a thin per-pixel slab instead
  of standing up as a sprite card, and it keeps its drawn elevation, so
  a bicycle hung clear of the floor stays hung. Its mask is measured
  rather than hand-drawn -- the plain panel tile composited across the
  same grid and the background flooded in through the pixels that still
  match it, which separates bicycle from stripe exactly.
 - **The Marts' cash register is a machine, not a decal.** An authored
  figure may now state a `depth`, which makes it an object rather than
  a person: a per-pixel solid standing on the counter instead of the
  flat card that turned edge-on with the camera. And the drawing is not
  a box -- its black linework packs two facings, an L of base and arm
  around a keypad that is the machine's deck seen from above. `flat`
  lays that rect horizontal in the notch of the L, and `thin` gives the
  receipt curl a paper's thickness where the body's would have made it
  a wedge.
 - **Shelf fronts have relief.** Everything the `bookcase` collapse is
  used for is a shelf, a rack or a display case, and all of them seal
  their contents behind the drawing's own black frame -- so those
  regions now sink a voxel, the same rule a facade's window panes are
  recessed by, and the books stand in the shelf instead of being
  painted on it. A tileset that borrows the collapse for something that
  is not a shelf says `bookcase_relief = false`: the League's masonry
  and pilasters, whose courses are the wall itself, and Bill's
  transporter drums, whose light regions are a lit barrel.
 ### Changed
 - **Class heights now follow the models under them.** A tileset's
  `heights` gets stools at 5 and tables at 6 in the houses, Bill's desk
  at 8, and cans at 9 -- each of them the drawn elevation the new
  template or hull stands at, so whoever sits on a stool sits on the
  seat, and whatever object sprite stands on a table lands on the
  modelled top rather than three voxels over it or under it.
 - The healing machines' two flanks leave the `wall` pin for the thin
  standee pool. They are equipment standing beside the console -- a
  pair of pipes and a keyboard -- and as wall each was boxed into a
  solid 16px half-cell wearing its drawing in relief.
 ### Fixed
 - **Water no longer hides behind water.** The reflective pass writes no
  depth -- the depth canvas is detached for the length of it so the
  shader can read it -- so nothing put a lake in the buffer and no lake
  could occlude another; the sheets were simply painted in mesh order.
  Flat water never showed it, one plane, a farther sheet always landing
  farther down the screen. The world curve ends that: it drops the far
  side of the map into the near field of view, and a sea a hundred and
  fifty tiles away came out rasterised on top of the pond at the
  player's feet, tall grass and all -- water and terrain "from the
  other side of the map", not reflected but there. The water meshes now
  go down flat first, through the ordinary scene shader with depth
  writes on, and the reflective pass draws over what survived. The
  buffer holds the surface, so the pass's own test throws the far sheet
  away; the reflection copy holds it too, so a ray grazing another part
  of the lake reads water rather than the void behind it; and a frame
  that cannot run the pass at all is unchanged, because the flat draw
  is the fallback that was already there.
 - **Reflections under the world curve.** The bend tips the world away
  and the things standing on it do not lean with it -- and a lake is
  one of those things. Reflected off the bowl the bend makes, the far
  half of a pond was a mirror tilted twenty degrees: it threw the ray
  past the vertical, where the sky ramp's own measure swings from one
  end to the other across a single column, and hard-edged patches of
  the wrong sky stamped into the water; the same tilt sent the
  screen-space march grazing along the bank rather than over it, which
  is what smeared the dock and the roofs across the harbour. What the
  water reflects is now worked out in the flat world, exactly as it
  would be with the curve off, and every marched sample is bent on its
  way to the screen by the vertex stage's own displacement -- so the
  ray is straight where it should be and lands where the geometry did.
  The wave columns are read on the flat sheet too: the relief walk is
  built on an even slab over a level plane, and in the curved world
  that slab is a bowl, which handed back a column a pixel or three off
  per fragment -- a patch of noise in the middle of a pond.
 - **Merged runs tore open under the curve.** A quad's interior is the
  chord of a parabola its neighbours draw the arc of, so a long run
  hangs below the short quads butted against it. Nothing bounded a
  run's length, and the ones that ran away were those wearing a
  constant texel -- a roof's black eave outline, its fascia, its shaded
  underside -- because a flat run has no art to break it. At 102px
  across a gym the eave tore off the roof and the slot showed the
  building's dark interior through it. Runs now stop at the next 8px
  lattice line, which is the lattice buildings are stamped on and the
  one every other quad in the scene already ends on, so every join is
  vertex-for-vertex and the bend carries them together. It costs quads
  whether the curve is on or not -- Cerulean's object stream goes from
  35.7k to 41.6k -- and that is deliberate: the mesh is cached per map
  and built over seconds, so meshing for the curve's sake only when the
  curve is on would mean rebuilding every live map on a keypress.
 ## 1.4.1
 ### Added
 - **Furniture through the building pipeline.** The band-table voxelizer
  that models whole buildings from their own drawings (lib/Buildings.lua)
  now reads interior furniture too, and the first four drawings are in:
  - **F01, the starter-ball table in Oak's lab** -- the tabletop's 16
    drawn rows lay flat over a 16px plot (1:1, the first template that
    never cycles), the black/#555/black edge band folds into the slab's
    own rim, and the base extrudes with its corner feet. Six voxels
    tall, exactly the drawn elevation.
  - **F03, the empty north table beside it** -- the same band table on a
    grid two tiles narrower.
  - **F02, the lab's computer desk** -- the first DESK-SET template: the
    drawing segments into PARTS, each classified by the surface it
    depicts. The monitor and the computer tower stand upright on the
    desk wearing their own drawn tops as lids; the keyboards and the
    mouse lie flat in front of them; the sheet of paper on the right
    lies flat across the desk. Flat parts keep the drawing's own rule --
    drawn row IS depth row, the same 1:1 the tabletop is drawn with --
    so an object's height on the drawing is its position on the desk.
    The Hall of Fame's recording machine is this drawing tile for tile
    on the GYM atlas, and models identically for free.
  - **F04, the Center PC** -- the desk-set read again: a Mac-style unit
    with its screen and drive slot in relief, standing at the back of a
    low white-topped desk with its keyboard lying at the front edge.
    Eleven Pokemon Centers, plus the Indigo Plateau lobby, whose MART
    tileset shares the atlas.
  Two measurements had to stop being assumptions for furniture to fit
  the pipeline: the GROUND LINE is now read off the drawing (a building
  ends on the black threshold row it stands on; a table's legs stop two
  rows short of theirs, and extruding against the grid floated them in
  the air), and a template may name its PLOT (`depth`) when the matched
  grid runs past it onto the walkable floor the legs merely stand on.
  Both are identities for every existing building.
 - **The Center couch has a backrest.** The couch is drawn from above --
  back-and-arm strip down the west side, cushions and seams on the east
  -- and rendered as one seat-high box. The new `backrest` class raises
  the drawn back strip to 12px over the 8px seat, in every Center and
  the Celadon Hotel. The man sitting on it keeps his seat: the figure
  anchor now scans under his card for the tallest authored upright (his
  cushion) instead of reading the corner tile, which is the backrest
  now.
 ### Changed
 - **Sprites ride at the height the art actually stands.** Class heights
  can now be overridden per tileset (a tileset entry's `heights`), and
  DOJO's lab tables use it: they are drawn 6px tall, not the default
  table's 12, so the starter balls sit exactly on the modelled tabletop
  -- and the volume-built north tables drop to the same height, keeping
  every table in the room level.
 - The Center PC's old rendering -- a 12px table box with the unit as a
  flat standee on it -- retires wherever the F04 template stamps; the
  pins stay only as the degradation path when the shape profile is
  absent.
 ## 1.4.0
 ### Added
 - **WATER, a new row on hotkey 9: water reflects the world, the sky, the sun
  and the moon.** Every lake, sea and pond in Kanto was a flat animated
  texture lying in a hole in the ground. It is now a surface, and it is
  reflective.
  What it reflects, in the order the shader resolves them:
  - **The sky.** The reflected direction goes through the very matrix the
    frame is drawn with, as a point at infinity, and the canvas row that
    lands on is looked up on Sky's own band ramp -- the identical texture,
    the identical checkerboard dither, the identical display-mode transform.
    So the sky in the lake is the sky over it, and the two meet at the
    waterline with no seam at any pitch, field of view, window shape or zoom.
    Blue at noon, gold at dusk, navy under the moon; GRAY gets a grey lake
    and CLASSIC a green one, for nothing.
  - **The sun and the moon**, hung by ANGLE rather than by screen position,
    because a reflected body is usually off the top of the frame entirely
    and a projected point stops meaning anything out there. The angular
    radius is the painted disc's own radius run back through the camera's
    field of view, so the two are the same size -- craters, dithered rim,
    the sunset's loom and all, off one shared list. This is also the
    specular: a low sun lays a broken gold path across the water on its own,
    out of the reflection rather than out of a highlight term nailed on
    beside it.
  - **The world, in screen space.** The reflected ray is walked forward in
    world space, each step projected through the same matrix, looking for
    where it passes behind what the depth buffer holds -- then binary-refined
    onto the contact and read out of a copy of the frame as it stood before
    the water went down. Shore trees, buildings, ledges and cliffs land in
    the water because they are on screen; where the ray leaves the frame or
    finds nothing, the sky above answers instead, which is what makes the far
    half of a lake sky and the near half scenery with no seam between them.
  Fresnel decides how much of it shows: almost nothing looked straight down
  at, almost everything looked along -- so the 15-degree rung is a pond and
  the 75-degree rung is a mirror, off the same surface.
  Every rung gets one, though, which took a lean. A reflection off flat water
  points as far above the horizon as the eye is above the water: 15 degrees
  at the top rung -- grazing the sky's pale end, sweeping the sun's own path,
  travelling far enough across the screen for the march to find the shoreline
  -- and 75 degrees, straight up, at the steepest. Up there the bands are at
  their darkest, the sun and moon sit at about 6 degrees of squashed
  elevation and are nowhere near it, and the screen-space ray leaves the top
  of the frame in two steps. All three are correct, and together they are a
  lake with nothing in it.
  So the reflection now LEANS toward the elevation the top rung reflects at,
  by however far the camera is from having a horizon in frame -- **zero** at
  the rung where the horizon IS in frame, so the one place the join can be
  seen, the waterline, is still the exact reflection it was. Toward an
  elevation rather than by a weight, because the ray it starts from differs
  at every rung and a fixed fraction lands them all somewhere different: the
  middle rungs came out further from the sun than the steepest one. And it
  leans the LEVEL reflection with each column's own deflection added back on
  top -- leaning the perturbed ray sets its elevation outright, which at full
  lean gave every column on the lake the same one, flattened the sky to a
  single band and removed the moon entirely.
  Three rungs rather than a toggle. FULL is the whole thing; SKY drops the
  ray march and keeps the sky, sun and moon, which is most of the look for a
  handful of instructions; OFF is the flat water this mode always drew. The
  FULL preset sets it to FULL.
 - **The water surface is a field of pixel-tall columns, and they are real.**
  Not a normal map: a heightfield of one-world-pixel bars -- the same unit
  every other voxel in this mode is built from, and exactly one texel of the
  water tile -- each standing a WHOLE number of pixels high and rising and
  falling on its own.
  Three travelling wave trains, and one of them dominates: a wave has a
  DIRECTION, and its crest is a line running across it for as far as the
  water goes. Three trains of equal weight cancel and reinforce in patches
  instead, and the surface comes out as round islands of raised pixels with
  no travel to them -- blobs rather than waves. The dominant train's
  wavelength is about forty world pixels, five tiles, so a crest is a long
  run of columns at one height with a step down either side.
  Drawn with no extra geometry at all: the mesh is still one flat quad per
  tile, and the columns are found by walking the view ray down through the
  slab in the pixel shader. That is what makes them read as solid -- a tall
  bar hides the shorter ones behind it, you see the SIDE of the ones facing
  you (wearing the mesh's own direction shading, so a crest is lit like every
  other voxel in the world), and the whole field parallaxes against the plane
  as the camera moves. The water's art is read at the column the ray landed
  on rather than at the flat quad underneath, so the pixels travel with the
  bars they are made of.
  The columns are what you SEE; the normal they reflect with is read off the
  smooth surface they are a quantisation of. That distinction is the whole
  difference between a moon on the water and confetti: whole-pixel heights
  have whole-pixel differences, so a normal built from them can only point in
  about five directions, and a sun or moon barely two degrees across falls
  between them. Still one normal per column, so the surface stays
  pixel-quantised in space while the value it reflects with is continuous.
  Crests stand up to five world pixels, well past the 2px recess water sits
  in -- deliberately, because the columns are relief drawn inside the water
  quad's own footprint, so a bar that reaches above the bank is clipped at
  the water's edge rather than spilling over it. What it buys is a surface
  with real swell in it instead of a two-rung terrace.
  And it moves in STEPS, at **15 a second** -- the cadence hand-drawn pixel
  art is animated at. A surface built out of whole pixels that crawls
  smoothly between them gives away that the quantisation is only skin deep.
  Each step advances the dominant wave by exactly one world pixel, derived
  from that train's own wavelength rather than tuned beside it, so nothing
  ever lands half-way between two pixels and changing a wavelength moves the
  speed with it.
 - **AA, a new options row: OFF / 2X / 4X.** Everything else in this game is
  flat art blitted at whole pixels. This mode's world is real geometry seen
  through a perspective camera, and a polygon edge that lands at an angle
  across the pixel grid is the one place where a hard stair-step is not a
  stylistic choice -- a roof ridge, a ledge lip, a tree's silhouette against
  the sky, the leaning card of a character. At the shallow rungs, where the
  diorama reads most like a photograph of a model, they crawl as the camera
  drifts.
  The row is SUPERSAMPLING: the whole pass renders into a canvas larger than
  the window and is folded back down at the end. The ladder is samples per
  display pixel, so 2X is a canvas root-two wider and taller and 4X one
  exactly twice the size -- an honest 2x2 box.
  Two alternatives were tried against what this pass already is, and both
  lost:
  - **MSAA** would have taken the water with it. The reflections read the
    frame's own depth buffer as a texture, and a multisampled depth
    attachment is not something a fragment shader in this dialect can sample.
    The row would have quietly switched the WATER row off.
  - **An edge filter** (FXAA and its relatives) works from the finished
    colour alone, so it would be guessing where the edges are out of one
    sample per pixel -- inventing detail it never rendered, and unable to
    tell a geometry edge from the boundary between two texels of a tileset.
  Rendering larger has neither problem, and nothing in the frame had to be
  taught about it: every pass already measures itself in the canvas it was
  handed, so the sky's dither, the water's ray march, the shadow lookups and
  the camera itself come out the same picture at a higher sample rate. It
  antialiases the geometry, the alpha-cut outline of a sprite card, the
  wireframe and the reflections at once, because none of them know it is
  happening.
  And it softens the ARTWORK with them, which is worth saying plainly. A
  tileset texel out here is not a screen pixel, it is a quad in a perspective
  view, and its boundary crosses the pixel grid at the same arbitrary angle a
  roof ridge does -- so the fold averages across it exactly as it averages
  across the ridge. That is what an honest extra sample says about that
  pixel, and it is also the trade the row is: the diorama comes out smoother,
  not sharper. Which is why it is a row and not something that is simply on.
  Two things are quoted in DISPLAY pixels rather than canvas ones and are
  multiplied up to match: the voxel wireframe's line width -- left alone it
  would fold down to half a line, so turning the smoothing up would appear to
  fade the grid out -- and the scale the overworld's FX closures draw at.
  The fold is a shader rather than a scaled draw, because the void this pass
  renders into is a transparent BLACK: averaging a straight-alpha edge against
  it drags the colour toward black as well as toward transparent, and the
  engine's composite then multiplies by that alpha a second time. Every
  silhouette against the sky would have come out ringed with a dark fringe --
  the exact artefact the row exists to remove. So the taps are premultiplied
  before they are averaged and divided back out after.
  The staged battle gets it too, on its own canvas: the arena is folded back
  to the window's pixel size before the depth-of-field pass and the HUDs go
  on, so the world is smoothed and the pics, panels and text box stay the
  chunky GB art they are.
  OFF by default, and **FULL neither sets it nor takes the row away** -- it
  is the one row that is not a knob on the look but on what the look COSTS,
  and only the player knows what their machine can carry. No hotkey, for the
  same reason: it is set once, not flicked while walking.
 ### Changed
 - **The water surface is its own mesh, and its own pass.** A mirror cannot be
  drawn until what it reflects exists, so water is lifted out of the terrain
  mesh at build time and drawn between the world and the characters. The
  shoreline faces around it are untouched -- they belong to the GROUND that
  exposes them -- and the sun still sees the surface, so a tree at the water's
  edge still throws its shadow onto the lake.
 - **The scene's depth buffer is a readable canvas.** It was an internal buffer
  that could be written and tested and never sampled; it is now the same
  buffer with a texture handle on it, at the same cost. Drivers that will not
  make one fall straight back to the old buffer and lose the reflections and
  nothing else.
 - **The cast is reflected too -- by being drawn twice.** Gen 1 draws people
  over the world and water is world, so a surfing player has to composite
  OVER the water they are sitting on, which puts them after it; and a
  reflection can only hold what came before it. So the walkers, the NPCs and
  the authored figures are painted into the reflection COPY alone, where they
  are in the picture the water reflects and not yet in the picture the water
  is drawn into. Both draws go through one function, so they cannot come out
  different. The staged battle does the same with its two Pokemon.
  The ray march finds them the honest way round: a sprite is not in the depth
  buffer at that point, so a ray aimed at one passes through to the terrain
  standing behind it and reads the copy there -- where the sprite is already
  painted. The reflection lands a hair off the sprite's own depth and exactly
  on its colour, which at a lake's worth of wave is the same picture.
 ### Changed
 - **The waves arrive in sets now, and a little slower.** Three fixed trains
  are an exactly periodic field -- every forty-odd pixels of sea wore the
  same crest at the same height, which reads as wallpaper the moment a lake
  is bigger than the repeat. Two long-wavelength fields now ride the
  dominant train, four to five carrier wavelengths apiece so neither reads
  as a wave itself: a SWELL that breathes its amplitude, so a few tall
  crests march through and hand over to a lull that is itself moving, and a
  BEND that bows its phase, so a crest line curves across the surface
  instead of ruling itself over all of it. The two lesser trains stay
  plain: they are texture rather than structure, and a third modulator is
  the soup the train weights exist to avoid. The step beat comes down from
  15 to 12 a second -- the crests were hurrying, and a big wave is slower
  than a walk cycle -- still a clean divisor of the engine's 60, and still
  exactly one world pixel of dominant-crest travel per step.
 - **Staged battles draw their water plain, whatever the WATER row says.**
  The reflective pass is tuned for the overworld's ladder of cameras; a
  battle's camera is PLACED -- low, tilted, framed like a picture -- and
  under it the pass read wrong: Fresnel opened all the way up, the leaned
  sky landed on bands the framing never shows, and a lake-sized arena came
  out as murk wearing the tile art. The battle is a stage set, and stage
  water is painted: the flat animated tiles the mode always drew, with the
  mons compositing over them like everything else on the set.
 ### Fixed
 - **On Android the water stayed flat, as if the row were off -- and once it
  did draw, it came up in blocks with the haze showing through the holes.**
  Three separate faults, every one of them invisible on desktop GL, run down
  on a Galaxy Z Fold 7 with the driver's own compiler errors in logcat:
  **The shader would not build.** Fragment floats default to **mediump** on
  GLSL ES while the vertex stage's default is highp, and the water shader is
  the mod's first to declare the same uniform -- the frame's `vp` matrix --
  in BOTH stages, one on each default; GLSL ES refuses to link that, and the
  pass fell back, quietly and by design, to the flat water the mode always
  drew. The pixel stage now lifts its float default to highp (guarded, so a
  GPU without fragment highp still compiles and falls back flat), which
  settles the link and is also simply needed: the march works in world
  coordinates that run to a few thousand, where fp16 has no fraction left.
  The world-position varying is qualified highp for the same reason the
  wireframe's always was, and the depth sampler too -- samplers default to
  **lowp** whatever the floats are set to, and eight bits of depth is a
  march with nothing to land on. One wrinkle inside the fix: LOVE's header
  forward-declares `effect()` under ITS default, and Samsung's Xclipse
  compiler treats a definition whose parameter precisions have drifted from
  the prototype's as an illegal overload -- so effect()'s own float
  parameters stay pinned to mediump, matching the declaration, and the
  maths above them runs highp regardless.
  **The depth test read the wrong texels.** The shader's own depth test
  normalised LOVE's pixel coordinate by the `screen` uniform, which counts
  canvas UNITS -- and on a highdpi phone (Android's density here is 2.625)
  a canvas holds that many PIXELS per unit, so the lookup ran to 2.6,
  clamped, and read edge texels across two thirds of the frame. Water
  discarded itself in blocks wherever the mis-read depth landed in front,
  and the haze backdrop showed through the holes. The coordinate is now
  normalised by `love_ScreenSize.xy` -- the bound canvas's own pixel size,
  measured in the same units on every display.
  **And the readable depth canvas** -- the one hardware requirement the
  rest of the mode does not already have -- now tries four formats before
  giving up: depth24, depth24 riding a stencil (a pairing some mobile
  drivers will texture when they refuse the bare format), depth32f, and
  depth16 as the floor every GLES3 device can read. Refused all four, the
  reflections are lost and nothing else, exactly as before.
 - **Under BACK SPRITES some of your own Pokemon were see-through -- Pikachu,
  Seel, Dewgong, Chansey, Jigglypuff -- with the arena showing through the
  middle of them.** Those back pics are drawn as OUTLINES: everything inside
  the ink is the lightest shade, the decoder keys that shade to nothing, and
  on hardware it did not matter because the field behind them was white too.
  BattlePics already put that paper back by flooding the background inward and
  filling whatever it could not reach, and along the bottom of a figure it told
  a narrow opening (a belly the drawing ran out of, sealed) from a wide one (a
  stride, left open for the world to show through). Right for a mon standing
  on the map -- but the pinned back pic is not on the map, it is on the text
  box with its feet on row 96, and there is white box under its lowest row
  rather than arena. Every one of those mons leaks out through an opening far
  too wide to read as a drain, so the flood walked straight up inside them.
  A pic on the box is now told so, and its bottom edge seals: nothing reaches
  it from below at any width, and the rule stops being a heuristic -- paper is
  whatever the background cannot walk to from the left, the right or the top.
  Twelve of the game's 151 back pics turn on this; the other 139 come back
  byte-identical, and no front pic is touched at all.
  **And a hole is filled with the pic's own paper rather than with white.**
  Shade 0 is only white while the pic is still grays, and pics arrive here
  after the bake -- a species SGB colour, a BGP fade mid-animation, PAL_BLACK
  across the whole screen while the blackout text is up. A hardcoded white
  belly would have been the one lit thing on a blacked-out mon. The lightest
  shade still standing in the pic is that colour, and every one of the game's
  battler pics keeps at least one such pixel -- an eye, a highlight down a
  cheek -- so what goes back is the baked shade itself.
 ### Known
 - Screen-space reflections can only reflect what is in the frame. A tree just
  off the top edge is not in the water below it, and a reflection whose ray
  runs off the side of the screen fades into the sky rather than ending on a
  hard line.
 ## 1.3.1
 ### Fixed
 - **A staged battle on a phone stood some Pokémon three times the size of the
  square they were on.** A Pidgey towered over the arena while the mon beside
  it was the right size, which reads as a bug in one species and is not one.
  Putting the paper back inside a battle pic (BattlePics, 1.3.0) needs the
  pic's pixels, and a LOVE Image does not hand them back -- so the pic is drawn
  into a canvas of its own size and the canvas is read. `newCanvas` takes the
  SURFACE's dpi scale when it is not told otherwise, `conf.lua` turns highdpi
  on for Android and iOS, and Android's display density is routinely 2.75. So
  `newCanvas(56, 56)` allocated a 154x154 texture there, the pic was magnified
  into it, and the readback came back at the magnified size. The rebuilt pic
  was 2.75x the artwork, the engine's pics layer drew it 1:1 because it trusts
  `getWidth()`, and the mon stood on its tile nearly three times too big.
  Only a pic with an enclosed hole in it is rebuilt at all -- the rest are
  handed straight back untouched -- which is why it hit some species and not
  others, and why it never showed on desktop, where the dpi scale is already 1.
  The readback now asks for one texel per pic pixel, the way the engine's own
  `PixelCanvas` does for the same reason. The animated-tile atlas readback took
  the same fix: on a phone it would have come back magnified too, and every
  tile coordinate in it counts in eights from the top-left.
 ## 1.3.0
 ### Added
 - **BACK SPRITES, a new row under 3D-BTL: your own Pokémon stays on the battle menu.**
  The staged shot stands both mons on the map, which is the mode's whole claim
  -- and it costs the framing Gen 1 is most recognisable by: your own Pokémon,
  seen from behind, sitting on top of the battle menu with its feet on the box.
  With BACK SPRITES on the foe is still geometry standing on its own tile at the far
  end of the arena, and the player's side goes back to being the GB's own flat
  back pic in the GB's own slot: same art, same 2x, same feet on row 96. It is
  the engine's own pics layer that draws it, through the `onlySide` argument
  that layer already takes, so every pic effect -- the grow-out-of-the-ball,
  the faint slide, the damage blink, the send-out trainer pic -- comes along
  unchanged and none of it is reimplemented.
  Nothing else about the shot moves. The arena, the camera and the drift are
  solved exactly as they were, so the foe stands where it always stood and the
  player's cell is simply empty ground in the foreground. Two things follow the
  setting: the `pokemon.sprite` hook stops asking for the front pic on the
  player's side (it is a back view again, and the front art would be that mon
  turned round to face the player it belongs to), and the move-animation offset
  drops that side's contribution, because a pic that has not moved cannot have
  moved the pair's centre.
  OFF by default -- what the mode advertises is the two of them out there --
  and only on the OPTIONS menu while 3D-BTL is on, since with staged battles
  off the engine already draws exactly this.
 ### Fixed
 - **Battle pics were see-through, and it took a back sprite on a tiled floor
  to make it obvious.** Gen 1 pics are two-bit art whose lightest shade is
  white, and the decoded PNGs key that shade to alpha 0 -- which cost nothing
  when the field behind them was white too. Over a route, every belly, every
  eye white and every highlight is a hole with the world showing through, and
  the mon reads as a stencil.
  `BattlePics` exists to put that paper back and, as written, put none of it
  back. It flood-filled the outside from the border and filled what the flood
  could not reach, which is exact and, on this game's art, empty: a Gen 1
  figure is an open drawing, and its belly walks out to the border through the
  gap between its legs. Read across all 305 of the game's battle pics, that
  rule finds an enclosed hole in exactly none of them.
  The fix is to start the flood somewhere else: at the edges of the ARTWORK'S
  OWN BOUNDING BOX, and at three of them -- left, right and top. The bottom is
  closed, because it is not a side the background is behind, it is where the
  drawing was CUT. A pic is bottom-aligned in its slot with all the margin at
  the top, so a mon's lowest row is the last row it was given and everything
  below the belly simply stops. Treat that cut as open and the background
  pours up inside the figure, which is the channel of world that used to show
  through a Clefairy.
  That is exact rather than a heuristic: nothing is filled because of what
  surrounds it, only because the background provably cannot reach it. Which is
  why it needs no idea whether it is holding a front pic or a back one -- the
  sky between a pair of ears reaches the top edge and stays sky, the gap
  between a body and a raised tail reaches the side and stays gap, the belly
  reaches neither and is paper. The silhouette is untouched, so the mon still
  cuts cleanly against the world.
  It replaces the border flood outright rather than sitting beside it, since
  anything the border could not reach the box edges cannot reach either.
  The bottom edge needs one more distinction, because two different things
  meet the underside of a figure. A DRAIN is where the drawing ran out -- a
  belly whose white carries on down until the artist stopped, leaking out
  through the inch between a body and a leg -- and is sealed. A MOUTH is the
  space between two legs, background that happens to be enclosed on three
  sides, and is left open so the world shows through a trainer's stride.
  Width tells them apart, and on this game's art it is not a close call.
  Measured along the bottom of every battle pic, the drains run 3 and 4 pixels
  (Clefairy's back, Wartortle's back, Red's back) and the mouths run 10, 12, 14
  and 17 (a Rattata's underbelly, Blue's stride, Brock's, a Pikachu's back).
  Nothing lands between 4 and 10, so the cut is taken at 6 with room either
  side rather than tuned to one sprite. Apart from that number the rule stays
  exact.
  Front pics come back untouched, and not by being special-cased: they are
  near-solid silhouettes with almost nothing inside them to fill, so their own
  shape is what says so.
  Both mons were affected -- the cards in the arena as much as anything -- so
  this lands wherever a battle pic is drawn over the world, not just under
  BACK SPRITES.
 - **The pinned back pic was lit at noon while the world behind it was not.**
  Everything standing in the arena goes through the voxel shader, and that
  shader multiplies by the hour's tint, so at dusk the diorama warms and at
  night it goes blue -- the two mons' cards included, because they are drawn
  in the same pass as the ground they stand on. A back pic pinned to the menu
  is not in that pass; it is a flat blit over the finished shot, and it stayed
  bright over a midnight route.
  The same tint is now applied to that one draw, by multiplying every colour
  the pics layer sets on its way past -- so the alpha, the faint slide's fade
  and the damage blink all compose with it instead of being overwritten. What
  it does not get is the sun: the cards are shadow-mapped and a pic pinned to
  the menu has no position in the scene to be shadowed at, so it carries the
  hour and not the weather.
 ### Added
 - **The hour reaches the FLAT world too, not just the diorama.** DAYTIME drove
  the 3D pass through the voxel shader's own tint uniform -- a uniform the 2D
  tile path never runs -- so with VOXEL 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. Outdoor maps now get the same multiply, painted as one
  rectangle over the composited world.
  The whole difficulty is WHERE, and it is worth writing down. Not on the world
  canvas: in a colorized mode that canvas is grayscale art and the blit that
  puts it on screen runs it through the palette shader, which classifies each
  pixel into a shade BY ITS RED CHANNEL -- multiply a night blue over it first
  and every pixel lands in the wrong bucket, so the world does not darken, it
  changes colour. Not over the finished frame either, or the dialog boxes and
  menus darken along with the world they are held up in front of, which is the
  same reason the tilt-shift blur is a `worldPresent` and not a `present`.
  Which leaves the instant between the world blit and the UI blit, and the
  engine has no seam there -- `worldPresent` only runs when a PIPELINE produced
  the world, which in flat mode is precisely what did not happen. So
  `Renderer:endFrame` is wrapped and the UI canvas's own draw is watched for:
  `blit` passes the canvas it is compositing as the first argument, so the
  first draw of `Renderer.canvas` IS the boundary, by identity rather than by
  counting. The shader and scissor that call arrives under belong to the UI
  blit already in progress, so both are put aside for the rectangle and handed
  straight back.
  Skipped entirely when a pipeline drew the frame (it tinted itself, and twice
  is wrong), indoors (a room has no sky to take its light from), and at midday
  (a multiply by white) -- so a game with the clock at DAY issues not one extra
  call.
 ### Changed
 - **FULL no longer takes the two battle rows off the menu.** It still owns the
  rows that describe the LOOK -- the wireframe, the horizon bend, the blur, the
  hour -- because it is a preset for the diorama and a row that no longer
  decides anything is worse than no row. 3D-BTL and BACK SPRITES are not that:
  one decides what a fight is drawn OVER and the other how it is framed.
  FULL still SETS both on arrival; it does not hold them, and leaving them
  reachable is the difference between a preset and a lock.
  This makes `stagedBattles()` honest as a side effect. It used to answer yes
  under FULL as well, on the grounds that FULL owned the 3D-BTL row and
  switched it on -- safe only while the row was hidden. With the row reachable
  from inside FULL, that clause would have claimed staged battles for a preset
  the player had just switched them off inside, pinning BATTLE LAYOUT to OG for
  a fight that never gets staged. The row is the only thing that decides now,
  which is what `OverworldBattle.begin` and `wantsFront` already believed.
 - **TILT and GBC FX are off the OPTIONS menu entirely while this mod is
  installed.** Both fight the diorama and both were already half-taken: the
  mode's own key 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 a player could set and watch get reverted -- TILT being the flat fake
  of what this mode does for real, and GBC FX a full-screen present pass over
  the top of the whole thing.
  Dropped AND held at zero, which is the part that matters: hiding a live
  setting is a trap, because a save written before the mod was installed can
  carry TILT 3 and a row that is not there cannot turn it back off. Pinned
  wherever the value could arrive from -- the menu opening, a save being
  loaded or begun -- so there is no route by which either is on and
  unreachable. Uninstalling the mod puts both rows back, at whatever they were
  last set to.
 - **The battle's text box and menus are frosted glass, like the HUDs.** The
  HUD blocks got panels because black glyphs on grass are not readable. The box
  at the bottom had the opposite problem and the same cause: it is drawn as an
  opaque white slab with a black border, which was the field's own colour back
  when the field was white and is a sheet of paper laid over the bottom third
  of the diorama now that it is not.
  It gets exactly what the HUDs get -- the world behind it, blurred to frosted
  glass and laid back down translucent, at the same frost and the same tint --
  and it is measured into the same brightness verdict, so the ink over the menu
  flips white with the ink over the HUDs rather than against it. Only the FILL
  is taken away: the border, the text, the cursor and the down arrow are the
  engine's own glyphs in their own places. The move menu's TYPE/PP box and
  Mimic's copy menu get their own panels, trimmed to the rows above the box
  below them so no pixel is frosted twice.
 ## 1.2.1
 ### Fixed
@@ -9,6 +9,22 @@ as leaning sprite slabs, a shadow map throws real cast shadows across
 whatever they land on, and an optional tilt-shift pass sells the
 miniature-model look.
 Water is a surface rather than a texture lying in a hole. It is a field of
 one-pixel-wide voxel columns, each standing a whole number of pixels tall and
 rising and falling as waves — found by walking the view ray through them in
 the shader, so a crest hides what is behind it and shows you its lit side,
 with no extra geometry anywhere.
 And it reflects. The sky it stands under, in the same bands, the same dither
 and off the same clock, so the lake and the sky above it meet at the
 waterline with no seam. The sun or moon hanging in it, at the size the
 painted disc is drawn, craters and all. Whoever is standing beside it —
 walkers, NPCs, the two Pokémon in a staged battle. And on **FULL**, a
 screen-space ray march adds the rest of what is on screen: the shoreline, the
 trees behind it, the buildings across the bay. How much of it shows is
 Fresnel, so the top rung is a mirror and a looking-straight-down rung is a
 pond, off the same water.
 And battles fought on that world rather than on a white field. When
 something picks a fight the map's NPCs are culled, the engine's own wipe
 plays over the empty map, and the battle draws over the nearest patch of
@@ -16,11 +32,26 @@ clear ground — shot over the shoulder, the player's mon low and left and
 the enemy high and right, with a slow parallax drift behind them and a
 depth-of-field pass that keeps both of them sharp.
-Purely presentational. Nothing here reaches collision, movement, triggers
+And the whole thing from inside. The ladder's top rung, **1ST**, dives the
-or scripts — it changes what the world *looks* like and nothing about what
+camera into the player's own head: free look on the mouse (captured while
-it *is*. The battle arena is where the **camera** goes, not where anybody
+the rung is on — left click is A, right click is B), the right stick, or a
-goes: no cell, facing, flag or warp is written, so the player is standing
+touch dragged across open screen; free movement that goes where you look,
-exactly where the fight found them when it ends.
+at any angle, sliding along walls — the left stick's raw deflection, the
 touch d-pad's true vector, or WASD as forward/backpedal/strafe. NPCs turn
 to face the eye wearing the frame their pose shows *this* viewer — walk
 behind someone and you see their back — and the sky, the shadows and the
 water reflections all carry over, because the head rides the same placed
 camera the battle shot proved out.
 Presentational, with one deliberate exception. Every rung but 1ST changes
 what the world *looks* like and nothing about what it *is*; the battle
 arena is where the **camera** goes, not where anybody goes. 1ST replaces
 the grid walk with a free one while it is selected — but 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 cell synced, and runs the
 engine's own landing pipeline per cell crossed, so warps, encounters,
 ledges, gates and scripts all fire exactly as themselves. Step off the
 rung and the grid walk is back.
 ## Controls
@@ -34,7 +65,23 @@ menu.
 | `6`, or the **T-SHIFT** options row | OFF → 1 → 2 → 3 → OFF (miniature blur) |
 | `7`, or the **V-CURVE** options row | OFF → 1 → 2 → 3 — bend the world over the horizon |
 | `8`, or the **3D-BTL** options row | ON / OFF — fight on the map instead of on a white field |
-| the **DAYTIME** options row | SYNC / DAY / NIGHT / DUSK / DAWN / CYCLE — what time it is outdoors; held at SYNC (and off the menu) while VOXEL is FULL |
+| `9`, or the **WATER** options row | FULL / SKY / OFF — waves and reflections on water. **SKY** gives the surface its pixel-tall wave columns and puts the sky, the sun, the moon and the cast in them; **FULL** adds a screen-space ray march that also reflects the shoreline, the trees and the buildings standing behind it |
 | the **BACK SPRITES** options row | OFF / ON — keep your own Pokémon on the battle menu, seen from behind in its classic slot, instead of standing it on the map; the foe is still out there. Only on the menu while **3D-BTL** is on, because it decides nothing without it |
 | the **AA** options row | OFF / 2X / 4X — smooth the stair-stepped edges of the 3D world by rendering the diorama larger than the window and folding it back down. The ladder is samples per display pixel: 2X is a canvas root-two wider and taller, 4X one exactly twice the size. Every edge in the projected picture softens with the silhouettes — the tileset's own texels are quads in a perspective view and cross the pixel grid at the same arbitrary angles — so the diorama reads smoother rather than sharper. The most expensive row in the mod, so it is OFF by default and **FULL** leaves it alone |
 | the **DAYTIME** options row | SYNC / DAY / NIGHT / DUSK / DAWN / CYCLE — what time it is outdoors, on the diorama *and* on the flat 2D world; held at SYNC (and off the menu) while VOXEL is FULL |
 **3D-BTL** is on by default and is independent of **VOXEL**: battles draw
-on the world whether or not the free-roam camera is pitched over.
+on the world whether or not the free-roam camera is pitched over.
 Two of the engine's own rows are taken away while this mod is installed:
 **TILT**, which is the flat fake of what this mode does for real, and **GBC
 FX**, a full-screen present pass over the top of the diorama. Both are held at
 off rather than merely hidden — a row that is not there cannot switch off a
 value an older save arrived with. Uninstall and both come back, at whatever
 they were last set to.
 Everything the battle screen draws as a box — the two HUD blocks, the text
 box and the menus over it — sits on frosted glass rather than on the white
 field it used to have behind it: the world underneath, blurred and laid back
 down translucent, with the ink flipping white where the ground it lands on is
 dark. Nothing the engine draws inside a box moves; only the paper is gone.
@@ -41,8 +41,15 @@ return {
  -- ------- routes
  -- narrow, deliberately: the route's interior is a 3-cell-wide lane and the
  -- wide shape only fits in the western connection border, which staged every
-  -- fight at the edge of the world instead of on the road
+  -- fight at the edge of the world instead of on the road.
-  ["ROUTE_1"] = { x = 9, y = 16, shape = "narrow" },
+  --
  -- Of the seventeen spots the route has outside that border, fourteen are
  -- this one mid-route clearing and the other three bury the near mon behind
  -- a hedge -- which the clearance test passes, since it measures terrain
  -- height along the sightline and a hedge in the apron row is not terrain.
  -- So the choice is where in the clearing, and this is its west end: tree
  -- line square behind the pair, nothing crossing either of them.
  ["ROUTE_1"] = { x = 4, y = 14, shape = "narrow" },
  ["ROUTE_2"] = { x = 1, y = 49, shape = "wide" },
  ["ROUTE_3"] = { x = 57, y = 1, shape = "wide" },
  ["ROUTE_4"] = { x = 46, y = 7, shape = "wide" },
@@ -0,0 +1,244 @@
 -- Voxel world mode: anti-aliasing, by supersampling.
 --
 -- Everything else in this mod is flat art blitted at whole pixels; this one
 -- pass is real geometry seen through a perspective camera, and a polygon
 -- edge that lands at an angle across the pixel grid is the one place in the
 -- game where a hard stair-step is not a stylistic choice. A roof ridge, a
 -- ledge lip, a tree's silhouette against the sky and the leaning card of a
 -- character are all cut by an edge that has no reason to line up with
 -- anything, and at the shallow rungs -- where the diorama reads most like a
 -- photograph of a model -- they crawl as the camera drifts.
 --
 -- SUPERSAMPLING, not MSAA and not a filter over the finished frame, for two
 -- reasons that both come out of what the pass already is:
 --
 --   MSAA would take the water with it. The reflections read the frame's own
 --   DEPTH buffer as a texture (Voxel3D.beginWater), and a multisampled depth
 --   attachment is not a thing a fragment shader in this dialect can sample.
 --   The row would have quietly switched the other row off.
 --
 --   An edge filter (FXAA and its relatives) works from the finished colour
 --   alone, and would be GUESSING where the edges are out of one sample per
 --   pixel -- inventing detail it never rendered, and unable to tell a
 --   geometry edge from the boundary between two texels of a tileset.
 --
 -- Rendering the pass larger and folding it back down has neither problem:
 -- the depth buffer stays an ordinary texture, every pass in the frame keeps
 -- working in the canvas it was handed, and the fold is an average of samples
 -- that were each rendered honestly. It antialiases everything at once --
 -- geometry, the alpha-cut outline of a sprite card, the wireframe, the
 -- water's ray march -- because none of them know it is happening.
 --
 -- Be clear about what "everything" means: the artwork softens too. A tileset
 -- texel out here is not a screen pixel, it is a quad in a perspective view,
 -- and its boundary crosses the pixel grid at the same arbitrary angle a roof
 -- ridge does -- so the fold averages across it exactly as it averages across
 -- the ridge. That is what an honest extra sample says about that pixel, and
 -- it is also the trade the row IS: the diorama comes out smoother, not
 -- sharper. Which is why this is a row and not something that is simply on.
 --
 -- What it costs is pixels, which is the whole of why this is a row and not
 -- something that is simply on: 2X is half again as many in each direction,
 -- 4X is twice, and the scene pass is the most expensive thing in the frame.
 -- the mod namespace (see main.lua): V.require loads a sibling module
 local V = ...
 local ModSetting = V.require("ModSetting")
 local AntiAlias = {}
 -- the key under options.modOptions.DRAMATIC_SHAPE, shared by the row in
 -- OPTIONS and the mod manager's own settings page for this mod
 AntiAlias.KEY = "aa"
 AntiAlias.LABEL = "AA"
 -- The ladder is SAMPLES PER DISPLAY PIXEL, which is how an AA setting reads
 -- everywhere else, and the canvas scale each rung costs is its square root:
 -- 2 samples is a canvas 1.41x wider and taller, 4 is one exactly twice the
 -- size. OFF is the default -- this is a cost knob, and a mod should not
 -- quietly spend four times the fill rate of the machine it lands on.
 AntiAlias.setting = ModSetting.new(AntiAlias.KEY, AntiAlias.LABEL,
                                   { 0, 2, 4 }, { "OFF", "2X", "4X" })
 -- The scale the pass currently open was actually expanded by (see expand).
 -- 1 while there is no supersampling in force, which is also what every
 -- reader gets on a frame that never opened a pass at all.
 local live = 1
 function AntiAlias.samples()
  return tonumber(AntiAlias.setting:get()) or 0
 end
 -- What the row ASKS for. The scale in force is `factor()`, which is this
 -- clamped to what the driver will actually allocate.
 local function wanted()
  local n = AntiAlias.samples()
  if n <= 1 then return 1 end
  return math.sqrt(n)
 end
 -- The biggest canvas this driver admits to, or nil where it will not say.
 -- A 4K window at 4X asks for 7680 across, which is past the limit on plenty
 -- of hardware and every phone -- and a refused canvas is not a softer
 -- diorama, it is beginScene returning false and the whole mode falling back
 -- to the flat 2D path.
 local function textureLimit()
  if not (love.graphics and love.graphics.getSystemLimits) then return nil end
  local ok, limits = pcall(love.graphics.getSystemLimits)
  return (ok and limits and limits.texturesize) or nil
 end
 -- The size to render `w` x `h` display pixels at, and the size everything
 -- inside the pass then measures itself in.
 --
 -- Also where `live` is set, which is why this must be called once per pass
 -- immediately before beginScene: the wireframe's line width and the FX
 -- overlay's sprite scale are both quoted in DISPLAY pixels and have to be
 -- multiplied up into canvas ones, and the honest multiplier is the one this
 -- returned rather than the one the row asked for.
 function AntiAlias.expand(w, h)
  local s = wanted()
  local max = textureLimit()
  if max and max > 0 then
    -- clamped rather than abandoned: a window too big for 4X can usually
    -- still carry some of it, and half a rung of smoothing is worth more
    -- than a row that silently does nothing at that size
    s = math.min(s, max / math.max(1, w), max / math.max(1, h))
  end
  if not (s > 1.01) then
    live = 1
    return w, h
  end
  local ew, eh = math.floor(w * s + 0.5), math.floor(h * s + 0.5)
  live = ew / math.max(1, w)
  return ew, eh
 end
 -- The scale the open pass was expanded by; 1 when it was not.
 function AntiAlias.factor()
  return live
 end
 -- ------- the fold
 --
 -- One target per pass (the free-roam world and the battle's arena are alive
 -- at different moments but reallocating on every battle entry and exit is
 -- what the scene canvas's own slots exist to avoid), reallocated only when
 -- that pass's DISPLAY size changes -- a window resize, or the row itself
 -- moving, which changes the source and not this.
 local targets = {}
 local function targetFor(slot, w, h)
  local t = targets[slot]
  if not (t and t.w == w and t.h == h) then
    local ok, c = pcall(love.graphics.newCanvas, w, h)
    if not (ok and c) then return nil end
    -- nearest, like the canvas it stands in for: this one is composited a
    -- canvas pixel to a display pixel, and the smoothing has already happened
    pcall(c.setFilter, c, "nearest", "nearest")
    if t and t.canvas and t.canvas.release then pcall(t.canvas.release, t.canvas) end
    t = { canvas = c, w = w, h = h }
    targets[slot] = t
  end
  return t.canvas
 end
 -- The box filter, and the whole of why it is a shader rather than a scaled
 -- draw with linear filtering on.
 --
 -- The void this pass renders into is cleared to a TRANSPARENT BLACK, and at
 -- the rungs below FULL a good deal of the frame is still that. Averaging a
 -- straight-alpha edge against it drags the result toward black as well as
 -- toward transparent, and then the engine's own composite multiplies by that
 -- alpha a second time -- so every silhouette against the void would come out
 -- ringed with a dark fringe, which is exactly the artefact the row is here to
 -- remove.
 --
 -- So the taps are premultiplied before they are averaged and divided back out
 -- after, which is the arithmetic that makes an edge pixel mean "half covered
 -- by this colour" instead of "covered by half of this colour".
 --
 -- Four taps, half a source texel from the destination centre. At 4X those
 -- land dead on the four texel centres the destination pixel covers, so it is
 -- an exact 2x2 box; at 2X the source grid does not divide, and the bilinear
 -- fetch under each tap widens the box a little rather than missing samples.
 local SHADER = [[
  uniform vec2 tap;        // half a SOURCE texel, in uv
  vec4 effect(vec4 color, Image tex, vec2 tc, vec2 sc) {
    vec4 a = Texel(tex, tc + vec2(-tap.x, -tap.y));
    vec4 b = Texel(tex, tc + vec2( tap.x, -tap.y));
    vec4 c = Texel(tex, tc + vec2(-tap.x,  tap.y));
    vec4 d = Texel(tex, tc + vec2( tap.x,  tap.y));
    float al = (a.a + b.a + c.a + d.a) * 0.25;
    if (al <= 0.0) return vec4(0.0);
    vec3 sum = a.rgb * a.a + b.rgb * b.a + c.rgb * c.a + d.rgb * d.a;
    return vec4(sum * 0.25 / al, al) * color;
  }
 ]]
 local shader = nil            -- nil = untried, false = unavailable
 local function getShader()
  if shader == nil then
    local ok, sh = pcall(love.graphics.newShader, SHADER)
    shader = (ok and sh) or false
  end
  return shader or nil
 end
 -- Fold `canvas` down to `w` x `h` and hand back the result.
 --
 -- Returns the input untouched when there is nothing to fold -- the row is
 -- off, or the canvas already IS that size -- so a caller can run it
 -- unconditionally, and so can a headless test run. A target that would not
 -- allocate is the same answer: the pass is lost either way if this hands back
 -- something the wrong size, so it hands back the input and the frame draws at
 -- the size it was rendered.
 function AntiAlias.resolve(canvas, w, h, slot)
  if not canvas then return canvas end
  local ok, cw, ch = pcall(canvas.getDimensions, canvas)
  if not ok or (cw == w and ch == h) then return canvas end
  local target = targetFor(slot or "world", w, h)
  if not target then return canvas end
  local sh = getShader()
  local prevBlend, prevAlpha = love.graphics.getBlendMode()
  -- the scene canvas filters nearest for its usual 1:1 blit; the taps want
  -- linear, put back below so every other pass finds what it expects
  pcall(canvas.setFilter, canvas, "linear", "linear")
  love.graphics.setColor(1, 1, 1, 1)
  -- replace, not alpha-blend: this is an image-processing copy, and the alpha
  -- the shader worked out has to land as itself rather than be composited
  -- against whatever the target held
  love.graphics.setBlendMode("replace", "premultiplied")
  if sh then
    love.graphics.setShader(sh)
    pcall(sh.send, sh, "tap", { 0.5 / cw, 0.5 / ch })
  end
  local drew = pcall(function()
    love.graphics.setCanvas(target)
    love.graphics.clear(0, 0, 0, 0)
    love.graphics.draw(canvas, 0, 0, 0, w / cw, h / ch)
  end)
  love.graphics.setCanvas()
  love.graphics.setShader()
  love.graphics.setBlendMode(prevBlend or "alpha", prevAlpha)
  pcall(canvas.setFilter, canvas, "nearest", "nearest")
  return drew and target or canvas
 end
 -- Drop the GPU objects (window resize, hot reload).
 function AntiAlias.invalidate()
  for slot, t in pairs(targets) do
    if t.canvas and t.canvas.release then pcall(t.canvas.release, t.canvas) end
    targets[slot] = nil
  end
 end
 function AntiAlias.row()
  return AntiAlias.setting:row()
 end
 return AntiAlias
@@ -9,12 +9,76 @@
 -- of every eye, the highlight down a Pikachu's cheek: all of it turns into a
 -- hole with the world showing through, and the mon reads as a stencil.
 --
-- So the paper is put back, and only where the paper was: the pic is read
+-- So the paper is put back, and only where the paper was. Which pixels those
-- back once, the transparent region OUTSIDE the figure is flood-filled from
+-- are is the whole problem, and it has to be ANSWERED rather than looked up:
-- the border, and every transparent pixel the flood could not reach -- every
+-- the hardware drew the mon's white belly and the white field behind it with
-- hole enclosed by the artwork -- is filled opaque white. The silhouette is
+-- the same shade, the decoder keyed both to the same alpha, and nothing in the
-- untouched, so the mon still cuts cleanly against the world; only its
+-- image says which was which. There is no distinction to recover; there is one
-- insides stop being see-through.
+-- to draw.
 --
 -- The rule is a flood fill from OUTSIDE the figure: whatever the background
 -- can reach is background, and whatever it cannot is paper. What makes that
 -- work is where the flood is allowed to start.
 --
 -- Start it at the image border and it fills everything and answers nothing.
 -- Gen 1 figures are open drawings and a belly is not a sealed room: it walks
 -- out between two legs and off the bottom of the frame. Run over all 352 of
 -- this game's battle pics, that finds an enclosed hole in NONE of them -- so
 -- it left every mon a stencil, which is the bug this file exists to fix and
 -- for a long time did not.
 --
 -- So the flood is started at the edges of the artwork's own BOUNDING BOX, and
 -- the left, the right and the top are seeded whole. The sky between a pair of
 -- ears reaches the top edge and stays sky; the gap between a body and a raised
 -- tail reaches the side and stays gap.
 --
 -- The BOTTOM is the interesting one, because two completely different things
 -- meet the underside of a figure and they have to be told apart.
 --
 --   A DRAIN is where the drawing simply ran out -- a belly whose white carries
 --   on down until the artist stopped, leaking to the outside through the inch
 --   between a body and a leg. Seal it: what is above it is the mon.
 --
 --   A MOUTH is the space BETWEEN two legs, or under an arch. It is background
 --   that happens to be enclosed on three sides. Leave it open: the world
 --   should show through the gap in a trainer's stride.
 --
 -- What separates them is how WIDE the opening is, and on this game's art that
 -- is not a close call. Measured along the bottom of every battle pic: the
 -- drains run 3 and 4 pixels (Clefairy's back, Wartortle's back, Red's back)
 -- and the mouths run 10, 12, 14 and 17 (a Rattata's underbelly, Blue's stride,
 -- Brock's, a Pikachu's back). Nothing lands between 4 and 10, so the cut is
 -- taken at 6 with room either side rather than tuned to a single sprite.
 --
 -- Apart from that one number the rule is exact: no pixel is filled for what
 -- surrounds it, only because the background provably cannot get to it. And it
 -- needs no idea whether it is holding a front pic, a back one or a trainer --
 -- fronts are near-solid silhouettes with almost nothing inside them to fill,
 -- and they come back untouched because that is what their own shape says, not
 -- because they were special-cased.
 --
 -- The drain/mouth cut is for a pic STANDING ON THE MAP, where a mouth is a
 -- real hole with real ground behind it. A pic PINNED TO THE MENU has no such
 -- hole to be: under BACK SPRITES the player's mon is drawn in the GB's own
 -- slot with its feet flush on the text box (BattleState.backPlacement pins
 -- row 96), so the only thing under its lowest row is white box. Nothing can
 -- reach it from below, whatever the opening's width, and the caller says so
 -- by asking for a SEALED BOTTOM -- for which the rule stops being a heuristic
 -- and becomes exact: paper is whatever the background cannot walk to from the
 -- left, the right or the top.
 --
 -- That is the difference between a Pikachu that reads as a mon and one that
 -- reads as wireframe. The pale-bodied back pics -- Pikachu, Seel, Dewgong,
 -- Chansey, Jigglypuff -- are drawn as OUTLINES: everything inside the ink is
 -- shade 0 and every one of them is keyed away, so the figure is a rim with the
 -- arena showing through it. Each one also has a wide opening along its bottom,
 -- which the drain cut correctly reads as a mouth and the sealed bottom
 -- correctly does not. Twelve of this game's 151 back pics turn on it; the
 -- other 139 come back byte-identical either way, because they had nothing
 -- under them the flood was getting in through.
 --
 -- The silhouette is untouched, so the mon still cuts cleanly against the
 -- world; only its insides stop being see-through.
 --
 -- Read back off the GPU rather than off the asset, deliberately. What comes
 -- back is the pic the engine actually decided to draw -- species palette,
@@ -27,14 +91,23 @@ local V = ...
 local BattlePics = {}
-- Cached by the image the engine handed over. Weak keys, so a pic that goes
+-- Cached by the image the engine handed over, one table per bottom rule --
-- out of scope takes its filled twin with it rather than pinning a texture
+-- the same pic answers differently sealed and unsealed, and a single table
-- for the session.
+-- would hand the wrong twin back to whichever caller asked second. Weak keys,
-local cache = setmetatable({}, { __mode = "k" })
+-- so a pic that goes out of scope takes its filled twin with it rather than
 -- pinning a texture for the session.
 local function newCache()
  return {
    [false] = setmetatable({}, { __mode = "k" }),
    [true]  = setmetatable({}, { __mode = "k" }),
  }
 end
 local cache = newCache()
-- What an enclosed hole is filled with. White, because white is what the
+-- What an enclosed hole is filled with when the pic itself offers nothing
-- battle field was: this restores the pixel the artist drew and the engine
+-- better. White, because white is what the battle field was: this restores the
-- then keyed away, it does not invent a new one.
+-- pixel the artist drew and the engine then keyed away, it does not invent a
 -- new one.
 BattlePics.FILL = { 1, 1, 1, 1 }
 -- Anything at or under this alpha counts as keyed-out rather than drawn.
@@ -44,6 +117,21 @@ local CUT = 0.5
 -- its data back, so it is drawn into a canvas of its own size and the canvas
 -- is read -- which is also what makes this work for every path that produces
 -- a pic, without knowing which one produced this one.
 --
 -- The canvas is forced to dpiscale = 1, and that is the whole difference
 -- between a pic and a MONSTER. love.graphics.newCanvas defaults its dpiscale
 -- to the surface's, conf.lua turns highdpi on for Android and iOS, and
 -- Android's density is routinely 2.75 -- so newCanvas(56, 56) hands back a
 -- 154x154 texture there, the pic is drawn into it magnified to fill it, and
 -- newImageData reads the magnified copy back at its own PIXEL size. The image
 -- built from that is 2.75x the artwork, drawPicsLayer draws it at 1:1 because
 -- it trusts getWidth(), and the mon stands on the map nearly three times the
 -- size of the square it is supposed to cover. Desktop never saw it: dpiscale
 -- is already 1 there. Nor did every species, because only a pic with an
 -- enclosed hole in it comes back through here at all (see `changed` below) --
 -- so a Pidgey came out giant and the mon beside it did not, which is what
 -- makes this read as a sprite bug rather than a scale one. See the engine's
 -- own src/render/PixelCanvas.lua, which exists for exactly this reason.
 local function readBack(img)
  local w, h = img:getDimensions()
  if w <= 0 or h <= 0 then return nil end
@@ -52,7 +140,7 @@ local function readBack(img)
  local prevR, prevG, prevB, prevA = love.graphics.getColor()
  local data = nil
  local ok = pcall(function()
-    local canvas = love.graphics.newCanvas(w, h)
+    local canvas = love.graphics.newCanvas(w, h, { dpiscale = 1 })
    love.graphics.setCanvas(canvas)
    love.graphics.clear(0, 0, 0, 0)
    love.graphics.setBlendMode("replace", "premultiplied")
@@ -72,32 +160,120 @@ local function readBack(img)
  return ok and data or nil
 end
-- Mark every transparent pixel reachable from the border. That set is the
+-- The box the artwork actually occupies, or nil for a pic with no ink in it.
-- OUTSIDE; everything transparent it does not reach is an enclosed hole.
+--
 -- Not the image: a pic is centred in a 7x7-tile buffer and a small mon leaves
 -- whole rows and columns of nothing around itself. The bottom of THIS box is
 -- the cut the rule below turns on, and the bottom of the image is just empty
 -- frame some distance under it.
 local function inkBounds(data, w, h)
  local x0, y0, x1, y1 = w, h, -1, -1
  for y = 0, h - 1 do
    for x = 0, w - 1 do
      local _, _, _, a = data:getPixel(x, y)
      if a > CUT then
        if x < x0 then x0 = x end
        if x > x1 then x1 = x end
        if y < y0 then y0 = y end
        if y > y1 then y1 = y end
      end
    end
  end
  if x1 < x0 then return nil end
  return x0, y0, x1, y1
 end
 -- The colour the keyed-away shade would have had: the LIGHTEST colour still
 -- standing in the pic.
 --
 -- Pure white is only the right answer while the pic is still grays, and by the
 -- time it reaches here it usually is not. picImage hands a pic over AFTER the
 -- bake -- a species SGB colour, a BGP fade mid-animation, PAL_BLACK for the
 -- whole screen while the blackout text is up -- and shade 0 travels with the
 -- rest. A white belly inside a blacked-out mon would be the one lit thing on a
 -- dark screen; inside a warm-palette mon it would be a cold patch the artist
 -- never drew.
 --
 -- So the paper is read off the pic rather than assumed, which needs shade 0 to
 -- have survived somewhere in it. It always has: every one of this game's 151
 -- back pics keeps at least one opaque shade-0 pixel -- a highlight down a
 -- cheek, the white of an eye -- because only the shade-0 pixels the decoder
 -- could reach were keyed. So what comes back is the baked shade 0 itself, not
 -- an approximation of it, and it tracks every palette the engine picks without
 -- being told which one that was.
 --
 -- Ranked by channel sum, which orders four DMG shades exactly: a palette maps
 -- all three channels monotonically, so lightest by sum is lightest full stop.
 local function paperColor(data, x0, y0, x1, y1)
  local best, pr, pg, pb = -1, nil, nil, nil
  for y = y0, y1 do
    for x = x0, x1 do
      local r, g, b, a = data:getPixel(x, y)
      if a > CUT then
        local lum = r + g + b
        if lum > best then best, pr, pg, pb = lum, r, g, b end
      end
    end
  end
  if best < 0 then return nil end
  return pr, pg, pb
 end
 -- The widest opening along the bottom of a figure that still counts as a drain
 -- rather than a mouth. See the header for the measurements either side of it.
 BattlePics.DRAIN = 6
 -- Mark every transparent pixel the BACKGROUND can reach, flooding inward from
 -- the edges of the artwork's box: the left, the right and the top whole, and
 -- along the bottom only those openings wide enough to be background rather
 -- than the underside of a figure the drawing ran out of -- or none of them at
 -- all, for a pic whose feet are on the text box and which therefore has
 -- nothing behind its lowest row to let in.
 --
 -- Confined to the box as well as seeded from it, so the empty frame under a
 -- short pic cannot walk around a sealed drain and come back up through it.
 --
 -- An explicit stack rather than recursion: a 56x56 pic is three thousand
 -- pixels and a keyed-out background is most of them, which is a deeper call
 -- chain than is worth risking for no gain.
-local function markOutside(data, w, h)
+local function markOutside(data, w, h, x0, y0, x1, y1, sealBottom)
  local outside = {}
  local stack, top = {}, 0
  local function clear(x, y)
    local _, _, _, a = data:getPixel(x, y)
    return a <= CUT
  end
  local function push(x, y)
-    if x < 0 or y < 0 or x >= w or y >= h then return end
+    if x < x0 or y < y0 or x > x1 or y > y1 then return end
    local key = y * w + x
    if outside[key] then return end
-    local _, _, _, a = data:getPixel(x, y)
+    if not clear(x, y) then return end
    if a > CUT then return end
    outside[key] = true
    top = top + 1
    stack[top] = key
  end
-  for x = 0, w - 1 do
+  for x = x0, x1 do push(x, y0) end
-    push(x, 0)
+  for y = y0, y1 do
-    push(x, h - 1)
+    push(x0, y)
    push(x1, y)
  end
-  for y = 0, h - 1 do
+  -- the bottom, run by run: a wide one is the gap between two legs and lets
-    push(0, y)
+  -- the world through, a narrow one is where a belly ran out and is sealed.
-    push(w - 1, y)
+  -- Skipped whole for a pic on the box, where even the widest of them has
  -- white paper behind it rather than arena.
  if not sealBottom then
    local x = x0
    while x <= x1 do
      if clear(x, y1) then
        local from = x
        while x <= x1 and clear(x, y1) do x = x + 1 end
        if (x - from) > BattlePics.DRAIN then
          for k = from, x - 1 do push(k, y1) end
        end
      else
        x = x + 1
      end
    end
  end
  while top > 0 do
    local key = stack[top]
@@ -114,9 +290,15 @@ end
 -- The pic with its enclosed holes filled, or the pic itself when that could
 -- not be done (no pixel access, a driver that refused the readback). Never
 -- nil for a non-nil argument: a caller must always have something to draw.
-function BattlePics.filled(img)
+--
 -- sealBottom for a pic pinned to the text box rather than standing on the map:
 -- see the header. A caller that does not say defaults to the map, which is
 -- where all but one of this mod's pics are.
 function BattlePics.filled(img, sealBottom)
  if not img then return img end
-  local hit = cache[img]
+  sealBottom = sealBottom and true or false
  local slot = cache[sealBottom]
  local hit = slot[img]
  if hit ~= nil then return hit or img end
  local made = nil
@@ -124,16 +306,24 @@ function BattlePics.filled(img)
    local data = readBack(img)
    if not data then return end
    local w, h = data:getDimensions()
-    local outside = markOutside(data, w, h)
+    local x0, y0, x1, y1 = inkBounds(data, w, h)
    if not x0 then return end          -- a pic with nothing drawn in it
    local outside = markOutside(data, w, h, x0, y0, x1, y1, sealBottom)
    local fill = BattlePics.FILL
    local pr, pg, pb = paperColor(data, x0, y0, x1, y1)
    local fr = pr or fill[1]
    local fg = pg or fill[2]
    local fb = pb or fill[3]
    local changed = false
-    for y = 0, h - 1 do
+    -- only inside the box: everything beyond it is frame the artist never
    -- reached, and filling that would put the mon in a white rectangle
    for y = y0, y1 do
      local row = y * w
-      for x = 0, w - 1 do
+      for x = x0, x1 do
        if not outside[row + x] then
          local _, _, _, a = data:getPixel(x, y)
          if a <= CUT then
-            data:setPixel(x, y, fill[1], fill[2], fill[3], fill[4])
+            data:setPixel(x, y, fr, fg, fb, fill[4])
            changed = true
          end
        end
@@ -146,12 +336,12 @@ function BattlePics.filled(img)
    made = out
  end)
-  cache[img] = (ok and made) or false
+  slot[img] = (ok and made) or false
  return made or img
 end
 function BattlePics.invalidate()
-  cache = setmetatable({}, { __mode = "k" })
+  cache = newCache()
 end
 return BattlePics
@@ -42,6 +42,7 @@ local BattleCam = V.require("BattleCam")
 local BattleBillboard = V.require("BattleBillboard")
 local VoxelGrid = V.require("VoxelGrid")
 local DayNight = V.require("DayNight")
 local AntiAlias = V.require("AntiAlias")
 local PaletteFX = require("src.render.PaletteFX")
 local Map = require("src.world.Map")
@@ -141,9 +142,10 @@ local function prefetchArena(state, host)
  for _, nb in ipairs(state.neighbors or {}) do live[nb.map.id] = true end
  ChunkMesher.setLive(live)
  TerrainAtlas.setLive(live)
-  local terrain = ChunkMesher.request(host, false, nil, true)
+  ChunkMesher.request(host, false, nil, true)
-                  or ChunkMesher.peek(host, true)
+  local terrain, water = ChunkMesher.pair(host, false)
-  return terrain, {}
+  if not terrain then terrain, water = ChunkMesher.pair(host, true) end
  return terrain, {}, water, {}
 end
 -- ------- the sun
@@ -227,7 +229,8 @@ local function shadowSignature(state, arena, terrain, nbMesh, token)
 end
 local function castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh,
-                           atlasFor, cards, token, host, neighbors)
+                           atlasFor, cards, token, host, neighbors,
                           water, nbWater)
  if not ShadowMap.available() then return end
  local sig = shadowSignature(state, arena, terrain, nbMesh, token)
  if not ShadowMap.stale(sig) then return end
@@ -237,6 +240,14 @@ local function castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh,
  for i, nb in ipairs(neighbors) do
    ShadowMap.draw(nbMesh[i], atlasFor(nb.map), Mat4.translate(nb.ox, 0, nb.oy))
  end
  -- the water surface is its own reflective pass now (see Water) and so is
  -- no longer inside the terrain mesh; the sun still has to see it, or the
  -- light's map has a hole at every lake
  ShadowMap.draw(water, atlasFor(host), nil)
  for i, nb in ipairs(neighbors) do
    ShadowMap.draw(nbWater and nbWater[i], atlasFor(nb.map),
                   Mat4.translate(nb.ox, 0, nb.oy))
  end
  -- thin cards are snugged toward the sun (ShadowMap.snug) so their shadows
  -- keep contact with their bases instead of starting a bias-width away
  ShadowMap.draw(ChunkMesher.flowers(host), atlasFor(host),
@@ -249,10 +260,15 @@ local function castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh,
  -- the mons themselves, as the same cards the camera will see. Their alpha
  -- is the silhouette, so what lands on the ground is the shape of the
  -- Pokemon rather than a blob standing in for one.
  -- marked as the CAST, so a fight staged at the water's edge does not lay a
  -- cut-out of a Pokemon across the lake (see ShadowMap.sprites); the arena's
  -- own floor still takes them, which is the shadow that matters here
  ShadowMap.sprites(true)
  for _, card in ipairs(cards or {}) do
    ShadowMap.draw(BattleBillboard.mesh(), card.tex,
                   ShadowMap.snug(card.model))
  end
  ShadowMap.sprites(false)
  ShadowMap.finish(sig)
 end
@@ -299,9 +315,36 @@ end
 BattleScene.FLASH_COLOR = { 1, 1, 1 }
 BattleScene.FLASH_STRENGTH = 0.5
 -- ------- the tile clock, while the overworld is not the one drawing
 --
 -- Water and flowers animate off TileRenderer's 60Hz counter, and the ENGINE
 -- only advances it from OverworldState:drawWorld -- which runs under dialogs
 -- and menus, but not under a battle, because a battle draws instead of the
 -- overworld rather than over it. So for the length of a staged fight the
 -- counter stood still: the water tiles stopped rotating their pixels and the
 -- wave field, which is driven off the same number so the two cannot drift
 -- (see Water), stopped with them. A lake in the background of a battle was a
 -- photograph.
 --
 -- Ticked HERE rather than from the mod's update hook, because here is the
 -- one place that means "a staged battle is drawing this frame, and the
 -- overworld is not". From the update hook the condition would have to be
 -- guessed at, and a frame where both ran would double the rate.
 local function tickTiles()
  local Game = require("src.core.Game")
  local ow = Game and Game.overworld
  local top = Game and Game.stack and Game.stack:top()
  -- during the wipe INTO a battle the overworld can still be the one
  -- drawing, and it is ticking the clock itself; two ticks in a frame would
  -- run the water at double speed
  if top and ow and top == ow then return end
  pcall(require("src.render.TileRenderer").tick)
 end
 function BattleScene.render(state, arena, textures, token)
  if not (state and state.map and arena) then return nil end
  if not Voxel3D.available() then return nil end
  tickTiles()
  -- the floor the fight is staged on: normally the player's own, sometimes
  -- another floor of the same cave or building (see BattleArena)
@@ -326,7 +369,7 @@ function BattleScene.render(state, arena, textures, token)
  -- shares the free-roam mode's request/evict bookkeeping, so a battle warms
  -- exactly the meshes walking around would have and nothing extra
-  local terrain, nbMesh = prefetchArena(state, host)
+  local terrain, nbMesh, water, nbWater = prefetchArena(state, host)
  if not terrain then return nil end
  local lx, ly, s, pw, ph = BattleScene.letterbox()
@@ -356,7 +399,7 @@ function BattleScene.render(state, arena, textures, token)
  local cards = monCards(arena, groundY, textures)
  Voxel3D.camera = nil
  castShadows(state, arena, terrain, nbMesh, cx, cy, vw, vh, atlasFor,
-              cards, token, host, neighbors)
+              cards, token, host, neighbors, water, nbWater)
  -- An opaque void either way. Outdoors the camera is low enough that the
  -- horizon is genuinely in frame, so it is sky; indoors it is the dark end
@@ -385,7 +428,16 @@ function BattleScene.render(state, arena, textures, token)
    -- its own canvas slot: this renders at the window's pixel size and the
    -- free-roam pass does too, but the two are alive at different moments
    -- and a shared slot would reallocate on every battle entry and exit
-    if not Voxel3D.beginScene(pw, ph, cx, cy, vw, vh, sky, "battle") then
+    --
    -- AA, if the row asks for it, renders it larger still and folds it back
    -- to pw x ph below (see AntiAlias). The framing is untouched by that:
    -- the lens was widened by the window's RATIO to the letterbox and the
    -- rig solved in the GB's own frame, so a bigger canvas is more samples
    -- of the identical shot -- which is why the pins below still measure in
    -- pw and ph, and why the HUDs and the depth of field, drawn onto the
    -- folded canvas afterwards, stay the chunky GB art they are.
    local rw, rh = AntiAlias.expand(pw, ph)
    if not Voxel3D.beginScene(rw, rh, cx, cy, vw, vh, sky, "battle") then
      return
    end
    Voxel3D.draw(terrain, atlasFor(host), nil)
@@ -393,6 +445,22 @@ function BattleScene.render(state, arena, textures, token)
      Voxel3D.draw(nbMesh[i], atlasFor(nb.map),
                   Mat4.translate(nb.ox, 0, nb.oy))
    end
    -- and the water over it -- PLAIN, always: the flat animated tiles, never
    -- the reflective pass, whatever the WATER row says. The reflection is
    -- tuned for the overworld's ladder of cameras; this shot's is PLACED --
    -- low, tilted and framed like a picture -- and under it the pass reads
    -- wrong: Fresnel opens all the way up, the leaned sky lands on bands the
    -- framing never shows, and a lake-sized arena comes out as murk wearing
    -- the tile art. The battle is a stage set, and stage water is painted.
    -- (No mirror also means the mons need no second draw into one -- they
    -- just composite over the water below, like everything else on the set.)
    if water then Voxel3D.draw(water, atlasFor(host)) end
    for i, nb in ipairs(neighbors) do
      if nbWater and nbWater[i] then
        Voxel3D.draw(nbWater[i], atlasFor(nb.map),
                     Mat4.translate(nb.ox, 0, nb.oy))
      end
    end
    -- The mons, standing on their tiles. Depth-tested like everything else,
    -- so a ledge or a tree between the camera and a Pokemon really is in
    -- front of it, and the alpha discard cuts the sprite's own outline out of
@@ -442,7 +510,7 @@ function BattleScene.render(state, arena, textures, token)
                   Mat4.translate(nb.ox, 0, nb.oy), fpull,
                   ShadowMap.snug(Mat4.translate(nb.ox, 0, nb.oy)))
    end
-    local canvas = Voxel3D.endScene()
+    local canvas = AntiAlias.resolve(Voxel3D.endScene(), pw, ph, "battle")
    if not canvas then return end
    local vp = Voxel3D.vp
@@ -473,6 +541,11 @@ function BattleScene.render(state, arena, textures, token)
      -- the letterbox, so the depth-of-field pass can put its sharp band on
      -- the two marks rather than on a fraction of the window
      lx = lx, ly = ly, scale = s, pw = pw, ph = ph,
      -- and the hour's light, for anything drawn over this shot that is NOT
      -- geometry and so never went past the shader that applied it -- the back
      -- pic pinned to the menu (see OverworldBattle.backPinned). Neutral
      -- indoors, which is what DayNight.tint answers for a room.
      tint = Voxel3D.tint,
    }
  end)
  -- the placed camera is ours for exactly this pass; anything else that
@@ -68,6 +68,47 @@ local RECESS_MAX = 24
 local SHADE = { top = 0.95, south = 1.0, north = 0.68,
                side = 0.78, bottom = 0.5 }
 -- ------- how far a merged run may reach: the tile lattice
 --
 -- Merging is what keeps a 90k-voxel house down to ~2k quads, and under a
 -- straight projection a run may be as long as it likes -- a straight line
 -- is a straight line however finely it is cut. THE WORLD CURVE IS NOT
 -- STRAIGHT. It drops every vertex by the square of its distance from the
 -- focus (see WorldCurve), so a quad's interior is the CHORD of a parabola
 -- its neighbours draw the arc of: a run of length L hangs k*L^2/4 below
 -- the short quads butted against it, and the join tears open.
 --
 -- Nothing bounded a run's length before, and the runs that ran away were
 -- the ones wearing a CONSTANT texel -- the roof's black eave outline, its
 -- fascia, the shaded underside -- because a flat run has no art to break
 -- it. Those reached 102px across a gym, which at V-CURVE 3 hangs some
 -- three world pixels under the roof surface beside it: the eave tore off
 -- the roof and the drop showed the building's dark interior through the
 -- slot. (Strip runs, the drawing marching along the atlas, break at the
 -- tileset's own boundaries and were never the problem.)
 --
 -- So a run stops at the next 8px lattice line. Buildings are stamped at
 -- tx*8 (see stamp), so the model's lattice IS the map's: every quad in the
 -- scene -- terrain, props, this -- now ends on the same lines, every join
 -- is vertex-for-vertex, and the bend carries them together. What is left
 -- is the sag WITHIN one cell, k*64/4, which is under a twentieth of a
 -- world pixel at any rung.
 --
 -- It costs quads on a dense city map (Cerulean's object stream goes from
 -- 35.7k to 41.6k, and its longest edge from 102px to 8px) and it costs them
 -- whether the curve is on or not, which is the deliberate trade: the mesh
 -- is cached per map and built asynchronously over seconds, so meshing for
 -- the curve's sake only when the curve is on would mean rebuilding every
 -- live map on a keypress.
 local CELL = 8
 -- How far a run starting at `a` may go before it crosses the next lattice
 -- line. Floor-mod, so the awning's negative z lands on the same lines the
 -- positive side does.
 local function runCap(a)
  return CELL - a % CELL
 end
 local function keyOf(tx, ty)
  return (ty + 64) * 4096 + (tx + 64)
 end
@@ -170,6 +211,39 @@ local function read(t, data, perRow)
  local inside = {}
  for i = 0, W * H - 1 do inside[i] = not outside[i] end
  -- `scrub` names pixel rects where the drawing paints an object standing
  -- ON the surface (Red's potted plant on the dining tabletop). The object
  -- keeps its own standee -- the template's `keep` leaves its tiles
  -- unclaimed -- so the band beneath it is the one surface the drawing
  -- implies but never paints clear: every rect pixel takes the field
  -- shade, sourced from the first field texel outside the rects, and the
  -- model's top comes out as the plain surface the object sat on.
  if t.scrub then
    local function inRect(x, y)
      for _, r in ipairs(t.scrub) do
        if x >= r[1] and x <= r[3] and y >= r[2] and y <= r[4] then
          return true
        end
      end
      return false
    end
    local donor = nil
    for i = 0, W * H - 1 do
      if col[i] == GREY and inside[i]
         and not inRect(i % W, math.floor(i / W)) then
        donor = i
        break
      end
    end
    for i = 0, W * H - 1 do
      if inRect(i % W, math.floor(i / W)) then
        col[i] = GREY
        ax[i], ay[i] = ax[donor], ay[donor]
        inside[i] = true
      end
    end
  end
  return { W = W, H = H, col = col, ax = ax, ay = ay, inside = inside }
 end
@@ -190,7 +264,24 @@ local function measure(sp, t)
    top[x] = r
  end
-  local wallH = H - roofRows
+  -- The drawing's own ground line: the row after the last drawn one. A
  -- building ends on the black threshold row it stands on (ground == H),
  -- but furniture is drawn standing on open floor -- the lab table's
  -- legs stop two rows short of its grid -- and extruding against H
  -- would float it that far above its own plot.
  local ground = roofRows
  for sy = H - 1, roofRows, -1 do
    local drawn = false
    for sx = 0, W - 1 do
      if sp.inside[sy * W + sx] then drawn = true break end
    end
    if drawn then
      ground = sy + 1
      break
    end
  end
  local wallH = ground - roofRows
  local ytop = wallH - 1 + t.slab
  -- Side faces must not come out as slabs of outline black: where the
@@ -259,6 +350,14 @@ local function measure(sp, t)
    end
  end
  -- The pane rule reads a LIGHT region the drawing seals behind a BLACK
  -- frame. A drawing built the other way round -- the healing machine's
  -- dark screens sealed behind their own white bezels -- inverts under
  -- it: every lit edge sinks and the black panes stand proud, a black
  -- lattice a voxel off the face. `panes = false` says the drawing does
  -- not carry the rule's polarity, so the facade stays flush.
  if t.panes == false then recess = {} end
  -- One representative texel per shade, taken from the building's own art:
  -- the roof's fascia and its undersides are geometry the drawing implies
  -- but never paints, and they must still wear its palette (and pick up
@@ -279,20 +378,510 @@ local function measure(sp, t)
  -- sprite taller than its footprint -- the tower's 16-row drawing
  -- stands on the 8 rows of it that are actually on the map, and D = H
  -- would have pushed its body 64px south into the town plaza.
-  return { top = top, ytop = ytop, D = #t.tiles * 8,
+  -- `depth` (in tile rows) names the plot when the grid runs PAST it
  -- onto ground the drawing merely stands its legs on: the lab table's
  -- third row is the walkable cell the player faces it from, and the
  -- full-grid depth would stand the model in their path.
  -- `depth` names the plot in TILE ROWS, which is the right grain for a
  -- building. `depthPx` names it in voxels, for an object whose real
  -- depth is not a whole tile row -- the Bike Shop toolbox is a box
  -- standing in the middle of its own cell, not a thing that fills a plot.
  return { top = top, ytop = ytop,
           D = t.depthPx or ((t.depth or #t.tiles) * 8),
           ground = ground,
           recess = recess, interior = interior, shadeTexel = shadeTexel }
 end
 -- ----------------------------------------------------------------- build --
 -- A desk with separately-classified objects on it (a template's `parts`
 -- list): the methodology's region classification at part granularity.
 -- Upright parts anchor their drawn bottom row to the desk's top plane
 -- and wear their own drawn tops as lids; flat parts (a keyboard, a
 -- sheet of paper) lie one voxel proud at drawn row = depth row -- the
 -- same 1:1 the tabletop itself is drawn with, so an object's height ON
 -- the drawing is its position ON the desk. The desk is the lab-table
 -- slab + base; its lid is the one synthesized surface in the model
 -- (the objects cover every drawn pixel of the tabletop), continued
 -- from the sibling tables' pattern in the drawing's own shades.
 -- tools/building_voxels.py `build_desk_set` is the reference twin.
 local function deskSetModel(sp, pr, t)
  local W, H, D = sp.W, sp.H, pr.D
  local ground = pr.ground
  local col, inside = sp.col, sp.inside
  local vox = {}
  local function key(x, y, z) return (y * D + z) * W + x end
  local function put(x, y, z, i) vox[key(x, y, z)] = i end
  -- de-outline walk bounded to the part, so a part's side faces show
  -- its own material and never the neighbour's (the sprite-wide walk
  -- the facade path uses would cross the black seam between units)
  local function interiorAt(sx, sy, lo, hi)
    local i = sy * W + sx
    if col[i] ~= BLACK then return sx end
    local step = sx < math.floor((lo + hi) / 2) and 1 or -1
    for d = 1, 3 do
      local nx = sx + step * d
      if nx >= lo and nx <= hi then
        local ni = sy * W + nx
        if inside[ni] and col[ni] ~= BLACK then return nx end
      end
    end
    return sx
  end
  -- The parts list, shared by every base piece: a desk plane or an
  -- open tray rim alike, `plane` is simply the height they ride.
  local ytop = 0
  local function buildParts(plane)
    for _, p in ipairs(t.parts) do
      Budget.tick()
      local x0, x1 = p.x[1], p.x[2]
      if p.kind == "flat" then
        -- drawn row = depth row by default; `z` renames the origin when
        -- the flat sits below the desk's own drawn top span (the Center
        -- PC's keyboard). `at` names the sheet's own height when it does
        -- not lie on the desk plane (the healing machine's keyboard is a
        -- shelf mounted on the cabinet's side); `thick` gives it a body
        -- -- layers below the sheet repeating each column's own texel,
        -- the same continuation rule every synthesized surface follows.
        local r0 = p.rows[1]
        local z0 = p.z or r0
        local atY = p.at or plane
        local thick = p.thick or 1
        if atY > ytop then ytop = atY end
        for sy = r0, p.rows[2] do
          local z = z0 + (sy - r0)
          if z >= 0 and z < D then
            for sx = x0, x1 do
              if inside[sy * W + sx] then
                for y = math.max(0, atY - thick + 1), atY do
                  put(sx, y, z, sy * W + sx)
                end
              end
            end
          end
        end
      elseif p.kind == "box" then
        -- A BOX part is a drawn rect standing at its own drawn
        -- elevation -- equipment attached to the machine rather than an
        -- object on the desk plane. The rows are face-on art: the top
        -- row's drawn height IS the box's top (ground - 1 - r0,
        -- measured), and the box runs down to `base` (default the drawn
        -- extent; 0 continues it to the floor, the legs-continue rule).
        -- Height beyond the drawn rows fills the way a roof band does:
        -- rows before `cycle` map 1:1 from the top, rows after it 1:1
        -- from the bottom -- the healing machine hoses' foot lands ON
        -- the floor -- and the cycle window repeats between.
        local r0, r1 = p.rows[1], p.rows[2]
        local c0 = p.cycle and p.cycle[1] or r1
        local c1 = p.cycle and p.cycle[2] or r1
        local pz = p.z or 0
        local pd = p.depth
        local top = pr.ground - 1 - r0
        local bot = p.base or (pr.ground - 1 - r1)
        local nTop, nBot = c0 - r0, r1 - c1
        if top > ytop then ytop = top end
        for y = bot, top do
          local k, j = top - y, y - bot
          local sy
          if k < nTop then
            sy = r0 + k
          elseif j < nBot then
            sy = r1 - j
          else
            sy = c0 + (k - nTop) % (c1 - c0 + 1)
          end
          for sx = x0, x1 do
            local i = sy * W + sx
            if inside[i] then
              local ix = interiorAt(sx, sy, x0, x1)
              for z = pz, pz + pd - 1 do
                if z >= 0 and z < D then
                  local px = (z == pz or z == pz + pd - 1) and sx or ix
                  put(sx, y, z, sy * W + px)
                end
              end
            end
          end
        end
      elseif p.kind == "iso" then
        -- An ISO part is drawn in 2:1 isometric -- a box TURNED 45
        -- degrees to the map, so one rhombus carries its top, its front
        -- and its side at once and no band or facade split can reach
        -- them. Un-projecting it is that projection run backwards: the
        -- box stands as a real diamond in plan and every voxel wears the
        -- texel the drawing paints where that voxel projects TO. The
        -- drawn top lands on the top, the screen on the screen-facing
        -- side and the flank on the flank, and nothing is segmented by
        -- hand -- which is the only way to get this right, because the
        -- three faces meet on a diagonal no rectangle can name.
        --
        -- Everything but the depth centre falls out of the drawn rect,
        -- because the projection fixes it: the half-width is the drawn
        -- rhombus's x radius, HALF that again its z radius (2:1 is what
        -- makes it isometric), the near corner's drawn row is the base
        -- rhombus's front tip, and whatever drawn height is left once
        -- that rhombus is accounted for is the box's own height. Bill's
        -- computer: rx 6, rz 3, base centre row 10, and 6 voxels tall --
        -- which puts its left corner's vertical edge at drawn rows
        -- 4..10, exactly where the drawing paints one.
        --
        -- `plan` is the one thing the drawing CANNOT state: 2:1 is the
        -- projection, not the object, so reading rz as the plan radius
        -- too builds a box half as deep as it is wide -- a slab, not the
        -- cube the drawing depicts. `plan` names the real z radius and
        -- the drawn row is scaled into it, so a cube is `plan = rx` and
        -- the drawing still lands on it pixel for pixel.
        local pr0, pr1 = p.rows[1], p.rows[2]
        local rx = math.floor((x1 - x0 + 1) / 2)
        local rz = math.floor(rx / 2)
        local plan = p.plan or rz
        local oy = pr1 - rz
        local h = oy - rz - pr0
        local ytp = plane + h
        if ytp > ytop then ytop = ytp end
        for sx = x0, x1 do
          -- doubled, so a rect of even width keeps its centre between
          -- two columns instead of limping one to the left
          local dx2 = 2 * sx - (x0 + x1)
          for dz = -plan, plan do
            local z = p.z + dz
            local d2 = math.abs(dx2) * plan + 2 * math.abs(dz) * rx
            if z >= 0 and z < D and d2 <= (2 * rx + 1) * plan then
              -- the plan row scaled back into the drawn rhombus
              local dzs = math.floor((2 * dz * rz + plan) / (2 * plan))
              for y = 0, h do
                local sy = oy + dzs - y
                local i = sy * W + sx
                if sy >= pr0 and sy <= pr1 and inside[i] then
                  put(sx, plane + y, z, i)
                end
              end
            end
          end
        end
      else
        local tr0, tr1 = p.top[1], p.top[2]
        local fr0, fr1 = p.facade[1], p.facade[2]
        local pd = p.depth
        -- `rise` lifts a part off the desk's top plane and `z` names its
        -- back-most depth row (the field a flat part already carries). An
        -- object STANDING on a desk needs neither: it starts on the plane
        -- at the plot's back. The healing machine's console needs both --
        -- it stands in the FRONT map row of a grid whose back row is the
        -- wall band it leans against, and its screen head is MOUNTED on
        -- the console's front two voxels above the body's top. Both come
        -- off the drawing, not off taste.
        local base = plane + (p.rise or 0)
        local pz = p.z or 0
        local ytp = base + (fr1 - fr0)
        if ytp > ytop then ytop = ytp end
        -- `inset` sinks an authored pane one voxel: the pane rule
        -- applied by hand, for a part whose screen IS sealed behind its
        -- own black frame while the template's `panes = false` (set for
        -- the polarity-inverted panel elsewhere in the same drawing)
        -- blocks the global pass. Same mechanism as a recess: the front
        -- voxel is simply not placed.
        local ins = p.inset
        for sx = x0, x1 do
          -- the lid: the part's drawn top laid across its depth from the
          -- back, last row continuing forward; the front lid row is the
          -- facade's own top row -- the drawn front-top edge.  `stretch`
          -- maps the drawn band over the whole depth instead, the tray's
          -- rule: for a part authored DEEPER than its drawing (the house
          -- stool grown past its drawn seat), clamping would print the
          -- last row as a long smear off the back band's edge.
          for z = pz, pz + pd - 1 do
            local front = z == pz + pd - 1
            local sy
            if front then
              sy = fr0
            elseif p.stretch then
              sy = math.min(tr0 + math.floor((z - pz) * (tr1 - tr0 + 1)
                                             / (pd - 1)), tr1)
            else
              sy = math.min(tr0 + z - pz, tr1)
            end
            while sy <= tr1 and not inside[sy * W + sx] do sy = sy + 1 end
            local ok = sy <= tr1 or (front and inside[fr0 * W + sx])
            if ok and z >= 0 and z < D then
              put(sx, ytp, z, (front and fr0 or sy) * W + sx)
            end
          end
          -- the body: facade rows anchored to the part's own base
          for sy = fr0 + 1, fr1 do
            local y = base + (fr1 - sy)
            local i = sy * W + sx
            if inside[i] then
              local ix = interiorAt(sx, sy, x0, x1)
              for z = pz, pz + pd - 1 do
                if z >= 0 and z < D then
                  if z == pz + pd - 1 then
                    local sunk = ins and sx >= ins.x[1] and sx <= ins.x[2]
                                 and sy >= ins.rows[1] and sy <= ins.rows[2]
                    if not sunk and not pr.recess[i] then put(sx, y, z, i) end
                  elseif z == pz then
                    put(sx, y, z, i)
                  else
                    put(sx, y, z, sy * W + ix)
                  end
                end
              end
            end
          end
        end
      end
    end
  end
  -- A TRAY is an open container -- the drawing looks down INTO it, so its
  -- top-view band is not a lid but the inside of the box, and the model
  -- has to be hollow. Bands, all measured 1:1 like any other band table:
  -- `top` is the opening (drawn row -> depth row), `front` the near wall
  -- seen face-on (drawn row -> elevation), `x` the box's outer span and
  -- `inner` the opening's, so the difference between them is the wall.
  -- Four walls stand to the rim, the floor slab lies `floor` voxels thick
  -- under the opening, and the cavity between them is left as AIR -- which
  -- is the whole point, and what an extruded facade can never be. Parts (a
  -- standing lid) then ride the rim like any object on a desk's plane.
  if t.tray then
    local tr = t.tray
    local top0 = tr.top[1]
    local fr0, fr1 = tr.front[1], tr.front[2]
    local bx0, bx1 = tr.x[1], tr.x[2]
    local ix0, ix1 = tr.inner[1], tr.inner[2]
    local floor = tr.floor or 0
    local plane = fr1 - fr0 + 1            -- the rim: the wall's height
    -- Which drawn row lies at depth z. The far rim is the band's first
    -- row and the near rim the front wall's own, and the drawn inside
    -- STRETCHES over whatever depth is between them: a box deeper than
    -- its drawing has rows to spare is the ordinary case once the plot
    -- stops being the grid, and the alternative -- running out of rows
    -- and repeating the last one -- would print the wrench twice.
    local lo, hi = top0 + 1, tr.top[2] - 1     -- the drawn inside
    local span = math.max(1, D - 3)            -- interior depth rows - 1
    local function trayRow(z)
      if z == 0 then return top0 end
      if z == D - 1 then return fr0 end
      return lo + math.floor((z - 1) * (hi - lo) / span)
    end
    for sx = bx0, bx1 do
      Budget.tick()
      for z = 0, D - 1 do
        local hollow = sx >= ix0 and sx <= ix1 and z > 0 and z < D - 1
        for y = 0, (hollow and floor or plane - 1) do
          if hollow or y == plane - 1 then
            -- the opening seen from above: the tray's own floor and
            -- whatever lies in it -- and the rim is the same band where
            -- the wall meets it
            local i = trayRow(z) * W + sx
            if inside[i] then put(sx, y, z, i) end
          else
            -- the wall below the rim: the front band folded up it, the
            -- drawn face on the front and back layers and the de-outlined
            -- interior between, exactly as a facade extrudes.
            --
            -- NO recess pass here, and it must stay that way: a pane sinks
            -- by DELETING its front voxel so the one behind becomes the
            -- pane, and a container's wall is one voxel thick -- there is
            -- nothing behind it, so the front panel simply opened a hole
            -- straight into the box and you could see the wrench through it.
            local sy = fr1 - y
            local i = sy * W + sx
            if inside[i] then
              local px = (z == 0 or z == D - 1) and sx
                         or interiorAt(sx, sy, bx0, bx1)
              put(sx, y, z, sy * W + px)
            end
          end
        end
      end
    end
    if plane > ytop then ytop = plane end
    buildParts(plane)
    return { at = function(x, y, z)
               if x < 0 or x >= W or y < 0 or z < 0 or z >= D then
                 return nil
               end
               return vox[key(x, y, z)]
             end,
             W = W, ytop = ytop, zmin = 0, zmax = D - 1 }
  end
  -- No base piece at all: the drawing IS its parts (the house stool -- a
  -- seat and its legs, nothing under them but floor). The plane the parts
  -- anchor to is the ground itself.
  if not t.desk then
    buildParts(0)
    return { at = function(x, y, z)
               if x < 0 or x >= W or y < 0 or z < 0 or z >= D then
                 return nil
               end
               return vox[key(x, y, z)]
             end,
             W = W, ytop = ytop, zmin = 0, zmax = D - 1 }
  end
  -- The desk's top plane. Usually the drawing states it: the fascia and
  -- base rows it paints below the objects ARE the front face, and their
  -- row count is the height. Bill's desk paints neither inside its grid
  -- -- its apron is drawn into the WALKABLE cell in front, and that cell
  -- is left out on purpose so the chair standing there keeps its own
  -- tiles -- so `plane` names the height directly and the body below the
  -- lid is synthesized: the band table's own rim treatment, a shaded box
  -- closed by the outline where it meets the floor, in the drawing's
  -- shades via shadeTexel.
  local f0, f1 = t.desk.fascia[1], t.desk.fascia[2]
  local b0, b1 = t.desk.base[1], t.desk.base[2]
  local plane = (b1 - b0 + 1) + (f1 - f0 + 1)
  -- The desk's own PLOT, when the grid holds more than the desk. Bill's
  -- grid runs on into the walkable cell, because the drawing puts the
  -- desk's apron AND the chair pushed up to it in the same tiles -- so
  -- the desk box has to stop at its own cell (`depth`) and stand on its
  -- own ground line rather than the grid's, which the chair's feet set
  -- eight rows lower. The base band's last row IS that ground line by
  -- definition, and for every desk drawn inside its own grid it is the
  -- measured one to the row (lab table, lab computers, Center PC, the
  -- Bike Shop toolbox), so this changes nothing for them.
  -- ...and in voxels (`depthPx`) plus a back origin (`z`) when the desk
  -- is shallower than a tile row and leans against something: the
  -- healing machine's cabinet is 10 deep -- its drawn top band's 9 rows
  -- plus the front edge -- standing against the wall band, so its box
  -- runs z 16..25 of a 32-deep plot.
  local deskD = t.desk.depthPx or (t.desk.depth and t.desk.depth * 8) or D
  local dz0 = t.desk.z or 0
  local dz1 = dz0 + deskD - 1
  local deskG = b1 + 1
  -- ...and the desk's COLUMNS (`x`), when the grid is wider than the
  -- desk: the healing machine's grid carries its flanking hoses and
  -- keyboard, and the cabinet is only the middle 16 columns.
  local dx0 = t.desk.x and t.desk.x[1] or 0
  local dx1 = t.desk.x and t.desk.x[2] or W - 1
  -- The WALL element: the band the machine backs onto, whose tiles this
  -- grid claims. The drawing shows it only as the stripe background
  -- around the tower (the same standing as the potted plants' floor),
  -- so the block cycles the drawing's own stripe unit -- real pixels of
  -- column `x`, rows `cycle` -- at wall-band height over the back plot,
  -- exactly what the neighbouring cells' `wall` pins render.
  if t.wall then
    local wl = t.wall
    local c0, c1 = wl.cycle[1], wl.cycle[2]
    local cn = c1 - c0 + 1
    local wx = wl.x or 0
    for y = 0, wl.h - 1 do
      Budget.tick()
      local sy = c0 + (wl.h - 1 - y) % cn
      for sx = 0, W - 1 do
        for z = 0, wl.depthPx - 1 do
          put(sx, y, z, sy * W + wx)
        end
      end
    end
  end
  -- the base band, extruded exactly like every lab table's
  for sy = b0, b1 do
    Budget.tick()
    local y = deskG - 1 - sy
    for sx = dx0, dx1 do
      if inside[sy * W + sx] then
        local ix = interiorAt(sx, sy, dx0, dx1)
        for z = dz0, dz1 do
          local px = (z == dz0 or z == dz1) and sx or ix
          put(sx, y, z, sy * W + px)
        end
      end
    end
  end
  for i in pairs(pr.recess) do
    local sy = math.floor(i / W)
    local sx = i % W
    if sy >= b0 and sy <= b1 and sx >= dx0 and sx <= dx1 then
      vox[key(sx, deskG - 1 - sy, dz1)] = nil
    end
  end
  -- the slab: fascia rows wrap every side
  for sy = f0, f1 do
    Budget.tick()
    local y = plane - 1 - (sy - f0)
    for sx = dx0, dx1 do
      for z = dz0, dz1 do put(sx, y, z, sy * W + sx) end
    end
  end
  if t.desk.top then
    -- The lid wears the desk's own drawn top band -- the drawing DOES
    -- paint this tabletop (the healing machine's white top face with
    -- its lit west and shaded east strips), so nothing is synthesized
    -- where it is visible: band rows map back-to-front, the first
    -- fascia row is the drawn front-top edge, same rule as an upright
    -- part's lid. Where a part's drawing occludes the band (the monitor
    -- standing on it), the lid continues the nearest strip BESIDE the
    -- part -- still the drawing's own pixels, the same sibling-pattern
    -- rule every synthesized lid follows.
    local tr0, tr1 = t.desk.top[1], t.desk.top[2]
    for z = dz0, dz1 do
      Budget.tick()
      local sy = z == dz1 and f0 or math.min(tr0 + (z - dz0), tr1)
      for sx = dx0, dx1 do
        local px = sx
        for _, p in ipairs(t.parts) do
          local px0, px1 = p.x[1], p.x[2]
          local r0, r1
          if p.kind == "flat" or p.kind == "iso" or p.kind == "box" then
            r0, r1 = p.rows[1], p.rows[2]
          else
            r0, r1 = p.top[1], p.facade[2]
          end
          if sx >= px0 and sx <= px1 and sy >= r0 and sy <= r1 then
            px = (sx - px0 < px1 - sx) and (px0 - 1) or (px1 + 1)
            px = math.max(dx0, math.min(dx1, px))
            break
          end
        end
        put(sx, plane - 1, z, sy * W + px)
      end
    end
  else
    -- the lid continues the sibling tables' top -- black rim, white
    -- highlight courses along the north and west, grey field
    local field = t.desk.lid == "white" and WHITE or GREY
    for sx = dx0, dx1 do
      for z = dz0, dz1 do
        local shade = field
        if sx == dx0 or sx == dx1 or z == dz0 or z == dz1 then
          shade = BLACK
        elseif sx == dx0 + 1 or z == dz0 + 1 then
          shade = WHITE
        end
        put(sx, plane - 1, z, pr.shadeTexel[shade])
      end
    end
  end
  if plane > ytop then ytop = plane end
  buildParts(plane)
  return { at = function(x, y, z)
             if x < 0 or x >= W or y < 0 or z < 0 or z >= D then return nil end
             return vox[key(x, y, z)]
           end,
           W = W, ytop = ytop, zmin = 0, zmax = D - 1 }
 end
 -- The voxel model as a lookup: `at(x, y, z)` is the index of the sprite
 -- pixel that voxel wears, or nil. Build ORDER is expressed as lookup
 -- order -- roof first, so it overwrites the walls it intersects, and walls
 -- are trimmed to its underside so nothing pokes through the surface.
 local function model(sp, pr, t)
  if t.parts then return deskSetModel(sp, pr, t) end
  local W, H, D = sp.W, sp.H, pr.D
  local slab, roofRows = t.slab, t.roofRows
-  local top, ytop = pr.top, pr.ytop
+  local top, ytop, ground = pr.top, pr.ytop, pr.ground
  -- The roof's drawn span. A sprite inset from its box (B03) leaves outer
  -- columns undrawn in the roof band; they carry no roof at all, and the
@@ -367,16 +956,18 @@ local function model(sp, pr, t)
    -- the awning: the band juts two voxels past the walls, front and back
    if ledge0 and (z == -2 or z == -1 or z == D or z == D + 1) then
-      local sy = H - 1 - y
+      local sy = ground - 1 - y
      if sy >= ledge0 and sy <= ledge1 and sp.inside[sy * W + x] then
        return sy * W + x
      end
      return nil
    end
-    -- the facade, extruded straight back over the footprint
+    -- the facade, extruded straight back over the footprint. Rows map
    -- against the measured ground line, not the grid's last row: the two
    -- differ only for furniture standing on open floor (see measure).
    if z < 0 or z >= D then return nil end
-    local sy = H - 1 - y
+    local sy = ground - 1 - y
    local i = sy * W + x
    if y == 0 and not sp.inside[i] and sy > 0 and sp.inside[i - W] then
      -- the drawing's last row is the ground the building stands on, so
@@ -464,7 +1055,8 @@ local function emit(m, sp, atlasW, atlasH)
  local function runX(y, z, dx, dy, dz, x)
    local i0 = ci(x, y, z)
    local strip, n = nil, 1
-    while true do
+    local cap = runCap(x)
    while n < cap do
      local nx = x + n
      local i = ci(nx, y, z)
      if not i or ci(nx + dx, y + dy, z + dz) then break end
@@ -556,8 +1148,8 @@ local function emit(m, sp, atlasW, atlasH)
        while z <= zmax do
          local i = ci(x, y, z)
          if i and not ci(x + d, y, z) then
-            local n = 1
+            local n, cap = 1, runCap(z)
-            while z + n <= zmax do
+            while n < cap and z + n <= zmax do
              local j = ci(x, y, z + n)
              if j ~= i or ci(x + d, y, z + n) then break end
              n = n + 1
@@ -666,7 +1258,7 @@ function Buildings.build(S, map, data, perRow)
              end
              built = models[key]
            end
-            Buildings.stamp(S, map, built, tx, ty, bw, bh)
+            Buildings.stamp(S, map, built, tx, ty, bw, bh, t)
          end
        end
      end
@@ -676,9 +1268,24 @@ end
 -- One placement: claim its tiles (so the detector leaves them alone and
 -- the mesher paints ground under them) and copy the model into place.
-function Buildings.stamp(S, map, quads, tx, ty, bw, bh)
+--
-  local shape = { class = "building", h = 0, art = "building",
+-- Two template fields alter what a claim means, for a drawing that
-                  flat = false, authored = true }
+-- carries a STANDEE on its surface (Red's potted plant on the dining
 -- table). `keep` names tile ids the stamp must NOT claim: their authored
 -- pins stay live, so the standee scan still stands the object exactly as
 -- it always did. `support` is the model's top plane in voxels: the claim
 -- shape carries it as its height, which is what tells that scan the
 -- standee's shelf -- a plain claim stays at h = 0, and Structures treats
 -- a building claim with height as a full model (skip, never a second
 -- box; see its support branches).
 function Buildings.stamp(S, map, quads, tx, ty, bw, bh, t)
  local shape = { class = "building", h = (t and t.support) or 0,
                  art = "building", flat = false, authored = true }
  local keep = nil
  if t and t.keep then
    keep = {}
    for _, id in ipairs(t.keep) do keep[id] = true end
  end
  -- the ground the building stands on: the commonest flat tile around its
  -- feet, so a house on a path keeps its path
@@ -704,9 +1311,18 @@ function Buildings.stamp(S, map, quads, tx, ty, bw, bh)
  for r = 0, bh - 1 do
    for c = 0, bw - 1 do
      local k = keyOf(tx + c, ty + r)
-      S.shapeAt[k] = shape
+      if keep and keep[S.tileAt[k]] then
-      S.skip[k] = true
+        -- unclaimed by request: the tile keeps its pin (the plant's
-      S.ground[k] = best or false
+        -- cutout pool) and the standee scan finds it there. Only the
        -- ground is set now, so the scan's own claim of these tiles has
        -- the building's floor to paint when no flat tile touches a
        -- cluster ringed by its own furniture.
        S.ground[k] = best or false
      else
        S.shapeAt[k] = shape
        S.skip[k] = true
        S.ground[k] = best or false
      end
    end
  end
@@ -221,8 +221,18 @@ end
 -- Kept free of any GPU call so it can be exercised headless -- the
 -- geometry is the part with the interesting invariants, and a suite that
 -- needed a real GL context to check them would never run in CI.
-local function runGeometry(map, bodyOnly, masks, sink)
+-- `waterSink`, when given, takes the WATER SURFACE quads instead of the
 -- main sink -- the one class in this world that is drawn as its own pass
 -- (see Water: a mirror cannot be drawn until what it reflects exists).
 -- Nothing else moves: the quads are the same quads, emitted by the same
 -- corner and uv arithmetic at the same recessed height, and the shoreline
 -- faces around them still belong to the GROUND that exposes them.
 --
 -- Omitted, water stays in the terrain mesh exactly as it always did, which
 -- is what the headless geometry() below and the sun's own pass both want.
 local function runGeometry(map, bodyOnly, masks, sink, waterSink)
  local push = sink.push
  local waterPush = waterSink and waterSink.push or nil
  local tileset = map.tileset
  local S = Structures.forMap(map)
  local perRow = tileset.tilesPerRow or 16
@@ -358,12 +368,14 @@ local function runGeometry(map, bodyOnly, masks, sink)
    return aoSide
  end
-  local function topQuad(x0, z0, h, tile, shade)
+  -- `to` routes the quad somewhere other than the main sink -- the water
  -- surface is the only caller that ever does (see runGeometry's header).
  local function topQuad(x0, z0, h, tile, shade, to)
    local u0, u1, v0, v1 = uvRect(tile, 0, 8)
-    push({ { x0, h, z0 }, { x0 + 8, h, z0 },
+    ;(to or push)({ { x0, h, z0 }, { x0 + 8, h, z0 },
-           { x0 + 8, h, z0 + 8 }, { x0, h, z0 + 8 } },
+                    { x0 + 8, h, z0 + 8 }, { x0, h, z0 + 8 } },
-         { { u0, v0 }, { u1, v0 }, { u1, v1 }, { u0, v1 } },
+                  { { u0, v0 }, { u1, v0 }, { u1, v1 }, { u0, v1 } },
-         aoShades(x0 / 8, z0 / 8, h, shade))
+                  aoShades(x0 / 8, z0 / 8, h, shade))
  end
  -- vertical quad for face direction `d` of the tile column at (x0, z0),
@@ -558,8 +570,14 @@ local function runGeometry(map, bodyOnly, masks, sink)
            end
            topTile = S.tileAt[keyOf(tx, row)]
          end
          -- water's surface, and only water's: the recessed sheet itself,
          -- never the ground's shoreline bands around it. A cell an object
          -- stands on took the branch above and paints synthesized GROUND,
          -- which is right -- a sign at the waterline stands on a plot, not
          -- on the pond.
          topQuad(x0, z0, h, topTile,
-                  s.art == "upright" and VOLUME_TOP_SHADE or 1)
+                  s.art == "upright" and VOLUME_TOP_SHADE or 1,
                  (s.class == "water") and waterPush or nil)
        end
        -- sides: 8px bands wherever the neighbour is lower. Band k spans
@@ -764,18 +782,34 @@ end
 -- The raw geometry for `map`: (vertex list, triangle index list, quad
 -- count). Synchronous and GPU-free -- the headless suite and the probes
 -- exercise the invariants through this.
-function ChunkMesher.geometry(map, bodyOnly, masks)
+--
 -- `split` lifts the water surface out, as it is lifted out for the
 -- reflective pass, and appends that sink's own three values -- so the suite
 -- can check the same separation the GPU path relies on without a GPU.
 -- Without it the water is in the first list, which is what every existing
 -- caller reads.
 function ChunkMesher.geometry(map, bodyOnly, masks, split)
  local sink = newTableSink()
-  runGeometry(map, bodyOnly, masks, sink)
+  local waterSink = split and newTableSink() or nil
-  return sink.results()
+  runGeometry(map, bodyOnly, masks, sink, waterSink)
  if not waterSink then return sink.results() end
  local v, i, n = sink.results()
  local wv, wi, wn = waterSink.results()
  return v, i, n, wv, wi, wn
 end
 -- Build the mesh for `map` synchronously. Returns nil when there is
 -- nothing to draw or meshes are unavailable (headless).
-function ChunkMesher.build(map, bodyOnly, masks)
+--
 -- `split` asks for the water surface as a SECOND mesh, returned after the
 -- terrain one -- the shape the reflective pass needs (see Water). Without
 -- it the water is inside the terrain mesh, which is the historical
 -- contract and what every other caller still wants.
 function ChunkMesher.build(map, bodyOnly, masks, split)
  local sink = newSink()
-  runGeometry(map, bodyOnly, masks, sink)
+  local waterSink = split and newSink() or nil
-  return sink.finish()
+  runGeometry(map, bodyOnly, masks, sink, waterSink)
  return sink.finish(), waterSink and waterSink.finish() or nil
 end
 local function quadsMesh(quads)
@@ -819,14 +853,24 @@ end
 -- character card (VoxelScene). A figure baked into the terrain mesh could
 -- not lean, and a shared mesh could not carry per-figure placement.
 --
-- A list, not a mesh: `{ mesh, wx, wz, y }` per figure. Maps have one or
+-- A list, not a mesh: `{ mesh, wx, wz, y, w }` per figure. Maps have one
-- none, so the loop that draws them is shorter than the terrain's.
+-- or none, so the loop that draws them is shorter than the terrain's.
 -- `w` is the card's own width in its local space (its quads start at
 -- x = 0), measured here because the first-person pass yaws a card about
 -- its middle -- a card yawed about its left edge swings off its seat.
 local function buildFigureMeshes(map)
  local out = {}
  for _, f in ipairs(Structures.forMap(map).figures or {}) do
    local mesh = quadsMesh(f.quads)
    if mesh then
-      out[#out + 1] = { mesh = mesh, wx = f.wx, wz = f.wz, y = f.y }
+      local w = 0
      for _, q in ipairs(f.quads) do
        for c = 1, 4 do
          local x = q[c] and q[c][1]
          if x and x > w then w = x end
        end
      end
      out[#out + 1] = { mesh = mesh, wx = f.wx, wz = f.wz, y = f.y, w = w }
    end
  end
  return out
@@ -858,8 +902,17 @@ local function entry(id)
  return c
 end
 -- The water surface that came out of a terrain slot's own build. Kept
 -- beside it rather than in a slot of its own because the two are ONE
 -- answer: a full mesh drawn beside a body build's water would draw the
 -- ring's ponds twice and miss the body's own.
 local function waterSlot(slot)
  return slot .. "Water"
 end
 local function releaseEntry(c)
-  for _, slot in ipairs({ "full", "body", "grass", "flowers" }) do
+  for _, slot in ipairs({ "full", "body", "fullWater", "bodyWater",
                          "grass", "flowers" }) do
    local mesh = c[slot]
    if mesh and mesh.release then pcall(mesh.release, mesh) end
    c[slot] = nil
@@ -924,13 +977,17 @@ local function runJob(job)
    if c.stale then c.stale.aux = nil end
  end
  local sink = newSink()
-  runGeometry(map, job.slot == "body", job.masks, sink)
+  local waterSink = newSink()
  runGeometry(map, job.slot == "body", job.masks, sink, waterSink)
  local mesh = sink.finish()
  local water = waterSink.finish()
  if (gen[job.id] or 0) ~= job.gen then
    if mesh and mesh.release then pcall(mesh.release, mesh) end
    if water and water.release then pcall(water.release, water) end
    return
  end
  swapSlot(c, job.slot, mesh or false)
  swapSlot(c, waterSlot(job.slot), water or false)
  if c.stale then
    c.stale[job.slot] = nil
    if not (c.stale.full or c.stale.body or c.stale.aux) then
@@ -1032,12 +1089,14 @@ function ChunkMesher.get(map, bodyOnly, masks)
    if c.stale then c.stale.aux = nil end
  end
  if c[slot] == nil or (c.stale and c.stale[slot]) then
-    local ok, mesh = pcall(ChunkMesher.build, map, bodyOnly, masks)
+    local ok, mesh, water = pcall(ChunkMesher.build, map, bodyOnly, masks,
                                  true)
    if not ok then
      print("[warn] voxel mesh build failed for " .. tostring(map.id)
            .. ": " .. tostring(mesh))
    end
    swapSlot(c, slot, (ok and mesh) or false)
    swapSlot(c, waterSlot(slot), (ok and water) or false)
    if c.stale then
      c.stale[slot] = nil
      if not (c.stale.full or c.stale.body or c.stale.aux) then
@@ -1058,6 +1117,21 @@ function ChunkMesher.peek(map, bodyOnly)
  return mesh or nil
 end
 -- A slot's terrain mesh AND the water surface lifted out of it, as one
 -- answer. Never builds, like peek.
 --
 -- Both or neither, always from the SAME slot: the water was cut out of that
 -- exact geometry, so pairing a full mesh with a body build's water would
 -- draw the border ring's ponds twice and leave the body's as holes. Callers
 -- that fall back from one variant to the other fall back through this, so
 -- there is nowhere for the two to be chosen separately.
 function ChunkMesher.pair(map, bodyOnly)
  local c = cache[map.id]
  if not c then return nil, nil end
  local slot = bodyOnly and "body" or "full"
  return c[slot] or nil, c[waterSlot(slot)] or nil
 end
 function ChunkMesher.grass(map)
  local c = cache[map.id]
  return c and c.grass or nil
@@ -1068,8 +1142,8 @@ function ChunkMesher.flowers(map)
  return c and c.flowers or nil
 end
-- Authored figures as `{ mesh, wx, wz, y }` records -- each placed by its
+-- Authored figures as `{ mesh, wx, wz, y, w }` records -- each placed by
-- own leaning matrix at draw time, so they cannot share one mesh.
+-- its own leaning matrix at draw time, so they cannot share one mesh.
 function ChunkMesher.figures(map)
  local c = cache[map.id]
  local list = c and c.figures
@@ -0,0 +1,169 @@
 -- The hour's light on the FLAT world.
 --
 -- The clock already reaches everything the 3D pass draws: VoxelScene and
 -- BattleScene multiply the whole scene by DayNight.tint, so walking around a
 -- route at dusk warms the diorama and midnight turns it blue. Switch voxel
 -- mode off and none of that happens -- the tint is a uniform in a shader the
 -- flat tile path never runs -- so the same evening that fell on the diorama
 -- left the 2D world at permanent noon. One clock, two worlds, one of them
 -- ignoring it.
 --
 -- So the flat composite gets the same multiply, painted as one rectangle.
 --
 -- ------- WHERE, which is the only difficult part
 --
 -- Not on the world canvas. In a colorized mode that canvas is grayscale art
 -- and the blit that puts it on screen runs it through the palette shader,
 -- which classifies each pixel into a shade BY ITS RED CHANNEL. Multiply a
 -- night blue over it first and every shade lands in the wrong bucket -- the
 -- world would not darken, it would change colour into whatever the palette
 -- said the wrong bucket was.
 --
 -- So it goes on AFTER that pass, on the composited world. And not after the
 -- whole frame either: the UI blit is next, and the dialog boxes, the menus and
 -- the HUD are paper held up in front of the world rather than part of it --
 -- the same reason the tilt-shift blur is a worldPresent and not a present.
 --
 -- Which leaves one instant: between the world blit and the UI blit, inside
 -- Renderer:endFrame. There is no seam there -- worldPresent, the engine's own
 -- hook for exactly this, only runs when a PIPELINE produced the world, which
 -- in flat mode is the one thing that did not happen. So endFrame is wrapped
 -- and the UI canvas's own draw call is watched for: `blit` passes the canvas
 -- as the first argument, so the first draw of Renderer.canvas IS the boundary,
 -- by identity rather than by counting or guessing.
 --
 -- The shader and scissor that call arrives under belong to the UI blit already
 -- in progress, so both are put aside for the rectangle and handed straight
 -- back -- otherwise the tint would be palette-remapped and clipped to a zone.
 --
 -- ------- WHEN
 --
 -- Outdoors, on the flat path, when the hour is not neutral. Each of those is
 -- load-bearing:
 --
 --   the flat path   a pipeline that rendered the world already applied the
 --                   tint inside its own shader; painting it again would apply
 --                   the hour twice. worldOverride is exactly "a pipeline drew
 --                   this frame".
 --   outdoors        a room has no sky to take its light from, which is the
 --                   same answer DayNight.tint gives on its own and the same
 --                   one applyRig gives the sun.
 --   not neutral     midday is a multiply by white. Skipped rather than drawn,
 --                   so a game with the clock at DAY issues not one extra call.
 -- the mod namespace (see main.lua): V.require loads a sibling module
 local V = ...
 local DayNight = V.require("DayNight")
 local DayTint = {}
 -- Below this the tint is close enough to white that the rectangle would not
 -- change a pixel, and the frame is left exactly as it was.
 DayTint.NEUTRAL = 0.999
 local function outdoorNow()
  local ok, Game = pcall(require, "src.core.Game")
  if not ok then return false end
  local ow = Game and Game.overworld
  local map = ow and ow.map
  if not map then return false end
  local okMap, Map = pcall(require, "src.world.Map")
  if not okMap then return false end
  local outdoor = map.def and Map.isOutdoor(map.def) or false
  -- a canopy floor takes the hour's colour and nothing else of it, exactly as
  -- it does in the 3D pass (BattleScene, VoxelScene)
  return outdoor or DayNight.isCanopy(map)
 end
 -- The colour this frame's world should be multiplied by, or nil to leave the
 -- frame alone.
 function DayTint.forFrame(renderer)
  if not renderer then return nil end
  if renderer.worldOverride then return nil end   -- a pipeline drew, and tinted
  if not renderer.worldActive then return nil end -- no world on screen at all
  if not outdoorNow() then return nil end
  local tint = DayNight.tint(true)
  if not tint then return nil end
  local r, g, b = tint[1] or 1, tint[2] or 1, tint[3] or 1
  if r > DayTint.NEUTRAL and g > DayTint.NEUTRAL and b > DayTint.NEUTRAL then
    return nil
  end
  return r, g, b
 end
 -- One rectangle over the window, multiplied into whatever is under it.
 --
 -- The whole window rather than the world's own rect, which is what the
 -- engine's warp fade does from the same place and for the same reason: the
 -- border fill, the letterbox bars and the world are all "the world" as far as
 -- the hour is concerned, and black multiplied by anything is still black.
 -- Every read of the graphics state is optional, because a headless driver
 -- ships some of these and not others -- the same reason TerrainAtlas reads the
 -- engine's seams guarded. What cannot be read cannot be put back either, and a
 -- missing accessor must cost the tint rather than the frame.
 local function saved(name, ...)
  local fn = love.graphics[name]
  if not fn then return nil end
  local ok, a, b, c, d = pcall(fn, ...)
  if not ok then return nil end
  return a, b, c, d
 end
 function DayTint.paint(r, g, b)
  local gfx = love.graphics
  local shader = saved("getShader")
  local sx, sy, sw, sh = saved("getScissor")
  local blend, alpha = saved("getBlendMode")
  local pr, pg, pb, pa = saved("getColor")
  local w, h = gfx.getDimensions()
  if gfx.setShader then gfx.setShader() end
  if gfx.setScissor then gfx.setScissor() end
  gfx.setBlendMode("multiply", "premultiplied")
  gfx.setColor(r, g, b, 1)
  gfx.rectangle("fill", 0, 0, w, h)
  gfx.setBlendMode(blend or "alpha", alpha)
  gfx.setColor(pr or 1, pg or 1, pb or 1, pa or 1)
  if gfx.setScissor then
    if sx then gfx.setScissor(sx, sy, sw, sh) else gfx.setScissor() end
  end
  if shader and gfx.setShader then gfx.setShader(shader) end
 end
 function DayTint.install()
  local Renderer = require("src.render.Renderer")
  if Renderer.dramaticShapeTintHook then return end
  local inner = Renderer.endFrame
  function Renderer:endFrame(zones, worldZones)
    local r, g, b = DayTint.forFrame(self)
    if not r then return inner(self, zones, worldZones) end
    local gfx = love.graphics
    local draw = gfx.draw
    local ui = self.canvas
    local painted = false
    gfx.draw = function(tex, ...)
      -- the UI canvas reaching the screen: the world is finished, the paper
      -- in front of it has not started. Restored FIRST so the rectangle's own
      -- drawing cannot re-enter this, and so a UI blit that draws one quad per
      -- SGB zone only triggers it once.
      if not painted and tex == ui then
        painted = true
        gfx.draw = draw
        DayTint.paint(r, g, b)
      end
      return draw(tex, ...)
    end
    local ok, err = pcall(inner, self, zones, worldZones)
    gfx.draw = draw
    if not ok then error(err, 0) end
  end
  Renderer.dramaticShapeTintHook = true
 end
 return DayTint
@@ -0,0 +1,713 @@
 -- Voxel world mode: the first-person camera -- the 1ST rung.
 --
 -- Every other rung is the same camera at a different pitch: an orbit over
 -- the view centre, described by one number. 1ST is a different rig
 -- entirely: the eye stands in the player's own head, the view direction is
 -- the player's to steer -- mouse, right stick or a touch drag -- and the
 -- rig rides the placed-camera seam (Voxel3D.camera) that the staged battle
 -- already proved out. Everything downstream of that seam -- the shader
 -- uniforms, project(), the sky's vanishing line, the water's lean -- reads
 -- eye and focus the same way it always has.
 --
 -- What this module owns:
 --
 --   the ATTITUDE   yaw and pitch, fed by whichever look input speaks:
 --                  relative mouse motion, the right stick's rate, or a
 --                  touch dragged across open screen. All three drive the
 --                  same two numbers, so they compose instead of fighting.
 --
 --   the BLEND      easing between the orbit and the head. Stepping onto
 --                  the rung dives the camera from wherever the orbit was
 --                  into the player's eyes over half a second; stepping off
 --                  flies it back out. Mid-blend the rig is a straight lerp
 --                  of the two cameras -- eye, focus, fov, up -- through
 --                  the same placed-camera record.
 --
 --   the MOVE INTENT   the analog vector FreeMove walks the player by,
 --                  gathered here because it is made of the same devices:
 --                  the left stick's raw axes, the touch d-pad's true
 --                  deflection, or the held keys, rotated by this camera's
 --                  yaw so "forward" means "where I am looking".
 --
 -- Deliberately NOT here: movement itself (lib/FreeMove.lua, which owns the
 -- collision walk and the grid the game logic still lives on), and the
 -- billboard math that faces cards at this eye (VoxelScene, which owns
 -- every other card matrix too).
 --
 -- Everything the module reaches -- the mouse's relative mode, the wrapped
 -- love handlers, the touch overlay's hit test -- is pcall-guarded the same
 -- way the 3D pass is: headless runs and drivers without a mouse simply
 -- never see the input, and the rung falls back to holding the 75-degree
 -- orbit.
 -- the mod namespace (see main.lua): V.require loads a sibling module
 local V = ...
 local Mat4 = V.require("Mat4")
 local Voxel = V.require("VoxelState")
 local Voxel3D = V.require("Voxel3D")
 local WorldCurve = V.require("WorldCurve")
 local FirstPerson = {}
 -- ------- the rig's numbers
 --
 -- EYE_HEIGHT stands the eye near the top of the 16px sprite -- the head,
 -- not the hat tip -- above the same ground-plus-lift the character card
 -- stands on, so surfing bobs and ledge hops carry the view with them.
 --
 -- FOV is wider than the diorama's ~53 degrees: inside the world, the
 -- diorama's lens reads as a keyhole. 65 vertical is the modern-shooter
 -- middle ground.
 --
 -- FOCUS_DIST is short on purpose: the placed-camera branch derives its
 -- near plane from |eye - focus| (dist * 0.05), and the eye walks within
 -- 2-3 world pixels of a wall face when sliding along it -- a far focus
 -- would push the near plane through the wall and clip a hole in it.
 FirstPerson.EYE_HEIGHT = 13
 FirstPerson.FOV = math.rad(65)
 FirstPerson.FOCUS_DIST = 24
 -- Pitch limits, in radians below horizontal (positive looks DOWN). The
 -- world has no ceiling and the sky's bands sit low, so looking far up
 -- shows the void above the gradient; the up-range is clamped tighter than
 -- the down-range for that reason, not a technical one.
 FirstPerson.PITCH_DOWN = math.rad(70)
 FirstPerson.PITCH_UP = -math.rad(50)
 FirstPerson.PITCH_DEFAULT = math.rad(10)
 -- how long the dive into (and out of) the head takes, in seconds
 FirstPerson.BLEND_TIME = 0.45
 -- ------- look input tuning
 --
 -- MOUSE_SENS is radians per relative-mode count -- about 0.18 degrees per
 -- count, the conventional shooter default. STICK rates are radians per
 -- second at full deflection, with a squared response curve so small
 -- deflections aim and full ones turn. TOUCH_TURN is what one full screen
 -- width of drag turns, mobile-shooter convention.
 FirstPerson.MOUSE_SENS = 0.0032
 FirstPerson.STICK_YAW = 3.5
 FirstPerson.STICK_PITCH = 2.4
 FirstPerson.STICK_DEAD = 0.18
 FirstPerson.TOUCH_TURN = 2.2 * math.pi
 FirstPerson.MOVE_DEAD = 0.25
 -- ------- state
 --
 -- Yaw is a world bearing: 0 faces south (+Z, the way a resting sprite
 -- faces), pi/2 east -- the same convention VoxelScene.YAW uses, so a
 -- facing converts to a yaw by table lookup.
 FirstPerson.yaw = 0
 FirstPerson.pitch = FirstPerson.PITCH_DEFAULT
 FirstPerson.blend = 0
 local wasEngaged = false
 local stick = { x = 0, y = 0 }        -- right stick, latest event values
 local mouseDX, mouseDY = 0, 0         -- relative counts since last update
 local lookTouch = nil                 -- { id, x, y } of the claimed finger
 local touchMove = nil                 -- the touch d-pad's analog deflection
 local captured = false                -- mouse relative mode engaged by us
 -- the placed-camera record this module last handed to Voxel3D, so passes
 -- that key behaviour off "is the first-person rig the one drawing" (the
 -- billboard yaw, the frame remap) can ask by identity rather than by mode
 -- -- the battle's own placed camera must never read as first person
 local rig = nil
 local FACING_ANGLE = {
  down = 0,
  right = math.pi / 2,
  up = math.pi,
  left = -math.pi / 2,
 }
 local FACING_ORDER = { "down", "right", "up", "left" }
 local function wrapPi(a)
  return (a + math.pi) % (2 * math.pi) - math.pi
 end
 local function ease(t)
  return t * t * (3 - 2 * t)
 end
 -- ------- gates
 -- Whether the 1ST rung is selected and the 3D pass can carry it.
 function FirstPerson.engaged()
  return Voxel.isFirstPerson(Voxel.level) and Voxel3D.available()
 end
 -- Whether first person should be READING the player's inputs right now:
 -- engaged, with the overworld on top of the stack (a menu, a dialog or a
 -- battle above it owns the buttons, exactly as it does for grid walking).
 function FirstPerson.driving()
  if not FirstPerson.engaged() then return false end
  local ok, top, ow = pcall(function()
    local Game = require("src.core.Game")
    return Game.stack and Game.stack:top(), Game.overworld
  end)
  return ok and top ~= nil and top == ow
 end
 -- The eased blend, 0 at the orbit and 1 in the head.
 function FirstPerson.blendEased()
  return ease(FirstPerson.blend)
 end
 -- The blend, but only while the free-roam pass's own rig is the placed
 -- camera. The battle scene places a camera of its own through the same
 -- seam, and its cards must keep their stage lean rather than yawing at a
 -- first-person eye that is not looking at them.
 function FirstPerson.cardBlend()
  if not rig or Voxel3D.camera ~= rig then return 0 end
  return ease(FirstPerson.blend)
 end
 -- Whether the player's own card should be left out of the camera draw:
 -- deep enough into the blend that the card would fill the lens from
 -- inside. The sun pass keeps drawing it either way -- a first-person
 -- player still throws a shadow on the ground ahead.
 function FirstPerson.hidePlayer()
  return FirstPerson.cardBlend() > 0.9
 end
 -- ------- attitude
 -- Apply a look delta, in radians. Everything that turns the head funnels
 -- through here, so the clamps live once.
 function FirstPerson.lookBy(dyaw, dpitch)
  FirstPerson.yaw = wrapPi(FirstPerson.yaw + dyaw)
  FirstPerson.pitch = math.max(FirstPerson.PITCH_UP,
                       math.min(FirstPerson.PITCH_DOWN,
                                FirstPerson.pitch + dpitch))
 end
 -- The view direction's flat compass facing, for everything that still
 -- thinks in the grid's four directions: the cell A interacts with, the
 -- sprite the sun sees, the direction a blocked slide bonks in.
 function FirstPerson.compassFacing()
  local s, c = math.sin(FirstPerson.yaw), math.cos(FirstPerson.yaw)
  if math.abs(s) > math.abs(c) then
    return s > 0 and "right" or "left"
  end
  return c > 0 and "down" or "up"
 end
 -- The unit look direction, and its flat (ground-plane) part.
 local function lookDir()
  local cp = math.cos(FirstPerson.pitch)
  return math.sin(FirstPerson.yaw) * cp,
         -math.sin(FirstPerson.pitch),
         math.cos(FirstPerson.yaw) * cp
 end
 function FirstPerson.lookFlat()
  return math.sin(FirstPerson.yaw), math.cos(FirstPerson.yaw)
 end
 -- ------- billboards seen from inside the world
 --
 -- The diorama's cards face south and lean back by the camera's pitch --
 -- correct for a camera that always stands south. An eye that can stand
 -- ANYWHERE sees a south-facing card edge-on from the east, so in first
 -- person every card yaws about its feet to face the eye (cylindrical
 -- billboarding: upright, never tipping). VoxelScene blends its matrices
 -- between the two by cardBlend.
 -- The yaw that turns a card's south-facing normal toward the eye.
 function FirstPerson.cardYaw(wx, wz)
  local eye = rig and rig.eye
  if not eye then return 0 end
  local dx, dz = eye[1] - wx, eye[3] - wz
  if dx * dx + dz * dz < 1e-9 then return 0 end
  return math.atan2(dx, dz)
 end
 -- Which of the four sprite frames an entity shows THIS eye: its facing
 -- rotated into the viewer's own frame, quantised. The flat game's frames
 -- are "how this pose looks from the south", so the apparent facing is the
 -- pose rotated by where the viewer actually stands -- walk behind an NPC
 -- and you see their back, circle to their flank and you see the profile,
 -- exactly as the four frames Gen 1 drew intend.
 function FirstPerson.apparentFacing(facing, wx, wz)
  local eye = rig and rig.eye
  local phi = FACING_ANGLE[facing]
  if not (eye and phi) then return facing end
  local dx, dz = eye[1] - wx, eye[3] - wz
  if dx * dx + dz * dz < 1e-9 then return facing end
  local rel = wrapPi(phi - math.atan2(dx, dz))
  local idx = math.floor((rel + math.pi / 4) / (math.pi / 2)) % 4
  return FACING_ORDER[idx + 1]
 end
 -- ------- the move intent
 --
 -- The analog vector FreeMove walks by, in CAMERA space: mx strafes (+
 -- right), mz advances (+ forward). Whichever device is actually deflected
 -- answers -- the left stick's raw axes first (the engine quantises them to
 -- a d-pad; the raw pair is the analog truth), then a touch d-pad finger,
 -- then the held keys. Magnitude caps at 1.
 function FirstPerson.moveVector()
  local ok, Game = pcall(require, "src.core.Game")
  local input = ok and Game.input or nil
  local ax = input and input.stickAxis or nil
  if ax then
    local mag = math.sqrt(ax.x * ax.x + ax.y * ax.y)
    if mag > FirstPerson.MOVE_DEAD then
      local t = math.min(1, (mag - FirstPerson.MOVE_DEAD)
                            / (1 - FirstPerson.MOVE_DEAD))
      return ax.x / mag * t, -ax.y / mag * t
    end
  end
  if touchMove then
    local mag = math.sqrt(touchMove.x * touchMove.x
                          + touchMove.y * touchMove.y)
    if mag > FirstPerson.MOVE_DEAD then
      local t = math.min(1, mag)
      return touchMove.x / mag * t, -touchMove.y / mag * t
    end
  end
  if input then
    local mx = (input:isDown("right") and 1 or 0)
               - (input:isDown("left") and 1 or 0)
    local mz = (input:isDown("up") and 1 or 0)
               - (input:isDown("down") and 1 or 0)
    if mx ~= 0 or mz ~= 0 then
      local mag = math.sqrt(mx * mx + mz * mz)
      return mx / mag, mz / mag
    end
  end
  return 0, 0
 end
 -- Rotate a camera-space move into world space: forward is the flat look
 -- direction, strafe-right is its right hand. (cross(forward, up) with
 -- forward = (sin y, 0, cos y) and up = +Y lands right on (-cos y, 0,
 -- sin y): face south and your right hand points west.)
 function FirstPerson.moveWorld(mx, mz)
  local s, c = math.sin(FirstPerson.yaw), math.cos(FirstPerson.yaw)
  return -c * mx + s * mz, s * mx + c * mz
 end
 -- ------- the tick
 -- Runs from the pipeline's update hook, every frame whatever the level --
 -- the same tick VoxelState eases the orbit on. Owns the blend, the mouse
 -- capture lifecycle, and the frame's stick-rate look.
 function FirstPerson.update(dt)
  local engagedNow = FirstPerson.engaged()
  -- entering the rung: the head starts looking the way the sprite faces,
  -- pitched gently down -- the reading pose of the flat game
  if engagedNow and not wasEngaged then
    local ok, facing = pcall(function()
      local Game = require("src.core.Game")
      return Game.overworld and Game.overworld.player
             and Game.overworld.player.facing
    end)
    FirstPerson.yaw = (ok and FACING_ANGLE[facing]) or 0
    FirstPerson.pitch = FirstPerson.PITCH_DEFAULT
  end
  wasEngaged = engagedNow
  -- the blend, held at flat until there is terrain to dive into -- the
  -- same wait Voxel.update keeps for the orbit tween, for the same reason
  local target = engagedNow and 1 or 0
  if target > FirstPerson.blend and FirstPerson.blend == 0
     and not Voxel.ready then
    target = 0
  end
  local step = dt / FirstPerson.BLEND_TIME
  if FirstPerson.blend < target then
    FirstPerson.blend = math.min(target, FirstPerson.blend + step)
  elseif FirstPerson.blend > target then
    FirstPerson.blend = math.max(target, FirstPerson.blend - step)
  end
  if FirstPerson.blend <= 0 and rig then
    -- fully out: let go of the placed camera (unless a battle already
    -- swapped its own in, which is not ours to clear)
    if Voxel3D.camera == rig then Voxel3D.camera = nil end
    rig = nil
  end
  -- mouse capture follows engagement: captured whenever the rung is on and
  -- the window has focus, released the moment either ends. Checked against
  -- the live mode rather than toggled on edges, so a capture lost to the
  -- OS (alt-tab) re-arms itself on the next focused frame.
  local wantCapture = engagedNow
  if wantCapture and love.window and love.window.hasFocus then
    local okF, focus = pcall(love.window.hasFocus)
    wantCapture = okF and focus or false
  end
  if love.mouse and love.mouse.setRelativeMode then
    local okM, isRel = pcall(love.mouse.getRelativeMode)
    if okM and isRel ~= wantCapture then
      pcall(love.mouse.setRelativeMode, wantCapture)
    end
    captured = wantCapture
  end
  local driving = FirstPerson.driving()
  -- The mouse's counts, accumulated by the wrapped handler since the last
  -- tick; dropped unread while something else owns the screen.
  --
  -- The yaw sign is NEGATED, here and in every look input below: yaw grows
  -- south -> east -> north (the world runs +X east, +Z south, and the
  -- direction is (sin yaw, cos yaw)), which seen from behind the eye is a
  -- LEFT turn -- so "move the mouse right, look right" means subtracting.
  local dx, dy = mouseDX, mouseDY
  mouseDX, mouseDY = 0, 0
  if driving and (dx ~= 0 or dy ~= 0) then
    FirstPerson.lookBy(-dx * FirstPerson.MOUSE_SENS,
                       dy * FirstPerson.MOUSE_SENS)
  end
  -- the right stick is a rate: radians per second, squared response so
  -- the first half of the throw aims and the rest turns
  if driving then
    local rx, ry = stick.x, stick.y
    local function curve(v)
      local a = math.abs(v)
      if a < FirstPerson.STICK_DEAD then return 0 end
      a = (a - FirstPerson.STICK_DEAD) / (1 - FirstPerson.STICK_DEAD)
      return (v < 0 and -1 or 1) * a * a
    end
    local cy, cp = curve(rx), curve(ry)
    if cy ~= 0 or cp ~= 0 then
      -- negated yaw for the same reason as the mouse above
      FirstPerson.lookBy(-cy * FirstPerson.STICK_YAW * dt,
                         cp * FirstPerson.STICK_PITCH * dt)
    end
  end
 end
 -- ------- the rig itself
 -- The orbit camera's eye/focus/fov/up for the frame's centre -- the same
 -- arithmetic Voxel3D.viewProjection runs, restated here because the blend
 -- needs both ends as DATA. Kept textually tiny so the two cannot drift:
 -- focus on the centre, eye FOCAL*vh away at the pitch, up perpendicular
 -- in the YZ plane.
 local function orbitRig(cx, cy, vh)
  local a = Voxel.angle
  local dist = Voxel.FOCAL * vh
  return { cx, dist * math.cos(a), cy + dist * math.sin(a) },
         { cx, 0, cy },
         2 * math.atan(1 / (2 * Voxel.FOCAL)),
         { 0, math.sin(a), -math.cos(a) }
 end
 local lastEye = nil                   -- frozen head pose for player-less frames
 -- Build this frame's placed camera and hand it to Voxel3D, plus the scene
 -- centre the curve and the depth reference should use. `me` is the
 -- player's posed entry (px, py, gh, lift) or nil (a Fly animation), and
 -- (cx, cy) the orbit's own view centre.
 --
 -- Returns nil with the blend fully out, which is the caller's signal to
 -- leave the orbit in charge.
 function FirstPerson.frame(me, cx, cy, vw, vh)
  local b = FirstPerson.blend
  if b <= 0 then
    if rig and Voxel3D.camera == rig then Voxel3D.camera = nil end
    rig = nil
    return nil
  end
  local e = ease(b)
  local head
  if me then
    head = { me.px + 8,
             (me.gh or 0) + (me.lift or 0) + FirstPerson.EYE_HEIGHT,
             me.py + 8 }
    lastEye = head
  else
    head = lastEye or { cx, FirstPerson.EYE_HEIGHT, cy }
  end
  local lx, ly, lz = lookDir()
  local fpFocus = { head[1] + lx * FirstPerson.FOCUS_DIST,
                    head[2] + ly * FirstPerson.FOCUS_DIST,
                    head[3] + lz * FirstPerson.FOCUS_DIST }
  local oEye, oFocus, oFov, oUp = orbitRig(cx, cy, vh)
  local function mix(p, q)
    return { p[1] + (q[1] - p[1]) * e,
             p[2] + (q[2] - p[2]) * e,
             p[3] + (q[3] - p[3]) * e }
  end
  local up = mix(oUp, { 0, 1, 0 })
  local ul = math.sqrt(up[1] * up[1] + up[2] * up[2] + up[3] * up[3])
  if ul > 1e-6 then up[1], up[2], up[3] = up[1] / ul, up[2] / ul, up[3] / ul
  else up = { 0, 1, 0 } end
  -- the world curve eases out with the blend: standing inside the world,
  -- the bend that sells the diorama reads as the ground falling away. A
  -- true zero (curve declined) needs the field present -- nil would let
  -- Voxel3D fall back to the setting
  local k = WorldCurve.k(vh) * (1 - e)
  rig = {
    eye = mix(oEye, head),
    focus = mix(oFocus, fpFocus),
    fov = oFov + (FirstPerson.FOV - oFov) * e,
    up = up,
    curve = k,
  }
  Voxel3D.camera = rig
  -- the scene centre walks from the orbit's view centre to the head, so
  -- the curve's focus, the depth reference and the glint's travel follow
  -- the camera that is actually in charge
  local sx = cx + (head[1] - cx) * e
  local sy = cy + (head[3] - cy) * e
  return rig, sx, sy
 end
 -- Where the shadow pass should centre its box: pushed along the flat look
 -- so the fitted frustum -- built for an orbit that always looks north --
 -- covers the ground THIS camera sees. The push is strongest looking
 -- south (the direction the orbit's box barely reaches) and scales with
 -- the blend.
 function FirstPerson.shadowCenter(sx, sy, vh)
  local e = FirstPerson.cardBlend()
  if e <= 0 then return sx, sy end
  local fx, fz = FirstPerson.lookFlat()
  local ShadowMap = V.require("ShadowMap")
  local cap = (ShadowMap.FAR_CAP or 2.5) * vh
  return sx + fx * 0.6 * vh * e,
         sy + fz * (fz > 0 and (cap - vh * 0.5) or vh * 0.4) * e
 end
 -- The first-person facts a shadow signature has to include: the sun's
 -- box is fitted around this camera, so turning the head or walking the
 -- blend has to re-fit it even standing still.
 function FirstPerson.signature()
  local b = FirstPerson.blend
  if b <= 0 then return "" end
  return table.concat({
    math.floor(b * 64),
    math.floor(FirstPerson.yaw * 64),
    math.floor(FirstPerson.pitch * 64),
  }, ",")
 end
 -- ------- input capture
 --
 -- The seams: relative mouse motion has no Game handler at all (the
 -- engine's love.mousemoved only feeds the mouse-as-touch debug path), the
 -- right stick's axes are explicitly ignored by Input, and a touch
 -- anywhere off the overlay's controls dies in TouchControls. Each wrap
 -- forwards everything it does not claim, and claims only while first
 -- person is actually driving -- so with the rung off, every byte flows
 -- exactly where it always did.
 local installed = false
 function FirstPerson.install()
  if installed then return end
  installed = true
  local Game = require("src.core.Game")
  -- ------- right stick
  do
    local inner = Game.gamepadaxis
    function Game:gamepadaxis(joystick, axis, value)
      if axis == "rightx" then stick.x = value
      elseif axis == "righty" then stick.y = value end
      return inner(self, joystick, axis, value)
    end
  end
  -- generic (non-gamepad) sticks: axes 1/2 are the left stick by SDL
  -- convention and Input already claims them; 3/4 are the usual right
  -- pair on the same class of device. Real gamepads are excluded -- they
  -- already spoke through the mapped rightx/righty above, and their RAW
  -- axis 3 is as likely a trigger as a stick.
  --
  -- Two more exclusions, both learned the hard way on Android, where this
  -- wrap runs BEFORE the engine's own generic-joystick guards:
  --
  --   the accelerometer arrives as a joystick named for what it is, with
  --   gravity pinning an axis well past any deadzone -- the same device
  --   Game:joystickaxis refuses for movement (#459), refused here by the
  --   same name test, or the view spins on its own the moment 1ST opens.
  --
  --   and a raw axis is only BELIEVED after it has been seen near centre
  --   once. A stick at rest sits at zero, so a real one earns trust with
  --   its first touch; a gravity-pinned sensor axis or a trigger resting
  --   at an extreme never centres and so never steers the look.
  local function isAccelerometer(joystick)
    local ok, name = pcall(function() return joystick:getName() end)
    return ok and type(name) == "string"
           and name:lower():find("accelerometer", 1, true) ~= nil
  end
  local rawCentred = {}
  do
    local inner = Game.joystickaxis
    function Game:joystickaxis(joystick, axis, value)
      local mapped = joystick and joystick.isGamepad and joystick:isGamepad()
      if not mapped and (axis == 3 or axis == 4)
         and not isAccelerometer(joystick) then
        if math.abs(value) < 0.3 then rawCentred[axis] = true end
        if rawCentred[axis] then
          if axis == 3 then stick.x = value else stick.y = value end
        end
      end
      return inner(self, joystick, axis, value)
    end
  end
  -- ------- mouse
  --
  -- love.mousemoved rather than a Game method, because the engine has no
  -- Game:mousemoved to wrap -- the callback in the project's main.lua is
  -- the one place relative counts arrive. Claimed only while captured;
  -- pass-through otherwise, including the mouse-as-touch path.
  do
    local inner = love.mousemoved
    love.mousemoved = function(x, y, dx, dy, istouch)
      if captured and not istouch then
        mouseDX = mouseDX + (dx or 0)
        mouseDY = mouseDY + (dy or 0)
        return
      end
      if inner then return inner(x, y, dx, dy, istouch) end
    end
  end
  -- While the mouse is captured there is no cursor to click UI with, so
  -- the buttons become GB buttons: left is A, right is B -- through the
  -- overlay's own press path, which a rebind can never detach. What WE
  -- pressed is remembered per button, so the release always reaches the
  -- overlay even if the capture ended while the button was down --
  -- otherwise a click that outlives the rung strands A held forever.
  local mouseHeld = {}
  local MOUSE_BTN = { [1] = "a", [2] = "b" }
  do
    local inner = love.mousepressed
    love.mousepressed = function(x, y, button, istouch, presses)
      if captured and not istouch and MOUSE_BTN[button] then
        local Input = require("src.core.Input")
        mouseHeld[button] = true
        Input:overlayPressed(MOUSE_BTN[button])
        return
      end
      if inner then return inner(x, y, button, istouch, presses) end
    end
  end
  do
    local inner = love.mousereleased
    love.mousereleased = function(x, y, button, istouch, presses)
      if mouseHeld[button] then
        local Input = require("src.core.Input")
        mouseHeld[button] = nil
        Input:overlayReleased(MOUSE_BTN[button])
        return
      end
      if inner then return inner(x, y, button, istouch, presses) end
    end
  end
  -- ------- touch
  --
  -- A finger on open screen -- not on the overlay's d-pad or buttons --
  -- becomes the look drag. One finger owns the look at a time; every
  -- other touch flows to TouchControls untouched, so a thumb can drag the
  -- view while the other walks the d-pad. That d-pad finger is also read
  -- back ANALOG here: TouchControls quantises it to four directions for
  -- the grid game, but the deflection it quantised is exactly the move
  -- vector a free walk wants.
  local TouchControls = require("src.core.TouchControls")
  local function dpadVector(x, y)
    local ok, v = pcall(function()
      local L = TouchControls:layout()
      local dz = L.dpad
      local half = dz.w * 0.65
      return { x = math.max(-1, math.min(1, (x - dz.cx) / half)),
               y = math.max(-1, math.min(1, (y - dz.cy) / half)) }
    end)
    return ok and v or nil
  end
  do
    local inner = Game.touchpressed
    function Game:touchpressed(id, x, y)
      if FirstPerson.driving() then
        local onControl = nil
        pcall(function() onControl = TouchControls:hitTest(x, y) end)
        if not onControl and not lookTouch then
          lookTouch = { id = id, x = x, y = y }
          return
        end
        inner(self, id, x, y)
        if onControl == "dpad" and TouchControls.dpadTouch == id then
          touchMove = dpadVector(x, y)
        end
        return
      end
      return inner(self, id, x, y)
    end
  end
  do
    local inner = Game.touchmoved
    function Game:touchmoved(id, x, y)
      if lookTouch and lookTouch.id == id then
        local w = 1280
        pcall(function() w = love.graphics.getWidth() end)
        local per = FirstPerson.TOUCH_TURN / math.max(320, w)
        if FirstPerson.driving() then
          -- negated yaw for the same reason as the mouse (see update):
          -- drag right, look right, the mobile-shooter convention
          FirstPerson.lookBy(-(x - lookTouch.x) * per,
                             (y - lookTouch.y) * per)
        end
        lookTouch.x, lookTouch.y = x, y
        return
      end
      if touchMove and TouchControls.dpadTouch == id then
        touchMove = dpadVector(x, y) or touchMove
      end
      return inner(self, id, x, y)
    end
  end
  do
    local inner = Game.touchreleased
    function Game:touchreleased(id, x, y)
      if lookTouch and lookTouch.id == id then
        lookTouch = nil
        return
      end
      if TouchControls.dpadTouch == id then touchMove = nil end
      return inner(self, id, x, y)
    end
  end
  -- a reset that drops held input state drops ours with it
  do
    local inner = Game.focus
    function Game:focus(f)
      lookTouch, touchMove = nil, nil
      stick.x, stick.y = 0, 0
      mouseDX, mouseDY = 0, 0
      return inner(self, f)
    end
  end
  -- a disconnected controller cannot send the centering event for whatever
  -- its stick last held -- the engine drops all input state here, and the
  -- look rate (plus the raw axes' earned trust) goes with it
  do
    local inner = Game.joystickremoved
    function Game:joystickremoved(joystick)
      stick.x, stick.y = 0, 0
      rawCentred[3], rawCentred[4] = nil, nil
      return inner(self, joystick)
    end
  end
 end
 return FirstPerson
@@ -0,0 +1,345 @@
 -- Voxel world mode: free movement for the first-person rung.
 --
 -- The engine walks a grid: sixteen frames per cell, four directions,
 -- input locked mid-step. Inside a first-person camera that gait reads as
 -- riding a rail, so while 1ST drives, this module replaces the WALK and
 -- nothing else: the player's position becomes continuous, steered by the
 -- camera's own yaw -- push forward and you go where you look, at any
 -- angle, sliding along whatever you graze.
 --
 -- THE GRID IS STILL THE GAME. Every fact the world cares about is a fact
 -- about cells -- what blocks, what warps, what rustles, what bites -- and
 -- this module keeps the player's logical cell synced to wherever the free
 -- walk stands, then reuses the engine's own machinery for every one of
 -- those questions:
 --
 --   passability      the same isWalkableCell / water-while-surfing /
 --                    tile-pair / entity-occupancy verdicts Collision
 --                    hands the grid walker, asked per cell the player's
 --                    body overlaps.
 --
 --   cell arrival     OverworldState:onStepComplete, the same landing
 --                    pipeline a grid step runs -- warps, spinners, gates,
 --                    forced currents, poison, repel, encounters, the
 --                    step counters -- fired once per cell crossed, which
 --                    is exactly the rate a grid walk fires it.
 --
 --   the special pushes   walking off the map edge, into a ledge, or into
 --                    a boulder hands the quantised direction straight to
 --                    checkEdgeExit / checkLedgeHop / checkBoulderPush,
 --                    the engine's own handlers, which validate and stage
 --                    everything themselves (connections, the hop arc,
 --                    the two-push arm). While any of those animates a
 --                    scripted grid move, this module stands aside and
 --                    adopts the result.
 --
 -- Nothing here writes save state, rolls encounters, or decides what a
 -- warp does -- it moves a point, keeps the cell honest, and lets the
 -- engine be the engine. Stepping off the rung snaps the point to its
 -- cell and hands the walk back to the grid, and with the rung off this
 -- module costs one gate check per frame.
 -- the mod namespace (see main.lua): V.require loads a sibling module
 local V = ...
 local FirstPerson = V.require("FirstPerson")
 local FreeMove = {}
 -- The body: a circle in the ground plane. Small enough to walk every
 -- one-cell corridor the grid game has (half a cell is 8), big enough to
 -- keep the eye's near plane out of wall faces when sliding along them.
 FreeMove.RADIUS = 5.5
 -- World pixels per fixed 60Hz frame -- the grid walker's own speeds (16
 -- frames per 16px cell on foot, 8 on the bike), so distance covered per
 -- second is unchanged and the encounter rate per tile crossed stays the
 -- game's own.
 FreeMove.WALK = 1.0
 FreeMove.BIKE = 2.0
 local EPS = 0.01
 -- the free position (player centre, world px) and the px/py we last wrote
 -- -- if they differ from the player's, something else (a warp, a script)
 -- moved them, and the free walk adopts rather than fights
 local pos = nil
 local lastPx, lastPy = nil, nil
 local function adopt(p)
  pos = { x = p.px + 8, z = p.py + 8 }
  lastPx, lastPy = p.px, p.py
 end
 function FreeMove.drop()
  pos = nil
 end
 -- named for the suite: the module's live position, nil while dropped
 function FreeMove._pos()
  return pos
 end
 -- ------- the per-cell verdict
 --
 -- The same questions Collision.canMove asks for a grid step, asked of one
 -- cell from the player's current standing. The player's OWN cell never
 -- blocks -- the body must always be free to leave wherever it stands
 -- (a warp mat, the water it is surfing, a cell an NPC just stepped
 -- against).
 local function pairBlocked(map, surfing, sx, sy, tx, ty)
  local Game = require("src.core.Game")
  local tp = Game.data and Game.data.field and Game.data.field.tilePairs
  if not tp then return false end
  local list = surfing and tp.water or tp.land
  if not list or #list == 0 then return false end
  local tileset = map.def.tileset
  local a = map:cellTile(sx, sy)
  local b = map:cellTile(tx, ty)
  for _, p in ipairs(list) do
    if p.tileset == tileset
       and ((p.a == a and p.b == b) or (p.a == b and p.b == a)) then
      return true
    end
  end
  return false
 end
 -- Why (cx, cy) refuses the player's body, or nil when it may enter:
 -- "bounds" | "tile" | "entity", the grid verdict's own names.
 local function blockedCell(state, p, cx, cy)
  if cx == p.cellX and cy == p.cellY then return nil end
  local map = state.map
  if not map:inBounds(cx, cy) then return "bounds" end
  if not map:isWalkableCell(cx, cy) then
    if not (p.surfing and map:isWaterCell(cx, cy)) then return "tile" end
  end
  if pairBlocked(map, p.surfing, p.cellX, p.cellY, cx, cy) then
    return "tile"
  end
  local Collision = require("src.world.Collision")
  if Collision.occupied(state.entities, cx, cy, p) then return "entity" end
  return nil
 end
 FreeMove._blockedCell = blockedCell   -- named for the suite
 -- ------- the slide
 --
 -- One axis at a time, clamped at the first refusing cell's face: the
 -- classic axis-separated walk, which is where wall-sliding comes from --
 -- the blocked axis stops and the free one keeps going. Returns the
 -- refusal ("bounds"/"tile"/"entity") when this axis was clamped.
 local function slideX(state, p, dx)
  if dx == 0 then return nil end
  local r = FreeMove.RADIUS
  local nx = pos.x + dx
  local z0 = math.floor((pos.z - r + EPS) / 16)
  local z1 = math.floor((pos.z + r - EPS) / 16)
  local hit = nil
  local edge = dx > 0 and math.floor((nx + r) / 16)
               or math.floor((nx - r) / 16)
  for zc = z0, z1 do
    hit = blockedCell(state, p, edge, zc)
    if hit then break end
  end
  if hit then
    if dx > 0 then nx = math.min(nx, edge * 16 - r - EPS)
    else nx = math.max(nx, (edge + 1) * 16 + r + EPS) end
  end
  pos.x = nx
  return hit
 end
 local function slideZ(state, p, dz)
  if dz == 0 then return nil end
  local r = FreeMove.RADIUS
  local nz = pos.z + dz
  local x0 = math.floor((pos.x - r + EPS) / 16)
  local x1 = math.floor((pos.x + r - EPS) / 16)
  local hit = nil
  local edge = dz > 0 and math.floor((nz + r) / 16)
               or math.floor((nz - r) / 16)
  for xc = x0, x1 do
    hit = blockedCell(state, p, xc, edge)
    if hit then break end
  end
  if hit then
    if dz > 0 then nz = math.min(nz, edge * 16 - r - EPS)
    else nz = math.max(nz, (edge + 1) * 16 + r + EPS) end
  end
  pos.z = nz
  return hit
 end
 -- ------- the blocked push
 --
 -- The grid game's blocked step is where half its verbs live: the map-edge
 -- crossing, the ledge hop, the boulder shove, the route-gate warp fired
 -- by collision, and the honest bonk. Hand the engine the quantised
 -- direction and let its own handlers decide -- each one validates itself
 -- (checkLedgeHop matches the tile pair, checkEdgeExit checks the bounds),
 -- so calling them on every firm push is safe. Returns true when one of
 -- them took the frame over.
 local function pushSpecials(state, dir, why)
  local p = state.player
  p.facing = dir      -- the handlers read the push off the facing
  if why == "bounds" and state:checkEdgeExit(dir) then return true end
  if state:checkLedgeHop(dir) then return true end
  if state:checkBoulderPush(dir) then return true end
  if why ~= "entity" and state:canCollisionWarp() then
    local Game = require("src.core.Game")
    local Warp = require("src.world.Warp")
    local w = Warp.onCollision(state.map, Game.data.field.warpCarpets,
                               p.cellX, p.cellY, dir)
    if w then
      state:takeWarp(w.def)
      return true
    end
  end
  if why ~= "entity" then
    if (state.bumpCooldown or 0) <= 0 then
      local Game = require("src.core.Game")
      require("src.core.Sound").play(Game.data, "Collision")
      state.bumpCooldown = 16
    end
  end
  return false
 end
 -- ------- the tick
 --
 -- Runs in place of OverworldState:handleInput while first person drives
 -- (see install below), which means it inherits every gate the grid walk
 -- has: never during scripted moves, transitions, or with anything above
 -- the overworld on the stack.
 function FreeMove.tick(state)
  local p = state.player
  -- a grid move is animating -- a ledge hop, a spinner slide, a scripted
  -- walk -- or a cutscene owns the player: stand aside, adopt the result
  if p.moving or p.inputLocked then
    FreeMove.drop()
    return
  end
  if not pos or p.px ~= lastPx or p.py ~= lastPy then adopt(p) end
  local Game = require("src.core.Game")
  local input = Game.input
  -- the head is the facing: what A talks to, what the sun's card shows,
  -- which way a bonk points
  p.facing = FirstPerson.compassFacing()
  if input:wasPressed("a") then
    state:interact()
    return
  end
  if input:wasPressed("start") then
    require("src.core.Sound").play(Game.data, "Start_Menu")
    require("src.ui.Screens").push(Game, "StartMenu")
    return
  end
  local mx, mz = FirstPerson.moveVector()
  local wx, wz = FirstPerson.moveWorld(mx, mz)
  -- Cycling Road's downhill pull, the free-walk restatement of the grid
  -- path's simulated PAD_DOWN: south drift with nothing held, braked by
  -- holding A or B exactly as the Route 17 sign promises
  local moving = (mx ~= 0 or mz ~= 0)
  if not moving and Game.save and Game.save.onBike then
    local fm = Game.data.field.forcedMovement
    local braking = input:isDown("a") or input:isDown("b")
    if fm and not braking then
      for _, m in ipairs(fm.slopeMaps or {}) do
        if m == state.map.id then
          wx, wz, moving = 0, 1, true
          break
        end
      end
    end
  end
  if not moving then return end
  state.bumpCooldown = math.max(0, (state.bumpCooldown or 0) - 1)
  local speed = (Game.save and Game.save.onBike) and FreeMove.BIKE
                or FreeMove.WALK
  local dx, dz = wx * speed, wz * speed
  local hitX = slideX(state, p, dx)
  local hitZ = slideZ(state, p, dz)
  -- the walk cycle: the wall-bonk clock animates the legs of a player the
  -- grid thinks is standing still, refreshed while the free walk covers
  -- ground (Player:update ticks animClock off it; walkPhase reads it)
  p.bumpFrames = 2
  p.px, p.py = pos.x - 8, pos.z - 8
  lastPx, lastPy = p.px, p.py
  -- the cell the body stands in; crossing into a new one IS a step
  local ncx = math.floor(pos.x / 16)
  local ncy = math.floor(pos.z / 16)
  if ncx ~= p.cellX or ncy ~= p.cellY then
    p.cellX, p.cellY = ncx, ncy
    state:onStepComplete()
    -- a warp or a battle may have moved the world out from under the
    -- walk; the adopt check on the next tick picks the pieces up
    return
  end
  -- a firm push into something that refused: the engine's own blocked-step
  -- verbs, aimed the way the push leans
  local hit, dir
  if hitX and (not hitZ or math.abs(dx) >= math.abs(dz)) then
    hit, dir = hitX, (dx > 0 and "right" or "left")
  elseif hitZ then
    hit, dir = hitZ, (dz > 0 and "down" or "up")
  end
  if hit and math.max(math.abs(dx), math.abs(dz)) > 0.4 * speed then
    if pushSpecials(state, dir, hit) then
      FreeMove.drop()
      return
    end
    -- the push handlers may have turned the facing; the head still rules
    p.facing = FirstPerson.compassFacing()
  end
 end
 -- ------- the seam
 --
 -- OverworldState:handleInput is the one choke point where the grid walk
 -- reads the pad -- the same seam the engine's own Cycling Road pull and
 -- collision warps live behind -- so replacing the walk means wrapping it
 -- and nothing else. Every gate ABOVE the call (scripted moves, trainer
 -- engagement, transitions, anything on the stack) still applies to the
 -- free walk, because the wrap sits below them all.
 function FreeMove.install()
  local OverworldState = require("src.world.OverworldController")
  if OverworldState.dramaticShapeFreeMoveHook then return end
  local inner = OverworldState.handleInput
  function OverworldState:handleInput()
    if not FirstPerson.driving() then
      if pos then
        -- stepping off the rung: back onto the grid, on the cell the
        -- free walk stood in
        local p = self.player
        p.px, p.py = p.cellX * 16, p.cellY * 16
        FreeMove.drop()
      end
      return inner(self)
    end
    return FreeMove.tick(self)
  end
  OverworldState.dramaticShapeFreeMoveHook = true
 end
 return FreeMove
@@ -0,0 +1,65 @@
 -- Voxel world mode: decoded pixels, kept.
 --
 -- Assets.imageData is deliberately uncached upstream -- "pixel-level reads
 -- resolve the same way but stay uncached: the caller keeps the derived
 -- product" (src/render/Assets.lua) -- which is the right contract for the
 -- flat renderer, whose one caller decodes a strip once and keeps the strip.
 --
 -- This mod is not that caller. It reads the same handful of images over and
 -- over, from several places that do not know about each other:
 --
 --   * the tileset atlas, decoded by Structures (its own cache), by
 --     TerrainAtlas twice (the SGB bake and the RED++ rebake), by
 --     TerrainAtlas again to learn a tile's shades, and by GlassMask;
 --   * the FLOWER FRAME files, decoded inside patch() -- which runs every
 --     time the animation step turns over, about three times a second, for
 --     as long as the map is on screen. That one is not a load cost at all,
 --     it is a recurring per-second cost on the render thread, and it was
 --     the single clearest waste the first profile turned up.
 --
 -- So: one table, keyed by the path as the CALLER gave it, holding the
 -- decoded ImageData. Registered with Assets.invalidate so a hot reload
 -- drops it alongside every other downstream cache.
 --
 -- The entries are never evicted by size. That is deliberate and bounded:
 -- what lands here is tileset art and animation frames -- a few dozen small
 -- images for a whole session, tens of kilobytes each -- not per-map bakes,
 -- which have their own eviction in TerrainAtlas.setLive.
 -- the mod namespace (see main.lua): V.require loads a sibling module
 local V = ...
 local Assets = require("src.render.Assets")
 local Perf = V.require("Perf")
 local ImageCache = {}
 local cache = {}
 -- The decoded pixels for `path`, or nil when it cannot be read.
 --
 -- `false` is cached for an unreadable path, so a missing or corrupt asset
 -- costs one failed decode for the session rather than one per frame -- the
 -- same sticky-failure shape the rest of this mod uses for GPU objects.
 function ImageCache.get(path)
  if not path then return nil end
  local hit = cache[path]
  if hit ~= nil then
    Perf.count("imageCache.hit")
    return hit or nil
  end
  local t0 = Perf.now()
  local ok, data = pcall(Assets.imageData, path)
  Perf.add("ImageCache.decode", t0)
  Perf.count("imageCache.miss")
  cache[path] = (ok and data) or false
  return cache[path] or nil
 end
 function ImageCache.invalidate()
  cache = {}
 end
 Assets.register(ImageCache.invalidate)
 return ImageCache
@@ -72,6 +72,63 @@ function OverworldBattle.enabled()
  return OverworldBattle.setting:get() and true or false
 end
 -- ------- BACK SPRITES: the player's own mon stays on the menu
 --
 -- The staged shot stands BOTH mons on the map, which is the mode's whole
 -- claim -- but it costs the one piece of framing Gen 1 is most recognisable
 -- by: your own Pokemon, seen from behind, sitting on top of the battle menu
 -- with its feet on the box. That silhouette is the series' shot.
 --
 -- So BACK SPRITES is offered as a middle setting rather than a compromise
 -- imposed on everyone. With it on the foe is still geometry standing on its
 -- tile at the far end of the arena, and the player's side goes back to being
 -- the GB's own flat back pic in the GB's own slot: same art, same 2x, same
 -- feet on row 96.
 -- Nothing else about the shot moves -- the arena, the camera and the drift are
 -- solved exactly as they were, so the foe stands where it always stood and the
 -- player's cell is simply empty ground in the foreground.
 --
 -- OFF by default: what the mode advertises is the pair of them out there.
 OverworldBattle.BACK_KEY = "battleBack"
 OverworldBattle.BACK_LABEL = "BACK SPRITES"
 OverworldBattle.backSetting = ModSetting.new(OverworldBattle.BACK_KEY,
                                             OverworldBattle.BACK_LABEL,
                                             { false, true }, { "OFF", "ON" })
 -- Gated on 3D-BTL rather than read alone: with staged battles off there is no
 -- staged shot for a back pic to be pinned in FRONT of, and the engine's own
 -- battle screen already draws exactly this.
 function OverworldBattle.backPinned()
  if not OverworldBattle.enabled() then return false end
  return OverworldBattle.backSetting:get() and true or false
 end
 -- Whether a pic is the one drawn in the GB's own slot with its feet on the
 -- text box, rather than geometry standing out on the map.
 --
 -- Exactly the player's side under BACK SPRITES -- its mon, or the trainer back
 -- that holds the slot until "Go!" -- because that is the only pic this mod
 -- ever leaves flat (see drawPicsLayer below). The foe is a billboard on its
 -- tile whichever mode is on, and with the mode off the player's side is one
 -- too, so both of those keep the open bottom that lets the arena through a
 -- stride. What the answer buys is in BattlePics: a pic on the box has nothing
 -- behind its lowest row, so its bottom edge seals.
 -- Read by TRUTHINESS rather than against nil, because sideTexture blanks the
 -- side it is not rendering by setting the field to FALSE (see OFF) and holds
 -- it that way for the whole render -- during which the pic layer runs, and
 -- picImage asks this. A nil test passes a `false` straight through to the
 -- index below, and the error comes out of sideTexture into the pcall that
 -- calls it: the foe's billboard is dropped for the frame and the Pokemon
 -- simply is not there.
 function OverworldBattle.pinnedPic(battle, img)
  if not (battle and img) then return false end
  if not OverworldBattle.backPinned() then return false end
  if img == battle.playerBackPic then return true end
  local player = battle.player
  return (player and img == player.sprite) and true or false
 end
 -- ------- both mons face you
 --
 -- Standing on a map, seen from in front, a Pokemon showing you its BACK is
@@ -81,6 +138,10 @@ end
 -- through the engine's own pokemon.sprite hook -- the seam that exists for
 -- exactly this, so no battle code has to be touched to get it.
 --
 -- Unless BACK SPRITES is on, the setting that asks for the back pic back:
 -- that mon is drawn in its own slot on the menu, seen from behind, and the
 -- front art would be it turned round to face the player it belongs to.
 --
 -- Answered BEFORE a battle exists, because the battler is built before the
 -- battle is pushed. So it cannot ask whether this fight is staged; it asks
 -- whether one on this map WOULD be -- the row is on, the 3D pass is
@@ -91,6 +152,7 @@ local staged = { mapId = nil, ok = false }
 function OverworldBattle.wantsFront()
  if not OverworldBattle.enabled() then return false end
  if OverworldBattle.backPinned() then return false end
  if not Voxel3D.available() then return false end
  -- required here rather than through the file's own helper: this runs
  -- while a battler is being built, which is before that helper is defined
@@ -140,6 +202,51 @@ OverworldBattle.HUD_RECT = {
  player = { 72, 56, 88, 40 },
 }
 -- ------- the box at the bottom, on the same glass
 --
 -- The HUDs got frosted panels because black glyphs on grass are not readable.
 -- The battle's text box and its menu had the opposite problem and the same
 -- cause: they are drawn as an OPAQUE WHITE slab with a black border, which was
 -- the field's own colour when the field was white and is a sheet of paper laid
 -- over the bottom third of the diorama now that it is not.
 --
 -- So the box gets exactly what the HUDs get: the world behind it, blurred to
 -- frosted glass and laid back down translucent, with the border and the text
 -- drawn over it unchanged, and the same brightness verdict flipping the ink
 -- when the ground under it is dark. Only the FILL is taken away -- every glyph
 -- the engine draws inside the box is still the engine's own, in its own place.
 --
 -- These are the boxes BattleState:drawTextArea lays down, as GB-frame rects.
 -- READ-ONLY duplicates of that function's own branches, the same kind of
 -- mirror hudLive is and for the same reason: there is no seam that reports "a
 -- move menu is up", and glass has to go down BEFORE the box that sits on it.
 -- The worst a future engine change can do is frost a rectangle nothing lands
 -- on, or leave a box unfrosted -- never break a battle.
 --
 -- Each rect stops where the next one starts rather than overlapping it: two
 -- panels over the same pixels would frost it twice and leave a visible step
 -- along the seam.
 OverworldBattle.TEXT_RECT = {
  box = { 0, 96, 160, 48 },       -- Font.drawBox(0, 12, 20, 6), always
  -- moveSelect's TYPE/PP box, Font.drawBox(0, 8, 11, 5), trimmed to the rows
  -- above the box above -- its last tile row sits inside that one
  moves = { 0, 64, 88, 32 },
  -- mimicSelect's copy menu, Font.drawBox(0, 7, 16, 6), trimmed the same way
  mimic = { 0, 56, 128, 40 },
 }
 function OverworldBattle.textRects(battle)
  if not battle or battle.blankForAskName then return {} end
  local r = OverworldBattle.TEXT_RECT
  local out = { box = r.box }
  if battle.phase == "moveSelect" then
    out.moves = r.moves
  elseif battle.phase == "mimicSelect" then
    out.mimic = r.mimic
  end
  return out
 end
 -- ------- the HUDs, out at the window's own edges
 --
 -- The battle screen is 160x144 in the MIDDLE of the window and the world is the
@@ -188,6 +295,17 @@ function OverworldBattle.snapRects(shot)
  return rects, { enemy = ex, player = px }
 end
 -- A rect measured in the GB frame, in WORLD-canvas pixels: where the letterbox
 -- blit will actually put it. The text box has not moved anywhere -- it is drawn
 -- where it always was -- but its glass is laid into the world image alongside
 -- the HUDs' (see snapHUDs), which is the surface that reaches the screen a
 -- pixel to a pixel rather than magnified out of a 160x144 canvas.
 local function toWorld(rect, shot)
  local s = shot.scale
  return { shot.lx + rect[1] * s, shot.ly + rect[2] * s,
           rect[3] * s, rect[4] * s }
 end
 -- ------- the live battle
 --
 -- nil when no overworld battle is running. Never more than one: battles do
@@ -471,6 +589,81 @@ local function withoutBackgroundFill(battle, fn)
  if not ok then error(err, 0) end
 end
 -- ------- the box, without its paper
 --
 -- Font.drawBox is a white fill and then six border glyphs, and the fill is the
 -- opaque slab the frosted panel underneath is there to replace. So for the
 -- length of one drawTextArea the white fills are dropped and everything else
 -- -- the border, the text, the cursor, the down arrow -- draws exactly as it
 -- always did, over the glass instead of over paper.
 --
 -- Every fill drawTextArea issues is one of those: the box's own, and the two
 -- eight-pixel cells MoveSelectionMenu wipes back to box white before it writes
 -- the border glyphs that hardware would have overwritten. Both are opaque
 -- white, both are paper, and both go.
 --
 -- The same shim shape as withoutBackgroundFill above, and scoped as tightly:
 -- installed around a single call, removed on the way out including on error,
 -- never live outside a battle frame this mode is drawing.
 local function withoutBoxFill(battle, fn)
  local g = love.graphics
  local rectangle = g.rectangle
  g.rectangle = function(mode, ...)
    if mode == "fill" then
      local r, gr, b, a = g.getColor()
      if r > 0.99 and gr > 0.99 and b > 0.99 and a > 0.99 then return end
    end
    return rectangle(mode, ...)
  end
  local ok, err = pcall(fn, battle)
  g.rectangle = rectangle
  if not ok then error(err, 0) end
 end
 -- ------- the hour's light, on a pic that is not geometry
 --
 -- Everything standing in the arena goes through the voxel shader, and that
 -- shader multiplies by the hour's tint: at dusk the whole diorama warms, at
 -- night it goes blue, and the two mons' cards go with it because they are
 -- drawn in the same pass as the ground they stand on.
 --
 -- A back pic pinned to the menu is not in that pass. It is the engine's own
 -- flat blit over the finished shot, so it arrived at noon while the world
 -- behind it was at midnight -- a mon lit by nothing in the frame.
 --
 -- So the tint is applied by hand, to that one draw. Every colour the pics
 -- layer sets is multiplied on its way past, which is the whole of it: the
 -- layer draws the pic with love.graphics.draw and LOVE multiplies by the draw
 -- colour, so tinting the colour tints the pixels -- and the alpha, the faint
 -- slide's fade and the blink's own colour all compose with it rather than
 -- being overwritten.
 --
 -- What this does NOT get is the sun: the cards are shadow-mapped, so one
 -- standing under a tree is darker than the tint alone, and this pic has no
 -- position in the scene to be shadowed at. It carries the hour and not the
 -- weather, which is the part the eye reads.
 local function withTint(tint, fn, ...)
  if not tint then return fn(...) end
  local r, g, b = tint[1] or 1, tint[2] or 1, tint[3] or 1
  if r > 0.999 and g > 0.999 and b > 0.999 then return fn(...) end
  local gfx = love.graphics
  local setColor = gfx.setColor
  gfx.setColor = function(cr, cg, cb, ca, ...)
    if type(cr) == "table" then
      return setColor({ (cr[1] or 1) * r, (cr[2] or 1) * g, (cr[3] or 1) * b,
                        cr[4] }, cg, ...)
    end
    if cr == nil then return setColor(cr, cg, cb, ca, ...) end
    return setColor(cr * r, (cg or 1) * g, (cb or 1) * b, ca, ...)
  end
  local ok, err = pcall(fn, ...)
  gfx.setColor = setColor
  -- the layer leaves whatever colour it last set, and that one is tinted;
  -- hand the next caller plain white rather than a dimmed one
  setColor(1, 1, 1, 1)
  if not ok then error(err, 0) end
 end
 -- ------- the mons, as textures for the 3D pass
 --
 -- The two Pokemon are not composited over the world any more: they are quads
@@ -600,11 +793,19 @@ function OverworldBattle.flashing(battle)
 end
 -- Both sides, or nil when neither has anything to show.
 --
 -- One side under BACK SPRITES: the player's mon is not standing on the map at all
 -- there, it is on the menu, so it has no card to be a texture for -- and
 -- nothing downstream has to know that. No billboard, and no shadow on the
 -- ground under a mon that is not on it.
 function OverworldBattle.textures(battle)
  if not battle then return nil end
  local out = {}
  local okE, enemy = pcall(OverworldBattle.sideTexture, battle, "enemy")
-  local okP, player = pcall(OverworldBattle.sideTexture, battle, "player")
+  local okP, player = true, nil
  if not OverworldBattle.backPinned() then
    okP, player = pcall(OverworldBattle.sideTexture, battle, "player")
  end
  out.enemy = okE and enemy or nil
  out.player = okP and player or nil
  if not (out.enemy or out.player) then return nil end
@@ -655,11 +856,17 @@ function OverworldBattle.install()
  -- behind it. There is a world back there now, so they are filled here
  -- instead -- see BattlePics, which puts the paper back without touching
  -- the silhouette.
  --
  -- The pinned pic is told that its feet are on the box, which is what lets
  -- the pale-bodied back sprites be filled at all: their bellies leak out
  -- through an opening too wide to read as a drain, and only the box under
  -- them settles that it is not a hole. Passed the pre-bake image, because
  -- that is the one the battle holds a reference to.
  local innerPic = BattleState.picImage
  function BattleState:picImage(img)
    local out = innerPic(self, img)
    if not OverworldBattle.shot() then return out end
-    return BattlePics.filled(out)
+    return BattlePics.filled(out, OverworldBattle.pinnedPic(self, img))
  end
  -- While a billboard texture is being rendered both pics are put in the same
@@ -719,10 +926,44 @@ function OverworldBattle.install()
  -- before this screen is composited at all, so the flat pics layer has
  -- nothing left to do here. Skipped rather than left to draw underneath, or
  -- every Pokemon would appear twice: once on its tile and once in its slot.
  --
  -- Except under BACK SPRITES, where the player's side never became geometry and this
  -- layer is the only thing that draws it. The engine's own onlySide argument
  -- does the whole job: one call, the player's branches alone, in the slot and
  -- at the scale the GB always put them -- feet on the box, 2x, back view.
  innerPics = BattleState.drawPicsLayer
-  function BattleState:drawPicsLayer(slide, sx, sy)
+  function BattleState:drawPicsLayer(slide, sx, sy, onlySide, skipMenuClip)
-    if self.dramaticShapeShot then return end
+    local shot = self.dramaticShapeShot
-    return innerPics(self, slide, sx, sy)
+    if not shot then
      return innerPics(self, slide, sx, sy, onlySide, skipMenuClip)
    end
    if OverworldBattle.backPinned() and onlySide ~= "enemy" then
      -- under the hour's own light, like everything else in the frame -- see
      -- withTint, and the tint BattleScene hands over with the shot.
      --
      -- Except on the wavy path, where the pic is baked into the GRAYSCALE bg
      -- canvas for the zone pass to colour by region. That pass keys off the
      -- red channel, and a night tint pulls red down -- it would not darken
      -- the mon, it would remap it to the wrong shade. SE_WAVY_SCREEN lasts a
      -- second and the hour survives it fine.
      local tint = not self.grayPics and shot.tint or nil
      return withTint(tint, innerPics, self, slide, sx, sy, "player",
                      skipMenuClip)
    end
  end
  -- The battle's text box and its menus, over the frosted glass laid down for
  -- them rather than over their own white paper -- and their ink flipped with
  -- the HUD's when the ground under the frame is dark, by the same rule and
  -- off the same verdict.
  local innerText = BattleState.drawTextArea
  function BattleState:drawTextArea()
    if not self.dramaticShapeShot then return innerText(self) end
    local battle = self
    if not self.dramaticShapeDark then return withoutBoxFill(battle, innerText) end
    BattleHud.flipGlyphs(BattleScene.GB_W, BattleScene.GB_H, function()
      withoutBoxFill(battle, innerText)
    end)
  end
  -- Move animations are authored against the pics' fixed slots, and a single
@@ -740,10 +981,13 @@ function OverworldBattle.install()
    -- mons' projected positions, less the midpoint of the slots they used to
    -- sit in. A hit still lands on the mon it is aimed at.
    local a = OverworldBattle.ANCHOR
-    local dx = (shot.enemy[1] + shot.player[1]) / 2
+    -- BACK SPRITES leaves the player's mon exactly where the GB put it, so that side
-                 - (a.enemy[1] + a.player[1]) / 2
+    -- contributes no movement at all and the pair's centre has gone half as
-    local dy = (shot.enemy[2] + shot.player[2]) / 2
+    -- far as the foe's mark did.
-                 - (a.enemy[2] + a.player[2]) / 2
+    local px, py = shot.player[1], shot.player[2]
    if OverworldBattle.backPinned() then px, py = a.player[1], a.player[2] end
    local dx = (shot.enemy[1] + px) / 2 - (a.enemy[1] + a.player[1]) / 2
    local dy = (shot.enemy[2] + py) / 2 - (a.enemy[2] + a.player[2]) / 2
    love.graphics.push()
    love.graphics.translate(math.floor(dx + 0.5), math.floor(dy + 0.5))
    local ok, err = pcall(innerAnim, self, colorized)
@@ -882,10 +1126,21 @@ function OverworldBattle.snapHUDs(battle, shot)
  local live = {}
  if enemy then live.enemy = rects.enemy end
  if player then live.player = rects.player end
  -- and the text box's own glass, on the same pass. It stays in the middle of
  -- the frame where the engine draws it -- only the HUDs were snapped out --
  -- so its GB rect is mapped into the letterbox rather than to an edge.
  for key, rect in pairs(OverworldBattle.textRects(battle)) do
    live[key] = toWorld(rect, shot)
  end
  -- measured under the SNAPPED rects: the panels are over whatever the world
  -- shows at the window's edges now, which is not what was behind them in the
-  -- middle of the frame
+  -- middle of the frame. ONE verdict over all of them, HUDs and box together,
  -- for the reason BattleHud.verdict gives: a frame with white glyphs in the
  -- corner and black ones on the menu reads as a bug rather than as adaptation.
  local dark = BattleHud.verdict(live, shot, true)
  -- the box's own ink is flipped where the engine draws it, in the GB frame,
  -- so the answer has to outlive this function (see drawHudPanels)
  if session then session.dark = dark end
  local layer = OverworldBattle.hudTexture(battle, slide, dark)
  if not layer then return false end
@@ -911,23 +1166,29 @@ function OverworldBattle.snapHUDs(battle, shot)
  return true
 end
-- Lay the frosted glass down under whichever HUD is about to draw, and
+-- Lay the frosted glass down under whichever HUD and box are about to draw,
-- record which way the glyphs have to flip.
+-- and record which way the glyphs have to flip.
 --
-- The fallback path only: with the HUDs snapped out to the window's edges their
+-- The panels are the fallback path only: normally the HUDs are snapped out to
-- panels went with them, and there is nothing left inside the GB frame to lay
+-- the window's edges and their glass, and the box's, went into the world image
-- glass under.
+-- with them (snapHUDs). The VERDICT is needed either way -- the box's ink is
 -- drawn here, in the GB frame, whichever path laid the glass under it.
 function OverworldBattle.drawHudPanels(battle)
  local shot = battle.dramaticShapeShot
  battle.dramaticShapeDark = nil
-  if not shot or snapped() then return end
+  if not shot then return end
  if snapped() then
    battle.dramaticShapeDark = session and session.dark or nil
    return
  end
  local slide = (battle.introSlide or 0) * 4
  local enemy, player = OverworldBattle.hudLive(battle, slide)
  if not (enemy or player) then return end
  local rect = OverworldBattle.HUD_RECT
  local live = {}
  if enemy then live.enemy = rect.enemy end
  if player then live.player = rect.player end
  for key, r in pairs(OverworldBattle.textRects(battle)) do live[key] = r end
  if not next(live) then return end
  local dark = BattleHud.verdict(live, shot)
  battle.dramaticShapeDark = dark
  for _, r in pairs(live) do BattleHud.panel(r, shot, dark) end
@@ -0,0 +1,353 @@
 -- Voxel world mode: the instrumentation core.
 --
 -- Ships DARK. Every entry point is one boolean test away from doing
 -- nothing, and the boolean is false unless a run explicitly asks for
 -- measurement (DS_PERF in the environment, or a ds_perf.flag file in the
 -- save directory for a device that has no environment to set). A mod that
 -- measures itself in every player's session is a mod that costs every
 -- player the measurement, so the default has to be off and the off path
 -- has to be free.
 --
 -- What it measures, and why those three things:
 --
 --   * LABELS -- named spans (a bake, a mesh build, a shader compile),
 --     accumulated as {n, total, max}. `max` is the one that matters: a
 --     bake that costs 40ms ONCE is a visible hitch, and an average hides
 --     it completely.
 --   * FRAMES -- a ring of the last N whole-frame times, stamped once per
 --     rendered frame. Frame time is the only number the player actually
 --     experiences; every label total is a hypothesis about which frames.
 --   * COUNTERS -- plain integers a caller bumps (sun-pass redraws, atlas
 --     rebakes). Cheaper than a span when the question is "how often",
 --     not "how long".
 --
 -- Spans are wall time, and on a GPU that means submission time, not
 -- completion time -- the driver is free to finish the work later. So a
 -- GPU-side saving shows up in the FRAME numbers rather than in the label
 -- for the pass that caused it, and both are reported.
 local Perf = {}
 local clock = (love and love.timer and love.timer.getTime) or os.clock
 -- Read through pcall: the loader's sandbox does not hand a mod `os`, and
 -- instrumentation must never be the reason the mod fails to load. Same
 -- shape as OverworldBattle's DS_BATTLE_DEBUG probe.
 local function envFlag(name)
  local ok, value = pcall(function() return os.getenv(name) end)
  if not ok then return nil end
  if value == nil or value == "" or value == "0" then return nil end
  return value
 end
 local function flagFile()
  if not (love and love.filesystem and love.filesystem.getInfo) then
    return false
  end
  local ok, info = pcall(love.filesystem.getInfo, "ds_perf.flag")
  return ok and info ~= nil
 end
 Perf.enabled = (envFlag("DS_PERF") ~= nil) or flagFile()
 Perf.labels = {}      -- label -> { n, total, max }
 Perf.order = {}       -- insertion order, so a report reads chronologically
 Perf.counters = {}    -- name -> integer
 Perf.frames = {}      -- ring of frame times, seconds
 Perf.frameCount = 0
 Perf.RING = 4096
 -- The segment a frame belongs to ("map:ROUTE_1:first"). A benchmark
 -- names the phase it is driving; every frame and every label span
 -- recorded while that name is set is attributed to it, which is what
 -- turns "the walk was slow" into "the walk was slow ONLY on the frames
 -- right after ROUTE_1 came into view".
 Perf.segment = nil
 Perf.segments = {}    -- name -> { frames = {}, labels = {}, order = {} }
 local function segmentEntry()
  local name = Perf.segment
  if not name then return nil end
  local s = Perf.segments[name]
  if not s then
    s = { name = name, frames = {}, labels = {}, order = {} }
    Perf.segments[name] = s
    Perf.segments[#Perf.segments + 1] = s   -- array half preserves order
  end
  return s
 end
 function Perf.setSegment(name)
  Perf.segment = name
  if name then segmentEntry() end
 end
 -- ---------------------------------------------------------------- spans
 --
 -- Call shape at the measured site:
 --
 --   local t0 = Perf.now()
 --   ... the work ...
 --   Perf.add("TerrainAtlas.staticAtlas", t0)
 --
 -- When disabled, now() returns nil and add() returns on the nil -- two
 -- function calls and a branch, no table touched, no string built. Sites
 -- that would run thousands of times a frame (per draw call, per vertex)
 -- are still too hot for that and are deliberately NOT instrumented; the
 -- frame ring covers them in aggregate.
 function Perf.now()
  if not Perf.enabled then return nil end
  return clock()
 end
 local function bump(store, order, label, dt)
  local s = store[label]
  if not s then
    s = { n = 0, total = 0, max = 0 }
    store[label] = s
    order[#order + 1] = label
  end
  s.n = s.n + 1
  s.total = s.total + dt
  if dt > s.max then s.max = dt end
 end
 function Perf.add(label, t0)
  if t0 == nil then return end
  local dt = clock() - t0
  bump(Perf.labels, Perf.order, label, dt)
  local seg = segmentEntry()
  if seg then bump(seg.labels, seg.order, label, dt) end
 end
 -- Wrap a function in a table, in place. Used by drivers to instrument
 -- module internals they do not own; the mod's own code calls now()/add()
 -- directly so the label is visible at the site.
 function Perf.wrap(tbl, name, label)
  local orig = tbl and tbl[name]
  if not orig then return false end
  tbl[name] = function(...)
    if not Perf.enabled then return orig(...) end
    local t0 = clock()
    local a, b, c, d = orig(...)
    Perf.add(label or name, t0)
    return a, b, c, d
  end
  return true
 end
 -- ------------------------------------------------------------- counters
 function Perf.count(name, by)
  if not Perf.enabled then return end
  Perf.counters[name] = (Perf.counters[name] or 0) + (by or 1)
 end
 -- --------------------------------------------------------------- frames
 --
 -- Called once per RENDERED frame (the endFrame seam), not once per
 -- logic update: a scripted run can step the game many times per render,
 -- and a frame the player never saw cannot have hitched for them.
 local lastFrame = nil
 function Perf.frame()
  if not Perf.enabled then return end
  local t = clock()
  if lastFrame then
    local dt = t - lastFrame
    local n = Perf.frameCount + 1
    Perf.frameCount = n
    Perf.frames[(n - 1) % Perf.RING + 1] = dt
    local seg = segmentEntry()
    if seg then seg.frames[#seg.frames + 1] = dt end
  end
  lastFrame = t
 end
 -- Discard the pending frame stamp: after a long blocking operation the
 -- next frame delta would include it and libel the renderer.
 function Perf.resync()
  lastFrame = Perf.enabled and clock() or nil
 end
 -- ------------------------------------------------------------ reporting
 local function percentile(sorted, p)
  local n = #sorted
  if n == 0 then return 0 end
  local i = math.ceil(p * n)
  if i < 1 then i = 1 end
  if i > n then i = n end
  return sorted[i]
 end
 -- Frame statistics in MILLISECONDS. p95/p99 rather than the average
 -- because smoothness is a tail property: a run that averages 9ms and
 -- spikes to 60ms four times reads as stuttering, and its average reads
 -- as fine.
 function Perf.frameStats(list)
  local src = list or Perf.frames
  local sorted = {}
  for i = 1, #src do sorted[i] = src[i] * 1000 end
  table.sort(sorted)
  local n = #sorted
  local total = 0
  for i = 1, n do total = total + sorted[i] end
  local over16, over33 = 0, 0
  for i = 1, n do
    if sorted[i] > 16.7 then over16 = over16 + 1 end
    if sorted[i] > 33.3 then over33 = over33 + 1 end
  end
  return {
    n = n,
    avg = n > 0 and total / n or 0,
    p50 = percentile(sorted, 0.50),
    p95 = percentile(sorted, 0.95),
    p99 = percentile(sorted, 0.99),
    worst = n > 0 and sorted[n] or 0,
    over16 = over16,
    over33 = over33,
  }
 end
 function Perf.reset()
  Perf.labels, Perf.order = {}, {}
  Perf.counters = {}
  Perf.frames, Perf.frameCount = {}, 0
  Perf.segments = {}
  Perf.segment = nil
  lastFrame = nil
 end
 local function sortedLabels(store, order)
  local out = {}
  for _, lbl in ipairs(order) do out[#out + 1] = lbl end
  table.sort(out, function(a, b) return store[a].total > store[b].total end)
  return out
 end
 function Perf.printReport(title)
  print(("[perf] ==== %s ===="):format(tostring(title or "report")))
  local f = Perf.frameStats()
  print(("[perf] frames n=%d avg=%.2fms p50=%.2f p95=%.2f p99=%.2f worst=%.2f  >16.7ms=%d  >33.3ms=%d")
    :format(f.n, f.avg, f.p50, f.p95, f.p99, f.worst, f.over16, f.over33))
  for _, seg in ipairs(Perf.segments) do
    local s = Perf.frameStats(seg.frames)
    print(("[perf] seg %-28s n=%4d avg=%6.2f p95=%6.2f p99=%6.2f worst=%7.2f >16.7=%3d >33.3=%3d")
      :format(seg.name, s.n, s.avg, s.p95, s.p99, s.worst, s.over16, s.over33))
  end
  print("[perf] ---- labels (ms, sorted by total) ----")
  for _, lbl in ipairs(sortedLabels(Perf.labels, Perf.order)) do
    local s = Perf.labels[lbl]
    print(("[perf] %-46s n=%6d total=%9.1f max=%8.2f")
      :format(lbl, s.n, s.total * 1000, s.max * 1000))
  end
  local names = {}
  for k in pairs(Perf.counters) do names[#names + 1] = k end
  table.sort(names)
  if #names > 0 then print("[perf] ---- counters ----") end
  for _, k in ipairs(names) do
    print(("[perf] %-46s %d"):format(k, Perf.counters[k]))
  end
 end
 -- ------------------------------------------------------------------ json
 --
 -- Hand-rolled rather than pulled from the engine: the report has to be
 -- readable by a diff tool between two runs, and that means stable key
 -- ORDER, which a generic serializer does not promise.
 local function q(s)
  return '"' .. tostring(s):gsub('[%c"\\]', function(c)
    if c == '"' then return '\\"' end
    if c == "\\" then return "\\\\" end
    return ("\\u%04x"):format(c:byte())
  end) .. '"'
 end
 local function num(x)
  return ("%.4f"):format(x)
 end
 local function statsJson(f)
  return ("{\"n\":%d,\"avg\":%s,\"p50\":%s,\"p95\":%s,\"p99\":%s,\"worst\":%s,\"over16\":%d,\"over33\":%d}")
    :format(f.n, num(f.avg), num(f.p50), num(f.p95), num(f.p99),
            num(f.worst), f.over16, f.over33)
 end
 local function labelsJson(store, order)
  local parts = {}
  for _, lbl in ipairs(sortedLabels(store, order)) do
    local s = store[lbl]
    parts[#parts + 1] = ("%s:{\"n\":%d,\"total\":%s,\"max\":%s}")
      :format(q(lbl), s.n, num(s.total * 1000), num(s.max * 1000))
  end
  return "{" .. table.concat(parts, ",") .. "}"
 end
 function Perf.toJson(meta)
  local parts = {}
  parts[#parts + 1] = "{"
  parts[#parts + 1] = "\"meta\":{"
  local m = {}
  for k, v in pairs(meta or {}) do
    m[#m + 1] = q(k) .. ":" .. (type(v) == "number" and num(v) or q(v))
  end
  table.sort(m)
  parts[#parts + 1] = table.concat(m, ",") .. "},"
  parts[#parts + 1] = "\"frames\":" .. statsJson(Perf.frameStats()) .. ","
  parts[#parts + 1] = "\"segments\":{"
  local segs = {}
  for _, seg in ipairs(Perf.segments) do
    segs[#segs + 1] = q(seg.name) .. ":{\"frames\":"
      .. statsJson(Perf.frameStats(seg.frames))
      .. ",\"labels\":" .. labelsJson(seg.labels, seg.order) .. "}"
  end
  parts[#parts + 1] = table.concat(segs, ",") .. "},"
  parts[#parts + 1] = "\"labels\":" .. labelsJson(Perf.labels, Perf.order) .. ","
  local cs = {}
  for k, v in pairs(Perf.counters) do cs[#cs + 1] = q(k) .. ":" .. v end
  table.sort(cs)
  parts[#parts + 1] = "\"counters\":{" .. table.concat(cs, ",") .. "}"
  parts[#parts + 1] = "}"
  return table.concat(parts, "")
 end
 -- Written through love.filesystem (the save directory) rather than io:
 -- a driver run and an Android session both have one, and neither is
 -- guaranteed a writable working directory.
 function Perf.write(name, meta)
  local body = Perf.toJson(meta)
  if love and love.filesystem then
    pcall(love.filesystem.createDirectory, "ds_bench")
    local ok = pcall(love.filesystem.write, "ds_bench/" .. name .. ".json", body)
    if ok then
      print("[perf] wrote " .. tostring(love.filesystem.getSaveDirectory())
            .. "/ds_bench/" .. name .. ".json")
      return true
    end
  end
  print("[perf] JSON " .. name .. ": " .. body)
  return false
 end
 -- ----------------------------------------------------------- draw stats
 --
 -- love.graphics.getStats() resets per frame, so it is only meaningful
 -- read at the END of a frame -- which is where Perf.frame() runs.
 function Perf.drawStats()
  if not (love and love.graphics and love.graphics.getStats) then return end
  local s = love.graphics.getStats()
  Perf.count("stat.drawcalls", s.drawcalls or 0)
  Perf.count("stat.canvasswitches", s.canvasswitches or 0)
  Perf.count("stat.shaderswitches", s.shaderswitches or 0)
  Perf.count("stat.frames", 1)
  Perf.texturememory = s.texturememory
  Perf.canvases = s.canvases
  Perf.images = s.images
 end
 return Perf
@@ -130,17 +130,23 @@ local SHADER = [[
  }
 #endif
 #ifdef PIXEL
  uniform float sprite;   // 1 while the CAST is being drawn; see ShadowMap.sprites
  vec4 effect(vec4 color, Image tex, vec2 tc, vec2 sc) {
    // the same alpha discard the main pass uses: a sprite card casts its
    // silhouette, not its 16x16 bounding box
    if (Texel(tex, tc).a < 0.5) discard;
-    // pack into two channels: the high byte in red, the low in green
+    // pack into two channels: the high byte in red, the low in green.
    // Blue says WHAT cast this, which costs a channel that was zero anyway
    // and lets a surface decline one kind of caster -- water does, for the
    // people (see Water's sunLit).
    float d = clamp(vDepth, 0.0, 1.0) * 255.0;
-    return vec4(floor(d) / 255.0, fract(d), 0.0, 1.0);
+    return vec4(floor(d) / 255.0, fract(d), sprite, 1.0);
  }
 #endif
 ]]
 ShadowMap._source = function() return SHADER end   -- named for the suite
 local shader = nil            -- nil = untried, false = unavailable
 local canvas = nil            -- nil = untried, false = unavailable
 local canvasRes = 0           -- the edge `canvas` was made at
@@ -440,6 +446,9 @@ function ShadowMap.begin(cx, cy, vw, vh)
  love.graphics.setShader(sh)
  love.graphics.setColor(1, 1, 1, 1)
  pcall(sh.send, sh, "lightVP", "row", ShadowMap.clipVP)
  -- the world until a cast pass says otherwise, reset per pass so one that
  -- forgot to put it back cannot leak into the next map's terrain
  pcall(sh.send, sh, "sprite", 0)
  drawing = true
  ready = false
  return true
@@ -448,6 +457,25 @@ end
 -- Draw one caster. Same signature as Voxel3D.draw minus the camera-ward
 -- pull, which is a trick for the VIEW's depth buffer and would drag a
 -- shadow off whatever throws it.
 -- Whether what is drawn next is one of the CAST -- a walker, an authored
 -- figure, a battle's Pokemon -- rather than part of the world. false for the
 -- length of such a pass, true to put it back.
 --
 -- The map records it per texel (the shader's blue channel) so a surface can
 -- decline that kind of caster, and exactly one does: water. A character
 -- standing at a lake's edge threw a hard cut-out of its own sprite across
 -- the surface, which on something showing the sky and the shoreline reads as
 -- a sticker rather than as a shadow in the water. Everything else -- ground,
 -- roofs, ledges, the characters themselves -- still takes them.
 --
 -- Sent rather than branched, so a caller that forgets to put it back only
 -- mislabels casters rather than losing them; begin() resets it per pass.
 function ShadowMap.sprites(on)
  if not drawing then return end
  local sh = getShader()
  if sh then pcall(sh.send, sh, "sprite", on and 1 or 0) end
 end
 function ShadowMap.draw(mesh, texture, model)
  if not (drawing and mesh) then return end
  local sh = getShader()
@@ -263,6 +263,27 @@ end
 Sky._rampFor = rampFor            -- named for the suite
 -- The band ramp for the CURRENT bands, plus how many texels wide it is --
 -- for a pass that wants to read the same sky this one paints. The water's
 -- reflection is the one caller: it looks the reflected direction up on this
 -- very ramp, so the sky on the lake and the sky over it are one palette,
 -- through one display-mode transform, off one clock.
 --
 -- nil where the ramp could not be built, which is exactly when Sky.paint
 -- falls back to flat bands -- so a driver that loses the gradient loses the
 -- reflected gradient with it rather than showing two different skies.
 function Sky.ramp()
  local bands = Sky.bands()
  if not (bands and bands[1]) then return nil end
  local img = rampFor(bands)
  if not img then return nil end
  return img, #bands, bands
 end
 -- How far the twilight glow reaches around the disc, in canvas pixels, for
 -- a `w`-wide frame. The same number Sky.paint sends as `glowInvR`.
 Sky.GLOW_REACH = 0.55
 local shader = nil            -- nil = untried, false = unavailable
 local function getShader()
@@ -323,20 +344,51 @@ end
 Sky.DISC_FRAC = 0.030     -- disc radius, as a fraction of the frame height
 Sky.DISC_MIN = 3          -- but never fewer cells than this across a radius
-- crater centres as fractions of the radius, so they ride any disc size
+-- crater centres as fractions of the radius, so they ride any disc size.
-local MOON_CRATERS = { { -0.4, -0.2 }, { 0.2, 0.45 }, { 0.5, -0.4 },
+-- Public because the water's reflection draws the same moon (see Water):
-                       { -0.15, 0.7 }, { 0.05, 0.05 } }
+-- one list, so the disc on the lake cannot drift from the one in the sky.
 Sky.MOON_CRATERS = { { -0.4, -0.2 }, { 0.2, 0.45 }, { 0.5, -0.4 },
                     { -0.15, 0.7 }, { 0.05, 0.05 } }
 -- a crater's radius, as a fraction of the disc's -- the r/5 paintDisc uses
 Sky.CRATER_FRAC = 0.2
 local MOON_CRATERS = Sky.MOON_CRATERS
 -- The disc's four shades as the display mode has them, lightest first.
 -- Shared with the reflection pass, so the sun on the water is the same sun
 -- that is in the sky, in the same mode's palette.
 function Sky.discShades(moon)
  local src = moon and DayNight.MOON_COLORS or DayNight.SUN_COLORS
  return PaletteFX.effectiveColors(src) or src
 end
 -- Whether this body is the LOOMING low sun -- the sunset exaggeration.
 local function looming(body)
  return (body.glowAmt or 0) > 0.25 and not body.moon
 end
 -- The disc's radius for a `h`-tall frame on a `cell`-pixel grid: in CANVAS
 -- PIXELS, and in whole cells. Sized by the FRAME rather than by the world
 -- (see DISC_FRAC), so a zoom does not swell the sun.
 --
 -- Read by paintDisc below and by the reflection, which needs the same
 -- number in radians -- a disc drawn one size and mirrored another would
 -- read as two different suns.
 function Sky.discRadius(h, cell, body)
  cell = math.max(1, cell or 1)
  local r = math.max(Sky.DISC_MIN,
                     math.floor(h * Sky.DISC_FRAC / cell + 0.5))
  if body and looming(body) then r = r + math.max(1, math.floor(r * 0.4)) end
  return r * cell, r
 end
 local function paintDisc(body, edge, cell, w, h)
  local g = love.graphics
  if not (body and body.y and g.setScissor) then return end
-  local src = body.moon and DayNight.MOON_COLORS or DayNight.SUN_COLORS
+  local shades = Sky.discShades(body.moon)
-  local shades = PaletteFX.effectiveColors(src) or src
+  local twilight = looming(body)
-  local twilight = (body.glowAmt or 0) > 0.25 and not body.moon
+  local _, r = Sky.discRadius(h, cell, body)
  local r = math.max(Sky.DISC_MIN,
                     math.floor(h * Sky.DISC_FRAC / cell + 0.5))
  -- the low sun looms: the classic sunset exaggeration, and it reads
  if twilight then r = r + math.max(1, math.floor(r * 0.4)) end
  -- snap the centre to the cell grid, like everything else in this sky
  local bx = math.floor(body.x / cell) * cell + cell / 2
  local by = math.floor(body.y / cell) * cell + cell / 2
@@ -429,7 +481,7 @@ function Sky.paint(w, h, sky, horizonY, cell, body)
      if glowAmt > 0 then
        local gc = body.glowColor or { 248, 224, 168 }
        sh:send("glowPos", { body.x, body.y })
-        sh:send("glowInvR", 1 / math.max(1, w * 0.55))
+        sh:send("glowInvR", 1 / math.max(1, w * Sky.GLOW_REACH))
        sh:send("glowColor", { gc[1] / 255, gc[2] / 255, gc[3] / 255 })
      end
    end)
@@ -270,7 +270,12 @@ local function readback(image)
  local prev = love.graphics.getCanvas()
  local ok, data = pcall(function()
    local w, h = image:getDimensions()
-    local canvas = love.graphics.newCanvas(w, h)
+    -- dpiscale = 1, or this is not a copy. On a highdpi surface (Android,
    -- iOS -- see conf.lua) newCanvas takes the surface's scale by default,
    -- so the atlas would be drawn into a texture 2.75x its size and read
    -- back magnified -- and every tile coordinate below, which counts in
    -- eights from the top-left, would land somewhere between two tiles.
    local canvas = love.graphics.newCanvas(w, h, { dpiscale = 1 })
    love.graphics.setCanvas(canvas)
    love.graphics.clear(0, 0, 0, 0)
    -- straight copy: no blending against the cleared target, no tint from
@@ -71,6 +71,21 @@ local FALLBACK_HEIGHTS = {
  -- body builds from the bark rows and the drawn ellipse projects onto
  -- the hull's round top
  stump = 16,
  -- the same hull cut at both ends, hollowed and tapered: an OPEN bin
  -- standing on a floor (the Vermilion Gym trash cans).  The drawn mouth
  -- ellipse projects onto the round top and down the well, the drawn base
  -- ellipse is ground contact rather than body, and the plan narrows toward
  -- the floor.  Height is AUTHORED (the profile's can_height, which this
  -- pin must be kept equal to so anything riding a can lands on its rim) --
  -- the drawing's own straight run is only a couple of rows, because a GB
  -- cell spends most of itself on the opening
  can = 9,
  -- round scenery drawn ONE cell wide and TWO cells TALL, standing on one
  -- cell of plot: the Pokemon Centers' potted plants. Carved as one
  -- 16x32x16 hull in the SOUTH (pot) cell -- the drawing's upper cell is
  -- the object's height, not its depth. BOTH cells take the class; the
  -- group build anchors on the north one (Structures.buildCylinders)
  planter = 32,
  billboard = 16,
  signpost = 16,
  post = 16,
@@ -83,10 +98,18 @@ local FALLBACK_HEIGHTS = {
  bed = 7,
  stool = 8,
  counter = 8,
  -- the raised back band of low seating: the Center couch's west strip
  -- is drawn from above like the rest of the couch, but depicts the
  -- back and arm rising over the 8px seat
  backrest = 12,
  table = 12,
  desk = 24,
  prop = 16,
  cutout = 16,
  -- a vehicle drawn SIDE-ON: the showroom bicycles.  Standee height like
  -- every other cutout pool -- what differs is the thickness (see
  -- Structures' PINNED_DEPTH)
  bike = 16,
  console = 16,
  relief = 3,
  bookcase = 32,
@@ -123,6 +146,8 @@ local ART = {
  cylinder = "cylinder",
  canopy = "canopy",
  stump = "cylinder",
  can = "cylinder",
  planter = "planter",
  billboard = "billboard",
  -- signposts share the billboard treatment but as their own pool at a
  -- 2-voxel depth: a sign is a thin plate on a stick, and the standard
@@ -145,6 +170,9 @@ local ART = {
  -- profile archetype Structures builds real steps for -- rising flights
  -- for stairs leading up, sunken stairwells for stairs leading down
  bed = "top",
  -- a backrest's art is the couch seen from above, so like the bed it
  -- rides the top face of its taller box
  backrest = "top",
  stool = "billboard",
  -- half-cell furniture: a service counter, a low couch.  One 8px band,
  -- so exactly the drawing's bottom row stands up as the front and
@@ -158,6 +186,13 @@ local ART = {
  desk = "upright",
  prop = "billboard",
  cutout = "billboard",
  -- a bicycle is a LINE drawing seen side-on, and its negative space --
  -- the air inside the frame, between the wheel and the fork -- is what
  -- makes it read as a bicycle at all.  Its own pool at two voxels: any
  -- thicker and the side faces of neighbouring strokes close those gaps
  -- from every angle but dead-on, and six of them in a showroom come out
  -- as one dark lump (which is what the 5px `prop` pool gave)
  bike = "billboard",
  -- a machine standing on furniture: the billboard treatment with
  -- body, plus the one-object contract `cutout` has -- the drawing is
  -- ringed by the furniture it sits on, and those edges must not be
@@ -176,6 +211,7 @@ local ART = {
 local spec = nil          -- the loaded data file, or false when absent
 local cache = {}          -- tileset id -> resolved shape list
 local figCache = {}       -- tileset id -> parsed figure masks, or false
 local mntCache = {}       -- tileset id -> parsed mounted masks, or false
 local bgCache = {}        -- tileset id -> prop background shades, or false
 -- The shape profile ships with the mod (data/voxel_heights.lua) and is read
@@ -295,6 +331,24 @@ function TileShape.forMap(map)
  if cache[id] then return cache[id] end
  local heights = TileShape.heights()
  -- Per-tileset height overrides (a tileset entry's `heights`): the class
  -- vocabulary is global but the drawings are not -- the DOJO lab tables
  -- are drawn 6px tall where the default `table` is 12 -- and the height
  -- a sprite RIDES at (VoxelScene.groundAt) must be the height the art
  -- actually stands, or the starter balls float over their own table.
  -- Same gate as the global list: known classes, numbers only.
  do
    local s = load()
    local entry = s and s.tilesets and s.tilesets[id]
    local over = entry and entry.heights
    if type(over) == "table" then
      for class, h in pairs(over) do
        if type(h) == "number" and FALLBACK_HEIGHTS[class] then
          heights[class] = h
        end
      end
    end
  end
  local authored = authoredGroups(id, heights)
  local count = math.floor((tileset.imageWidth or 128) / 8)
                * math.floor((tileset.imageHeight or 48) / 8)
@@ -405,68 +459,158 @@ end
 -- pixel by pixel (see data/voxel_heights.lua):
 --
 --   figures = { { w      = <tiles across>,
 --                 depth  = <voxels of body; ABSENT for a person>,
 --                 thin   = { rows = <top rows>, depth = <voxels> },
 --                 flat   = { x = { <lx0>, <lx1> }, rows = { <r0>, <r1> } },
 --                 tiles  = { ...w*h tile ids, row-major... },
 --                 under  = { ...w*h ids: what each tile wears once the
 --                            figure is lifted off it... },
 --                 pixels = { ...h*8 strings of w*8 chars, "." = not the
 --                            figure... } } }
 --
-- No class: a figure is always a flat sprite card, drawn the way
+-- No class -- what the entry carries instead is a `depth`, or does not:
-- SpriteBillboards draws a character (see Structures.buildFigures).
+--
 --   WITHOUT one it is a flat sprite card, drawn the way SpriteBillboards
 --   draws a character.  That is the right reading for a PERSON: a Gen 1
 --   figure is a face-on 2D icon, and extruding one reconstructs a body
 --   nobody drew (see Structures.buildFigures).
 --   WITH one it is an OBJECT and gets the standee treatment every other
 --   solid here gets -- a per-pixel slab in world space, standing on the
 --   same furniture the card would have stood on.  The Marts' cash
 --   register is the case: a machine on a counter is a box, not an icon.
 --
 -- Two fields say which parts of such a drawing are NOT the extrusion,
 -- because a solid drawn in one 16x16 GB cell still packs more than one
 -- facing:
 --
 --   `thin` caps the thickness over the mask's top rows, for the part of
 --   the drawing that is not the machine (the register's receipt curl).
 --   `flat` names a rect of the mask that is a TOP-VIEW surface rather
 --   than a face -- the register's keypad, whose keys lie ON its deck.
 --   The rect lays horizontal one voxel proud of whatever the extrusion
 --   leaves below it, at the elevation its BOTTOM row would have had,
 --   with drawn row = depth row 1:1 (the mapping the lab tabletop is
 --   drawn with).  So a drawing whose front elevation is an L reads as
 --   one: body up the side and along the base, keys lying in the notch.
 --
 -- Returned normalized: `mask` as a set keyed by ly * (w * 8) + lx, so
 -- Structures can read it as a bitmap without re-parsing per position.
 -- A malformed entry is dropped rather than half-applied -- a typo in a
 -- mask should leave the couch alone, not carve a hole in it.
 --
 -- `mounted` (below) carries the same four fields, so the parse is shared,
 -- and so are the optional ones that give an authored mask a BODY: `depth`,
 -- `thin` and `flat` above.  `depth` is left nil when unstated, because
 -- absence is meaningful on a figure: no depth means the flat sprite card a
 -- person is drawn as.
 local function authoredMasks(list)
  local out = {}
  if type(list) ~= "table" then return out end
  for _, f in ipairs(list) do
    local ok = type(f) == "table" and type(f.w) == "number"
               and type(f.tiles) == "table" and type(f.under) == "table"
               and type(f.pixels) == "table"
    local w = ok and math.floor(f.w) or 0
    local h = (w >= 1) and (#f.tiles / w) or 0
    ok = ok and w >= 1 and h >= 1 and h == math.floor(h)
         and #f.under == #f.tiles and #f.pixels == h * 8
    if ok then
      for i = 1, h * 8 do
        local row = f.pixels[i]
        if type(row) ~= "string" or #row ~= w * 8 then
          ok = false
          break
        end
      end
    end
    if ok then
      local mask, n = {}, 0
      for ly = 0, h * 8 - 1 do
        local row = f.pixels[ly + 1]
        for lx = 0, w * 8 - 1 do
          if row:sub(lx + 1, lx + 1) ~= "." then
            mask[ly * (w * 8) + lx] = true
            n = n + 1
          end
        end
      end
      local depth = tonumber(f.depth)
      local thin = nil
      if type(f.thin) == "table" and tonumber(f.thin.rows)
         and tonumber(f.thin.depth) then
        thin = { rows = math.floor(tonumber(f.thin.rows)),
                 depth = math.floor(tonumber(f.thin.depth)) }
      end
      local flat = nil
      if type(f.flat) == "table" and type(f.flat.x) == "table"
         and type(f.flat.rows) == "table" then
        flat = { x0 = math.floor(f.flat.x[1]), x1 = math.floor(f.flat.x[2]),
                 r0 = math.floor(f.flat.rows[1]),
                 r1 = math.floor(f.flat.rows[2]) }
      end
      if n > 0 then
        out[#out + 1] = { w = w, h = h, n = n, mask = mask,
                          tiles = f.tiles, under = f.under,
                          depth = depth and math.floor(depth) or nil,
                          thin = thin, flat = flat }
      end
    end
  end
  return out
 end
 function TileShape.figures(tilesetId)
  local hit = figCache[tilesetId]
  if hit ~= nil then return hit or nil end
  local s = load()
  local entry = s and s.tilesets and s.tilesets[tilesetId]
-  local list = entry and entry.figures
+  local out = authoredMasks(entry and entry.figures)
  local out = {}
  if type(list) == "table" then
    for _, f in ipairs(list) do
      local ok = type(f) == "table" and type(f.w) == "number"
                 and type(f.tiles) == "table" and type(f.under) == "table"
                 and type(f.pixels) == "table"
      local w = ok and math.floor(f.w) or 0
      local h = (w >= 1) and (#f.tiles / w) or 0
      ok = ok and w >= 1 and h >= 1 and h == math.floor(h)
           and #f.under == #f.tiles and #f.pixels == h * 8
      if ok then
        for i = 1, h * 8 do
          local row = f.pixels[i]
          if type(row) ~= "string" or #row ~= w * 8 then
            ok = false
            break
          end
        end
      end
      if ok then
        local mask, n = {}, 0
        for ly = 0, h * 8 - 1 do
          local row = f.pixels[ly + 1]
          for lx = 0, w * 8 - 1 do
            if row:sub(lx + 1, lx + 1) ~= "." then
              mask[ly * (w * 8) + lx] = true
              n = n + 1
            end
          end
        end
        if n > 0 then
          out[#out + 1] = { w = w, h = h, n = n, mask = mask,
                            tiles = f.tiles, under = f.under }
        end
      end
    end
  end
  figCache[tilesetId] = (#out > 0) and out or false
  return figCache[tilesetId] or nil
 end
 -- Hand-authored MOUNTED objects for one tileset: a thing drawn INTO the
 -- wall band it hangs on, cut out by an explicit pixel mask and stood
 -- proud of the wall's face.
 --
 -- Same authoring problem as `figures` and the same answer -- a class pin
 -- resolves a whole 8x8 tile, and the detector cannot segment a drawing
 -- that has no background margin to flood from.  The Bike Shop's two wall
 -- bicycles are the case: the shop's striped wall panel runs BEHIND them,
 -- and its #555 stripes are a flood boundary, so a silhouette flood comes
 -- back with the stripes attached to the bike.
 --
 -- Two things differ from a figure, and both follow from the object being
 -- an object rather than a character:
 --
 --   it keeps its DRAWN ELEVATION.  A figure stands on its own feet; a
 --   mounted thing sits where the wall band draws it, so a bicycle hung
 --   clear of the floor stays hung.
 --   it has THICKNESS (`depth`, default 2), and it is built in world
 --   space as a per-pixel slab jutting south of the band -- not as a
 --   camera-facing sprite card.  A bicycle drawn side-on is a plane
 --   parallel to the wall, not a face-on icon.
 --
 --   mounted = { { w      = <tiles across>,
 --                 depth  = <voxels it juts into the room>,
 --                 tiles  = { ...w*h tile ids, row-major... },
 --                 under  = { ...w*h ids: what each tile wears once the
 --                            object is lifted off it (the plain panel)... },
 --                 pixels = { ...h*8 strings of w*8 chars, "." = wall... } } }
 function TileShape.mounted(tilesetId)
  local hit = mntCache[tilesetId]
  if hit ~= nil then return hit or nil end
  local s = load()
  local entry = s and s.tilesets and s.tilesets[tilesetId]
  local out = authoredMasks(entry and entry.mounted)
  mntCache[tilesetId] = (#out > 0) and out or false
  return mntCache[tilesetId] or nil
 end
 -- Which GB shades count as BACKGROUND for a pinned per-pixel prop, per tile
 -- (a tileset entry's prop_bg). Returns tile id -> set of shade names, or nil.
 --
@@ -539,12 +683,30 @@ function TileShape.bookcaseBackfill(tilesetId)
  return mode == "above" and mode or nil
 end
 --- Does this tileset's `bookcase` run carry the measured pane RELIEF on
 --- its front (a tileset entry's bookcase_relief)?  Default yes: the class
 --- almost always collapses a shelf, a rack or a display case, and every
 --- one of those seals its contents behind a frame that should stand proud
 --- of them.
 ---
 --- A tileset says `bookcase_relief = false` when it borrows the collapse
 --- for something that is NOT a shelf -- the League's gate walls and
 --- pilasters, Bill's transporter drums -- where the drawing's light
 --- regions are the masonry and the barrel, not panes, and sinking them
 --- carves the surface instead of describing it.
 function TileShape.bookcaseRelief(tilesetId)
  local s = load()
  local entry = s and s.tilesets and s.tilesets[tilesetId]
  return not (entry and entry.bookcase_relief == false)
 end
 -- Drop the cache: a mod that shadows data/voxel_heights.lua or a tileset
 -- record needs the next lookup to re-resolve (hot reload, mod toggle).
 function TileShape.invalidate()
  spec = nil
  cache = {}
  figCache = {}
  mntCache = {}
  bgCache = {}
 end
@@ -283,8 +283,66 @@ local activeShader = nil      -- the variant this pass bound
 -- resize, so the pair is stable for a session.
 local slots = {}
 local canvas, canvasW, canvasH = nil, 0, 0   -- the slot this pass bound
 local held = nil                             -- and the whole record for it
 local active = false
 -- A READABLE depth canvas, so a later pass in the same frame can ask the
 -- buffer questions rather than only write to it -- which is the whole of
 -- what makes screen-space reflections possible (see Water).
 --
 -- `depth = true` in the target list, which is what this used to bind,
 -- allocates an internal depth buffer that is written and tested and can
 -- never be sampled. An explicit canvas is the same buffer with a texture
 -- handle on it, and costs the same memory.
 --
 -- nil where the driver will not make one -- every depth format is optional
 -- in GLES and a canvas is the only honest test of any of them, so this asks
 -- for several in order of preference: 24 bits, the same 24 riding a stencil
 -- (a pairing some mobile drivers will texture when the bare format they
 -- refuse), 32-bit float, and 16 as the floor every GLES3 device can read.
 -- Refused all four, beginScene falls straight back to the internal buffer,
 -- which is exactly the old behaviour minus the reflections.
 local DEPTH_FORMATS = { "depth24", "depth24stencil8", "depth32f", "depth16" }
 local function newDepth(w, h)
  if not (love.graphics and love.graphics.newCanvas) then return nil end
  local c = nil
  for _, format in ipairs(DEPTH_FORMATS) do
    local ok, made = pcall(love.graphics.newCanvas, w, h,
                           { format = format, readable = true })
    if ok and made then c = made break end
  end
  if not c then return nil end
  -- nearest: a depth is a distance, and a blend of two of them is a
  -- distance to nothing. The march wants the texel it landed on.
  pcall(c.setFilter, c, "nearest", "nearest")
  pcall(c.setWrap, c, "clamp", "clamp")
  -- and no compare mode: with one set, Texel returns a 0/1 shadow verdict
  -- instead of the depth, which is not what any reader here wants
  pcall(c.setDepthSampleMode, c)
  return c
 end
 -- The bound target for the slot this pass holds: the colour canvas plus
 -- either the readable depth canvas or the internal buffer.
 local function depthTarget()
  if held and held.depth then
    return { held.canvas, depthstencil = held.depth }
  end
  return { canvas, depth = true }
 end
 -- Every GPU object one slot owns. The mirror is the copy of the frame the
 -- water pass reads (see beginWater); it is only ever made if something asks
 -- for one, so a session that never sees a lake never pays for it.
 local function releaseSlot(slotHeld)
  for _, key in ipairs({ "canvas", "depth", "mirror" }) do
    local obj = slotHeld[key]
    if obj and obj.release then pcall(obj.release, obj) end
    slotHeld[key] = nil
  end
 end
 local IDENTITY = Mat4.identity()
 -- Whether the driver admits to supporting derivatives. Only a hint --
@@ -363,7 +421,8 @@ end
 -- ---------------------------------------------------------------- camera --
 -- An explicit camera, replacing the orbit below for as long as it is set:
-- { eye = {x,y,z}, focus = {x,y,z}, fov = radians, curve = k or nil }.
+-- { eye = {x,y,z}, focus = {x,y,z}, fov = radians, curve = k or nil,
 --   up = {x,y,z} or nil }.
 --
 -- The orbit is the free-roam camera and it is described entirely by ONE
 -- number, the pitch, because that is all a camera following the player over
@@ -379,6 +438,41 @@ end
 -- way either way.
 Voxel3D.camera = nil
 -- ------- which way, and how steeply, this camera looks
 --
 -- Two facts about the view direction, set alongside the eye and the focus
 -- because they ARE the eye and the focus, and read by anything that has to
 -- reason about the camera's ATTITUDE rather than about a point in front of
 -- it:
 --
 --   lookFlat   the view direction flattened onto the ground plane and
 --              normalized -- "the way the horizon lies from here", which is
 --              what a reflection leans toward at the steeper rungs (Water).
 --   descent    how far below horizontal the view runs, as a sine: 0 looking
 --              level, 1 looking straight down. It is the number that says
 --              whether there is a horizon in frame at all, and it answers
 --              the same way for the orbit and for a placed battle camera --
 --              which is why this is derived from the two vectors rather than
 --              read off Voxel.angle, a rung the battle camera does not have.
 --
 -- A camera looking exactly straight down has no horizontal direction at all,
 -- and lookFlat then keeps whatever it last held rather than becoming a zero
 -- vector nothing downstream could normalize.
 Voxel3D.lookFlat = { 0, 0, -1 }
 Voxel3D.descent = 0
 local function setLook(eye, focus)
  local dx = focus[1] - eye[1]
  local dy = focus[2] - eye[2]
  local dz = focus[3] - eye[3]
  local len = math.sqrt(dx * dx + dy * dy + dz * dz)
  if len < 1e-6 then return end
  Voxel3D.descent = math.max(0, math.min(1, -dy / len))
  local flat = math.sqrt(dx * dx + dz * dz)
  if flat < 1e-6 then return end
  Voxel3D.lookFlat = { dx / flat, 0, dz / flat }
 end
 -- View and projection for a `vw` x `vh` world-pixel view centred on
 -- (cx, cy) in world pixels. Returns the combined matrix.
 function Voxel3D.viewProjection(cx, cy, vw, vh)
@@ -389,18 +483,26 @@ function Voxel3D.viewProjection(cx, cy, vw, vh)
    -- kept beside the eye for horizonY: where the sky's pale end goes is a
    -- question about which way this camera looks, and only these two answer it
    Voxel3D.focus = focus
    setLook(eye, focus)
    local dx = eye[1] - focus[1]
    local dy = eye[2] - focus[2]
    local dz = eye[3] - focus[3]
    local dist = math.max(1, math.sqrt(dx * dx + dy * dy + dz * dz))
    -- kept for the passes that measure an ANGLE against this camera rather
    -- than a position: the water's reflected sun is sized in radians, and
    -- radians per canvas pixel is exactly this over the frame height
    Voxel3D.fovY = cam.fov
    local proj = Mat4.perspective(cam.fov, vw / vh,
                                  math.max(1, dist * 0.05), dist * 4 + 4096)
    -- the same clip-space Y flip the orbit needs, for the same reason: we
    -- bypass LOVE's transform_projection and canvas coordinates run Y down
    proj = Mat4.mul(Mat4.scale(1, -1, 1), proj)
-    -- world up, so the horizon stays level -- a placed camera that rolled
+    -- world up by default, so the horizon stays level -- a placed camera
-    -- with its own pitch would tip the whole arena
+    -- that rolled with its own pitch would tip the whole arena. A caller
-    return Mat4.mul(proj, Mat4.lookAt(eye, focus, { 0, 1, 0 }))
+    -- may hand its own up: the first-person BLEND does, because its far
    -- end is the orbit, whose up leans with the pitch -- world up at the
    -- orbit's steep end degenerates against a straight-down view.
    return Mat4.mul(proj, Mat4.lookAt(eye, focus, cam.up or { 0, 1, 0 }))
  end
  local a = Voxel.angle
@@ -409,12 +511,14 @@ function Voxel3D.viewProjection(cx, cy, vw, vh)
  -- the FOV that makes a straight-down camera at `dist` frame exactly `vh`
  -- world pixels, which is the framing the flat view already has
  local fov = 2 * math.atan(1 / (2 * focal))
  Voxel3D.fovY = fov
  local focus = { cx, 0, cy }
  local eye = { cx, dist * math.cos(a), cy + dist * math.sin(a) }
  -- exposed for camera-facing billboards (VoxelScene yaws sprites at it)
  Voxel3D.eye = eye
  Voxel3D.focus = focus
  setLook(eye, focus)
  -- perpendicular to the view direction in the YZ plane: north is screen-up
  -- when looking straight down, +Y is screen-up when looking level. Never
  -- parallel to the view direction, so there is no degenerate a = 0 case.
@@ -538,22 +642,29 @@ function Voxel3D.beginScene(w, h, cx, cy, vw, vh, sky, slot)
  end
  if not sh then return false end
  local name = slot or "world"
-  local held = slots[name]
+  local slotHeld = slots[name]
-  if not (held and held.w == w and held.h == h) then
+  if not (slotHeld and slotHeld.w == w and slotHeld.h == h) then
    local ok, c = pcall(love.graphics.newCanvas, w, h)
    if not ok then return false end
    c:setFilter("nearest", "nearest")
-    if held and held.canvas and held.canvas.release then
+    if slotHeld then releaseSlot(slotHeld) end
-      pcall(held.canvas.release, held.canvas)
+    -- the depth canvas is sized with its colour, so a window resize
-    end
+    -- reallocates the pair together and they can never disagree
-    held = { canvas = c, w = w, h = h }
+    slotHeld = { canvas = c, w = w, h = h, depth = newDepth(w, h) }
-    slots[name] = held
+    slots[name] = slotHeld
  end
  held = slotHeld
  canvas, canvasW, canvasH = held.canvas, w, h
  -- a depth buffer is what makes occlusion real: walk behind a building and
  -- the building wins, with no y-sorting anywhere
-  local ok = pcall(love.graphics.setCanvas,
+  local ok = pcall(love.graphics.setCanvas, depthTarget())
-                   { canvas, depth = true })
+  if not ok and held.depth then
    -- the readable canvas would not bind; fall back to the internal buffer
    -- for the rest of this session rather than losing the whole 3D pass
    pcall(held.depth.release, held.depth)
    held.depth = nil
    ok = pcall(love.graphics.setCanvas, depthTarget())
  end
  if not ok then
    pcall(love.graphics.setCanvas)
    return false
@@ -561,6 +672,14 @@ function Voxel3D.beginScene(w, h, cx, cy, vw, vh, sky, slot)
  -- Ahead of the clear, because the sky's bands are placed off the ground
  -- plane's vanishing line and that is a property of this matrix.
  Voxel3D.vp = Voxel3D.viewProjection(cx, cy, vw, vh)
  -- This frame's pixels per WORLD pixel: the size a diorama pixel is on
  -- screen. The sky's dither grid is cut to it, and so is the water's --
  -- one number, so the two break up on the same checkerboard.
  Voxel3D.cell = w / math.max(1, vw or w)
  -- and where the sky's bottom edge lands, which is what the reflection
  -- reads its bands against (see Water). nil when nothing painted bands.
  Voxel3D.skyEdge = (sky and sky.bands)
                    and Sky.region(h, Voxel3D.horizonY(h)) or nil
  if sky then
    love.graphics.clear(sky[1], sky[2], sky[3], sky[4] or 1, true, true)
    -- The sky goes down here, in the one window in this function where a
@@ -573,7 +692,7 @@ function Voxel3D.beginScene(w, h, cx, cy, vw, vh, sky, slot)
    -- are the same size as the world's own and follow every resize and zoom.
    -- The banded sky also hangs the hour's sun or moon (skyBody projects it
    -- through this very camera); a flat sky has no bands and hangs nothing.
-    Sky.paint(w, h, sky, Voxel3D.horizonY(h), w / math.max(1, vw or w),
+    Sky.paint(w, h, sky, Voxel3D.horizonY(h), Voxel3D.cell,
              sky.bands and Voxel3D.skyBody(w, h) or nil)
  else
    love.graphics.clear(0, 0, 0, 0, true, true)
@@ -600,7 +719,7 @@ function Voxel3D.beginScene(w, h, cx, cy, vw, vh, sky, slot)
  pcall(sh.send, sh, "sunTexel", { texel, texel })
  if grid then
    pcall(sh.send, sh, "gridDark", VoxelGrid.DARK)
-    pcall(sh.send, sh, "gridWidth", VoxelGrid.WIDTH)
+    pcall(sh.send, sh, "gridWidth", VoxelGrid.width())
  end
  -- ordinary shading until the silhouette pass asks for otherwise. Sent
  -- every frame rather than once, because a scene that opened mid-ghost --
@@ -720,6 +839,108 @@ function Voxel3D.flatten(color, amount)
  end
 end
 -- ------------------------------------------------------- the water pass --
 --
 -- A reflective surface has to READ the frame it is being drawn into: the
 -- colour of what is standing around it and the depth that says where. Both
 -- are attachments of the target this pass is bound to, and a texture cannot
 -- be sampled while it is one -- so for the length of the water draw the
 -- frame is taken apart:
 --
 --   the COLOUR is copied to a mirror canvas, which is a texture like any
 --   other and is what the reflection samples.
 --
 --   the DEPTH is simply detached. The water shader does the test itself
 --   against the texture (see Water), which is the same comparison the
 --   hardware would have made -- what it gives up is depth WRITES, and water
 --   is flat, never overlaps itself, and has nothing drawn under it later.
 --
 -- `paint`, when given, is called with the MIRROR bound and the scene shader
 -- set, to add things that must be REFLECTED without being composited yet.
 --
 -- The characters are the whole reason it exists. Gen 1 draws people over
 -- the world and water is world, so the cast has to composite AFTER the
 -- water -- but a reflection can only contain what was drawn BEFORE it, and
 -- a lake with everyone standing beside it and nobody in it reads as glass.
 -- Painting them into the mirror alone settles both: they are in the picture
 -- the water reflects and not yet in the picture the water is drawn into.
 --
 -- They go down depth-TESTED and depth-WRITE-FREE. Tested, so a figure behind
 -- a building is behind it in the reflection too; write-free because the very
 -- next thing to read that buffer is the water's own depth test, and a cast
 -- that had written to it would punch itself out of the water it is standing
 -- beside.
 --
 -- Returns the two textures, or nil when there is nothing to hand over: no
 -- readable depth canvas on this driver, or no pass open. A caller that gets
 -- nil draws its water like ordinary terrain, which is what this mode always
 -- did.
 --
 -- MUST be paired with endWater, which puts the frame back together.
 function Voxel3D.beginWater(paint)
  if not (active and canvas and held and held.depth) then return nil end
  if not held.mirror then
    local ok, c = pcall(love.graphics.newCanvas, held.w, held.h)
    if not (ok and c) then return nil end
    pcall(c.setFilter, c, "nearest", "nearest")
    pcall(c.setWrap, c, "clamp", "clamp")
    held.mirror = c
  end
  love.graphics.setShader()
  -- the frame's own depth rides along, so the paint below can test against
  -- it; the copy underneath switches the test off rather than detaching it
  local ok = pcall(love.graphics.setCanvas,
                   { held.mirror, depthstencil = held.depth })
  if not ok then
    pcall(love.graphics.setCanvas, depthTarget())
    return nil
  end
  love.graphics.setDepthMode("always", false)
  -- COLOUR only. The last two arguments are what keep the depth buffer the
  -- frame's rather than this canvas's: cleared here, the water's own depth
  -- test a few lines later would find nothing in front of anything and every
  -- lake would draw straight through the buildings standing in it.
  love.graphics.clear(0, 0, 0, 0, false, false)
  -- premultiplied over a cleared target is a straight copy: every channel
  -- lands exactly as it stood, including the alpha, so the mirror is the
  -- frame rather than the frame composited against something
  love.graphics.setBlendMode("alpha", "premultiplied")
  love.graphics.setColor(1, 1, 1, 1)
  love.graphics.draw(canvas)
  love.graphics.setBlendMode("alpha")
  if paint and activeShader then
    love.graphics.setDepthMode("lequal", false)
    love.graphics.setShader(activeShader)
    pcall(paint)
    love.graphics.setShader()
  end
  love.graphics.setDepthMode()
  -- and back to the scene canvas WITHOUT its depth: that texture is about
  -- to be read
  if not pcall(love.graphics.setCanvas, canvas) then
    pcall(love.graphics.setCanvas, depthTarget())
    return nil
  end
  return held.mirror, held.depth
 end
 -- Put the frame back: depth reattached, depth test and the scene shader as
 -- the pass had them. Safe to call after a beginWater that returned nil.
 function Voxel3D.endWater()
  if not active then return end
  pcall(love.graphics.setCanvas, depthTarget())
  pcall(love.graphics.setDepthMode, "lequal", true)
  love.graphics.setColor(1, 1, 1, 1)
  if activeShader then love.graphics.setShader(activeShader) end
 end
 -- Whether a reflective water pass can run in this frame at all -- there is
 -- a depth texture to read. Callers use it to choose between the water
 -- shader and an ordinary terrain draw before they start moving canvases.
 function Voxel3D.depthReadable()
  return (active and held and held.depth) and true or false
 end
 -- Whether what is drawn next carries the voxel wireframe. false for the
 -- length of a draw, true to put it back.
 --
@@ -931,18 +1152,25 @@ function Voxel3D.canvas()
  return canvas
 end
 -- The bound canvas's pixel size, for a pass that has to work in screen
 -- coordinates (the water's reflection marches in them).
 function Voxel3D.size()
  return canvasW, canvasH
 end
 -- Drop the GPU objects (window resize, hot reload).
 function Voxel3D.invalidate()
-  for name, held in pairs(slots) do
+  for name, slotHeld in pairs(slots) do
-    if held.canvas and held.canvas.release then
+    releaseSlot(slotHeld)
      pcall(held.canvas.release, held.canvas)
    end
    slots[name] = nil
  end
  canvas, canvasW, canvasH = nil, 0, 0
  held = nil
  ShadowMap.invalidate()
  -- the sky is part of this pass and holds a shader of its own
  Sky.invalidate()
  -- and so does the water, for the same reason
  V.require("Water").invalidate()
  -- and the glass masks are textures of this context too
  GlassMask.invalidate()
 end
@@ -44,6 +44,19 @@ VoxelGrid.DARK = 0.45
 -- 1.0 here is the one-pixel wireframe.
 VoxelGrid.WIDTH = 1.0
 -- The same width in the CANVAS pixels the shader measures in, which is what
 -- every sender of it actually wants.
 --
 -- The two are the same number until AA renders the pass larger than the
 -- window (see AntiAlias): there a canvas pixel is a fraction of a display
 -- one, and a width left at 1.0 would come out a half or a quarter of a line
 -- after the fold -- the wireframe fading as the smoothing goes up, which
 -- reads as one row breaking the other. Scaled, it stays a one-pixel seam and
 -- simply gains the antialiasing everything else in the frame just gained.
 function VoxelGrid.width()
  return VoxelGrid.WIDTH * V.require("AntiAlias").factor()
 end
 -- where it persists and the rows that cycle it (see ModSetting)
 VoxelGrid.setting = ModSetting.new(VoxelGrid.KEY, VoxelGrid.LABEL,
                                   { false, true }, { "OFF", "ON" })
@@ -21,7 +21,10 @@ local TileShape = V.require("TileShape")
 local TerrainAtlas = V.require("TerrainAtlas")
 local Voxel = V.require("VoxelState")
 local Sky = V.require("Sky")
 local Water = V.require("Water")
 local VoxelGrid = V.require("VoxelGrid")
 local DayNight = V.require("DayNight")
 local FirstPerson = V.require("FirstPerson")
 local PaletteFX = require("src.render.PaletteFX")
 local Map = require("src.world.Map")
@@ -212,6 +215,22 @@ local function frameFor(def, facing, phase, flip)
  return frame, mirror
 end
 -- The facing a pose SHOWS this camera. The flat frames are "how this pose
 -- looks from the south", which is where the orbit always stands; a
 -- first-person eye stands anywhere, so deep enough into the blend the
 -- facing is remapped to how the pose looks from THERE -- walk behind an
 -- NPC and their card wears the back sprite. Used by the camera draw and
 -- the sun pass BOTH: the card the sun stored and the transform a lit card
 -- reads its own shadowing with must describe the same frame, or the
 -- mirror-flip half of the pair asks the map about texels the sun filed
 -- under the other cheek.
 local function viewFacing(p)
  if FirstPerson.cardBlend() > 0.5 then
    return FirstPerson.apparentFacing(p.facing, p.px + 8, p.py + 8)
  end
  return p.facing
 end
 -- FALLBACK ONLY (see castShadows below). Draw one entity's drop shadow as
 -- a decal: its current sprite frame as a single quad, flattened onto the
 -- ground along the sun line (Voxel3D.shadowMatrix). Runs inside
@@ -234,10 +253,22 @@ end
 -- Shared by the solid draw and the silhouette below, so the two can never
 -- drift apart -- a silhouette standing anywhere but exactly behind the
 -- figure would read as a second character.
 --
 -- IN FIRST PERSON the card stops leaning and starts TURNING: upright, yawed
 -- about its feet to face the eye (cylindrical billboarding). A south-facing
 -- card is invisible edge-on to an eye standing east of it, which no orbit
 -- camera could ever do and a first-person one does constantly. The blend
 -- carries one pose into the other -- the lean eases out as the yaw eases in
 -- -- and cardBlend is zero for every camera that is not the first-person
 -- rig, the battle's placed shot included, so nothing else moves.
 local function billboardMatrix(px, py, y, mirror)
  local Voxel = V.require("VoxelState")
-  local m = Mat4.mul(Mat4.translate(px + 8, y, py + 8),
+  local b = FirstPerson.cardBlend()
-                     Mat4.rotateX(Voxel.angle - math.pi / 2))
+  local m = Mat4.translate(px + 8, y, py + 8)
  if b > 0 then
    m = Mat4.mul(m, Mat4.rotateY(FirstPerson.cardYaw(px + 8, py + 8) * b))
  end
  m = Mat4.mul(m, Mat4.rotateX((Voxel.angle - math.pi / 2) * (1 - b)))
  if mirror then m = Mat4.mul(m, Mat4.scale(-1, 1, 1)) end
  return Mat4.mul(m, Mat4.translate(-8, 0, 0))
 end
@@ -256,10 +287,24 @@ end
 -- the Pokemon Center couch reads face-on at every tilt like the NPCs
 -- around him. No cell centring: unlike a character he is not standing on a
 -- cell, he is standing where he was drawn, which may straddle two.
 --
 -- First person turns him at the eye like the walkers (see billboardMatrix)
 -- -- about his own middle, because unlike a character card his local space
 -- starts at x = 0 rather than being anchored by a -8 shift, and a yaw about
 -- his edge would swing him off his seat. The width rode in on the record
 -- for exactly this (ChunkMesher.buildFigureMeshes).
 local function figureMatrix(f, offX, offZ)
  local Voxel = V.require("VoxelState")
-  return Mat4.mul(Mat4.translate(f.wx + (offX or 0), f.y, f.wz + (offZ or 0)),
+  local b = FirstPerson.cardBlend()
-                  Mat4.rotateX(Voxel.angle - math.pi / 2))
+  local wx, wz = f.wx + (offX or 0), f.wz + (offZ or 0)
  local m = Mat4.translate(wx, f.y, wz)
  if b > 0 and f.w and f.w > 0 then
    local half = f.w / 2
    m = Mat4.mul(m, Mat4.translate(half, 0, 0))
    m = Mat4.mul(m, Mat4.rotateY(FirstPerson.cardYaw(wx + half, wz) * b))
    m = Mat4.mul(m, Mat4.translate(-half, 0, 0))
  end
  return Mat4.mul(m, Mat4.rotateX((Voxel.angle - math.pi / 2) * (1 - b)))
 end
 -- What the sun sees: the same card UNLEANED and flattened, exactly as
@@ -331,7 +376,7 @@ VoxelScene.drawEntity = drawEntity
 -- mesh for it.
 local function drawGhost(p)
  local def = p.sprite.def
-  local frame, mirror = frameFor(def, p.facing, p.phase, p.flip)
+  local frame, mirror = frameFor(def, viewFacing(p), p.phase, p.flip)
  local mesh = SpriteBillboards.shadowQuad(def, frame)
  if not mesh then return end
  local tex = p.sprite:resolveImage()
@@ -404,17 +449,25 @@ function VoxelScene.prefetch(state)
  -- crossing demotes the map just left, and it must not vanish from
  -- behind the player while its body variant builds; its ring is
  -- already masked out under this map's body, so the stand-in is safe.
-  local terrain = ChunkMesher.request(state.map, false, masks, true)
+  -- The water surface rides along with whichever variant answers: it was
  -- cut out of that build's own geometry (ChunkMesher.pair), so the two
  -- always come from the same slot and a lake is never drawn twice or left
  -- as a hole.
  ChunkMesher.request(state.map, false, masks, true)
  local terrain, water = ChunkMesher.pair(state.map, false)
  if not terrain then
-    terrain = ChunkMesher.peek(state.map, true)
+    terrain, water = ChunkMesher.pair(state.map, true)
  end
-  local nbMesh = {}
+  local nbMesh, nbWater = {}, {}
  for i, nb in ipairs(state.neighbors or {}) do
-    nbMesh[i] = ChunkMesher.request(nb.map, true)
+    ChunkMesher.request(nb.map, true)
-                or ChunkMesher.peek(nb.map, false)
+    nbMesh[i], nbWater[i] = ChunkMesher.pair(nb.map, true)
    if not nbMesh[i] then
      nbMesh[i], nbWater[i] = ChunkMesher.pair(nb.map, false)
    end
  end
  Voxel.ready = terrain ~= nil
-  return terrain, nbMesh
+  return terrain, nbMesh, water, nbWater
 end
 -- Capture every entity's pose for this frame. pose() advances the hop /
@@ -452,7 +505,13 @@ local function posesOf(state, spriteColors)
        gh = groundAt(state.map, e.cellX, e.cellY),
        lift = e.py - vy, colors = colors,
      }
-      if e == state.player then me = posed[#posed] end
+      if e == state.player then
        me = posed[#posed]
        -- marked so the camera draw can leave the card out in first
        -- person, where it would fill the lens from inside; the SUN pass
        -- reads the same list and deliberately does not check the mark
        me.isPlayer = true
      end
    end
  end
  return posed, me
@@ -490,6 +549,175 @@ end
 local glint = {}
 -- ------- the cast
 --
 -- Everybody standing on the map: the walkers, and the authored FIGURES the
 -- tileset draws into its own furniture (they ARE characters as far as the
 -- artwork is concerned, just ones drawn by the tileset instead of by a
 -- sprite sheet, so they get the same lean and the same camera-ward pull).
 --
 -- One function because it is drawn TWICE and the two must be identical: once
 -- into the frame, and once into the water's reflection copy (see drawWater --
 -- Gen 1 draws people over the world, and water is world, so the cast cannot
 -- be composited before the water it has to appear in).
 --
 -- Characters carry no wireframe out here, whatever the V-GRID row says. The
 -- seams are what makes the WORLD read as built out of voxels, and the people
 -- walking around in it are the one thing that should read as drawn instead --
 -- a grid over a 16x16 sprite lands a line every couple of display pixels and
 -- turns a face into a mesh. (The battle pass makes the opposite call for its
 -- own combatants, deliberately -- see BattleBillboard.)
 --
 -- Sprite sheets until the figure pass: their texture coordinates mean
 -- nothing to the tileset-shaped glass mask, so the glass is off or the
 -- panes' atlas positions stripe the cast with lamplight at night.
 local function drawCast(state, posed, atlasFor)
  Voxel3D.glass(false)
  Voxel3D.seams(false)
  -- Characters, normally depth-tested: the camera-ward pull inside
  -- drawEntity resolves the lean-over-the-wall-in-front case, and a
  -- character genuinely behind a building is far deeper and loses the
  -- test, so buildings and trees really occlude.
  --
  -- In first person two of them change: the player's own card is left out
  -- (the eye is standing in it), and every other card wears the frame its
  -- pose SHOWS this eye (viewFacing) rather than the one it shows the
  -- south. Both run through here, so the water's reflection copy -- drawn
  -- by this same function -- agrees with the frame to the pixel.
  local hideMe = FirstPerson.hidePlayer()
  for _, p in ipairs(posed) do
    if not (p.isPlayer and hideMe) then
      drawEntity(p.sprite, p.px, p.py, viewFacing(p), p.phase, p.flip, p.gh,
                 p.colors, p.lift)
    end
  end
  -- back on for everything textured from the atlas again -- figures, grass
  -- and flowers all sample it, where the mask's coordinates are honest
  Voxel3D.glass(true)
  -- Figures after the walkers, so a player standing in front of the couch
  -- wins the overlap -- the order the flat game draws them in.
  local figPull = billboardPull()
  eachFigure(state.map, 0, 0, function(mesh, model, caster)
    Voxel3D.draw(mesh, atlasFor(state.map), model, figPull,
                 ShadowMap.snug(caster))
  end)
  for _, nb in ipairs(state.neighbors or {}) do
    eachFigure(nb.map, nb.ox, nb.oy, function(mesh, model, caster)
      Voxel3D.draw(mesh, atlasFor(nb.map), model, figPull,
                   ShadowMap.snug(caster))
    end)
  end
  -- and the seams are back on for the terrain art that follows: grass and
  -- flowers are the world's own drawing, not people
  Voxel3D.seams(true)
 end
 -- ------- the water pass
 --
 -- Between the terrain and everything that stands on it, because water is a
 -- MIRROR and a mirror can only reflect what is already down: the ground, the
 -- shoreline, the trees and buildings behind it, and the sky the frame opened
 -- with.
 --
 -- THE CAST IS THE AWKWARD ONE, and it is settled by drawing it twice. Gen 1
 -- draws people over the world and water is world, so a surfing player has to
 -- composite OVER the water they are sitting on -- which puts them after it,
 -- and a reflection can only hold what came before it. So `cast` is painted
 -- into the reflection copy alone (Voxel3D.beginWater), where it is in the
 -- picture the water reflects and not yet in the picture the water is drawn
 -- into. Both draws go through drawCast, so they cannot come out different.
 --
 -- The ray march finds them the honest way round: a sprite is not in the
 -- DEPTH buffer at that point, so a ray aimed at one passes through to the
 -- terrain standing behind it and reads the copy there -- where the sprite is
 -- already painted. The reflection lands a hair off the sprite's own depth
 -- and exactly on its colour, which at a lake's worth of ripple is the same
 -- picture.
 --
 -- `draws` is a list of { mesh, texture, model }. Nothing is a special case:
 -- with the row OFF, no depth texture to read, or a shader that would not
 -- build, the same meshes go through the ordinary scene shader and come out
 -- as the flat animated water this mode always drew.
 -- The overworld's alone: the staged battle draws its water plain, always --
 -- its placed camera reads this pass wrong, and a stage set wants painted
 -- water anyway (see BattleScene, where the choice is argued).
 -- ------- and why the flat draw happens FIRST while the world is curved
 --
 -- The reflective pass writes no depth -- it cannot, the depth canvas is
 -- detached for the length of it so the shader can READ it -- and it does its
 -- own depth test against that texture instead. That test asks whether
 -- something opaque is in front, and it answers correctly for every case but
 -- one: WATER IN FRONT OF WATER. Nothing puts water in the depth buffer, so
 -- no lake can hide another, and the pass simply paints them in mesh order.
 --
 -- On a flat world that never matters: every surface lies in the one plane
 -- at its own recessed height, and a farther sheet always lands farther down
 -- the screen. THE WORLD CURVE ENDS THAT. The bend drops the world by the
 -- square of its distance, so the far side of the map swings down and back
 -- up into the near field of view -- and a sheet of sea a hundred and fifty
 -- tiles away, drawn later in the same mesh, paints straight over the pond
 -- at the player's feet. Not a reflection of the far shore: the far shore
 -- itself, rasterised on top of the water in front of you.
 --
 -- So WHILE THE CURVE IS ON, the meshes go down flat first, through the
 -- ordinary scene shader with depth writes on, and the reflective pass draws
 -- over the top of what survived: the depth buffer now holds the water
 -- surface, so the pass's own test throws the far sheet away, and the
 -- reflection COPY holds it too, so a ray grazing another part of the lake
 -- reads water rather than the void behind it.
 --
 -- With the curve OFF the prepass is not just unnecessary, it is a LIABILITY,
 -- and it stays off -- the reflective pass tests only against terrain, as it
 -- always did. Painting the surface into the depth texture turns the pass's
 -- test into a comparison of the surface against ITSELF, which asks the two
 -- rasterisations to agree to within interpolation error -- and on mobile
 -- GPUs they don't reliably (that fight is what put the Android port back on
 -- flat water). Confined to the curve there is no regression to reach: the
 -- flat world never had the far-shore bug in the first place.
 function VoxelScene.drawWater(draws, cast)
  -- prepass only under the bend; see the header
  local curved = (Voxel3D.curveK or 0) > 0
  if curved then
    for _, d in ipairs(draws) do
      Voxel3D.draw(d[1], d[2], d[3])
    end
  end
  local plain = not curved
  if Water.enabled() and Voxel3D.depthReadable() then
    local mirror, depth = Voxel3D.beginWater(cast)
    local w, h = Voxel3D.size()
    local ok = mirror and depth and Water.begin({
      reflect = mirror, depth = depth,
      vp = Voxel3D.vp, eye = Voxel3D.eye, curve = { Voxel3D.curveX or 0,
                                                    Voxel3D.curveZ or 0,
                                                    Voxel3D.curveK or 0 },
      screen = { w, h }, cell = Voxel3D.cell, fov = Voxel3D.fovY,
      skyEdge = Voxel3D.skyEdge, grid = VoxelGrid.enabled(),
      lookFlat = Voxel3D.lookFlat, descent = Voxel3D.descent,
    })
    if ok then
      for _, d in ipairs(draws) do
        Water.draw(d[1], d[2], d[3])
      end
      Water.finish()
      plain = false
    end
    -- Unconditionally, and OUTSIDE the success branch: beginWater unbinds
    -- the shader and the depth mode BEFORE it can discover it cannot go on,
    -- so a frame that bails halfway through has to be put back together
    -- exactly like one that succeeded -- otherwise every pass after it runs
    -- with no shader and no depth test.
    Voxel3D.endWater()
  end
  -- the fallback flat draw -- unless the curve's prepass already put the
  -- same meshes down, in which case a bailed frame is already whole
  if plain then
    for _, d in ipairs(draws) do
      Voxel3D.draw(d[1], d[2], d[3])
    end
  end
 end
 -- A stamp of everything the sun pass depends on. Nothing in it moving
 -- means the shadow map it produced last frame is still exactly right, and
 -- redrawing the whole world from the sun would buy nothing -- which is
@@ -517,6 +745,10 @@ local function shadowSignature(terrain, nbMesh, posed, cx, cy, vw, vh)
  -- few times a minute rather than every frame.
  put(math.floor(ShadowMap.KX * 128))
  put(math.floor(ShadowMap.KZ * 128))
  -- and the first-person head: the box is fitted around wherever it looks
  -- and the sprite cards swap frames as it circles them, so a turn on the
  -- spot re-fits and redraws exactly like a camera move ("" outside 1ST)
  put(FirstPerson.signature())
  put(tostring(terrain))
  for i = 1, #nbMesh do put(tostring(nbMesh[i])) end
  for _, p in ipairs(posed) do
@@ -540,7 +772,7 @@ end
 -- left out on purpose: thousands of tufts would cast a speckle no bigger
 -- than the pixels it lands on, at the cost of the mesh being drawn twice.
 local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh,
-                           atlasFor)
+                           atlasFor, water, nbWater)
  if not ShadowMap.available() then return end
  local sig = shadowSignature(terrain, nbMesh, posed, cx, cy, vw, vh)
  if not ShadowMap.stale(sig) then return end
@@ -551,6 +783,15 @@ local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh,
    ShadowMap.draw(nbMesh[i], atlasFor(nb.map),
                   Mat4.translate(nb.ox, 0, nb.oy))
  end
  -- The water surface, which the terrain mesh no longer carries (it is its
  -- own reflective pass now -- see Water). The sun still has to see it, or
  -- the map the light records has a hole at every lake and the frustum's
  -- far plane answers for the surface a shoreline tree's shadow falls on.
  ShadowMap.draw(water, atlasFor(state.map), nil)
  for i, nb in ipairs(state.neighbors or {}) do
    ShadowMap.draw(nbWater and nbWater[i], atlasFor(nb.map),
                   Mat4.translate(nb.ox, 0, nb.oy))
  end
  -- flower billboards live outside the terrain mesh (they draw after the
  -- characters, pulled -- see render), but the sun still sees them: a
  -- handful of cutouts per meadow, unlike the grass left out below.
@@ -563,6 +804,11 @@ local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh,
    ShadowMap.draw(ChunkMesher.flowers(nb.map), atlasFor(nb.map),
                   ShadowMap.snug(Mat4.translate(nb.ox, 0, nb.oy)))
  end
  -- From here down it is the CAST, marked as such in the map (see
  -- ShadowMap.sprites) so water can decline them: everything the world casts
  -- still shades a lake, a silhouette of somebody standing beside it does
  -- not. Ground, roofs and the characters themselves take them as before.
  ShadowMap.sprites(true)
  -- authored figures cast too, for the same reason the flowers do: a
  -- handful of cards per map, and a person with no shadow reads as pasted on
  eachFigure(state.map, 0, 0, function(mesh, _, caster)
@@ -575,7 +821,12 @@ local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh,
  end
  for _, p in ipairs(posed) do
    local def = p.sprite.def
-    local frame, mirror = frameFor(def, p.facing, p.phase, p.flip)
+    -- viewFacing, exactly as the camera draw picks it (see viewFacing for
    -- why the two passes must agree): in first person the sun's card
    -- swaps frame as the eye circles, which costs a redraw the signature
    -- already charges for (FirstPerson.signature) and keeps a card from
    -- fringing against a mirror-flipped record of itself
    local frame, mirror = frameFor(def, viewFacing(p), p.phase, p.flip)
    local mesh = SpriteBillboards.shadowQuad(def, frame)
    if mesh then
      ShadowMap.draw(mesh, p.sprite:resolveImage(),
@@ -584,6 +835,7 @@ local function castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh,
                                            mirror)))
    end
  end
  ShadowMap.sprites(false)
  ShadowMap.finish(sig)
 end
@@ -593,7 +845,7 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor)
  -- return nil: the engine keeps the 2D path for the frame and
  -- Voxel.ready holds the camera tween at flat, so the switch waits
  -- invisibly instead of freezing or tilting an empty stage.
-  local terrain, nbMesh = VoxelScene.prefetch(state)
+  local terrain, nbMesh, water, nbWater = VoxelScene.prefetch(state)
  if not terrain then return nil end
  local cam = state.camera
@@ -630,7 +882,24 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor)
  end
  local posed, me = posesOf(state, spriteColors)
-  castShadows(state, terrain, nbMesh, posed, cx, cy, vw, vh, atlasFor)
+
  -- The first-person rig, built (or blended) for this frame and handed to
  -- Voxel3D BEFORE either pass runs: the sun's box is fitted around this
  -- camera, and every card matrix asks it which way to turn. With the
  -- blend fully out the call clears the placed camera and the orbit is
  -- exactly what it always was. The scene centre it returns walks from
  -- the orbit's view centre into the head, so the curve's focus and the
  -- depth reference follow the camera actually in charge.
  local fpRig, fpCx, fpCy = FirstPerson.frame(me, cx, cy, vw, vh)
  if fpRig then cx, cy = fpCx, fpCy end
  -- The sun's box, pushed along the first-person look so it covers the
  -- ground THIS camera sees (a no-op at blend zero): the orbit's fit
  -- reaches far north and barely south, which is right for every rung
  -- but a head free to face south.
  local shCx, shCy = FirstPerson.shadowCenter(cx, cy, vh)
  castShadows(state, terrain, nbMesh, posed, shCx, shCy, vw, vh, atlasFor,
              water, nbWater)
  if not Voxel3D.beginScene(w, h, cx, cy, vw, vh, skyFor(state.map)) then
    return nil
@@ -652,12 +921,40 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor)
  if not Voxel3D.shadowsActive() then
    Voxel3D.beginShadows()
    for _, p in ipairs(posed) do
-      drawShadow(p.sprite, p.px, p.py, p.facing, p.phase, p.flip, p.gh,
+      drawShadow(p.sprite, p.px, p.py, viewFacing(p), p.phase, p.flip, p.gh,
                 p.lift)
    end
    Voxel3D.endShadows()
  end
  -- and the water over the top of it, reflecting everything just drawn plus
  -- the sky the frame opened with (see drawWater).
  --
  -- After the fallback decals deliberately: those are the stand-in drop
  -- shadows for a frame with no shadow map, they write no depth, and a
  -- lake would otherwise wear one as a black smear. Water covers them,
  -- which is the same answer the shadow map's own pass gives (see
  -- ShadowMap.sprites) -- people do not shadow water either way.
  local waterDraws = {}
  if water then
    waterDraws[#waterDraws + 1] = { water, atlasFor(state.map), nil }
  end
  for i, nb in ipairs(state.neighbors or {}) do
    if nbWater and nbWater[i] then
      waterDraws[#waterDraws + 1] = { nbWater[i], atlasFor(nb.map),
                                      Mat4.translate(nb.ox, 0, nb.oy) }
    end
  end
  -- the cast goes into the reflection copy only -- see drawWater for why it
  -- cannot be composited yet and why it is drawn through the same function
  -- the real pass below uses
  if #waterDraws > 0 then
    VoxelScene.drawWater(waterDraws, function()
      drawCast(state, posed, atlasFor)
    end)
  end
  -- Sprite sheets from here to the figure pass: their texture coordinates
  -- mean nothing to the tileset-shaped glass mask, so the glass is off or
  -- the panes' atlas positions stripe the cast with lamplight at night
@@ -670,7 +967,11 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor)
  -- wrote it, so the silhouette would paint over the player at all times.
  -- Every character then draws on top as usual, which leaves the silhouette
  -- showing in exactly one situation: where the world hides them.
-  if me then
+  --
  -- Not in first person: the card it silhouettes is the one the camera is
  -- standing inside, and "the world is in front of the player" is every
  -- wall the player faces.
  if me and not FirstPerson.hidePlayer() then
    Voxel3D.beginGhost()
    drawGhost(me)
    Voxel3D.endGhost()
@@ -689,33 +990,7 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor)
  -- drawEntity resolves the lean-over-the-wall-in-front case, and a
  -- character genuinely behind a building is far deeper and loses the
  -- test, so buildings and trees really occlude.
-  Voxel3D.seams(false)
+  drawCast(state, posed, atlasFor)
  for _, p in ipairs(posed) do
    drawEntity(p.sprite, p.px, p.py, p.facing, p.phase, p.flip, p.gh,
               p.colors, p.lift)
  end
  -- back on for everything textured from the atlas again -- figures, grass
  -- and flowers all sample it, where the mask's coordinates are honest
  Voxel3D.glass(true)
  -- Authored figures, alongside the characters and with the same lean and
  -- the same camera-ward pull -- they ARE characters as far as the artwork
  -- is concerned, just ones the tileset draws instead of a sprite sheet.
  -- Drawn after the walkers so a player standing in front of the couch
  -- wins the overlap, which is the order the flat game draws them in.
  local figPull = billboardPull()
  eachFigure(state.map, 0, 0, function(mesh, model, caster)
    Voxel3D.draw(mesh, atlasFor(state.map), model, figPull,
                 ShadowMap.snug(caster))
  end)
  for _, nb in ipairs(state.neighbors or {}) do
    eachFigure(nb.map, nb.ox, nb.oy, function(mesh, model, caster)
      Voxel3D.draw(mesh, atlasFor(nb.map), model, figPull,
                   ShadowMap.snug(caster))
    end)
  end
  -- and the seams are back on for the terrain art that follows: grass and
  -- flowers are the world's own drawing, not people
  Voxel3D.seams(true)
  -- tall grass last, pulled camera-ward exactly as far as the characters
  -- were (same per-vertex shader bias, so grass never drifts either):
  -- relative depth between a walker and the tuft row south of their feet
@@ -32,8 +32,18 @@ local Voxel = {}
 -- Its ANGLE is 35 degrees, the same as the rung of that name. The duplicate
 -- in the table is deliberate: the ladder is a list of what each rung LOOKS
 -- like, and two rungs may look the same while meaning different things.
-Voxel.ANGLES_DEG = { 0, 35, 15, 35, 50, 75 }
+--
-Voxel.ANGLE_LABELS = { "OFF", "FULL", "15", "35", "50", "75" }
+-- 1ST is the other rung that is more than an angle: the camera steps off its
 -- orbit entirely and stands in the player's own eyes (lib/FirstPerson.lua),
 -- with free look and free movement. Its ANGLE entry is 75 -- the orbit rung
 -- it hands over from -- because the tween in and out of first person starts
 -- from whatever the orbit shows, and the lowest rung is the one a dive into
 -- a head should start from. Everything angle-derived (the sky's fade, the
 -- billboard lean the blend eases away) reads that 75 while the first-person
 -- rig owns the actual camera.
 Voxel.ANGLES_DEG = { 0, 35, 15, 35, 50, 75, 75 }
 Voxel.ANGLE_LABELS = { "OFF", "FULL", "15", "35", "50", "75",
                       "1ST (EXPERIMENTAL)" }
 Voxel.MAX_LEVEL = #Voxel.ANGLES_DEG - 1
 -- the rung FULL sits on, so nothing has to hunt for it by label
@@ -43,6 +53,13 @@ function Voxel.isFull(level)
  return (level or Voxel.level) == Voxel.FULL_LEVEL
 end
 -- the rung the first-person camera sits on, likewise
 Voxel.FP_LEVEL = 6
 function Voxel.isFirstPerson(level)
  return (level or Voxel.level) == Voxel.FP_LEVEL
 end
 -- ------- what the hotkey walks
 --
 -- The ANGLE rungs only, with FULL left out. The key is a display-mode
@@ -51,7 +68,12 @@ end
 -- mid-walk, would silently turn the blur to maximum and flatten the horizon
 -- with no indication that a keypress had done so. FULL stays on the OPTIONS
 -- row, which is where a preset that changes other rows belongs.
-Voxel.HOTKEY_ORDER = { 0, 2, 3, 4, 5 }   -- OFF, 15, 35, 50, 75
+--
 -- 1ST is on the path: it changes the camera and only the camera, which is
 -- exactly what the key promises -- and the key is also the way back OUT of
 -- first person on a keyboard, where the mouse is captured and the OPTIONS
 -- menu is a trip.
 Voxel.HOTKEY_ORDER = { 0, 2, 3, 4, 5, 6 }   -- OFF, 15, 35, 50, 75, 1ST
 -- The rung a press moves to from `level`.
 --
@@ -23,9 +23,16 @@
 -- the engine's TILT mode -- is engine plumbing driven by the records
 -- below.  This file declares; lib/ draws.
 --
-- Nothing here reaches collision, movement, triggers or scripts.  Voxel
+-- Voxel mode is presentational: it changes what the world LOOKS like and
-- mode is purely presentational: it changes what the world LOOKS like and
+-- nothing about what it IS.  ONE rung is the deliberate exception. 1ST --
-- nothing about what it IS.
+-- the first-person camera -- replaces the grid WALK with a free,
 -- camera-relative one while it is selected (lib/FreeMove.lua), because a
 -- head 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 = ...
@@ -80,6 +87,11 @@ local WorldCurve = V.require("WorldCurve")
 local OverworldBattle = V.require("OverworldBattle")
 local BattleExit = V.require("BattleExit")
 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")
 -- Forward declaration: the voxel pipeline's update hook (registered below)
 -- calls this, and it is defined further down with the settings it drives.
@@ -159,6 +171,11 @@ mod.content.render_pipelines:register("voxel", {
    -- 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
@@ -201,20 +218,34 @@ mod.content.render_pipelines:register("voxel", {
    -- a magnified low-res image, while the FX closures keep drawing in
    -- world-pixel units.
    local sw, sh = sceneSize(ctx)
-    local canvas = VoxelScene.render(ctx.state, sw, sh,
+    -- 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 return nil end   -- fall back to the 2D path
    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)
+                 ctx.scale * AntiAlias.factor())
      Voxel3D.endOverlay()
    end
-    return canvas
+    -- 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.
    return AntiAlias.resolve(canvas, sw, sh, "world")
  end,
  invalidate = function()
    Voxel3D.invalidate()
    OverworldBattle.invalidate()
    AntiAlias.invalidate()
    ChunkMesher.invalidate()   -- no map id = every cached mesh
  end,
 })
@@ -281,13 +312,22 @@ applyFull = function(level)
  -- 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 rather than forced -- the row is gone from the
+  -- half of it is spent. Set and then LET GO of -- unlike the rows above, both
-  -- menu while FULL is on, but a save that already had it off gets it on.
+  -- 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
@@ -302,29 +342,69 @@ applyFull = function(level)
 end
 -- Whether a fight can be staged on the map, as far as the OPTIONS menu is
-- concerned: 3D-BTL is on, or FULL is selected -- which owns that row and
+-- concerned: the 3D-BTL row, and nothing else.
-- switches it on. Deliberately NOT gated on Voxel3D.available(): the engine
+--
-- offers a pipeline's row whether or not the hardware can run it
+-- It used to answer yes under FULL as well, on the grounds that FULL owned
-- (Pipelines.rows), so this mode's rows say ON on a machine without a depth
+-- that row and switched it on. FULL no longer owns it -- the row stays on the
-- buffer too, and a menu that claims 3D battles are on must not also offer the
+-- menu under FULL and can be switched off there (see the rows hook) -- so that
-- layout they cannot be drawn in.
+-- 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()
-  local Pipelines = require("src.render.Pipelines")
+  return OverworldBattle.enabled()
  return OverworldBattle.enabled() or Voxel.isFull(Pipelines.level("voxel"))
 end
 local SETTINGS = {
  { VoxelGrid.setting, "One-pixel wireframe along every voxel edge." },
  { 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." },
  -- `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.
  { OverworldBattle.setting,
    "Fight on the map: the battle draws over the nearest clear ground, "
-    .. "shot over the shoulder with a slow parallax drift." },
+    .. "shot over the shoulder with a slow parallax drift.",
    full = true },
  -- Only offered while a fight can actually be staged on the map: with 3D-BTL
  -- off the engine draws the classic screen, which is this row's ON already,
  -- and a row that no longer decides anything is worse than no row.
  { 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() end, full = true },
  { 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." },
  -- 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 },
 }
 local schema = {}
@@ -340,6 +420,7 @@ mod.options:define(schema)
 --   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,
@@ -354,9 +435,12 @@ mod.options:define(schema)
 -- 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. Both are still reachable on
+-- (3) and GBC FX (5) are unreachable by key -- and unreachable on the OPTIONS
-- the OPTIONS menu, and TILT is the one this mode supersedes anyway -- the
+-- menu too, where both rows are taken away and both values held at zero (see
-- registry already forces it off whenever a world pipeline takes the pass.
+-- 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
@@ -369,6 +453,7 @@ local HOTKEYS = {
  ["5"] = VoxelGrid.setting,
  ["7"] = WorldCurve.setting,
  ["8"] = OverworldBattle.setting,
  ["9"] = Water.setting,
 }
 do
@@ -418,19 +503,19 @@ do
          return
        end
      elseif Pipelines.canToggle("voxel", top, self.overworld) then
-        -- All three answer to the voxel pass's own free-roam gate --
+        -- 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. Two of them parameterise that
+        -- it would be for the mode itself. Three of them parameterise that
-        -- pass; the third (3D-BTL) decides what a battle is drawn over, and
+        -- 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 two keys
+        -- 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 three, so nothing here has to know which key it was.
+        -- for all of them, so nothing here has to know which key it was.
        if stagedBattles() then OverworldBattle.forceOG(self) end
        return
      end
@@ -464,10 +549,12 @@ local function insertGrouped(out, extra)
  return out
 end
-- FULL owns every one of those settings, so while it is selected they are
+-- FULL owns the settings that describe the LOOK, so while it is selected those
-- taken off the menu rather than left to be changed under it -- including
+-- 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
+-- T-SHIFT, which is a pipeline row the engine put there. A row that no longer
-- longer decides anything is worse than no row.
+-- 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
@@ -475,12 +562,50 @@ local function dropRow(out, id)
  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.
 local function pinEngineFx(game)
  game = game or require("src.core.Game")
  local opts = game and game.save and game.save.options
  local Tilt = require("src.render.Tilt")
  local GBCFX = require("src.render.GBCFX")
  local changed = false
  if opts then
    changed = (opts.tilt or 0) ~= 0 or (opts.gbcfx or 0) ~= 0
    opts.tilt, opts.gbcfx = 0, 0
  end
  pcall(Tilt.setLevel, 0)
  pcall(GBCFX.setLevel, 0)
  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")
  -- 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
@@ -492,14 +617,32 @@ mod.hooks:wrap("ui.options.rows", function(next, game, rows)
    OverworldBattle.forceOG(game)
    dropRow(out, "battleLayout")
  end
-  if Voxel.isFull(Pipelines.level("voxel")) then
+  local full = Voxel.isFull(Pipelines.level("voxel"))
-    -- FULL keeps every mod row off the menu (the early return skips the
+  if full then
-    -- insert below), and holds DAYTIME at SYNC while the row is unreachable
+    -- FULL owns the rows that PARAMETERISE the diorama -- the wireframe, the
    -- horizon bend, the blur, the hour -- so those come off the menu and
    -- DAYTIME is held at SYNC while its row is unreachable.
    DayNight.forceSync(game)
-    return dropRow(out, "pipeline:tiltshift")
+    dropRow(out, "pipeline:tiltshift")
  end
  local extra = {}
-  for _, entry in ipairs(SETTINGS) do extra[#extra + 1] = entry[1]:row() end
+  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 = (entry.full or not full)
                    and (not entry.when or entry.when())
    if offered then extra[#extra + 1] = entry[1]:row() end
  end
  return insertGrouped(out, extra)
 end)
@@ -660,6 +803,32 @@ end
 -- so this file keeps naming every engine seam the mod touches.
 OverworldBattle.install()
 -- ------- the first-person rung's inputs and its walk
 --
 -- 1ST needs two things no other rung does, and each is a named seam:
 --
 -- 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 (love.mousemoved --
 -- there is no Game handler to wrap; the engine's own callback only feeds
 -- the mouse-as-touch debug path, which stays untouched), 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 1ST is actually driving.
 --
 -- FreeMove.install wraps OverworldState:handleInput -- the one choke point
 -- where the grid walk reads the pad, and the same seam the engine's own
 -- Cycling Road pull lives behind. While 1ST drives, the walk is continuous
 -- and camera-relative; the player's logical cell stays synced and every
 -- per-cell consequence still runs through the engine's own machinery
 -- (onStepComplete, checkEdgeExit, checkLedgeHop, checkBoulderPush). The
 -- file argues the whole arrangement.
 FirstPerson.install()
 FreeMove.install()
 -- 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
@@ -714,6 +883,16 @@ mod.content.transitions:register(BattleExit.ID, {
 BattleExit.install()
 -- ------- 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
@@ -728,10 +907,16 @@ 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()
 end)
 mod.events:on("save.created", function()
  DayNight.restore()
  pinEngineFx()
 end)
 -- The engine's own time-of-day seam. OverworldState:timeOfDay() is an
@@ -745,7 +930,7 @@ mod.hooks:wrap("world.tod", function(next, tod, ctx)
  return DayNight.tod()
 end)
-mod.exports.version = "1.2.1"
+mod.exports.version = "1.5.0"
 -- 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
@@ -1,7 +1,7 @@
 {
  "id": "DRAMATIC_SHAPE",
  "name": "Dramatic Shape Voxel Mod",
-  "version": "1.2.1",
+  "version": "1.5.0",
  "api": 2,
  "entry": "main.lua",
  "profile": "content",
@@ -15,5 +15,6 @@
    "engine_internals"
  ],
  "affects_link": false,
-  "description": "A full 3D diorama overworld: extruded terrain, depth-buffered occlusion, voxel characters and a tilt-shift miniature pass -- and battles fought on the map itself, shot over the shoulder at the nearest clear ground with a slow parallax drift and a depth-of-field pass. Registers two render pipelines and claims hotkeys 3, 5, 6, 7 and 8 -- 3 and 5 displace the engine's TILT and GBC FX keys, both still reachable on the OPTIONS menu. Presentational only: it changes what a battle is drawn over, never where anybody stands."
+  "description": "A full 3D diorama overworld: extruded terrain, depth-buffered occlusion, voxel characters and a tilt-shift miniature pass -- and battles fought on the map itself, shot over the shoulder at the nearest clear ground with a slow parallax drift and a depth-of-field pass. Water reflects the sky, the sun, the moon and -- through a screen-space ray march -- the shoreline standing behind it. Registers two render pipelines and claims hotkeys 3, 5, 6, 7, 8 and 9 -- 3 and 5 displace the engine's TILT and GBC FX keys, both still reachable on the OPTIONS menu. Presentational only: it changes what a battle is drawn over, never where anybody stands.",
  "github": "DramaticShape/DramaticShapeVoxelMod"
 }
@@ -11,28 +11,39 @@ return {
      "with VOXEL on, the overworld draws as 3D geometry instead of flat tiles",
      "occlusion comes from a depth buffer rather than a y-sort, so buildings really hide what is behind them",
      "with 3D-BTL on, a battle draws over the map's nearest clear ground instead of over a white field",
      "the battle's text box and menu are frosted glass over that ground rather than an opaque white slab, on the same panels the HUDs sit on",
      "the map's NPCs are culled for the length of a battle, so the wipe plays over an empty map",
      "a battle's letterbox voids go black rather than white, because the battle canvas is no longer white",
-      "VOXEL and the engine's TILT are mutually exclusive -- turning one on switches the other off",
+      "the engine's TILT and GBC FX rows are taken OFF the OPTIONS menu and held at off for as long as this mod is installed -- TILT is the flat fake of what this mode does for real, GBC FX is a full-screen pass over the top of it; uninstalling puts both rows back",
-      "hotkeys 3 and 5 are taken over from the engine's TILT and GBC FX; both remain on the OPTIONS menu",
+      "hotkeys 3 and 5 are taken over from those two, which have no key and no row while this is loaded",
-      "the VOXEL key (3) turns TILT and GBC FX off on every press -- both fight the diorama, and 3 is now the only key that reaches either",
+      "on the 1ST rung ONLY, the grid walk is replaced by free camera-relative movement: collision, warps, ledges, encounters and scripts still run through the engine's own machinery, and every other rung leaves movement untouched",
      "on the 1ST rung the mouse cursor is captured for free look; left click is A, right click is B, and any touch off the overlay's controls drags the view",
    },
    added = {
-      "VOXEL options row and hotkey 3 (OFF / 15 / 35 / 50 / 75 degrees)",
+      "VOXEL options row and hotkey 3 (OFF / 15 / 35 / 50 / 75 degrees / 1ST, a first-person camera with free look and free movement)",
      "T-SHIFT options row and hotkey 6 (OFF / 1 / 2 / 3), the miniature blur",
      "V-GRID on hotkey 5 and V-CURVE on hotkey 7",
      "WATER on hotkey 9 (FULL / SKY / OFF, FULL by default): the water surface becomes a field of pixel-tall voxel columns rising and falling as waves, reflecting the sky, the sun, the moon and the cast standing beside it -- and, on FULL, the shoreline, trees and buildings behind it, by a screen-space ray march",
      "3D-BTL on hotkey 8 (ON / OFF, on by default), battles fought on the world map",
      "BACK SPRITES options row (OFF / ON, off by default), which keeps your own Pokemon on the battle menu in its classic slot while the foe stands out on the map",
      "a day/night clock that reaches the flat 2D overworld as well as the diorama -- outdoor maps only, and only when the hour is not midday",
      "an over-the-shoulder battle camera on a slow parallax orbit, with a depth-of-field pass that holds both mons sharp",
      "a sky behind the diorama at the 75-degree rung, outdoor maps only, coloured by the active palette mode",
      "a hand-authored tile shape profile (data/voxel_heights.lua) a mod can extend",
    },
    known = {
      "needs shader and depth-canvas support; without them the rows still cycle but the world stays 2D and battles draw plainly",
      "water reflections additionally need a READABLE depth canvas; a driver without one draws the flat animated water this mode always drew",
      "WATER on FULL ray-marches the depth buffer per water pixel, so a map that is mostly sea costs real fill rate on a weak GPU -- SKY is the same look minus the ray march, and OFF is the flat water",
      "a screen-space reflection can only reflect what is in the frame: a tree just off the top edge is not in the water below it, and a ray that runs off the side fades into the sky rather than ending on a line",
      "a map with no 3x6 clearing falls back to a 1x4 one, and a map with neither draws the plain battle screen",
      "the arena is where the CAMERA goes -- nobody is moved, so a fight staged across the map is a shot of that ground, not a trip to it",
      "the battle backdrop renders at the GB's 160x144 to match the pics composited over it, so it is chunkier than the free-roam pass",
      "menus and cutscenes are unaffected -- outside a battle the mode only draws the free-roam overworld",
      "terrain meshes are cached per map, so the first frame after entering a large map costs a build",
      "1ST needs the 3D pass like every rung; without it the level still persists but the world stays 2D and the grid walk stays in charge",
      "in 1ST, scripted walks, ledge hops and spinner slides play out as the grid moves they are, with the camera riding along; free control resumes when they land",
      "rooms have no ceilings, so a first-person look over an interior wall shows the void the diorama always had behind it",
    },
  },
  credits = {
@@ -0,0 +1,195 @@
 -- Driver: one scene, once per rung of the AA row.
 --
 -- The AA row is the one setting in this mod whose whole effect is a pixel
 -- wide, so it is also the one that cannot be judged from a description. This
 -- renders the SAME frame at each rung and writes one PNG per rung; put two of
 -- them side by side, magnified, and the row is either doing something or it
 -- is not.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/aa_shots.lua \
 --   SHOT_DIR=<dir> lovec.exe .
 --
 -- knobs (env):
 --   SHOT_DIR   output directory (created if missing)  (default "shots/aa")
 --   AA_MAP     map id                                 (default VIRIDIAN_CITY)
 --   AA_SPOT    "x,y[,facing]"                         (default 20,26,up)
 --   AA_RUNG    the voxel camera rung                  (default 5, the 75 one)
 --
 -- The scene defaults to a town at the LOW camera on purpose: roof ridges, the
 -- diagonal of a fence and a tree's silhouette against the sky are the edges
 -- that stair-step, and 75 degrees is the rung that puts the most of them at an
 -- angle to the pixel grid.
 --
 -- Determinism matters here for the same reason it does in voxel_shots_ab: the
 -- three shots differ ONLY by the row under test, or comparing them means
 -- nothing. The clock is pinned, the animated tile slots are frozen, the
 -- townsfolk are stopped where they stand, and the tilt-shift is held at zero
 -- (a gaussian over the frame would smear away the very edges being looked at).
 --
 -- Nothing here writes the player's options: the row is moved with
 -- ModSetting:sync, which moves the cached index and persists nothing.
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local OverworldState = require("src.world.OverworldController")
  local ROOT = os.getenv("SHOT_DIR") or "shots/aa"
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[aa] DRAMATIC_SHAPE mod not loaded -- nothing to shoot")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local AntiAlias = V.require("AntiAlias")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  local ShadowMap = V.require("ShadowMap")
  local MAP = os.getenv("AA_MAP") or "VIRIDIAN_CITY"
  local SPOT = os.getenv("AA_SPOT") or "20,26,up"
  local RUNG = math.floor(tonumber(os.getenv("AA_RUNG")) or 5)
  local sx, sy, sf = SPOT:match("^(%-?%d+),%s*(%-?%d+),?%s*(%a*)$")
  sx, sy = tonumber(sx) or 20, tonumber(sy) or 26
  if sf == "" then sf = "up" end
  OverworldState.rollEncounter = function() return nil end
  local NPC = require("src.world.NPC")
  if not NPC.dramaticShapeAaFreeze then
    local inner = NPC.update
    function NPC:update(...)
      self.frozen = true
      return inner(self, ...)
    end
    NPC.dramaticShapeAaFreeze = true
  end
  pcall(love.math.setRandomSeed, 20260801)
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function cameraStill()
    local o = game.overworld
    local c = o and o.camera
    if not c then return true end
    local lx, ly, held = nil, nil, 0
    for _ = 1, 300 do
      if c.x == lx and c.y == ly then
        held = held + 1
        if held >= 10 then return true end
      else
        held = 0
        lx, ly = c.x, c.y
      end
      U.wait(1)
    end
    return false
  end
  -- The camera PITCH, which is the one that caught this driver out. The tween
  -- runs on wall-clock dt and Voxel.t reaching 1 is not the same instant the
  -- angle stops moving, so the first shot of a run came out at 67 degrees
  -- while the two after it were at 75 -- three frames that differ by the
  -- camera, in a comparison whose entire subject is a pixel.
  local function angleStill()
    local last, held = nil, 0
    for _ = 1, 600 do
      if Voxel.angle == last then
        held = held + 1
        if held >= 10 then return true end
      else
        held = 0
        last = Voxel.angle
      end
      U.wait(1)
    end
    return false
  end
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    angleStill()
    cameraStill()
    -- the sun map is only redrawn when its inputs move, and the AA row is not
    -- one of them -- so force one pass at the settled camera rather than
    -- comparing a frame against a map fitted a few hundredths of a pixel ago
    if ShadowMap.forget then ShadowMap.forget() end
    U.wait(20)
  end
  DayNight.setting:sync("day")
  U.teleport(game, MAP, sx, sy, sf)
  Pipelines.setLevel("voxel", RUNG)
  Pipelines.setLevel("tiltshift", 0)
  -- Warm up before the FIRST shot, not just between them.
  --
  -- Neighbour maps are requested from inside the render itself
  -- (VoxelScene.prefetch), so an empty build queue right after a teleport
  -- means "nothing has been asked for yet", not "everything is here". The
  -- first capture of a run came out with the map beyond Viridian missing --
  -- a whole tree line absent from one frame of a three-way comparison, which
  -- looks exactly like the row under test doing something enormous. Settling
  -- twice lets the first render request the neighbourhood and the second
  -- drain it.
  settle()
  settle()
  local shots, missed = 0, 0
  for _, samples in ipairs({ 0, 2, 4 }) do
    AntiAlias.setting:sync(samples)
    settle()
    -- AA_TRACE=1 prints the state each shot was taken in. When two shots of a
    -- run disagree by more than the row could account for, this is what says
    -- which input moved -- it is how the camera-tween and the neighbour-mesh
    -- settles above were both found.
    if os.getenv("AA_TRACE") == "1" then
      local Voxel3D = V.require("Voxel3D")
      local o = game.overworld
      local cw, chh = Voxel3D.size()
      print(("[aa] trace samples=%d angle=%.6f fov=%.6f cell=%.4f canvas=%dx%d cam=(%.3f,%.3f) eye=(%.2f,%.2f,%.2f) factor=%.4f")
        :format(samples, Voxel.angle or -1, Voxel3D.fovY or -1,
                Voxel3D.cell or -1, cw or 0, chh or 0,
                o and o.camera and o.camera.x or -1,
                o and o.camera and o.camera.y or -1,
                (Voxel3D.eye or {})[1] or 0, (Voxel3D.eye or {})[2] or 0,
                (Voxel3D.eye or {})[3] or 0, AntiAlias.factor()))
    end
    local path = ("%s/aa_%d.png"):format(ROOT, samples)
    game.capturePath = path
    U.wait(6)
    local f = io.open(path, "rb")
    if f then
      f:close()
      shots = shots + 1
      print(("[aa] %s  samples=%d"):format(path, samples))
    else
      missed = missed + 1
      print("[aa] capture did not reach disk: " .. path)
    end
  end
  -- left where it was found, so a run cannot leak a rung into the next one
  AntiAlias.setting:sync(0)
  print(("[aa] %d shots into %s (%d failed to reach disk)")
    :format(shots, ROOT, missed))
 end
@@ -0,0 +1,79 @@
 -- Scratch driver: shots of the Bike Shop showroom, for the bicycle
 -- voxelization.  Two viewpoints -- the north wall (the two bikes drawn
 -- INTO the wall band) and the showroom floor (the six standing bikes).
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/bike_shop_shots.lua \
 --   SHOT_DIR=.scratchpad/bikes AB_TAG=before lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/bikes")
    .. "/" .. (os.getenv("AB_TAG") or "before")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[bike] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  -- cells: wall bikes ride cell row 0 (tile cols 1-3 and 6-8); the six
  -- floor bikes stand in cell columns 0 and 2, rows 1-2 and 4-5
  local SCENES = {
    { x = 2, y = 2, face = "up",   label = "wall" },
    { x = 3, y = 3, face = "up",   label = "room" },
    { x = 2, y = 4, face = "left", label = "floor" },
    { x = 3, y = 6, face = "up",   label = "wide" },
    -- the two toolboxes, cells (6,6) and (7,7)
    { x = 5, y = 6, face = "right", label = "tools" },
    { x = 6, y = 4, face = "down",  label = "tools2" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, "BIKE_SHOP", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[bike] capture missed: " .. path) end
    end
  end
  print(("[bike] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,77 @@
 -- Scratch driver: shots of Bill's desk, for the `bills_desk`
 -- voxelization.  The desk fills cells (1,4) and (2,4) of Bill's house
 -- with its chair in the walkable cell (1,5) below it, so these are the
 -- angles you can actually stand at: head-on from the floor two cells
 -- south, and from either flank.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/bills_desk_shots.lua \
 --   SHOT_DIR=.scratchpad/billsdesk AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/billsdesk")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[bills] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { x = 1, y = 6, face = "up",    label = "headon" },
    { x = 2, y = 6, face = "up",    label = "headon_e" },
    { x = 4, y = 5, face = "left",  label = "east" },
    { x = 0, y = 5, face = "right", label = "west" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, "BILLS_HOUSE", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[bills] capture missed: " .. path) end
    end
  end
  print(("[bills] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,81 @@
 -- Scratch driver: shots of the Celadon chief's house, for the display
 -- cabinet and long table voxelizations.  Three viewpoints -- the
 -- cabinet rank along the north wall, the long table in the middle of
 -- the room, and a wide shot with both in frame.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/chief_house_shots.lua \
 --   SHOT_DIR=.scratchpad/chief AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/chief")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[chief] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  -- the cabinets occupy cells 2..5 of rows 0-1; the long table cells
  -- 2..5 of rows 3-4; the player walks rows 2 and 5
  local SCENES = {
    { x = 3, y = 2, face = "up",    label = "cabinets" },
    { x = 5, y = 2, face = "up",    label = "bookcase" },
    { x = 3, y = 5, face = "up",    label = "table" },
    { x = 1, y = 5, face = "right", label = "wide" },
    -- the same rank on CELADON_MANSION_1F, where it stands against the
    -- interior partition and the grids start on an ODD tile row
    { map = "CELADON_MANSION_1F", x = 2, y = 4, face = "up",
      label = "mansion1f" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, s.map or "CELADON_CHIEF_HOUSE", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[chief] capture missed: " .. path) end
    end
  end
  print(("[chief] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,159 @@
 -- Scratch driver: shots of the 1ST (first-person) rung -- the rig standing
 -- in the player's head, billboards yawing to face it, the sky meeting the
 -- horizon, the shadow box following the look, water seen from eye level,
 -- and an interior with its figures.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/fp_shots.lua \
 --   SHOT_DIR=.scratchpad/fpshots lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/fp")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[fp] DRAMATIC_SHAPE mod not loaded")
    return love.event.quit()
  end
  local V = handle.lib
  local FirstPerson = V.require("FirstPerson")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  local DayNight = V.require("DayNight")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 0
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if FirstPerson.blend >= 1 and Voxel.ready
         and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  -- Teleport to the nearest WALKABLE cell: a guessed coordinate inside a
  -- building footprint buries the eye in the geometry, which is what the
  -- first cut of every Pallet shot did.
  local function place(mapId, x, y)
    U.teleport(game, mapId, x, y, "down")
    local ow = game.stack:top()
    local map = ow and ow.map
    if not map or map:isWalkableCell(x, y) then return end
    for r = 1, 8 do
      for dy = -r, r do
        for dx = -r, r do
          if math.max(math.abs(dx), math.abs(dy)) == r then
            local cx, cy = x + dx, y + dy
            if map:inBounds(cx, cy) and map:isWalkableCell(cx, cy) then
              U.teleport(game, mapId, cx, cy, "down")
              print(("[fp] (%d,%d) not walkable; standing at (%d,%d)")
                    :format(x, y, cx, cy))
              return
            end
          end
        end
      end
    end
  end
  -- yaw is a world bearing: 0 south, pi/2 east, pi north, -pi/2 west
  local SCENES = {
    -- Pallet Town, mid-street: houses, the lab, NPCs -- the town seen
    -- from inside it, in each compass direction plus a diagonal
    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi, label = "pallet_north" },
    { map = "PALLET_TOWN", x = 13, y = 14, yaw = 0, label = "pallet_south" },
    { map = "PALLET_TOWN", x = 9, y = 7, yaw = math.pi / 2, label = "pallet_east" },
    { map = "PALLET_TOWN", x = 9, y = 7, yaw = 3 * math.pi / 4,
      label = "pallet_diag" },
    -- the shoreline: water at eye level, which is where the battle pass
    -- says a low placed camera reads the reflection wrong -- the shot
    -- decides whether 1ST keeps it
    { map = "PALLET_TOWN", x = 9, y = 12, yaw = 0, label = "pallet_water" },
    -- looking up: the sky's bands and the horizon line
    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi,
      pitch = -math.rad(25), label = "pallet_skyward" },
    -- and down: the ground, the feet-level shadow
    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi,
      pitch = math.rad(45), label = "pallet_down" },
    -- Route 1: grass rows and ledges from inside them
    { map = "ROUTE_1", x = 10, y = 28, yaw = math.pi, label = "route1_north" },
    -- an interior: the Center's counter, machines and couch figures
    { map = "VIRIDIAN_POKECENTER", x = 3, y = 5, yaw = math.pi,
      label = "center_north" },
    { map = "VIRIDIAN_POKECENTER", x = 6, y = 4, yaw = -math.pi / 2,
      label = "center_west" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    place(s.map, s.x, s.y)
    Pipelines.setLevel("voxel", Voxel.FP_LEVEL)
    Pipelines.setLevel("tiltshift", 0)
    settle()
    FirstPerson.yaw = s.yaw
    FirstPerson.pitch = s.pitch or FirstPerson.PITCH_DEFAULT
    U.wait(20)
    if U.shot(game, ("%s/%s.png"):format(ROOT, s.label)) then
      shots = shots + 1
    end
  end
  -- one mid-blend shot: step the ladder onto 1ST from 75 and catch the
  -- dive halfway
  place("PALLET_TOWN", 13, 14)
  Pipelines.setLevel("voxel", 5)
  settle()
  Pipelines.setLevel("voxel", Voxel.FP_LEVEL)
  for _ = 1, 300 do
    if FirstPerson.blend >= 0.5 then break end
    U.wait(1)
  end
  if U.shot(game, ROOT .. "/blend_mid.png") then shots = shots + 1 end
  -- ------- the free walk, exercised
  --
  -- Hold forward with the head yawed off-grid and confirm the player
  -- GLIDES: the position moves along the look direction, lands off the
  -- 16px grid (which no grid step can do), and the logical cell follows.
  place("PALLET_TOWN", 13, 14)
  Pipelines.setLevel("voxel", Voxel.FP_LEVEL)
  settle()
  local ow = game.stack:top()
  local p = ow.player
  FirstPerson.yaw = 3 * math.pi / 4       -- northeast, deliberately off-grid
  FirstPerson.pitch = FirstPerson.PITCH_DEFAULT
  local x0, y0, c0x, c0y = p.px, p.py, p.cellX, p.cellY
  U.hold(game, "up", 90)
  U.wait(5)
  local moved = math.abs(p.px - x0) + math.abs(p.py - y0)
  print(("[fp] walk: (%.1f,%.1f) cell(%d,%d) -> (%.1f,%.1f) cell(%d,%d)")
        :format(x0, y0, c0x, c0y, p.px, p.py, p.cellX, p.cellY))
  print(("[fp] walk moved %.1f px; off-grid: %s; diagonal: %s")
        :format(moved,
                tostring(p.px % 16 ~= 0 or p.py % 16 ~= 0),
                tostring(math.abs(p.px - x0) > 8
                         and math.abs(p.py - y0) > 8)))
  if U.shot(game, ROOT .. "/walked.png") then shots = shots + 1 end
  print(("[fp] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,78 @@
 -- Scratch driver: shots of the Pokemon Center healing machines behind
 -- the counter, for the center_heal_machine voxelization.  The pair
 -- stands at cells (1,0):(2,1) and (6,0):(7,1) of every Center; the
 -- nurse aisle (row 2) is the row you can actually face them from, and
 -- the public floor south of the counter gives the wide view.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/heal_machine_shots.lua \
 --   SHOT_DIR=.scratchpad/healshots AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/healmachine")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[heal] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { x = 1, y = 2, face = "up",   label = "west_head" },
    { x = 2, y = 2, face = "up",   label = "west_keyboard" },
    { x = 3, y = 2, face = "left", label = "west_side" },
    { x = 6, y = 2, face = "up",   label = "east_head" },
    { x = 3, y = 4, face = "up",   label = "wide" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, "VIRIDIAN_POKECENTER", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[heal] capture missed: " .. path) end
    end
  end
  print(("[heal] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,98 @@
 -- Scratch driver: shots of the house dining tables and stools, for the
 -- band-table + no-desk-part voxelization.  Every generic home places the
 -- table at cells (3,3):(4,4) with four stools around it (Blue's house has
 -- Daisy seated at hers); Red's and the Copycat's ground floors place the
 -- same furniture one cell lower, with the potted plant CUTOUT standing on
 -- the tabletop -- the standee the table template must support, not
 -- swallow.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/house_furniture_shots.lua \
 --   SHOT_DIR=.scratchpad/housefurn AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/housefurn")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[housefurn] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    -- head on: below Blue's table looking north over a stool at it,
    -- Daisy seated at the left one
    { map = "BLUES_HOUSE", x = 3, y = 5, face = "up", label = "blues_front" },
    -- from the east, table and both east stools in profile
    { map = "BLUES_HOUSE", x = 6, y = 3, face = "left", label = "blues_side" },
    -- from the north wall looking south down over the tabletop
    { map = "BLUES_HOUSE", x = 4, y = 2, face = "down", label = "blues_over" },
    -- close beside a stool: seat top, legs and the gap between them
    { map = "BLUES_HOUSE", x = 2, y = 5, face = "up", label = "stool_close" },
    -- Red's table head on from the south: the plant cutout standing on
    -- the modelled tabletop
    { map = "REDS_HOUSE_1F", x = 4, y = 6, face = "up", label = "reds_front" },
    -- and from the east along the stool row, plant in profile
    { map = "REDS_HOUSE_1F", x = 6, y = 4, face = "left", label = "reds_side" },
    -- the Fan Club's four members' chairs round the boardroom table:
    -- from the south of the west pair, both stools stacked in profile
    { map = "POKEMON_FAN_CLUB", x = 1, y = 5, face = "up",
      label = "club_west_pair" },
    -- across the table from the west, both pairs and the octagon between
    { map = "POKEMON_FAN_CLUB", x = 0, y = 3, face = "right",
      label = "club_across" },
    -- close on the east pair from the north, looking down over the seats
    { map = "POKEMON_FAN_CLUB", x = 6, y = 2, face = "down",
      label = "club_over" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, s.map, s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[housefurn] capture missed: " .. path) end
    end
  end
  print(("[housefurn] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,76 @@
 -- Scratch driver: shots of a Poke Mart's clerk counter, for the cash
 -- register voxelization.  The register is drawn at cell (1,5) of the 4x4
 -- shop layout every Mart shares, in the middle of the counter's east arm,
 -- so these are the three angles you can actually stand at: head-on from
 -- the aisle, side-on from the east, and over the counter's south arm.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/mart_shots.lua \
 --   SHOT_DIR=.scratchpad/register AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/register")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[mart] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { x = 1, y = 7, face = "up",   label = "aisle" },
    { x = 2, y = 5, face = "left", label = "side" },
    { x = 2, y = 6, face = "left", label = "over" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, "VIRIDIAN_MART", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[mart] capture missed: " .. path) end
    end
  end
  print(("[mart] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,71 @@
 -- Driver: one overworld-battle screenshot per species, the mon fighting
 -- ITSELF -- its back pic on the player's mark and its front pic on the
 -- enemy's, so a single frame shows both sprites the 3D mode draws for it.
 --
 -- The point is a visual sweep for pic glitches (holes the paper-fill missed,
 -- a silhouette cut wrong, a pin that leaves the mon floating), so every shot
 -- is staged identically: same map, same cells, same beat -- the battle menu,
 -- both HUD panels up. Whatever differs between two shots is the mon.
 --
 --   SHOT_DIR=.scratchpad/mon_shots \
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/mon_shots.lua love .
 --
 -- Files land as NNN_species.png in dex order.
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local DIR = os.getenv("SHOT_DIR") or ".scratchpad/mon_shots"
  local Pokemon = require("src.pokemon.Pokemon")
  local BattleState = require("src.battle.BattleState")
  -- every real species the merged data carries, walked in dex order
  local species = {}
  for id, def in pairs(game.data.pokemon) do
    if type(id) == "string" and type(def) == "table"
       and def.dex and def.dex >= 1 and def.dex <= 151 then
      species[#species + 1] = { id = id, dex = def.dex }
    end
  end
  table.sort(species, function(a, b) return a.dex < b.dex end)
  U.log(("%d species"):format(#species))
  game.save.player.name = "RED"
  for _, s in ipairs(species) do
    -- level 50 both sides: high enough that nothing about the staging is
    -- species-specific, and a wild battle never awards exp off a menu shot
    game.save.party = { Pokemon.new(game.data, s.id, 50) }
    U.teleport(game, "ROUTE_1", 5, 8, "down")
    -- let the neighbourhood's meshes land so the first battle frame is the
    -- real arena rather than the flat fallback
    U.wait(60)
    local battle = BattleState.newWild(game, s.id, 50)
    battle.onFinish = function() end
    game.overworld:pushBattle(battle)
    -- the wipe, then tap through "Wild X appeared!" and the send-out until
    -- the battle MENU is actually up -- a fixed tap count lands on whatever
    -- beat the intro happened to be on, which is how a shot ends up with the
    -- trainer still standing where the mon should be
    U.wait(70)
    for _ = 1, 200 do
      if battle.phase == "menu" then break end
      U.tap(game, "a")
      U.wait(6)
    end
    if battle.phase ~= "menu" then
      U.log(("STUCK before menu: %s (phase %s)"):format(s.id, tostring(battle.phase)))
    end
    -- let the send-out slide/ball beat finish so the mon is standing still
    U.wait(40)
    U.shot(game, ("%s/%03d_%s.png"):format(DIR, s.dex, s.id:lower()))
    while game.stack:top() and game.stack:top() ~= game.overworld do
      game.stack:pop()
    end
    U.wait(10)
  end
  U.log("done -- " .. DIR)
 end
@@ -0,0 +1,63 @@
 -- Driver: dump the exact pic textures a live 3D battle draws, per stage --
 -- the sprite as loaded (raw) and what picImage hands the billboard after the
 -- palette bake and BattlePics' paper fill (final). Diagnostic for pics that
 -- render with holes: whichever stage the transparency first appears in is
 -- the stage that made it.
 --
 --   SHOT_DIR=.scratchpad/pic_dump \
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/pic_dump.lua love .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local DIR = os.getenv("SHOT_DIR") or ".scratchpad/pic_dump"
  local Pokemon = require("src.pokemon.Pokemon")
  local BattleState = require("src.battle.BattleState")
  local function save(img, path)
    if not img then U.log("NIL image for " .. path) return end
    local w, h = img:getDimensions()
    local g = love.graphics
    local prev = g.getCanvas()
    local canvas = g.newCanvas(w, h, { dpiscale = 1 })
    g.setCanvas(canvas)
    g.clear(0, 0, 0, 0)
    g.setBlendMode("replace", "premultiplied")
    g.setColor(1, 1, 1, 1)
    g.draw(img, 0, 0)
    g.setCanvas(prev)
    g.setBlendMode("alpha")
    local f = assert(io.open(path, "wb"))
    f:write(canvas:newImageData():encode("png"):getString())
    f:close()
  end
  local SPECIES = os.getenv("PIC_SPECIES")
  local list = {}
  if SPECIES then
    for id in SPECIES:gmatch("[^,%s]+") do list[#list + 1] = id:upper() end
  else
    list = { "PIKACHU", "SEEL", "BULBASAUR", "MEWTWO" }
  end
  for _, id in ipairs(list) do
    game.save.party = { Pokemon.new(game.data, id, 50) }
    U.teleport(game, "ROUTE_1", 5, 8, "down")
    U.wait(30)
    local battle = BattleState.newWild(game, id, 50)
    battle.onFinish = function() end
    game.overworld:pushBattle(battle)
    U.wait(80)
    local lo = id:lower()
    save(battle.enemy.sprite, ("%s/%s_front_raw.png"):format(DIR, lo))
    save(battle:picImage(battle.enemy.sprite), ("%s/%s_front_final.png"):format(DIR, lo))
    save(battle.player.sprite, ("%s/%s_back_raw.png"):format(DIR, lo))
    save(battle:picImage(battle.player.sprite), ("%s/%s_back_final.png"):format(DIR, lo))
    U.log("dumped " .. id)
    while game.stack:top() and game.stack:top() ~= game.overworld do
      game.stack:pop()
    end
    U.wait(5)
  end
  U.log("done -- " .. DIR)
  love.event.quit()
 end
@@ -0,0 +1,91 @@
 -- Scratch driver: shots of the potted plants, for the plant standee
 -- voxelization.  Every Center places three side-by-side pairs on its
 -- bottom row -- crowns at cells (0,6)/(1,6), (6,6)/(7,6), (12,6)/(13,6),
 -- pots below at y=7 -- and INDIGO_PLATEAU_LOBBY (the MART tileset id,
 -- same atlas) lines four of them along its hall at cells (12,10)..(15,10).
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/potted_plant_shots.lua \
 --   SHOT_DIR=.scratchpad/plants AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/plants")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[plant] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    -- east of the left pair, looking west along the bottom row: both
    -- plants in profile, crown overhang and pot silhouette side-on
    { map = "VIRIDIAN_POKECENTER", x = 3, y = 6, face = "left",
      label = "pair_side" },
    -- north of the left pair, looking south down over the crowns
    { map = "VIRIDIAN_POKECENTER", x = 1, y = 5, face = "down",
      label = "pair_over" },
    -- head on: standing below the middle pair looking north at it
    { map = "VIRIDIAN_POKECENTER", x = 6, y = 7, face = "up",
      label = "pair_front" },
    -- close up beside the east pair's pot
    { map = "VIRIDIAN_POKECENTER", x = 11, y = 7, face = "right",
      label = "close" },
    -- the Plateau lobby's row of four (MART tileset id), along the row
    { map = "INDIGO_PLATEAU_LOBBY", x = 11, y = 10, face = "right",
      label = "lobby_row" },
    -- and head on from the hall below
    { map = "INDIGO_PLATEAU_LOBBY", x = 13, y = 12, face = "up",
      label = "lobby_front" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, s.map, s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[plant] capture missed: " .. path) end
    end
  end
  print(("[plant] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,80 @@
 -- Scratch driver: the Cerulean gym and the houses beside it, shot at
 -- several camera rungs with V-CURVE walked OFF..3, to see what the world
 -- bend does to a building's roof.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/roof_curve_shots.lua \
 --   SHOT_DIR=.scratchpad/roofcurve AB_TAG=before lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/roofcurve")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[roof] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  local WorldCurve = V.require("WorldCurve")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(30)
  end
  -- the gym door is CERULEAN_CITY (30,19); the bike shop and the row of
  -- houses along the west side give a second, smaller roof in frame
  local SCENES = {
    { map = "CERULEAN_CITY", x = 30, y = 20, face = "up",   label = "gym" },
    { map = "CERULEAN_CITY", x = 27, y = 21, face = "up",   label = "gymwide" },
    { map = "PALLET_TOWN",   x = 5,  y = 6,  face = "up",   label = "house" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      for _, curve in ipairs({ 0, 3 }) do
        U.teleport(game, s.map, s.x, s.y, s.face)
        Pipelines.setLevel("voxel", rung)
        Pipelines.setLevel("tiltshift", 0)
        WorldCurve.setting:setIndex(curve + 1, game)
        settle()
        local path = ("%s/%s_v%d_c%d.png"):format(ROOT, s.label, rung, curve)
        game.capturePath = path
        U.wait(8)
        local f = io.open(path, "rb")
        if f then f:close() shots = shots + 1
        else print("[roof] capture missed: " .. path) end
      end
    end
  end
  print(("[roof] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,47 @@
 -- Scratch probe: how long do a building model's merged quads get?
 --
 -- A quad's longest world-space edge is what decides how far its CHORD
 -- falls below the world curve's parabola, so this is the number that says
 -- whether the bend can crack the mesh open.
 --
 --   BUILD_MAP=CERULEAN_CITY POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/roof_span_probe.lua lovec .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local mapId = os.getenv("BUILD_MAP") or "CERULEAN_CITY"
  U.teleport(game, mapId, tonumber(os.getenv("BUILD_X") or "30"),
             tonumber(os.getenv("BUILD_Y") or "20"), "up")
  U.wait(30)
  local V = game.mods.exports["DRAMATIC_SHAPE"]
  V = V and V.lib
  local Structures = V and V.require("Structures")
  local ow = game.overworld
  if not (Structures and ow and ow.map) then
    print("[span] mod or map unavailable")
    love.event.quit()
    return
  end
  local S = Structures.forMap(ow.map)
  local hist, worst = {}, 0
  for _, q in ipairs(S.objectQuads) do
    local dx = math.max(q[1][1], q[2][1], q[3][1], q[4][1])
             - math.min(q[1][1], q[2][1], q[3][1], q[4][1])
    local dz = math.max(q[1][3], q[2][3], q[3][3], q[4][3])
             - math.min(q[1][3], q[2][3], q[3][3], q[4][3])
    local dy = math.max(q[1][2], q[2][2], q[3][2], q[4][2])
             - math.min(q[1][2], q[2][2], q[3][2], q[4][2])
    local span = math.max(dx, dz, dy)
    local bucket = span <= 8 and "<=8" or (span <= 16 and "<=16"
                  or (span <= 32 and "<=32" or (span <= 64 and "<=64" or ">64")))
    bucket = bucket .. (q.own and " bld" or " prop")
    hist[bucket] = (hist[bucket] or 0) + 1
    if span > worst then worst = span end
  end
  print(("[span] %d object quads, longest edge %d px"):format(#S.objectQuads, worst))
  for _, b in ipairs({ "<=8", "<=16", "<=32", "<=64", ">64" }) do
    for _, kind in ipairs({ " bld", " prop" }) do
      print(("[span]   %-10s %d"):format(b .. kind, hist[b .. kind] or 0))
    end
  end
  love.event.quit()
 end
@@ -0,0 +1,75 @@
 -- Scratch driver: one shot of every OTHER user of the round-hull builder
 -- (tree canopies, boulders, hedges, stumps, the Center planter), to check
 -- that the `can` class's base cut is the identity it is supposed to be for
 -- everything that does not ask for it.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/round_regress_shots.lua \
 --   SHOT_DIR=.scratchpad/round AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/round")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then return end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { map = "VIRIDIAN_FOREST", x = 16, y = 20, face = "up",   label = "forest" },
    { map = "PEWTER_GYM",      x = 4,  y = 10, face = "up",   label = "boulders" },
    { map = "CELADON_GYM",     x = 4,  y = 8,  face = "up",   label = "hedges" },
    { map = "VIRIDIAN_POKECENTER", x = 6, y = 5, face = "up", label = "planter" },
    { map = "PALLET_TOWN",     x = 5,  y = 8,  face = "up",   label = "trees" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    local ok = pcall(U.teleport, game, s.map, s.x, s.y, s.face)
    if ok then
      Pipelines.setLevel("voxel", 5)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s.png"):format(ROOT, s.label)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[round] capture missed: " .. path) end
    else
      print("[round] teleport failed: " .. s.map)
    end
  end
  print(("[round] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,218 @@
 -- Driver: propose and photograph several battle arenas for ONE map.
 --
 -- data/battle_arenas.lua holds a single authored spot per area, chosen by
 -- arena_pick's nearest-to-the-middle search and then looked at. This is the
 -- other half of that job: when the shipped spot is up for review, it lays out
 -- the ALTERNATIVES -- every arena on the map both mons can be seen in, spread
 -- along the map so the shortlist is places rather than neighbours -- and
 -- stages a real battle in each so they can be compared by eye.
 --
 --   SHOT_DIR=.scratchpad/route1_candidates CAND_MAP=ROUTE_1 CAND_N=5 \
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/route1_candidates.lua love .
 --
 -- CAND_MAP is the map id (default ROUTE_1), CAND_N how many to photograph.
 -- One `CAND` line per shot, ready to paste into the data file, plus a PNG
 -- named for its corner and shape.
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local DIR = os.getenv("SHOT_DIR") or ".scratchpad/route1_candidates"
  local MAP = os.getenv("CAND_MAP") or "ROUTE_1"
  local WANT = tonumber(os.getenv("CAND_N") or "") or 5
  local Pokemon = require("src.pokemon.Pokemon")
  local BattleState = require("src.battle.BattleState")
  game.save.party = { Pokemon.new(game.data, "CHARIZARD", 45) }
  game.save.player.name = "RED"
  local exports = game.mods and game.mods.exports
  local lib = exports and exports.DRAMATIC_SHAPE and exports.DRAMATIC_SHAPE.lib
  if not lib then
    U.log("DRAMATIC_SHAPE is not loaded -- enable it and run again")
    return
  end
  local Arena = lib.require("BattleArena")
  local Battles = lib.require("OverworldBattle")
  U.teleport(game, MAP, 1, 1, "down")
  local map = game.overworld.map
  U.log(("%s is %dx%d cells"):format(MAP, map.widthCells, map.heightCells))
  -- ------- every arena the map can offer
  --
  -- BattleArena.search answers "the nearest one", which is the wrong question
  -- for a shortlist -- it returns one spot and hides the rest. So walk the
  -- same grid ourselves and keep them all, tagged with whether the pair would
  -- actually be SEEN there (Arena.clearance), because an obstructed spot is
  -- not a candidate no matter how good the ground looks.
  --
  -- The map's outermost cells are its CONNECTION BORDER -- the strip the
  -- neighbouring map is drawn into, walkable so the player can step across.
  -- Ground there passes every test and is still the wrong answer: a fight
  -- staged on it happens at the edge of the world with the border ring's tree
  -- wall at the mons' backs, and every spot in the strip looks like every
  -- other one. CAND_MARGIN keeps the shortlist on the route proper.
  local MARGIN = tonumber(os.getenv("CAND_MARGIN") or "") or 2
  local cands = {}
  for _, shape in ipairs(Arena.SHAPES) do
    for y = MARGIN, map.heightCells - shape.h - MARGIN do
      for x = MARGIN, map.widthCells - shape.w - MARGIN do
        local fits = true
        for cy = y, y + shape.h - 1 do
          for cx = x, x + shape.w - 1 do
            if not Arena.openCell(map, cx, cy, false) then fits = false break end
          end
          if not fits then break end
        end
        if fits then
          local a = Arena.at(x, y, shape.id)
          if a and Arena.clearance(map, a) then
            cands[#cands + 1] = { x = x, y = y, shape = shape.id,
                                  mx = x + (shape.w - 1) / 2,
                                  my = y + (shape.h - 1) / 2 }
          end
        end
      end
    end
  end
  U.log(("%d clear arenas on %s"):format(#cands, MAP))
  if #cands == 0 then U.log("done -- nothing to propose") return end
  for _, c in ipairs(cands) do
    U.log(("  fit  %d,%d %s"):format(c.x, c.y, c.shape))
  end
  -- CAND_AT=x,y,shape;x,y,shape;... photographs an explicit shortlist instead
  -- of the spread one. The spread is a first pass over ground the clearance
  -- test approved, and that test measures terrain height along the sightline
  -- only -- it has no opinion on a hedge sitting in the apron row between the
  -- camera and the near mon, which is the failure that keeps turning up. So
  -- the loop is: spread, look, then re-shoot the survivors and the
  -- replacements by hand.
  local explicit = os.getenv("CAND_AT")
  if explicit and explicit ~= "" then
    local list = {}
    for spot in explicit:gmatch("[^;]+") do
      local x, y, s = spot:match("^%s*(%-?%d+)%s*,%s*(%-?%d+)%s*,%s*(%a+)%s*$")
      if x then
        list[#list + 1] = { x = tonumber(x), y = tonumber(y), shape = s }
      else
        U.log("BAD CAND_AT entry: " .. spot)
      end
    end
    cands = list
    WANT = #list
    U.log(("%d spots given explicitly"):format(#list))
  end
  local function shapeOf(id)
    for _, s in ipairs(Arena.SHAPES) do if s.id == id then return s end end
  end
  for _, c in ipairs(cands) do
    local s = shapeOf(c.shape)
    c.mx = c.x + ((s and s.w or 1) - 1) / 2
    c.my = c.y + ((s and s.h or 1) - 1) / 2
  end
  -- ------- thin them down to a shortlist that is actually a CHOICE
  --
  -- Adjacent corners are the same patch of ground shifted a cell, so a naive
  -- top-N is five photographs of one place, and pure farthest-point selection
  -- goes straight to the extremes -- which on a route means the ends, where
  -- the ground is emptiest and the shots are least distinguishable.
  --
  -- So: spread along the route's LONG AXIS, one pick per band, and within a
  -- band take the spot nearest the middle of the road. The road is measured
  -- rather than assumed -- the median cross-axis position of everywhere a
  -- fight fits IS the lane, on a map whose walkable ground is mostly lane.
  local horizontal = map.widthCells > map.heightCells
  local function along(c) return horizontal and c.mx or c.my end
  local function across(c) return horizontal and c.my or c.mx end
  local xs = {}
  for _, c in ipairs(cands) do xs[#xs + 1] = across(c) end
  table.sort(xs)
  local road = xs[math.ceil(#xs / 2)]
  U.log(("road runs %s, centre of the lane is %s = %.1f")
        :format(horizontal and "east-west" or "north-south",
                horizontal and "y" or "x", road))
  local lo, hi = math.huge, -math.huge
  for _, c in ipairs(cands) do
    lo, hi = math.min(lo, along(c)), math.max(hi, along(c))
  end
  -- an explicit shortlist is already the answer; the spread below would only
  -- thin it, and its overlap rule would silently drop two spots deliberately
  -- asked for a cell apart
  local picked, taken = {}, {}
  for band = 1, (explicit and explicit ~= "") and 0 or WANT do
    -- band centres, not band edges: the first and last picks sit inside the
    -- route rather than on its two connection mouths
    local target = lo + (hi - lo) * (band - 0.5) / WANT
    local best, bestScore
    for _, c in ipairs(cands) do
      if not taken[c] then
        local da = along(c) - target
        local dr = across(c) - road
        -- distance from the band centre, plus a heavier penalty for being off
        -- the lane; wide arenas are worth a detour, being the shot this mode
        -- is framed for
        local score = da * da + 4 * dr * dr - (c.shape == "wide" and 100 or 0)
        if not bestScore or score < bestScore then best, bestScore = c, score end
      end
    end
    if best then
      picked[#picked + 1] = best
      -- everything overlapping the pick is off the table, so two bands whose
      -- best spots touch cannot return the same patch of ground twice
      for _, c in ipairs(cands) do
        if math.abs(along(c) - along(best)) < 3
           and math.abs(across(c) - across(best)) < 3 then
          taken[c] = true
        end
      end
    end
  end
  if #picked == 0 then picked = cands end
  -- north to south (or west to east), so the filenames read along the route
  table.sort(picked, function(a, b)
    if along(a) ~= along(b) then return along(a) < along(b) end
    return across(a) < across(b)
  end)
  for i, c in ipairs(picked) do
    U.log(("CAND %d  [%q] = { x = %d, y = %d, shape = %q },")
          :format(i, MAP, c.x, c.y, c.shape))
    -- forced through the authored-entry seam, so what gets staged is exactly
    -- this spot rather than whatever the search would pick from the player's
    -- cell
    Arena.setOverride(MAP, { x = c.x, y = c.y, shape = c.shape })
    local staged = Arena.find(map, 0, 0, false)
    if not staged then
      U.log(("SKIP %d -- override did not stage"):format(i))
    else
      game.overworld.player.cellX = staged.playerCell[1]
      game.overworld.player.cellY = staged.playerCell[2]
      U.wait(90)                              -- let the meshes land
      local battle = BattleState.newWild(game, "NIDORINO", 20)
      battle.onFinish = function() end
      game.overworld:pushBattle(battle)
      U.wait(70)
      for _ = 1, 14 do U.tap(game, "a"); U.wait(8) end
      local got = Battles.arena()
      U.log(("SHOT %d  staged at %s,%s"):format(i, tostring(got and got.x),
                                                tostring(got and got.y)))
      U.shot(game, ("%s/%d_%s_x%d_y%d_%s.png")
                   :format(DIR, i, MAP:lower(), c.x, c.y, c.shape))
      while game.stack:top() and game.stack:top() ~= game.overworld do
        game.stack:pop()
      end
      U.wait(6)
    end
  end
  Arena.setOverride(MAP, nil)
  U.log("done -- " .. DIR)
 end
@@ -0,0 +1,92 @@
 -- Scratch driver: shots of the `bookcase` class across the tilesets that
 -- pin it, for the shelf-front relief.  Two of them are NOT shelves --
 -- the League's gate walls and the terraces on PLATEAU -- and are here as
 -- the control: their courses run edge to edge, so nothing should sink.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/shelf_relief_shots.lua \
 --   SHOT_DIR=.scratchpad/shelves AB_TAG=before lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/shelves")
    .. "/" .. (os.getenv("AB_TAG") or "before")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[shelf] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { map = "OAKS_LAB",           x = 7, y = 2, face = "up", label = "dojo_lab" },
    { map = "CELADON_MANSION_2F", x = 2, y = 4, face = "up", label = "mansion_2f" },
    { map = "CELADON_MART_2F",    x = 5, y = 5, face = "up", label = "lobby_mart" },
    { map = "MUSEUM_1F",          x = 2, y = 4, face = "up", label = "museum" },
    { map = "VIRIDIAN_MART",      x = 3, y = 5, face = "up", label = "mart" },
    { map = "SS_ANNE_CAPTAINS_ROOM", x = 5, y = 2, face = "up", label = "ship" },
    -- the controls, both of them tilesets that borrow the collapse for
    -- something that is NOT a shelf and say so with `bookcase_relief =
    -- false`: the League's masonry gate walls, and Bill's transporter
    -- drums.  Nothing in either may move.
    { map = "INDIGO_PLATEAU",     x = 2, y = 5, face = "up", label = "plateau" },
    { map = "BILLS_HOUSE",        x = 2, y = 3, face = "up", label = "bills" },
    -- the house shelves: pinned `desk`, NOT `bookcase`, so they go
    -- through the world mesher's box fold and this relief never reaches
    -- them.  Here to show the gap.
    { map = "REDS_HOUSE_1F",      x = 1, y = 2, face = "up", label = "reds" },
    { map = "BLUES_HOUSE",        x = 1, y = 2, face = "up", label = "blues" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    local ok = pcall(U.teleport, game, s.map, s.x, s.y, s.face)
    -- twice: the first load of the session has no mesh to settle against
    pcall(U.teleport, game, s.map, s.x, s.y, s.face)
    if ok then
      Pipelines.setLevel("voxel", 5)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s.png"):format(ROOT, s.label)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[shelf] capture missed: " .. path) end
    else
      print("[shelf] teleport failed: " .. s.map)
    end
  end
  print(("[shelf] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,78 @@
 -- Scratch driver: shots of the SS Anne's galley barrels, which are Lt.
 -- Surge's trash can redrawn on the ship atlas.  Three down the kitchen's
 -- east wall at cells (13,5)/(13,7)/(13,9), one in the captain's room at
 -- (4,1), and one each in the two ship-interior houses at (7,7).
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/ship_can_shots.lua \
 --   SHOT_DIR=.scratchpad/ssanne AB_TAG=after lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/ssanne")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[ship] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    { map = "SS_ANNE_KITCHEN",       x = 12, y = 11, face = "up",    label = "galley_up" },
    { map = "SS_ANNE_KITCHEN",       x = 12, y = 3,  face = "down",  label = "galley_down" },
    { map = "SS_ANNE_KITCHEN",       x = 11, y = 7,  face = "right", label = "galley_side" },
    { map = "SS_ANNE_CAPTAINS_ROOM", x = 4, y = 4,   face = "up",    label = "captain" },
    { map = "CERULEAN_BADGE_HOUSE",  x = 6, y = 7,   face = "right", label = "house" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    local ok = pcall(U.teleport, game, s.map, s.x, s.y, s.face)
    if ok then
      Pipelines.setLevel("voxel", 5)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s.png"):format(ROOT, s.label)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[ship] capture missed: " .. path) end
    else
      print("[ship] teleport failed: " .. s.map)
    end
  end
  print(("[ship] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,80 @@
 -- Scratch driver: shots of Vermilion Gym's trash cans, for the trash can
 -- voxelization.  The fifteen cans stand on odd cell columns 1..9 in cell
 -- rows 7, 9 and 11; the sixteenth is up at cell (6,1) beside the leader's
 -- platform.  Even columns are open floor, so the player can be parked
 -- between two cans and look along a row.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/trash_can_shots.lua \
 --   SHOT_DIR=.scratchpad/cans AB_TAG=before lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/cans")
    .. "/" .. (os.getenv("AB_TAG") or "before")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[can] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync("day")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  local SCENES = {
    -- head on into the middle of the field, cans left, right and ahead
    { x = 4, y = 12, face = "up",    label = "field" },
    -- close up: standing between two cans of the bottom row
    { x = 2, y = 11, face = "left",  label = "close" },
    -- along the row, so the cans line up in depth
    { x = 4, y = 13, face = "up",    label = "row" },
    -- from the north, looking back down over all three rows
    { x = 4, y = 6,  face = "down",  label = "over" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    for _, rung in ipairs({ 3, 5 }) do
      U.teleport(game, "VERMILION_GYM", s.x, s.y, s.face)
      Pipelines.setLevel("voxel", rung)
      Pipelines.setLevel("tiltshift", 0)
      settle()
      local path = ("%s/%s_v%d.png"):format(ROOT, s.label, rung)
      game.capturePath = path
      U.wait(6)
      local f = io.open(path, "rb")
      if f then f:close() shots = shots + 1
      else print("[can] capture missed: " .. path) end
    end
  end
  print(("[can] %d shots into %s"):format(shots, ROOT))
 end
@@ -0,0 +1,246 @@
 -- Driver: the A/B performance benchmark.
 --
 -- One scripted, deterministic session that exercises the three things the
 -- mod is slow at, and writes the numbers to a JSON file so two runs can be
 -- diffed:
 --
 --   1. LOADING IN      -- engaging the mode from flat: shader compiles,
 --                         canvas allocations, the first map's mesh, its
 --                         atlas bakes and its glass mask, all at once.
 --   2. A NEW AREA      -- walking Pallet -> Route 1 -> Viridian with cold
 --                         caches, then walking the SAME route again with
 --                         them warm. The gap between the two is the
 --                         complaint; closing it is the fix.
 --   3. A LOW CAMERA    -- standing still at each pitch rung. The 75 degree
 --                         rung puts the horizon in frame, which triples the
 --                         sun frustum and hands the sky its disc to draw.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/voxel_bench.lua \
 --   DS_PERF=1 BENCH_TAG=baseline lovec.exe .
 --
 -- knobs (env):
 --   DS_PERF     must be set, or lib/Perf.lua stays dark and measures nothing
 --   BENCH_TAG   output name, ds_bench/<tag>.json     (default "run")
 --   BENCH_HOLD  frames to walk per leg              (default 900)
 --
 -- THREE THINGS THIS RUN CONTROLS FOR, because a benchmark that does not is
 -- measuring the weather:
 --
 --   * VSYNC OFF. With it on every frame costs exactly one refresh interval
 --     and the whole exercise reads as 16.7ms flat, saving or no saving.
 --   * THE CLOCK PINNED to day. The day/night cycle changes the sky, the sun
 --     angle, the shadow frustum and whether windows are lit -- so an
 --     unpinned run compares two different scenes.
 --   * ENCOUNTERS OFF. A wild battle mid-walk derails the route and charges
 --     its frames to whichever map the script thought it was on. Stubbed on
 --     the state class for this process only; nothing is written to disk.
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local OverworldState = require("src.world.OverworldController")
  local TAG = os.getenv("BENCH_TAG") or "run"
  -- Route 1 is 36 cells tall and a walk step is 16 frames, so a leg that
  -- means to reach Viridian needs about 1200 -- short of that the "new
  -- area" the benchmark is named for never gets entered.
  local HOLD = math.floor(tonumber(os.getenv("BENCH_HOLD")) or 1300)
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[bench] DRAMATIC_SHAPE mod not loaded -- nothing to measure")
    return
  end
  local V = handle.lib
  local Perf = V.require("Perf")
  if not Perf.enabled then
    print("[bench] DS_PERF is not set -- run with DS_PERF=1 or this measures nothing")
    return
  end
  local loadBytes = V.loadBytes
  local Structures = V.require("Structures")
  local ChunkMesher = V.require("ChunkMesher")
  local Buildings = V.require("Buildings")
  local DayNight = V.require("DayNight")
  local VoxelScene = V.require("VoxelScene")
  -- module internals worth naming that the mod does not time itself
  Perf.wrap(Structures, "forMap", "Structures.forMap")
  Perf.wrap(Buildings, "build", "Buildings.build")
  Perf.wrap(ChunkMesher, "pump", "ChunkMesher.pump")
  Perf.wrap(VoxelScene, "render", "VoxelScene.render")
  if love.window and love.window.setVSync then
    pcall(love.window.setVSync, 0)
  end
  DayNight.setting:sync("day")
  OverworldState.rollEncounter = function() return nil end
  -- ---- the run ------------------------------------------------------
  local function seg(name)
    Perf.setSegment(name)
    -- the frame that STRADDLES a segment boundary belongs to neither: it
    -- carries the teleport, the level change or the report print that
    -- opened it, and charging that to the new segment libels it
    Perf.resync()
  end
  local function settle(frames)
    Perf.setSegment(nil)
    U.wait(frames or 60)
    Perf.resync()
  end
  -- Hold a direction, attributing each frame to the map the player is
  -- STANDING ON as it lands. Crossing a seam mid-leg is the whole point of
  -- the walk, so the segment has to follow the player rather than the
  -- script's idea of where they are.
  local function walk(dir, frames, prefix)
    local last = nil
    for _ = 1, frames do
      local o = game.overworld
      local id = o and o.map and o.map.id
      if id ~= last then
        last = id
        seg(prefix .. ":" .. tostring(id))
        print(("[bench] %s entered %s at frame %d"):format(prefix, tostring(id),
                                                           U.frame()))
      end
      -- press and RELEASE each frame, the way tests/voxel_perf_probe's seam
      -- crossing does: a direction left held accumulates in pressQueue and
      -- the walk stalls where a single tap would have stepped
      table.insert(game.input.pressQueue, dir)
      game.input.state[dir] = true
      coroutine.yield()
      game.input.state[dir] = false
    end
    local o = game.overworld
    print(("[bench] %s ended on %s at cell (%d,%d)"):format(
      prefix, tostring(o and o.map and o.map.id),
      o and o.player and o.player.cellX or -1,
      o and o.player and o.player.cellY or -1))
    Perf.setSegment(nil)
  end
  print("[bench] tag=" .. TAG .. " loadBytes=" .. tostring(loadBytes))
  -- ORDER MATTERS. The cold walk has to be the first time this session
  -- draws Route 1 and Viridian, so everything before it stays in Pallet
  -- Town -- a map whose caches the walk does not depend on. Measuring a
  -- "first entry" into a map an earlier segment already warmed is the one
  -- way to make this whole benchmark lie.
  -- 1. the flat reference: the game with this mod present but not
  --    drawing. Every later number is only interesting against this one.
  U.teleport(game, "PALLET_TOWN", 10, 8, "down")
  Pipelines.setLevel("voxel", 0)
  Pipelines.setLevel("tiltshift", 0)
  settle(90)
  seg("flat")
  U.wait(180)
  -- 2. loading in: FULL is what a player picks first and it is the most
  --    expensive configuration there is (tilt-shift to maximum, 3D
  --    battles on). Measured from the frame the level changes, so it
  --    carries the shader compiles, the canvas allocations, the first
  --    mesh, the first atlas bake and the first glass scan together.
  settle(60)
  seg("engage.full")
  Pipelines.setLevel("voxel", 1)          -- FULL
  U.wait(240)
  Perf.setSegment(nil)
  -- 3. the low camera. 75 degrees puts the horizon in frame; the rungs
  --    below it are the control. Standing still, so what is measured is
  --    the frame's own cost and not the walk's mesh streaming.
  for _, rung in ipairs({ 2, 3, 4, 5 }) do   -- 15, 35, 50, 75 degrees
    Pipelines.setLevel("voxel", rung)
    settle(60)                                -- let the tween finish
    seg("pitch:" .. tostring(V.require("VoxelState").ANGLE_LABELS[rung + 1]))
    U.wait(180)
    Perf.setSegment(nil)
  end
  -- 3b. the same low camera at DUSK, which is where the sky costs most:
  --     the horizon is in frame, so the banded region is at its tallest,
  --     and the sun is low enough to be in it -- the disc only draws at
  --     all when it is above the horizon point, so a midday run never
  --     touches that code and would report it as free.
  for _, when in ipairs({ "dusk", "night" }) do
    DayNight.setting:sync(when)
    settle(60)
    seg("pitch:75:" .. when)
    U.wait(180)
    Perf.setSegment(nil)
  end
  DayNight.setting:sync("day")
  settle(30)
  -- 4/5. arriving somewhere new, at the rung that hurts.
  --
  -- Arrival is measured by LOADING each map rather than by walking into
  -- it. Walking would be more lifelike, but Route 1's ledges make a held
  -- direction stall against geometry, so a fixed frame count buys a
  -- different amount of travel on every run -- and a benchmark whose
  -- route drifts cannot compare two runs at all. A load is the same
  -- arrival stripped of the travel: the map swaps, and the next frames
  -- pay for its mesh, its structure analysis, its atlas bake and its
  -- glass mask exactly as they do behind a door fade.
  --
  -- Then the identical list a second time. Every cost in the gap between
  -- the two passes is a cache that was cold, and that gap IS the
  -- complaint.
  Pipelines.setLevel("voxel", 5)             -- 75 degrees
  local TOUR = { "ROUTE_1", "VIRIDIAN_CITY", "ROUTE_2", "ROUTE_22",
                 "VIRIDIAN_FOREST", "PEWTER_CITY" }
  local DWELL = math.max(60, math.floor(HOLD / #TOUR))
  -- Stand in the middle of each map, derived from its own def rather than
  -- written down: a hardcoded cell that falls outside a map teleports the
  -- player nowhere and the segment silently measures the previous map.
  local function centreOf(id)
    local def = game.data.maps and game.data.maps[id]
    if not def then return nil end
    return math.floor(def.width), math.floor(def.height)
  end
  local function tour(prefix)
    for _, id in ipairs(TOUR) do
      local cx, cy = centreOf(id)
      if cx then
        U.teleport(game, id, cx, cy, "up")
        -- the segment opens on the frame AFTER the teleport, so the load
        -- itself is not charged to the arrival it caused
        seg(prefix .. ":" .. id)
        U.wait(DWELL)
        Perf.setSegment(nil)
      else
        print("[bench] skipping unknown map " .. id)
      end
    end
  end
  tour("first")
  tour("revisit")
  -- 6. streaming while walking: the one crossing that is reliably
  --    walkable (tests/voxel_perf_probe crosses the same seam) -- Route 1
  --    south into Pallet, which pulls a neighbour's meshes in mid-stride.
  U.teleport(game, "ROUTE_1", 10, 34, "down")
  settle(120)
  walk("down", 240, "walk")
  -- ---- the report ---------------------------------------------------
  Perf.setSegment(nil)
  Perf.printReport("bench " .. TAG)
  Perf.write(TAG, {
    tag = TAG,
    loadBytes = loadBytes,
    hold = HOLD,
    texturememory = Perf.texturememory or 0,
    canvases = Perf.canvases or 0,
    images = Perf.images or 0,
  })
  print("[bench] done")
 end
@@ -214,6 +214,172 @@ Structures.buildFigures(twice, map, 0, 3, 8, 11)
 T.eq(#twice.figures, 1,
  "the repaint replaces the pattern, so a rescan cannot match it again")
 -- ------- a figure with a DEPTH is an object, not a card
 --
 -- The Marts' cash register: the same authored-mask escape, but a machine
 -- set down on a counter is a box seen from the front rather than a
 -- face-on icon, so it builds as a per-pixel solid.  Driven over a
 -- synthetic copy of the counter's east arm, as all nine maps on the MART
 -- id draw it at cell (1,5):
 --
 --     y=9    16 41      the work surface north of it
 --     y=10   14 15      the register: keypad and receipt curl
 --     y=11   30 31
 --     y=12   16 41      the work surface it stands on
 T.check(TileShape.figures("POKECENTER")[1].depth == nil,
  "the seated man states no depth -- he stays a flat sprite card")
 local regs = TileShape.figures("MART")
 T.check(type(regs) == "table" and #regs == 1,
  "MART carries exactly one figure")
 local reg = regs[1]
 T.eq(reg.w, 2, "the register is two tiles across")
 T.eq(reg.h, 2, "and two tall")
 T.eq(reg.n, 150, "the mask claims 150 pixels of the 256 it spans")
 T.eq(reg.depth, 12, "its body is 12 voxels deep -- three quarters of the cell")
 T.check(reg.thin and reg.thin.rows == 4 and reg.thin.depth == 2,
  "the four rows above its drawn top edge are 2-voxel paper")
 T.check(reg.flat and reg.flat.x0 == 2 and reg.flat.x1 == 8
        and reg.flat.r0 == 4 and reg.flat.r1 == 11,
  "and the keypad is a TOP-VIEW rect, not a face")
 local MART_ROWS = { [9] = { 16, 41 }, [10] = { 14, 15 },
                    [11] = { 30, 31 }, [12] = { 16, 41 } }
 local martS = { shapeAt = {}, tileAt = {}, figures = {}, skip = {},
                ground = {}, runs = {}, objectQuads = {} }
 for ty, row in pairs(MART_ROWS) do
  for i, tile in ipairs(row) do
    martS.tileAt[keyOf(1 + i, ty)] = tile
    martS.shapeAt[keyOf(1 + i, ty)] = COUNTER
  end
 end
 local martMap = {
  tileset = { id = "MART", tilesPerRow = 16,
              imageWidth = 128, imageHeight = 48 },
  isWalkableCell = function() return false end,
 }
 Structures.buildFigures(martS, martMap, 2, 3, 9, 12)
 T.eq(#martS.figures, 0, "no card was built -- it is a solid")
 T.eq(#martS.objectQuads, 351,
  "and it landed in the standee channel as 351 quads")
 T.eq(martS.tileAt[keyOf(2, 10)], 16,
  "its tiles wear the plain work surface now")
 T.eq(martS.tileAt[keyOf(3, 11)], 41, "all four of them")
 T.eq(martS.shapeAt[keyOf(2, 10)].class, "counter",
  "and keep the counter box the machine stands on")
 local rx0, rx1, ry0, ry1, rz0, rz1
 for _, q in ipairs(martS.objectQuads) do
  for c = 1, 4 do
    local p = q[c]
    rx0 = math.min(rx0 or p[1], p[1]); rx1 = math.max(rx1 or p[1], p[1])
    ry0 = math.min(ry0 or p[2], p[2]); ry1 = math.max(ry1 or p[2], p[2])
    rz0 = math.min(rz0 or p[3], p[3]); rz1 = math.max(rz1 or p[3], p[3])
  end
 end
 T.eq(ry0, 8, "it stands ON the counter's 8px top plane, not the floor")
 T.eq(ry1, 24, "and is its drawn 16px tall")
 T.eq(rx0, 18, "west edge at the mask's column 2")
 T.eq(rx1, 30, "east edge at column 13, inside its own cell (16..32)")
 T.eq(rz1, 96, "its FRONT is the cell's own front edge, where it is drawn")
 T.eq(rz0, 84, "and it grows north from there, 4 short of the cell's back")
 -- the two thicknesses: the body at 8, the receipt curl at 2, the curl
 -- centred in the body's own band rather than flush with its front
 local bands = {}
 for _, q in ipairs(martS.objectQuads) do
  for c = 1, 4 do bands[q[c][3]] = true end
 end
 for _, z in ipairs({ 84, 89, 91, 96 }) do
  T.check(bands[z], "the model has a face at z = " .. z)
 end
 local curl = {}
 for _, q in ipairs(martS.objectQuads) do
  local lo = math.min(q[1][2], q[2][2], q[3][2], q[4][2])
  if lo >= 21 then for c = 1, 4 do curl[q[c][3]] = true end end
 end
 T.check(curl[89] and curl[91] and not curl[84] and not curl[96],
  "clear of the arm's top only the 2-voxel paper band exists")
 -- THE L.  The base band (drawn rows 12-15) stands 4 above the counter and
 -- the keypad lies on it as a horizontal plate, so the whole machine is
 -- exactly three surfaces: a foot, an arm, and a deck in the notch.
 local plate, deckTop = {}, 0
 for _, q in ipairs(martS.objectQuads) do
  local flatQuad = q[1][2] == q[2][2] and q[2][2] == q[3][2]
                   and q[3][2] == q[4][2]
  if flatQuad and q[1][2] == 13 then
    plate[#plate + 1] = q
  elseif flatQuad and q[1][2] == 12 then
    deckTop = deckTop + 1
  end
 end
 T.eq(#plate, 83,
  "the keypad lies FLAT: one top quad per masked voxel of the deck")
 T.eq(deckTop, 7,
  "on the base band's own top, which is 4 voxels up (drawn rows 12-15)")
 local dz0, dz1
 for _, q in ipairs(martS.objectQuads) do
  if q[1][2] == 12 and q[3][2] == 12 then
    for c = 1, 4 do
      dz0 = math.min(dz0 or q[c][3], q[c][3])
      dz1 = math.max(dz1 or q[c][3], q[c][3])
    end
  end
 end
 T.eq(dz0, 84, "and that deck runs the body's whole depth")
 T.eq(dz1, 96, "-- plain behind the panel, covered by it in front")
 local px0, px1, pz0, pz1
 for _, q in ipairs(plate) do
  for c = 1, 4 do
    px0 = math.min(px0 or q[c][1], q[c][1]); px1 = math.max(px1 or q[c][1], q[c][1])
    pz0 = math.min(pz0 or q[c][3], q[c][3]); pz1 = math.max(pz1 or q[c][3], q[c][3])
  end
 end
 T.eq(px0, 18, "the deck spans the mask's columns 2..8")
 T.eq(px1, 25, "-- the keypad panel and its own black rim")
 T.eq(pz1, 96, "the deck reaches the body's front edge")
 T.eq(pz0, 84, "and its back -- 8 drawn rows STRETCHED over 12 voxels")
 -- the stretch is by whole voxels, centre-sampled: 8 drawn rows over 12
 -- voxels of deck doubles every second one and blurs nothing
 local perRow16, atlasH16 = 16, 48
 local depthRow = {}
 for _, q in ipairs(plate) do
  local z = math.min(q[1][3], q[2][3], q[3][3], q[4][3])
  depthRow[z] = math.floor(q.v * atlasH16)
 end
 local seen = {}
 for z = 84, 95 do
  T.check(depthRow[z] ~= nil, "deck voxel at z = " .. z .. " wears a texel")
  seen[depthRow[z]] = (seen[depthRow[z]] or 0) + 1
 end
 T.eq(depthRow[95], 11, "the front voxel wears the keypad's own bottom rim")
 T.eq(depthRow[84], 4, "the back one wears its top rim")
 local doubled = 0
 for _, n in pairs(seen) do
  T.check(n == 1 or n == 2, "no drawn row spreads over more than two voxels")
  if n == 2 then doubled = doubled + 1 end
 end
 T.eq(doubled, 4, "exactly four of the eight rows double -- 8 into 12")
 -- and the arm still stands its drawn 8 rows above that deck, carrying
 -- the paper: nothing in the notch reaches higher than the plate
 local armTop, notchTop = 0, 0
 for _, q in ipairs(martS.objectQuads) do
  for c = 1, 4 do
    if q[c][1] >= 25 then armTop = math.max(armTop, q[c][2])
    elseif q[c][1] <= 24 then notchTop = math.max(notchTop, q[c][2]) end
  end
 end
 T.eq(armTop, 24, "the arm and its receipt curl reach the drawn 16px")
 T.eq(notchTop, 23,
  "and west of it only the keys (13) and the paper overhanging them")
 -- ------- prop_bg: the shades a pinned prop treats as background
 --
 -- The potted plants needed this: their pot's olive base is drawn flush on
@@ -0,0 +1,346 @@
 -- Driver: the pixel-identity gate for performance work.
 --
 -- Every optimization in this mod's performance pass claims the frame comes
 -- out the same. This driver is what makes that claim checkable rather than
 -- asserted: it renders a fixed set of scenes -- several maps, indoors and
 -- out, at every camera rung, in every display mode -- and writes one PNG
 -- per scene. Run it before a change and after it, hash the two directories,
 -- and any file whose hash moved is a scene the change altered.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/voxel_shots_ab.lua \
 --   SHOT_DIR=<dir> AB_TAG=before lovec.exe .
 --
 -- knobs (env):
 --   SHOT_DIR   output directory (created if missing)   (default "shots/ab")
 --   AB_TAG     subdirectory under SHOT_DIR             (default "before")
 --   AB_MODES   display modes to sweep, comma list      (default all four)
 --
 -- DETERMINISM is the whole game here, because a shot that differs for a
 -- reason other than the change under test makes the gate useless:
 --
 --   * the day/night clock is PINNED (an unpinned sky is a different sky
 --     every second, and it drives the sun angle and the shadow frustum);
 --   * the animated tile slots ride the engine's 60Hz counter, so every
 --     scene is reached after the SAME number of frames from the same
 --     starting state, and the water is at the same point in its roll;
 --   * levels are set through Pipelines.setLevel, never the hotkey, so the
 --     run cannot write the player's options;
 --   * encounters are stubbed off -- a wild battle would replace the scene
 --     the shot is named for.
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local OverworldState = require("src.world.OverworldController")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/ab")
    .. "/" .. (os.getenv("AB_TAG") or "before")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[ab] DRAMATIC_SHAPE mod not loaded -- nothing to compare")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  OverworldState.rollEncounter = function() return nil end
  -- NPCs roam on a random timer (src/world/NPC.lua), and LOVE's RNG is
  -- seeded differently every launch -- so two runs of this driver put the
  -- same townsfolk in different places and every shot with a person in it
  -- differs for a reason that has nothing to do with the change under
  -- test. Freeze them: `frozen` is the flag the NPC's own update already
  -- honours, and an NPC mid-step still finishes it, so the settle below
  -- lands on a still scene. They are still POSED and still drawn, so the
  -- billboard, its lean and its shadow are all still under test.
  local NPC = require("src.world.NPC")
  if not NPC.dramaticShapeAbFreeze then
    local inner = NPC.update
    function NPC:update(...)
      self.frozen = true
      return inner(self, ...)
    end
    NPC.dramaticShapeAbFreeze = true
  end
  pcall(love.math.setRandomSeed, 20260730)
  -- Freeze the tile-animation clock, on BOTH routes to it.
  --
  -- TileRenderer.tick consumes WALL-CLOCK dt (so the water rolls at the
  -- same speed on a 60Hz and a 144Hz panel), which means the step a shot
  -- catches depends on how fast the machine got there rather than on
  -- anything the run did. Stubbing tick pins the counter the flat tile
  -- layer reads.
  --
  -- The mod reads the SAME counter but through its own chain
  -- (TerrainAtlas.animFrame): TileRenderer.animFrame if the build exports
  -- one, else the local off tick's upvalues, else -- and this is the trap
  -- -- wall-clock time. A stubbed tick has no upvalues, so stubbing it
  -- ALONE knocks the mod onto the wall-clock fallback and makes the
  -- flowers drift between two otherwise identical runs. Exporting a
  -- constant animFrame takes the first branch and pins that route too.
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  -- The scenes. Chosen for what each one can BREAK, not for looks:
  --   ROUTE_1          open ground, grass billboards, a long view north --
  --                    the case a shadow-frustum or culling change moves
  --   VIRIDIAN_CITY    buildings, window panes (the glass mask), signs
  --   PALLET_TOWN      the seam with Route 1: neighbour meshes and ring
  --   VIRIDIAN_FOREST  dense round-tree hulls, heavy occlusion
  --   REDS_HOUSE_1F    indoors: no sky, no sun, authored figures
  --   PEWTER_CITY      a second tileset with its own atlas bake
  local SCENES = {
    { id = "ROUTE_1", x = 10, y = 20, face = "up", label = "open" },
    { id = "VIRIDIAN_CITY", x = 20, y = 26, face = "up", label = "town" },
    { id = "PALLET_TOWN", x = 10, y = 2, face = "up", label = "seam" },
    { id = "VIRIDIAN_FOREST", x = 16, y = 24, face = "up", label = "trees" },
    { id = "REDS_HOUSE_1F", x = 4, y = 4, face = "up", label = "indoor" },
    { id = "PEWTER_CITY", x = 16, y = 20, face = "down", label = "pewter" },
  }
  -- OFF is in the list deliberately: a change that speeds the 3D path up
  -- must not have touched the flat one either. Then the three camera
  -- rungs, 75 last because it is the low camera this performance work is
  -- aimed at.
  --
  -- FULL (rung 1) is NOT here, and cannot usefully be. It is a settings
  -- PRESET, not a render path: it sets tilt-shift to maximum, flattens the
  -- world curve, fits the zoom, switches 3D battles on -- and pins DAYTIME
  -- to SYNC and HOLDS it there (main.lua's applyFull / DayNight.forceSync),
  -- which overrides this driver's pinned clock and makes every shot after
  -- it depend on the wall clock. It also persists all of that, so one run's
  -- FULL changes the options the NEXT run starts from. What FULL renders is
  -- 35 degrees with the blur at 3, which rung 3 plus AB_TSHIFT=3 covers
  -- exactly.
  local RUNGS = {}
  for n in (os.getenv("AB_RUNGS") or "0,2,3,5"):gmatch("%d+") do
    RUNGS[#RUNGS + 1] = tonumber(n)
  end
  local TSHIFT = math.floor(tonumber(os.getenv("AB_TSHIFT")) or 0)
  -- AB_SHADOW=0 renders with the sun pass's contribution turned off
  -- (SHADOW_ALPHA 0 short-circuits the lookup in the scene shader). A
  -- bisection tool: when a set of shots will not reproduce, this says
  -- whether what is moving is in the shadow map or somewhere else.
  if os.getenv("AB_SHADOW") == "0" then
    V.require("Voxel3D").SHADOW_ALPHA = 0
  end
  -- PaletteFX.MODES, minus the inverted novelties: `ogred` and `classic`
  -- are the SGB paths this mod bakes an atlas for, `gbc` is the shared
  -- default, and `redpp` is the one that rebakes an atlas PER MAP -- four
  -- genuinely different routes through TerrainAtlas.
  local MODES = {}
  for m in (os.getenv("AB_MODES") or "ogred,classic,gbc,redpp"):gmatch("[^,]+") do
    MODES[#MODES + 1] = m
  end
  -- Two times of day, because half the shader only runs in one of them:
  -- the window lamps, the moon disc and the night tint are all dark-only,
  -- and the glint sweep and the sun disc are day-only.
  local TIMES = { "day", "night" }
  local shots, missed = 0, 0
  -- U.shot's own mkdir is the POSIX one, which cmd.exe does not
  -- understand, and a missing directory makes every capture vanish
  -- silently. Try both spellings once, up front.
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  -- A capture that always costs the SAME number of frames.
  --
  -- U.shot spins up to 120 frames waiting for the capture to land, which
  -- is right for a screenshot and wrong for this: the animated tile slots
  -- (water rolling, flowers opening) ride the engine's frames-since-boot
  -- counter, so a scene reached after a different number of frames renders
  -- its water at a different point in the roll and the shot differs for a
  -- reason no change caused. A driver resume and a rendered frame are 1:1
  -- here, so the capture lands on the next draw and a fixed budget is both
  -- enough and constant.
  local CAPTURE_FRAMES = 4
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  local ShadowMap = V.require("ShadowMap")
  -- Wait for the scene to actually BE the scene the shot is named for.
  -- Two things are still in motion after a teleport, and both are timed in
  -- wall-clock seconds rather than frames, so "wait N frames" settles them
  -- by a different amount on every machine and every run:
  --
  --   the build queue -- meshes are built on a per-frame time budget, so a
  --   slower run captures a half-built neighbour;
  --   the camera tween -- Voxel.t runs on dt over TWEEN_TIME, so a shot
  --     taken before it lands is at some arbitrary intermediate pitch.
  --
  -- Both are waited on by their own completion flag, then a short fixed
  -- settle. The variable wait is harmless now that the animation clock is
  -- frozen above -- otherwise it would move the water instead.
  -- and the CAMERA, which is the subtle one. It eases toward the player
  -- over wall-clock dt, so after a fixed wait it has covered a distance
  -- that depends on how fast the machine ran -- and the sun pass is only
  -- redrawn when the camera crosses a quarter-world-pixel (VoxelScene's
  -- shadow signature), so a frame caught mid-ease carries a shadow map
  -- fitted for a slightly different camera than the one it is drawn with.
  -- That is a real and deliberate tolerance in the mod, but it makes the
  -- gate compare two arbitrary points inside it. Waiting for the camera
  -- to stop moving entirely puts every shot at the same steady state.
  local function cameraStill()
    local o = game.overworld
    local c = o and o.camera
    if not c then return true end
    local lx, ly, held = nil, nil, 0
    for _ = 1, 300 do
      if c.x == lx and c.y == ly then
        held = held + 1
        if held >= 10 then return true end
      else
        held = 0
        lx, ly = c.x, c.y
      end
      U.wait(1)
    end
    return false
  end
  local function settleBuild()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    cameraStill()
    -- and then force one final sun pass at the settled camera. The map is
    -- only redrawn when the camera crosses a quarter world pixel, so a
    -- still camera holds whatever was drawn at the moment it last did --
    -- correct to within that tolerance, but fitted from a position that
    -- depends on where the easing happened to be, which differs by a few
    -- hundredths of a pixel between runs and moves every shadow edge by a
    -- shade or two. Forgetting the stamp redraws from the state the shot
    -- is actually taken in, and two runs then agree exactly.
    -- guarded so this driver can also be pointed at a build that predates
    -- the seam, which is exactly what capturing a "before" reference means
    if ShadowMap.forget then ShadowMap.forget() end
    U.wait(20)
  end
  -- AB_TRACE=1 prints the state each shot was taken in. When two runs of
  -- this driver disagree, this is what says which input moved.
  local TRACE = os.getenv("AB_TRACE") == "1"
  local function trace(name)
    if not TRACE then return end
    local o = game.overworld
    local e = ShadowMap.extent or {}
    print(("[ab] %-28s cam=(%.4f,%.4f) player=(%.3f,%.3f) res=%d extent=(%.3f,%.3f,%.3f) KX=%.6f KZ=%.6f angle=%.6f pend=%d")
      :format(name,
              o and o.camera and o.camera.x or -1,
              o and o.camera and o.camera.y or -1,
              o and o.player and o.player.px or -1,
              o and o.player and o.player.py or -1,
              ShadowMap.res or 0,
              e[1] or 0, e[2] or 0, e[3] or 0,
              ShadowMap.KX or 0, ShadowMap.KZ or 0,
              Voxel.angle or 0,
              ChunkMesher.pending()))
  end
  -- AB_SHADOWDUMP=1 also writes the packed depth map itself, into the save
  -- directory. When the scene differs but every input to the sun pass is
  -- identical, the map is the only place left to look.
  local DUMP = os.getenv("AB_SHADOWDUMP") == "1"
  local function dumpShadow(name)
    if not DUMP then return end
    local tex = ShadowMap.texture()
    if not (tex and tex.newImageData) then return end
    pcall(function()
      love.filesystem.createDirectory("ab_shadow")
      tex:newImageData():encode("png", "ab_shadow/" .. name .. ".png")
    end)
  end
  local function capture(name)
    trace(name)
    dumpShadow(name)
    local path = ("%s/%s.png"):format(ROOT, name)
    game.capturePath = path
    U.wait(CAPTURE_FRAMES)
    local f = io.open(path, "rb")
    if f then
      f:close()
      shots = shots + 1
    else
      missed = missed + 1
      print("[ab] capture did not reach disk: " .. path)
    end
  end
  local PaletteFX = require("src.render.PaletteFX")
  local function setMode(mode)
    local known = false
    for _, m in ipairs(PaletteFX.MODES) do
      if m == mode then known = true break end
    end
    if not known then return false end
    return (pcall(PaletteFX.setMode, mode))
  end
  -- A fixed zoom, so the view size every shot is composed at is the same
  -- one. Zoom is persisted, so without this a session that ever ran the
  -- FULL preset (which fits the zoom to the window) leaves a different
  -- view size behind for every later run.
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  for _, mode in ipairs(MODES) do
    if setMode(mode) then
      for _, when in ipairs(TIMES) do
        DayNight.setting:sync(when)
        for _, s in ipairs(SCENES) do
          for _, rung in ipairs(RUNGS) do
            U.teleport(game, s.id, s.x, s.y, s.face)
            Pipelines.setLevel("voxel", rung)
            -- pinned AFTER the voxel rung, because FULL is a preset that
            -- reaches over and sets this row itself (main.lua's applyFull)
            -- and persists it -- so without this, one run's FULL leaks a
            -- blur level into the NEXT run's options.lua and every shot
            -- differs for a reason no code change caused. Sharp by
            -- default: a gaussian smears a one-pixel geometry difference
            -- across the whole frame, which is exactly what a gate meant
            -- to localise differences must not do. AB_TSHIFT=3 runs the
            -- blur path deliberately.
            Pipelines.setLevel("tiltshift", TSHIFT)
            -- Wait for the build queue to drain rather than for a fixed
            -- number of frames. Meshes are built on a per-frame time
            -- budget, so how much of a map exists after N frames is a
            -- property of the MACHINE -- a slower run captures a
            -- half-built neighbour and the shot differs for no reason the
            -- change caused. Draining first, then settling a fixed 40
            -- frames for the camera tween, makes the scene the same
            -- scene everywhere. (Safe now that the animation clock above
            -- is frozen: a variable wait no longer moves the water.)
            settleBuild()
            capture(("%s_%s_%s_v%d"):format(mode, when, s.label, rung))
          end
        end
      end
    else
      print("[ab] display mode " .. mode .. " unavailable, skipped")
    end
  end
  print(("[ab] %d shots into %s (%d failed to reach disk)")
    :format(shots, ROOT, missed))
 end
@@ -0,0 +1,121 @@
 -- Scratch driver: water shot with V-CURVE walked OFF..3, to see what the
 -- world bend does to the reflective pass.
 --
 --   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/water_curve_shots.lua \
 --   SHOT_DIR=.scratchpad/watercurve AB_TAG=before lovec.exe .
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local ROOT = (os.getenv("SHOT_DIR") or "shots/watercurve")
    .. "/" .. (os.getenv("AB_TAG") or "after")
  local handle = game.mods.exports["DRAMATIC_SHAPE"]
  if not (handle and handle.lib) then
    print("[water] DRAMATIC_SHAPE mod not loaded")
    return
  end
  local V = handle.lib
  local DayNight = V.require("DayNight")
  local ChunkMesher = V.require("ChunkMesher")
  local Voxel = V.require("VoxelState")
  local WorldCurve = V.require("WorldCurve")
  local Water = V.require("Water")
  -- WATER_RUNG=sky drops the screen-space march and leaves the sky path, to
  -- tell an artefact of the one from an artefact of the other
  if os.getenv("WATER_RUNG") then Water.setting:sync(os.getenv("WATER_RUNG")) end
  require("src.world.OverworldController").rollEncounter = function() return nil end
  local TileRenderer = require("src.render.TileRenderer")
  TileRenderer.tick = function() end
  TileRenderer.animFrame = function() return 0 end
  DayNight.setting:sync(os.getenv("WATER_TIME") or "night")
  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
  local Zoom = require("src.render.Zoom")
  pcall(function()
    game.save.options.zoom = 1
    Zoom.applyOptions(game.save.options)
  end)
  local function settle()
    for _ = 1, 900 do
      if ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    for _ = 1, 300 do
      if Voxel.t >= 1 and Voxel.ready and ChunkMesher.pending() == 0 then break end
      U.wait(1)
    end
    U.wait(40)
  end
  -- Stand on the walkable cell just north of the widest run of water on the
  -- map, so a scene is picked by where the water actually is rather than by
  -- a coordinate guessed off the block list.
  local TileShape = V.require("TileShape")
  local function shore(map)
    local def = map.def
    local shapes = TileShape.forMap(map)
    local function classAt(cx, cy)
      local tx, ty = cx * 2, cy * 2
      local s = TileShape.at(map, shapes, map:tileAt(tx, ty), tx, ty)
      return s and s.class
    end
    local best, bestRun = nil, 0
    for cy = 1, def.height * 2 - 1 do
      local run, start = 0, nil
      for cx = 0, def.width * 2 - 1 do
        if classAt(cx, cy) == "water" then
          start = start or cx
          run = run + 1
          if run > bestRun and classAt(cx, cy - 1) ~= "water" then
            bestRun, best = run, { x = start + math.floor(run / 2), y = cy - 1 }
          end
        else
          run, start = 0, nil
        end
      end
    end
    return best
  end
  local SCENES = {
    { map = "PALLET_TOWN",     label = "pallet" },
    { map = "CERULEAN_CITY",   label = "cerulean" },
    { map = "VERMILION_CITY",  x = 18, y = 27, label = "vermilion" },
    { map = "ROUTE_24",        label = "route24" },
    { map = "VIRIDIAN_CITY",   label = "viridian" },
  }
  local shots = 0
  for _, s in ipairs(SCENES) do
    if not s.x then
      -- teleport once so the map is loaded, then let the scan place us
      U.teleport(game, s.map, 1, 1, "down")
      U.wait(4)
      local spot = game.overworld and game.overworld.map and shore(game.overworld.map)
      if spot then s.x, s.y = spot.x, spot.y else s.x, s.y = 1, 1 end
      print(("[water] %s shore at (%d,%d)"):format(s.label, s.x, s.y))
    end
    for _, rung in ipairs({ 3, 4 }) do
      for _, curve in ipairs({ 0, 3 }) do
        U.teleport(game, s.map, s.x, s.y, s.face or "down")
        Pipelines.setLevel("voxel", rung)
        Pipelines.setLevel("tiltshift", 0)
        WorldCurve.setting:setIndex(curve + 1, game)
        settle()
        local path = ("%s/%s_v%d_c%d.png"):format(ROOT, s.label, rung, curve)
        game.capturePath = path
        U.wait(8)
        local f = io.open(path, "rb")
        if f then f:close() shots = shots + 1
        else print("[water] capture missed: " .. path) end
      end
    end
  end
  print(("[water] %d shots into %s"):format(shots, ROOT))
  love.event.quit()
 end
@@ -0,0 +1,128 @@
 -- Driver: WHY is the water not reflecting anything?
 --
 -- The reflective pass has several links and every one of them fails quietly
 -- back to flat water, which looks exactly like the row being off. This walks
 -- the chain in the LIVE game and prints where it stops.
 --
 --   POKEPORT_DRIVER=mods/DRAMATIC_SHAPE/tests/water_reflect_probe.lua lovec .
 --
 -- knobs (env):
 --   REFL_MAP    map id                       (default PALLET_TOWN)
 --   REFL_SPOT   "x,y[,facing]"               (default 5,6,down)
 --   REFL_LEVEL  voxel rung                   (default 5, the 75-degree camera,
 --                                             which is where a reflection is
 --                                             most of what you can see)
 --   REFL_TIME   daytime pin (day/dusk/...)   (default: leave as-is)
 return function(game)
  local U = dofile("tests/drivers/util.lua")
  local Pipelines = require("src.render.Pipelines")
  local mapId = os.getenv("REFL_MAP") or "PALLET_TOWN"
  local level = math.floor(tonumber(os.getenv("REFL_LEVEL")) or 5)
  local sx, sy, facing = (os.getenv("REFL_SPOT") or "5,6,down")
    :match("^%s*(%d+)%s*,%s*(%d+)%s*,?%s*(%a*)")
  facing = (facing ~= "" and facing) or "down"
  local function say(...) print("[water-ssr] " .. string.format(...)) end
  U.teleport(game, mapId, tonumber(sx), tonumber(sy), facing)
  U.wait(20)
  Pipelines.setLevel("voxel", level)
  U.wait(40)                       -- outlast the camera tween and the build
  local V = game.mods.exports["DRAMATIC_SHAPE"]
  V = V and V.lib
  if not V then return say("mod exports unreachable -- is it enabled?") end
  local Water = V.require("Water")
  local Voxel3D = V.require("Voxel3D")
  local ChunkMesher = V.require("ChunkMesher")
  local Sky = V.require("Sky")
  local DayNight = V.require("DayNight")
  if os.getenv("REFL_TIME") then
    DayNight.setting:sync(os.getenv("REFL_TIME"))
    U.wait(5)
  end
  local ow = game.overworld
  local map = ow and ow.map
  if not map then return say("no live map") end
  -- 1. is the row on at all?
  say("row=%s level=%d", tostring(Water.setting:get()), Water.level())
  if not Water.enabled() then
    return say("STOP: WATER is OFF -- press 9, or set the row")
  end
  -- 2. is there any water on this map to reflect in?
  local terrain, water = ChunkMesher.pair(map, false)
  if not terrain then terrain, water = ChunkMesher.pair(map, true) end
  say("terrain mesh=%s water mesh=%s", tostring(terrain ~= nil),
      tostring(water ~= nil))
  if not terrain then
    return say("STOP: no terrain mesh yet -- the build is still cooking")
  end
  if not water then
    say("STOP: this map has no water surface. That is not a fault unless")
    say("      you can see a lake: check the tileset's water tiles reach")
    say("      TileShape (run voxel_survey.lua for the shape breakdown).")
    return
  end
  -- 3. did the driver give us a depth texture to read? This is the one
  --    hardware requirement the rest of the mode does not already have.
  say("depth canvas readable: %s", tostring(Voxel3D.depthReadable()))
  if not Voxel3D.depthReadable() then
    say("STOP: no readable depth canvas on this driver (tried depth24, ")
    say("      depth24stencil8, depth32f and depth16).")
    say("      The water falls back to the flat scene shader, which is")
    say("      exactly what it looked like before this feature existed.")
    return
  end
  -- 4. did the shader build? Both variants -- the wireframe one needs
  --    derivatives, which a driver may refuse on its own.
  say("shader plain=%s grid=%s",
      tostring(Water.shader(false) ~= nil), tostring(Water.shader(true) ~= nil))
  if not Water.shader(false) then
    return say("STOP: the water shader did not compile -- the mod log has "
               .. "the driver's own message")
  end
  -- 5. is there a sky to reflect, and something hanging in it?
  local ramp, count = Sky.ramp()
  say("sky ramp=%s bands=%s edge=%s", tostring(ramp ~= nil), tostring(count),
      tostring(Voxel3D.skyEdge))
  local body = DayNight.body()
  if body then
    local amt = DayNight.glow()
    local w, h = Voxel3D.size()
    local rpx = Sky.discRadius(h, Voxel3D.cell or 1,
                               { moon = body.moon, glowAmt = amt })
    local ang = rpx / ((h or 1) / math.max(1e-4, Voxel3D.fovY or 1))
    say("body=%s dir=(%.2f, %.2f, %.2f) disc=%.1fpx (%.2f deg)",
        body.moon and "moon" or "sun", body.dx, body.dy, body.dz, rpx,
        math.deg(ang))
  else
    say("body: none in the sky right now (set REFL_TIME=day or =night)")
  end
  if not ramp then
    say("NOTE: no band ramp -- indoors, or the ramp could not be built. The")
    say("      sky half of the reflection is off; the ray march still runs.")
  end
  -- 6. how much reflection this camera is actually asking for. Both numbers
  --    fall out of the rung, and between them they explain every "it only
  --    works at 75" report: Fresnel decides how much shows, and the lean
  --    decides whether what shows has anything in it.
  local f = Water.FRESNEL_FLOOR + (Water.FRESNEL_CEIL - Water.FRESNEL_FLOOR)
            * (1 - Voxel3D.descent) ^ Water.FRESNEL_POWER
  say("camera: descent %.3f -> fresnel about %.2f, horizon lean %.2f",
      Voxel3D.descent, f, Water.lean(Voxel3D.descent))
  say("waves: %d px columns, phase %.2f", Water.WAVE_HEIGHT, Water._waveTime())
  say("OK: every link is live. The effect is strongest at REFL_LEVEL=5 (the")
  say("    75-degree rung, where Fresnel is highest and the reflection is")
  say("    exact) and with a low sun (REFL_TIME=dusk).")
 end
Author	SHA1	Message	Date
DramaticShape	3f7210bfcd	mobile spin fix	2026-08-02 01:20:39 -04:00
DramaticShape	9ef8644bff	add first person mode	2026-08-02 01:16:42 -04:00
DramaticShape	e6d4059c38	fix water again on android	2026-08-02 00:53:38 -04:00
DramaticShape	1a283d6771	bump version	2026-08-02 00:14:13 -04:00
DramaticShape	a7c9541ac4	pokecenter machines, water occlusion	2026-08-02 00:01:39 -04:00
DramaticShape	91cc2d6f51	bills, pewter gym, register, celadon mansion, tables, garbage cans	2026-08-01 23:48:23 -04:00
DramaticShape	47363b8d23	iterate version	2026-08-01 16:41:03 -04:00
DramaticShape	752653e243	update oak's pc	2026-08-01 16:20:04 -04:00
DramaticShape	6887f5d951	updates to oak's lab	2026-08-01 16:03:32 -04:00
DramaticShape	a140980b1d	seal transparent back sprites	2026-08-01 15:19:26 -04:00
DramaticShape	eb231d221e	Merge pull request #46 from DramaticShape/water-reflections Add fancy water	2026-08-01 00:32:30 -04:00
DramaticShape	980383bb92	update battle water	2026-08-01 00:28:54 -04:00
DramaticShape	22b58e27a4	fix android water shading	2026-08-01 00:13:01 -04:00
DramaticShape	98f7419b72	fix water for android glsl shaders	2026-07-31 23:39:05 -04:00
DramaticShape	92fef2a37e	update for modkit update	2026-07-31 23:29:39 -04:00
DramaticShape	8f38aeb36e	water updates	2026-07-31 23:05:54 -04:00
DramaticShape	9a9441899a	first pass at water	2026-07-31 22:54:16 -04:00
DramaticShape	7f76caa5f6	Merge pull request #35 from DramaticShape/mobile-dpi-fix bump version	2026-07-31 14:19:02 -04:00
DramaticShape	be2f0464c5	Merge branch 'mobile-dpi-fix' of https://github.com/DramaticShape/DramaticShapeVoxelMod into mobile-dpi-fix	2026-07-31 14:18:25 -04:00
DramaticShape	8728783b22	account for dpi issues on updated 3d battles	2026-07-31 14:18:02 -04:00
DramaticShape	731ecd9677	Merge pull request #34 from DramaticShape/mobile-dpi-fix Mobile dpi fix	2026-07-31 14:10:24 -04:00
DramaticShape	851f36d46f	Merge pull request #33 from DramaticShape/master rebase	2026-07-31 14:04:17 -04:00
DramaticShape	775757b2d6	account for dpi issues on updated 3d battles	2026-07-31 13:51:54 -04:00
DramaticShape	20f1807edd	Merge pull request #25 from DramaticShape/back-sprite-battles add day/night filter to 2d	2026-07-30 22:37:52 -04:00
DramaticShape	4da8e5dc3e	add day/night filter to 2d	2026-07-30 22:36:59 -04:00
DramaticShape	3eb62a5e00	Merge pull request #24 from DramaticShape/back-sprite-battles Back sprite battles	2026-07-30 22:05:14 -04:00
DramaticShape	26d1d96d52	hide tilt/gbcfx	2026-07-30 21:57:29 -04:00
DramaticShape	d9a000d7ad	add back sprite option for 3d battles	2026-07-30 21:52:54 -04:00
DramaticShape	f12b564dcd	moved route 1 battle location again, added transparency to bottom battle menu	2026-07-30 21:34:25 -04:00
DramaticShape	d1a1c69c7d	Merge pull request #16 from DramaticShape/android-night-cycle-fix iterate version to 1.2.1	2026-07-30 00:11:29 -04:00
DramaticShape	e621c28a74	Merge pull request #15 from DramaticShape/android-night-cycle-fix android fix for day night cycle issue	2026-07-30 00:09:22 -04:00
DramaticShape	785838e6cd	Merge pull request #14 from DramaticShape/3d-battle-mod fix issue with fight transition in oak's lab	2026-07-29 23:14:58 -04:00
DramaticShape	cb325af6cf	Merge pull request #13 from DramaticShape/3d-battle-mod 3d battle mod	2026-07-29 22:55:21 -04:00
DramaticShape	e898cedad6	Merge pull request #12 from DramaticShape/3d-battle-mod 1.2.0 updates	2026-07-29 22:31:17 -04:00