Merge pull request #89 from DramaticShape/dev

1.5.5

CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## 1.5.5
+
+### Added
+
+- **A third-person camera: the 3RD rung.** The VOXEL ladder's eighth rung
+  (`3` / SELECT walk onto it after 1ST, and it is on the OPTIONS row)
+  stands the camera on a boom behind the player's shoulder. It is the
+  first-person rig with one number added, so everything 1ST already did
+  it does: the look steers on a mouse, the right stick or a touch drag,
+  and the grid walk is replaced by continuous camera-relative movement --
+  push in any direction and you go there, at any angle, with collision,
+  warps, ledges, encounters and scripts still running through the
+  engine's own machinery.
+
+  The boom **collides**: it marches back through the terrain height field
+  and the map's own walkability, so backing into a wall walks the camera
+  in to your shoulders instead of through it, and rounding a corner eases
+  it back out rather than snapping. Squeezed all the way into the head it
+  simply draws as 1ST until you step clear. It also carries a small
+  over-the-shoulder rail offset, which fades out as the boom shortens.
+
+  Every sprite in the world **turns to face it** -- yours, the NPCs', the
+  figures drawn into the furniture -- and shows the frame it would look
+  like from where the camera actually stands, so walking behind someone
+  shows you their back. Your own character is drawn (with the
+  through-the-wall silhouette 1ST had no use for) and **turns to face
+  where they are walking** rather than where the camera looks, so a strafe
+  reads as one; standing still they come back round to the camera's
+  bearing, which is the one A talks along.
+
+  Your card's frame is chosen from your body's **continuous** bearing
+  rather than from the compass direction the grid game stores. An NPC's
+  facing really is one of four directions, but yours is the angle the
+  camera itself is hung off, and quantising it before measuring it against
+  the eye leaves no margin for the shoulder rail's few degrees of offset:
+  in a band just short of each 45-degree boundary the pair read as 135
+  degrees apart and picked the mirrored PROFILE frame. Standing still.
+  Spinning the camera swept four of those bands a revolution, which showed
+  up as the character flicking sideways for a split second.
+
+  In VR the boom is declined outright and 3RD presents as 1ST does: a
+  headset that seats its wearer three cells behind their own body is a
+  well-known way to make people ill. The rung still changes the walk and
+  the sprites the same way.
+
+- **Every camera zooms, on whatever the machine has.** The mouse wheel,
+  `Q`/`E`, a two-finger pinch and the pad's two stick clicks all reach
+  whichever camera is actually in front of you -- the third-person boom,
+  the staged battle's lens, or the engine's own survey zoom on an orbit
+  rung. One module (`lib/CamControl.lua`) answers "which camera is this
+  aimed at" so the four cameras never race each other for an event, and
+  forwards everything it does not claim. 1ST claims nothing: the eye is in
+  the player's head, and a pinch there would only wind the survey zoom for
+  whenever they stepped back out.
+
+- **The battle camera is yours to steer.** The right stick, a drag across
+  the screen or the mouse walks the staged shot around the arena and raises
+  the seat; the wheel, `Q`/`E`, a pinch or a stick click work the lens.
+
+  Both axes stop where the composition does. LEFT stops at the shot the rig
+  was solved for, because there is nothing to the left of it. RIGHT ends
+  SIDE-ON -- the eye square to the arena's axis, both Pokemon at the same
+  distance instead of one behind the other -- computed from each rig's own
+  stance rather than written down. DOWN stops at the rig's low stance and
+  UP is 45 degrees above it, raised about the focus at a constant radius so
+  climbing never doubles as zooming. Input accumulates into a goal the eye
+  eases after, so a flick reads as the camera being pushed rather than
+  dragged.
+
+  The lens **opens by exactly the amount the pair spreads**: the solved
+  shot looks along the arena's axis at a shallow angle, which foreshortens
+  the gap between the two mons to less than half its length, and swinging
+  round or climbing un-foreshortens it. Left alone that threw both Pokemon
+  off the edges of the frame at the far end of either range, which made the
+  whole far end unusable.
+
+  Where you leave the camera is where the next battle opens. An angle and a
+  lens you chose are how you want to watch battles, not a fact about one
+  encounter.
+
+- **Move animations track the camera.** They already slid to follow the
+  pair's midpoint; now they follow its SEPARATION too. Both mons are
+  geometry standing on the map, so the camera sizes them -- and an effects
+  layer that kept the authored 106-pixel spacing through a zoom and a
+  60-degree swing fired its beams into the air beside the Pokemon they were
+  aimed at.
+
+- **BACK SPRITES locks the battle camera.** That setting pins your own mon
+  to the GB's slot on the menu while the foe stands out on the map, and no
+  angle holds a composition that is half frame and half world. The steer,
+  the climb and the lens all stand down -- in the rig as well as at the
+  inputs, so an angle stored from before the row was switched on cannot
+  leave it steered anyway. The slow drift stays: it was always there under
+  BACK SPRITES and two degrees is not a composition problem.
+
+- **BATTLE BG is pinned to WHITE and its row comes off the menu.** The row
+  picks what fills the screen AROUND the battle, and this mode fills the
+  window with the map the fight is standing on -- there are no voids left
+  for it to be about. WORLD was actively wrong under it: it makes the
+  battle non-opaque so the engine draws a second, dimmed copy of the
+  overworld beneath the arena pass's own. Pinned rather than merely hidden,
+  so a save written before the mod was installed cannot carry a value the
+  menu can no longer reach. Uninstall and the row is back.
+
+### Fixed
+
+- **Grass and flowers are closed off at the sides.** Both stand as
+  per-pixel slabs built from runs of lit pixels, and only the front, the
+  back and a lid were ever emitted -- so from any angle off square you
+  looked straight in through the open end of every run and out the far
+  side. At the low cameras this release adds, that is most of the time.
+  Each run now wears end walls in the colour of the pixel they close off.
+
+  Flowers needed more than that, because a flower SWAYS: the mesh spans the
+  union of every animation frame and each frame is cut back out in texture
+  space, so a pixel that drops out of a frame takes the union's wall with
+  it and leaves an interior boundary that never had one. The first cut of
+  this looked solid on the base frame and still had gaps on every other.
+  Every pixel of a flower now carries a cap on all four of its remaining
+  faces: enclosed and invisible while its neighbour is there, and already
+  in place the moment the animation takes that neighbour away.
+
+- **No more machine-gun bonking in 1ST and 3RD.** The grid walk's collision
+  sound marks a discrete event -- a direction pressed, a step refused. A
+  free walk has no such moment: the body slides along every wall it grazes,
+  continuously, so a corridor taken at a slight angle rang the bonk twice a
+  second from end to end. The wall stopping you is the feedback.
+
 ## 1.5.2
 
 ### Added

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DramaticShape
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -3,7 +3,8 @@
 A mod for the [Pokémon Gen 1 Recompilation
 Project](https://github.com/bryanthaboi/pokemon-gen1-recomp-project).
 
-The overworld as a voxelized 3D diorama. Also supports experimental first-person and VR.
+The overworld as a voxelized 3D diorama. Also supports experimental
+first-person, third-person and VR.
 
 ## Controls
 
@@ -12,7 +13,7 @@ menu.
 
 | control | does |
 | --- | --- |
-| `3`, or the **VOXEL** options row | OFF → 15 → 35 → 50 → 75 → 1ST → OFF (camera pitch) |
+| `3`, or the **VOXEL** options row | OFF → 15 → 35 → 50 → 75 → 1ST → 3RD → OFF (camera pitch) |
 | `SELECT` (pad / touch) | the same step as `3` — for the machines with no number row |
 | `5`, or the **V-GRID** options row | OFF / ON — a one-pixel wireframe on every voxel |
 | `6`, or the **T-SHIFT** options row | OFF → 1 → 2 → 3 → OFF (miniature blur) |
@@ -23,11 +24,72 @@ menu.
 | 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 |
 
+## Free-roam cameras (1ST / 3RD)
+
+The last two rungs of the **VOXEL** ladder are experimental, and they are
+the same camera: **1ST** stands it in the player's own eyes, **3RD** pulls
+it back onto a boom behind their shoulder. Both steer, and on both the grid
+walk is replaced by continuous camera-relative movement — push in any
+direction and you go there, at any angle, not just along the four compass
+lines. Collision, warps, ledges, encounters and scripts all still run
+through the engine's own machinery.
+
+| control | does |
+| --- | --- |
+| mouse | look (the cursor is captured; left click is A, right click is B) |
+| right stick | look |
+| a touch drag off the overlay's controls | look |
+| left stick / touch d-pad / arrow keys | walk, relative to where the camera looks |
+| wheel, `Q` / `E`, pinch, or a stick click | **3RD only** — let the boom out and pull it in (`Q` and left stick click out, `E` and right stick click in) |
+
+On an **orbit rung** the same wheel, `Q`/`E` and pinch drive the engine's own
+survey zoom. On **1ST** they do nothing at all: the eye is in your head, and
+there is no distance to change.
+
+On **3RD** the boom shortens against whatever is behind you, so backing into
+a wall walks the camera in to your shoulders rather than through it — squeeze
+it all the way in and the view is 1ST until you step clear. The character
+turns to face where they are walking, and every sprite in the world — yours,
+the NPCs', the figures drawn into the furniture — turns to face the camera
+and shows the frame it would look like from where the camera actually
+stands, so walking behind someone shows you their back.
+
+## The battle camera
+
+A fight staged on the map (**3D-BTL**, on by default) is shot with a solved
+over-the-shoulder rig — and you can steer it.
+
+| control | does |
+| --- | --- |
+| right stick, a touch drag, or the mouse | swing the shot around the arena (→) and raise the seat (↑) |
+| wheel, `Q` / `E`, pinch, or a stick click | the lens (`Q` / left stick click out, `E` / right stick click in) |
+
+Both axes stop where the composition does. Left stops at the shot the rig was
+solved for — there is nothing to the left of it. Right ends **side-on**: the
+eye square to the arena's axis, both Pokémon at the same distance instead of
+one behind the other. Down stops at the rig's own low stance; up is 45° above
+it. The lens opens as you swing or climb, by exactly the amount the two
+Pokémon spread apart, so they stay framed at every angle. Move animations
+follow the pair's position *and* its separation, so a beam still lands on the
+Pokémon it was aimed at.
+
+Where you leave the camera is where the next battle opens.
+
+**BACK SPRITES locks it.** That setting pins your own Pokémon to the GB's slot
+on the menu while the foe stands out on the map, and no angle holds a
+composition that is half frame and half world — so with it on, the shot holds
+the one the rig was solved for.
+
 ## VR
 
 The **VR** options row (OFF / ON, off by default) drives a PCVR headset
 through OpenXR on Windows — SteamVR, Oculus or WMR.
 
+Both free-roam rungs put the headset in the player's *head*: a boom that
+seats its wearer three cells behind their own body is a reliable way to make
+people ill, so **3RD** in VR is **1ST** in VR. The rung still changes the
+walk and the sprites the same way.
+
 ### VR controls
 
 Suggested onto Touch, Index and WMR controllers (rebindable in the
@@ -41,14 +103,16 @@ alongside.
 | either trigger | START |
 | left stick click | step the VOXEL angle ladder (same as the "3" key) |
 | right stick up / down | *diorama only* — zoom the model |
-| right stick left / right | *1ST only* — snap-turn 45° |
+| right stick left / right | *1ST only* — snap-turn 45°, or turn smoothly with **SMOOTH TURN** on |
 | grip squeeze + raise / lower that hand | *diorama only* — drag the table's height |
 | head | *1ST and battles* — look; FreeMove walks where you look |
 | left hand | *1ST and battles* — the Pokédex: menus, dialogs and the 2D battle screen on its screen |
 
 ## Licenses
 
-This mod redistributes one third-party binary:
+This mod is released under the **MIT License** — see [`LICENSE`](LICENSE).
+
+It redistributes one third-party binary:
 
 - **`assets/vr/openxr_loader.dll`** — the Khronos OpenXR loader
   (version 1.0.10.2, x64, unmodified), © The Khronos Group Inc.,

lib/BattleArena.lua

@@ -242,7 +242,10 @@ end
 -- Whether both mons would be in plain view from the battle camera.
 function BattleArena.clearance(map, arena)
   local BattleCam = V.require("BattleCam")
-  local ok, rig = pcall(BattleCam.rig, arena, 0)
+  -- the CANONICAL shot: whether a fight fits somewhere is a fact about the
+  -- ground, so it must not depend on the drift's phase or on where the
+  -- player last swung the camera (see BattleCam.rig's third argument)
+  local ok, rig = pcall(BattleCam.rig, arena, 0, true)
   if not (ok and rig and rig.eye) then return true end
   local eye = rig.eye
   local H = BattleArena.MON_H

lib/BattleCam.lua

@@ -124,6 +124,83 @@ BattleCam.PAN_PERIOD = 26         -- seconds for one there-and-back
 BattleCam.PAN_DOLLY = 0.02        -- how far the eye breathes, as a fraction
 BattleCam.DOLLY_PERIOD = 37
 
+-- ------- the player's own orbit
+--
+-- The drift above is the shot breathing. THIS is the player steering it:
+-- a right stick, a drag across the screen or the mouse walks the eye
+-- around the arena's axis, and it stops at both ends.
+--
+-- 0 is the shot the rig was solved for and the LEFT stop, because there is
+-- nothing to the left of it -- the composition below is what the whole
+-- module exists to land, and past it the two mons start swapping sides.
+--
+-- 1 is SIDE-ON: the eye swung round until it is square to the arena's
+-- north-south axis, where the two mons stand at the same distance instead
+-- of one behind the other. That is as far as the picture stays a battle
+-- rather than a diorama with two Pokemon in it, and it is a different angle
+-- for each rig -- the tele lens starts 28 degrees off the axis and the wide
+-- one 45 -- so the stop is COMPUTED from the rig rather than written down,
+-- and retuning either moves its own stop with it.
+--
+-- The input is deliberately not 1:1 with the pixels: it accumulates into
+-- `orbitGoal` and the live angle eases after it, so a flick reads as the
+-- camera being pushed rather than as the camera being dragged.
+BattleCam.ORBIT_TIME = 0.22       -- seconds for the eye to catch its goal
+BattleCam.ORBIT_DRAG = 1.15       -- fraction of the range per screen width
+BattleCam.ORBIT_STICK = 0.9       -- fraction of the range per second, full tilt
+BattleCam.ORBIT_MOUSE = 0.0011    -- fraction of the range per mouse count
+BattleCam.STICK_DEAD = 0.2
+
+-- ------- and the height it is watched from
+--
+-- The same steering on the other axis, with the same shape of stop at each
+-- end: 0 is the rig's own stance -- the low, near-floor seat the whole
+-- composition is solved around, and the DOWN stop, because below it the
+-- camera starts looking up the arena's nose -- and 1 is 45 degrees above
+-- it, which is high enough to read the ground the fight is standing on
+-- without becoming the diorama's own top-down.
+--
+-- Raised about the FOCUS rather than about the eye, so the aim stays on
+-- the two mons and only the seat climbs; and at a constant radius, so
+-- climbing never changes how big anything is -- that is the zoom's job.
+BattleCam.PITCH_RANGE = math.rad(45)
+BattleCam.PITCH_TIME = 0.22
+BattleCam.PITCH_DRAG = 1.6        -- fraction of the range per screen HEIGHT
+BattleCam.PITCH_STICK = 0.9
+BattleCam.PITCH_MOUSE = 0.0016
+
+-- ------- and the player's own zoom
+--
+-- How much world the frame holds, as a multiple of the rig's own frameH:
+-- BELOW one is zoomed in. It has to be the LENS rather than the distance,
+-- because the rig derives its field of view from frameH and the distance
+-- together -- so moving the eye alone changes the perspective and not the
+-- framing, which is exactly what the dolly breath above is for.
+BattleCam.ZOOM_MIN = 0.45         -- the pair filling the frame
+BattleCam.ZOOM_MAX = 2.0          -- the fight in its own landscape
+BattleCam.ZOOM_STEP = 1.15
+BattleCam.ZOOM_TIME = 0.18
+
+BattleCam.orbit = 0
+BattleCam.orbitGoal = 0
+BattleCam.pitch = 0
+BattleCam.pitchGoal = 0
+BattleCam.zoom = 1
+BattleCam.zoomGoal = 1
+
+-- Whether the player may steer at all. BACK SPRITES clears it: that
+-- setting pins the player's own mon to the GB's own slot on the menu
+-- (OverworldBattle.backPinned) instead of standing it out on the map, so
+-- half the picture is nailed to the frame and half of it is geometry. Swing
+-- the camera under that and the two halves come apart -- the foe walks
+-- around an arena its opponent is not standing in, and the move animations
+-- that reach between them stretch across the gap. There is no angle that
+-- composition survives, so the answer is not to allow one.
+--
+-- Only the STEER is withheld: the slow drift stays, because it was always
+-- there under BACK SPRITES and two degrees is not a composition problem.
+BattleCam.steerable = true
+
 -- Hold the rig perfectly still (VR sets this while a session runs). The
 -- drift exists to give a FLAT screen the depth cue the picture cannot
 -- have; a headset gets real parallax from the player's own head, and a
@@ -134,10 +211,170 @@ BattleCam.still = false
 
 BattleCam.t = 0
 
+-- Only the DRIFT's phase, so every fight opens on the same breath. Where
+-- the player last put the camera is deliberately NOT reset: an angle and a
+-- lens they chose are how they want to watch battles, not a thing about
+-- this battle, and having to re-find them every encounter would make them
+-- not worth setting. They are session state -- a fresh run opens on the
+-- rig's own shot, which is the one the composition is solved for.
 function BattleCam.reset()
   BattleCam.t = 0
 end
 
+-- Back to the solved shot, for anything that wants the composition as
+-- authored rather than as steered.
+function BattleCam.recentre()
+  BattleCam.orbit, BattleCam.orbitGoal = 0, 0
+  BattleCam.pitch, BattleCam.pitchGoal = 0, 0
+  BattleCam.zoom, BattleCam.zoomGoal = 1, 1
+end
+
+-- How far the eye may swing, in radians, before it is square to the arena's
+-- axis. The rig's own stance decides it: `side` and `back` are the offset
+-- it starts at, so the bearing it starts on is atan2(side, back) and what
+-- is left to a quarter turn is the room the player has.
+function BattleCam.orbitRange(arena)
+  local R = BattleCam.rigFor(arena)
+  return math.max(0, math.pi / 2 - math.atan2(R.side, R.back))
+end
+
+-- ------- what the player's inputs reach
+--
+-- All four take a signed amount and clamp; positive is RIGHTWARD, toward
+-- the side-on stop. Returning whether the goal actually moved lets a
+-- caller tell "steered" from "already against the stop".
+
+-- Both axes go through here, so the "nothing while BACK SPRITES holds the
+-- composition" rule and the two stops live in one place each.
+local function setAxis(key, goal)
+  if not BattleCam.steerable then return false end
+  local was = BattleCam[key]
+  BattleCam[key] = math.max(0, math.min(1, goal))
+  return BattleCam[key] ~= was
+end
+
+-- A drag, in fractions of the screen's width (orbit) or height (pitch).
+function BattleCam.dragOrbit(fraction)
+  return setAxis("orbitGoal",
+                 BattleCam.orbitGoal + (fraction or 0) * BattleCam.ORBIT_DRAG)
+end
+
+function BattleCam.dragPitch(fraction)
+  return setAxis("pitchGoal",
+                 BattleCam.pitchGoal + (fraction or 0) * BattleCam.PITCH_DRAG)
+end
+
+-- Relative mouse motion, in counts.
+function BattleCam.mouseOrbit(dx)
+  return setAxis("orbitGoal",
+                 BattleCam.orbitGoal + (dx or 0) * BattleCam.ORBIT_MOUSE)
+end
+
+function BattleCam.mousePitch(dy)
+  return setAxis("pitchGoal",
+                 BattleCam.pitchGoal + (dy or 0) * BattleCam.PITCH_MOUSE)
+end
+
+-- A stick held for `dt` seconds, as a rate with a squared response -- the
+-- first half of the throw aims and the rest travels, the same curve the
+-- free-roam look uses.
+local function curve(v)
+  local a = math.abs(v or 0)
+  if a < BattleCam.STICK_DEAD then return 0 end
+  a = (a - BattleCam.STICK_DEAD) / (1 - BattleCam.STICK_DEAD)
+  return ((v < 0) and -1 or 1) * a * a
+end
+
+function BattleCam.stickOrbit(x, dt)
+  local v = curve(x)
+  if v == 0 then return false end
+  return setAxis("orbitGoal",
+                 BattleCam.orbitGoal + v * BattleCam.ORBIT_STICK * (dt or 0))
+end
+
+function BattleCam.stickPitch(y, dt)
+  local v = curve(y)
+  if v == 0 then return false end
+  return setAxis("pitchGoal",
+                 BattleCam.pitchGoal + v * BattleCam.PITCH_STICK * (dt or 0))
+end
+
+-- The zoom, in notches (positive pulls OUT, like every other zoom here).
+function BattleCam.stepZoom(notches)
+  if not BattleCam.steerable then return false end
+  local was = BattleCam.zoomGoal
+  BattleCam.zoomGoal = math.max(BattleCam.ZOOM_MIN,
+                        math.min(BattleCam.ZOOM_MAX,
+                                 was * (BattleCam.ZOOM_STEP ^ (notches or 0))))
+  return BattleCam.zoomGoal ~= was
+end
+
+-- How far apart the two mons READ from the current orbit, as a multiple of
+-- how far apart they read from the solved shot.
+--
+-- The arena's axis runs from one mon to the other, and the solved shot
+-- looks along it at a shallow 28 degrees, which foreshortens that gap to
+-- less than half its length. Swing round to square-on and the
+-- foreshortening is gone: the same two cells now read at their full
+-- separation, better than twice as wide. Left alone, that threw the pair
+-- out to the edges of the frame -- half of each mon off-screen at the
+-- side-on stop, which made the whole far end of the range unusable.
+--
+-- Climbing does the same thing on the other axis -- a raised camera looks
+-- less along the ground and more across it, which un-foreshortens the gap
+-- again -- so the correction has to answer to both.
+--
+-- What it measures is how much of the arena's axis survives projection:
+-- the axis runs due north-south, the view line points back at the arena at
+-- plan bearing `beta` and elevation `elev`, and the part of a unit axis
+-- that lands across the frame rather than along the view is the sine of
+-- the angle between them. The ratio of that to the solved shot's own is
+-- the factor the lens opens by -- 1 at the solved shot by construction,
+-- about 1.9 at side-on, about 1.7 fully raised.
+--
+-- Analytic rather than measured off the built rig, so nothing has to
+-- reason about a camera to ask the question, and so the sun's box (which
+-- asks through frameH) gets the identical number the lens does.
+--
+-- Measured off the STEER alone, deliberately: the drift's own two degrees
+-- moved this before and must keep moving it by exactly as much, or every
+-- battle shot that has ever been taken shifts.
+local function axisSpan(beta, elev)
+  local c = math.cos(elev)
+  local s = math.sin(beta) * c
+  local v = math.sin(elev)
+  return math.sqrt(s * s + v * v)
+end
+
+function BattleCam.spread(arena)
+  local R = BattleCam.rigFor(arena)
+  local beta = math.atan2(R.side, R.back)
+  local elev = math.atan2(R.height - R.lookY,
+                          math.sqrt((R.side - R.lookX) ^ 2 + R.back ^ 2))
+  local home = axisSpan(beta, elev)
+  if home < 1e-6 then return 1 end
+  return axisSpan(beta + BattleCam.orbit * BattleCam.orbitRange(arena),
+                  elev + BattleCam.pitch * BattleCam.PITCH_RANGE) / home
+end
+
+-- How much world the frame holds right now: the rig's own reach at the
+-- player's zoom and at whatever the orbit has done to the pair's spacing,
+-- or the rig's own alone whenever both are being withheld (VR's fixed
+-- seat, BACK SPRITES' pinned composition). The sun's box is fitted to this
+-- too, so a zoomed shot lights exactly the ground it shows -- which is why
+-- BattleScene asks this rather than multiplying for itself.
+function BattleCam.frameH(arena)
+  local base = BattleCam.rigFor(arena).frameH
+  if BattleCam.still or not BattleCam.steerable then return base end
+  return base * BattleCam.zoom * BattleCam.spread(arena)
+end
+
+local function chase(now, goal, dt, time)
+  if now == goal then return goal end
+  local v = now + (goal - now) * math.min(1, (dt or 0) / time)
+  return (math.abs(goal - v) < 1e-4) and goal or v
+end
+
 -- Real frame time, like every other presentational tween in this mod: a
 -- fast-forwarded battle must not spin the camera.
 function BattleCam.update(dt)
@@ -146,6 +383,14 @@ function BattleCam.update(dt)
   -- float precision in the sines below
   local wrap = BattleCam.PAN_PERIOD * BattleCam.DOLLY_PERIOD
   if BattleCam.t > wrap then BattleCam.t = BattleCam.t - wrap end
+  -- and the steered three easing after whatever the player last asked for,
+  -- which is what keeps a flick of the stick from being a cut
+  BattleCam.orbit = chase(BattleCam.orbit, BattleCam.orbitGoal, dt,
+                          BattleCam.ORBIT_TIME)
+  BattleCam.pitch = chase(BattleCam.pitch, BattleCam.pitchGoal, dt,
+                          BattleCam.PITCH_TIME)
+  BattleCam.zoom = chase(BattleCam.zoom, BattleCam.zoomGoal, dt,
+                         BattleCam.ZOOM_TIME)
 end
 
 local function phase(t, period)
@@ -163,17 +408,35 @@ end
 --
 -- `groundY` is the height of the arena floor, so a fight staged on a ledge
 -- or a raised walkway is shot from above THAT rather than from inside it.
-function BattleCam.rig(arena, groundY)
+-- `canonical` asks for the shot the rig was SOLVED for -- no drift, no
+-- breath, no steer, no zoom -- from a caller that is reasoning about the
+-- arena rather than drawing it. BattleArena's clearance test is the one
+-- that needs it: whether a fight can be staged somewhere is a fact about
+-- the ground, and answering it through whatever angle the player happened
+-- to leave the last battle on would pick a different arena depending on
+-- where they had swung the camera an hour ago.
+function BattleCam.rig(arena, groundY, canonical)
   groundY = groundY or 0
   local R = BattleCam.rigFor(arena)
   local mx, mz = arena.mid[1], arena.mid[2]
+  -- VR asks for the same stillness for its own reason (see BattleCam.still)
+  local fixed = BattleCam.still or canonical
+  -- and the steer is withheld a second way, on its own: BACK SPRITES holds
+  -- the composition and the DRIFT still runs under it (see steerable)
+  local steered = (not fixed) and BattleCam.steerable
 
-  local yaw = BattleCam.still and 0
-              or BattleCam.PAN_YAW * phase(BattleCam.t, BattleCam.PAN_PERIOD)
+  -- The drift, plus wherever the player has steered to. The steer is
+  -- NEGATIVE because the rotation below runs the other way from the bearing
+  -- it turns: rotating (side, back) by +yaw carries the eye back toward the
+  -- arena's own axis, and the room the player has is all on the far side of
+  -- that -- out toward square-on. (orbitRange measures exactly that room.)
+  local steer = steered and -BattleCam.orbit * BattleCam.orbitRange(arena) or 0
+  local yaw = steer + (fixed and 0
+              or BattleCam.PAN_YAW * phase(BattleCam.t, BattleCam.PAN_PERIOD))
   local c, s = math.cos(yaw), math.sin(yaw)
   -- the breath scales the whole offset, height included, so the eye moves
   -- along its own line to the arena and the pitch of the shot never changes
-  local k = BattleCam.still and 1
+  local k = fixed and 1
             or 1 + BattleCam.PAN_DOLLY
                    * phase(BattleCam.t, BattleCam.DOLLY_PERIOD)
   local dx = (R.side * c - R.back * s) * k
@@ -182,16 +445,45 @@ function BattleCam.rig(arena, groundY)
   local eye = { mx + dx, groundY + R.height * k, mz + dz }
   local focus = { mx + R.lookX, groundY + R.lookY, mz }
 
+  -- and the climb: the eye swung UP about the focus, at a constant radius.
+  -- About the focus so the aim stays nailed to the two mons and only the
+  -- seat moves, and at a constant radius so climbing never changes how big
+  -- anything is -- that is the lens's job below, and a rig that did both at
+  -- once would have no way to do either on purpose.
+  local lift = steered and BattleCam.pitch * BattleCam.PITCH_RANGE or 0
+  if lift > 0 then
+    local vx, vy, vz = eye[1] - focus[1], eye[2] - focus[2], eye[3] - focus[3]
+    local flat = math.sqrt(vx * vx + vz * vz)
+    local r = math.sqrt(flat * flat + vy * vy)
+    if flat > 1e-6 and r > 1e-6 then
+      local a = math.atan2(vy, flat) + lift
+      -- short of straight down, always: the placed camera's up vector is
+      -- world up, which degenerates against a view looking exactly along it
+      a = math.min(a, math.rad(85))
+      local nf = r * math.cos(a)
+      eye[1] = focus[1] + vx / flat * nf
+      eye[3] = focus[3] + vz / flat * nf
+      eye[2] = focus[2] + r * math.sin(a)
+    end
+  end
+
   local ex = eye[1] - focus[1]
   local ey = eye[2] - focus[2]
   local ez = eye[3] - focus[3]
   local dist = math.max(1, math.sqrt(ex * ex + ey * ey + ez * ez))
   local horiz = math.sqrt(ex * ex + ez * ez)
 
+  -- The lens carries the player's zoom: how much world the frame holds is
+  -- the one thing that actually changes the framing here, because the field
+  -- of view is DERIVED from that reach and the distance. Moving the eye
+  -- instead would leave the picture the same size and only change its
+  -- perspective -- which is what the dolly breath above is deliberately
+  -- for, and is not what "zoom" means to anyone holding a wheel.
+  local frameH = fixed and R.frameH or BattleCam.frameH(arena)
   return {
     eye = eye,
     focus = focus,
-    fov = 2 * math.atan((R.frameH / 2) / dist),
+    fov = 2 * math.atan((frameH / 2) / dist),
     -- the world curve is a free-roam flourish that bends the horizon away
     -- from the player; a fixed camera on a staged shot has no player to bend
     -- around, and the bend would tip the arena floor out from under the mons

lib/BattleScene.lua

@@ -472,7 +472,10 @@ function BattleScene.render(state, arena, textures, token)
   local cx, cy = arena.mid[1], arena.mid[2]
   -- the world extents the sun frustum is fitted to; the camera itself is
   -- framed by cam.fov, so these only have to describe the ground in shot
-  local vh = BattleCam.rigFor(arena).frameH * ph / (BattleScene.GB_H * s)
+  -- the player's zoom is part of this: the sun's box is fitted to what the
+  -- frame holds, so a shot pulled wide has to light the ground it just
+  -- brought into view rather than the ground the rig alone would have
+  local vh = BattleCam.frameH(arena) * ph / (BattleScene.GB_H * s)
   local vw = vh * pw / ph
 
   -- the cards need the camera's eye to face it, so the rig has to be live

lib/CamControl.lua

@@ -0,0 +1,415 @@
+-- The player's own camera controls: zoom everywhere, and the battle's orbit.
+--
+-- This mod has four cameras, and by the time a wheel notch arrives they all
+-- want it. So one module owns the INPUTS and answers the only question that
+-- matters -- which camera is this aimed at -- rather than each camera
+-- growing its own wheel handler and racing the others for the event:
+--
+--   a staged battle      the camera the fight is shot with (BattleCam): the
+--                        wheel and Q/E work its lens, and the right stick,
+--                        a drag or the mouse walk it around the arena.
+--
+--   the 3RD rung         the boom behind the player's shoulder
+--                        (ThirdPerson): the wheel, Q/E and a pinch let it
+--                        out and pull it in.
+--
+--   an orbit rung        the engine's own survey zoom, which the wheel has
+--                        always driven -- so here the module mostly gets
+--                        out of the way, and only ADDS the two keys and the
+--                        pinch that the engine has no handler for.
+--
+--   the 1ST rung         nothing. The eye is in the player's head; there is
+--                        no distance to change, and a pinch there would
+--                        silently wind the survey zoom for whenever they
+--                        stepped back out. Inputs pass through untouched.
+--
+-- Every claim is answered by a GATE rather than by a mode flag, and every
+-- wrap forwards whatever it does not claim -- so with voxel mode off, and
+-- on every screen that is not the overworld or a battle, each byte flows
+-- exactly where it always did.
+--
+-- Installed AFTER FirstPerson (see main.lua), which makes these wraps the
+-- outer ones: a battle's controls get first refusal on the mouse and the
+-- touch screen, which is right, because while a fight is staged the
+-- free-roam look is not driving anyway.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Voxel = V.require("VoxelState")
+local Voxel3D = V.require("Voxel3D")
+local FirstPerson = V.require("FirstPerson")
+local ThirdPerson = V.require("ThirdPerson")
+local BattleCam = V.require("BattleCam")
+
+local CamControl = {}
+
+-- ------- tuning
+--
+-- PINCH_SLACK is how far apart two fingers must travel, as a ratio of
+-- their starting gap, before the gesture counts as a pinch at all -- below
+-- it a two-finger tap wobbles rather than zooms.
+--
+-- SURVEY_PINCH is how many of the engine's integer survey steps one
+-- doubling of the finger gap is worth. The survey ladder is coarse (whole
+-- pixels per world pixel), so a pinch has to be geared down or the first
+-- centimetre of travel crosses the whole range.
+CamControl.PINCH_SLACK = 0.02
+CamControl.SURVEY_PINCH = 2.2
+
+-- ------- gates
+
+-- A fight staged on the map, drawn and on screen. Asked of the shot rather
+-- than of the battle state, because the shot is exactly "there is a 3D
+-- battle in front of the player right now" -- with 3D-BTL off, or on a map
+-- with no arena, the engine's own flat battle screen is up and its camera
+-- is not ours to steer.
+-- BACK SPRITES also closes it, through BattleCam.steerable: that setting
+-- nails the player's own mon to the GB's slot on the menu while the foe
+-- stands out on the map, and no camera angle holds a composition that is
+-- half frame and half world (see BattleCam.steerable, which is where the
+-- reasoning lives and which the RIG answers to as well -- so a stored
+-- angle from before the setting was switched on stands down with it).
+local function battleLive()
+  local ok, shot = pcall(function()
+    return V.require("OverworldBattle").shot()
+  end)
+  return (ok and shot and BattleCam.steerable) and true or false
+end
+
+CamControl.battleLive = battleLive
+
+-- The free-roam overworld, with the 3D pass carrying it: the gate every
+-- zoom that is not a battle's answers to.
+local function roaming()
+  return Voxel.active() and Voxel3D.available() and FirstPerson.onTop()
+end
+
+-- Which camera a zoom is aimed at: "battle", "boom", "survey", or nil for
+-- nothing that zooms (1ST, or a screen with no camera of ours behind it).
+function CamControl.zoomTarget()
+  if battleLive() then return "battle" end
+  if not roaming() then return nil end
+  if Voxel.isThirdPerson(Voxel.level) then return "boom" end
+  if Voxel.isFirstPerson(Voxel.level) then return nil end
+  return "survey"
+end
+
+-- ------- zoom
+--
+-- `notches` is signed the way every zoom in this file is: POSITIVE pulls
+-- the camera OUT. The engine's own survey step runs the other way, and is
+-- negated at the one place it is called rather than everywhere else being
+-- bent to match it.
+--
+-- Returns true when the input was ours, which is what tells a wrap to stop
+-- rather than forward.
+
+local function surveyStep(notches)
+  local ok = pcall(function()
+    local Game = require("src.core.Game")
+    Game:zoomStep(notches > 0 and -1 or 1)
+  end)
+  return ok
+end
+
+function CamControl.zoomBy(notches)
+  if not notches or notches == 0 then return false end
+  local target = CamControl.zoomTarget()
+  if target == "battle" then
+    BattleCam.stepZoom(notches)
+    return true
+  elseif target == "boom" then
+    ThirdPerson.stepZoom(notches)
+    return true
+  elseif target == "survey" then
+    -- one call per notch: the engine's ladder is integer rungs, and a
+    -- wheel spun hard should climb them all rather than one
+    for _ = 1, math.min(8, math.abs(notches)) do surveyStep(notches) end
+    return true
+  end
+  return false
+end
+
+-- A pinch's own scale: > 1 is fingers spreading, which means zoom IN
+-- (pull the world closer), which is a NEGATIVE notch count.
+function CamControl.pinchBy(factor)
+  if not (factor and factor > 0) then return false end
+  local target = CamControl.zoomTarget()
+  if target == "boom" then
+    return ThirdPerson.scaleZoom(1 / factor)
+  elseif target == "battle" then
+    -- battles take a pinch too: the wheel and the keys reach this camera
+    -- and a phone has neither, so without it the lens would be the one
+    -- control a touch screen could not work
+    return BattleCam.stepZoom(math.log(1 / factor)
+                              / math.log(BattleCam.ZOOM_STEP))
+  elseif target == "survey" then
+    CamControl.surveyAccum = (CamControl.surveyAccum or 0)
+      + math.log(factor) / math.log(2) * CamControl.SURVEY_PINCH
+    local moved = false
+    while CamControl.surveyAccum >= 1 do
+      CamControl.surveyAccum = CamControl.surveyAccum - 1
+      surveyStep(-1)
+      moved = true
+    end
+    while CamControl.surveyAccum <= -1 do
+      CamControl.surveyAccum = CamControl.surveyAccum + 1
+      surveyStep(1)
+      moved = true
+    end
+    return moved
+  end
+  return false
+end
+
+CamControl.surveyAccum = 0
+
+-- ------- the battle's orbit
+--
+-- Only ever the battle's: the free-roam rungs already steer their own look
+-- through FirstPerson, and these wraps sit outside it precisely so a fight
+-- can borrow the same devices without either of them growing a mode check.
+
+-- The right stick, read as a rate off the axes FirstPerson's own wrap is
+-- already recording (it records whatever the rung, so a battle can read
+-- them without a second wrap on the same seam). Ticked from
+-- OverworldBattle.update, which runs whatever is on top of the stack.
+--
+-- X walks the shot round the arena, Y raises the seat. The Y is NEGATED:
+-- a stick pushed forward reads as negative on SDL's axis, and pushing
+-- forward should send the camera UP and over -- the same "push the camera
+-- where you want it" the drag and the mouse below use.
+function CamControl.tick(dt)
+  if not battleLive() then return end
+  local x, y = FirstPerson.stickX(), FirstPerson.stickY()
+  if x ~= 0 then BattleCam.stickOrbit(x, dt) end
+  if y ~= 0 then BattleCam.stickPitch(-y, dt) end
+end
+
+-- ------- the wraps
+
+local installed = false
+
+function CamControl.install()
+  if installed then return end
+  installed = true
+
+  local Game = require("src.core.Game")
+
+  -- ------- the wheel
+  --
+  -- The engine's own handler is the survey zoom, so the wrap only has to
+  -- take the notch away when some OTHER camera wants it; "survey" falls
+  -- through to exactly the code that always ran.
+  do
+    local inner = Game.wheelmoved
+    function Game:wheelmoved(dx, dy)
+      local target = CamControl.zoomTarget()
+      if (target == "battle" or target == "boom") and dy and dy ~= 0 then
+        CamControl.zoomBy(dy > 0 and -1 or 1)
+        return
+      end
+      return inner(self, dx, dy)
+    end
+  end
+
+  -- ------- the stick clicks
+  --
+  -- Q and E, on the pad: the left stick's click pulls the camera out and the
+  -- right stick's pulls it in. A controller has no wheel and no number row,
+  -- and the two clicks are the only buttons a Gen 1 pad layout leaves free
+  -- (SELECT already walks the angle ladder).
+  --
+  -- Claimed for the two cameras a pad player can actually be looking at
+  -- while pressing them -- the third-person boom and a staged battle's lens
+  -- -- and forwarded untouched everywhere else, so a player who has rebound
+  -- either click keeps it on every other screen, a rebind capture included.
+  -- Not on the orbit rungs: the survey zoom has the OPTIONS row and the
+  -- wheel already, and taking a pad button for it would be taking one from
+  -- a player who never asked.
+  local CLICK_ZOOMS = { boom = true, battle = true }
+  do
+    local inner = Game.gamepadpressed
+    function Game:gamepadpressed(joystick, button)
+      if (button == "leftstick" or button == "rightstick")
+         and CLICK_ZOOMS[CamControl.zoomTarget() or ""] then
+        CamControl.zoomBy(button == "leftstick" and 1 or -1)
+        return
+      end
+      return inner(self, joystick, button)
+    end
+  end
+
+  -- ------- the mouse
+  --
+  -- Battle only. The free-roam look already owns relative motion through
+  -- FirstPerson's own wrap (this one is outside it, so what is claimed here
+  -- never reaches it) and a fight is exactly when that look is not driving.
+  --
+  -- Bare motion, no button held: moving the mouse moves the shot.
+  --
+  -- Each event's contribution is CLAMPED, though, because not every motion
+  -- event is a hand moving. The pointer entering the window, a warp back to
+  -- centre, an alt-tab -- each arrives as ONE event carrying the whole
+  -- distance from wherever the cursor was last seen, and in testing that
+  -- was a couple of hundred counts: enough to swing the shot a quarter of
+  -- the way to side-on before the player had touched anything. A real hand
+  -- delivers its travel as a stream of small events and is unaffected; a
+  -- teleport delivers it as one and is cut down to the size of a flick.
+  local MOUSE_STEP = 40
+  local function clamp(v)
+    return math.max(-MOUSE_STEP, math.min(MOUSE_STEP, v or 0))
+  end
+  do
+    local inner = love.mousemoved
+    love.mousemoved = function(x, y, dx, dy, istouch)
+      if battleLive() and not istouch then
+        -- dy is NEGATED for the same reason the stick's is: moving the
+        -- mouse away from you sends the camera up and over
+        if dx and dx ~= 0 then BattleCam.mouseOrbit(clamp(dx)) end
+        if dy and dy ~= 0 then BattleCam.mousePitch(-clamp(dy)) end
+        -- forwarded anyway: the cursor still has UI to point at, and the
+        -- steer is a read of the motion rather than a claim on it
+      end
+      if inner then return inner(x, y, dx, dy, istouch) end
+    end
+  end
+
+  -- ------- the touch screen
+  --
+  -- Two gestures, told apart by how many fingers are down on OPEN screen
+  -- (the overlay's own d-pad and buttons are never either):
+  --
+  --   one finger, in a battle    drags the shot around the arena
+  --   two fingers               pinch to zoom, wherever zooming means
+  --                             something -- and while they are down the
+  --                             free-roam look stands aside, so a pinch in
+  --                             3RD does not also spin the view
+  local TouchControls = require("src.core.TouchControls")
+
+  local free = {}          -- id -> {x, y} for every finger on open screen
+  local pinch = nil        -- { a, b, gap } while two of them are pinching
+
+  local function freeCount()
+    local n = 0
+    for _ in pairs(free) do n = n + 1 end
+    return n
+  end
+
+  local function gapOf(a, b)
+    local dx, dy = free[a].x - free[b].x, free[a].y - free[b].y
+    return math.sqrt(dx * dx + dy * dy)
+  end
+
+  -- Two free fingers and a camera that zooms: start measuring. The look
+  -- drag is dropped for the duration -- FirstPerson never sees the moves
+  -- below -- and re-seated on whichever finger survives, so the view does
+  -- not jump by however far the pinch travelled.
+  local function startPinch()
+    if pinch or freeCount() < 2 then return end
+    local ids = {}
+    for id in pairs(free) do ids[#ids + 1] = id end
+    local gap = gapOf(ids[1], ids[2])
+    if gap < 16 then return end
+    pinch = { a = ids[1], b = ids[2], gap = gap }
+    CamControl.surveyAccum = 0
+    pcall(FirstPerson.dropLook)
+  end
+
+  local function endPinch(lifted)
+    if not pinch then return end
+    local survivor = nil
+    for id in pairs(free) do
+      if id ~= lifted then survivor = id break end
+    end
+    pinch = nil
+    if survivor and free[survivor] then
+      pcall(FirstPerson.reseatLook, survivor,
+            free[survivor].x, free[survivor].y)
+    end
+  end
+
+  local function onControl(x, y)
+    local hit = nil
+    pcall(function() hit = TouchControls:hitTest(x, y) end)
+    return hit
+  end
+
+  -- Whether this module has any interest in touches at all this frame.
+  -- Kept deliberately wide -- a battle, or anything that zooms -- because
+  -- the wrap forwards everything it does not claim regardless.
+  local function wantsTouch()
+    return battleLive() or CamControl.zoomTarget() ~= nil
+  end
+
+  do
+    local inner = Game.touchpressed
+    function Game:touchpressed(id, x, y)
+      if wantsTouch() and not onControl(x, y) then
+        free[id] = { x = x, y = y }
+        if CamControl.zoomTarget() then startPinch() end
+        -- forwarded even so: a single free finger is the free-roam look's
+        -- to claim (FirstPerson's wrap is inside this one), and in a
+        -- battle it is nobody's until it MOVES
+      end
+      return inner(self, id, x, y)
+    end
+  end
+
+  do
+    local inner = Game.touchmoved
+    function Game:touchmoved(id, x, y)
+      local f = free[id]
+      if f then
+        local px, py = f.x, f.y
+        f.x, f.y = x, y
+        if pinch and (id == pinch.a or id == pinch.b) then
+          local gap = gapOf(pinch.a, pinch.b)
+          local factor = gap / math.max(1, pinch.gap)
+          if math.abs(factor - 1) > CamControl.PINCH_SLACK then
+            CamControl.pinchBy(factor)
+            pinch.gap = gap
+          end
+          return                       -- claimed: never a look drag too
+        end
+        if battleLive() and not pinch then
+          local w, h = 1280, 720
+          pcall(function()
+            w, h = love.graphics.getWidth(), love.graphics.getHeight()
+          end)
+          BattleCam.dragOrbit((x - px) / math.max(320, w))
+          -- dragged UP sends the camera up and over, the same way the
+          -- stick and the mouse do
+          BattleCam.dragPitch(-(y - py) / math.max(240, h))
+          return
+        end
+      end
+      return inner(self, id, x, y)
+    end
+  end
+
+  do
+    local inner = Game.touchreleased
+    function Game:touchreleased(id, x, y)
+      if free[id] then
+        if pinch and (id == pinch.a or id == pinch.b) then endPinch(id) end
+        free[id] = nil
+      end
+      return inner(self, id, x, y)
+    end
+  end
+
+  -- a reset that drops held input state drops ours with it, exactly as the
+  -- free-roam look's does
+  do
+    local inner = Game.focus
+    function Game:focus(f)
+      free, pinch = {}, nil
+      CamControl.surveyAccum = 0
+      return inner(self, f)
+    end
+  end
+end
+
+return CamControl

lib/FirstPerson.lua

@@ -1,4 +1,4 @@
--- Voxel world mode: the first-person camera -- the 1ST rung.
+-- Voxel world mode: the free-roam camera -- the 1ST and 3RD rungs.
 --
 -- 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
@@ -9,6 +9,13 @@
 -- uniforms, project(), the sky's vanishing line, the water's lean -- reads
 -- eye and focus the same way it always has.
 --
+-- 3RD is that same rig with the eye pulled back onto a boom behind the
+-- player's shoulder (lib/ThirdPerson.lua). Everything in this file is
+-- already general over where the eye stands -- the attitude, the look
+-- inputs, the move intent, the cards that turn to face the eye -- so the
+-- third-person rung is one number applied at the very end of frame(),
+-- rather than a second camera to keep in step with this one.
+--
 -- What this module owns:
 --
 --   the ATTITUDE   yaw and pitch, fed by whichever look input speaks:
@@ -47,6 +54,7 @@ local Mat4 = V.require("Mat4")
 local Voxel = V.require("VoxelState")
 local Voxel3D = V.require("Voxel3D")
 local WorldCurve = V.require("WorldCurve")
+local ThirdPerson = V.require("ThirdPerson")
 
 local FirstPerson = {}
 
@@ -102,6 +110,15 @@ FirstPerson.yaw = 0
 FirstPerson.pitch = FirstPerson.PITCH_DEFAULT
 FirstPerson.blend = 0
 
+-- A multiplier on the first-person field of view, for anything that wants
+-- to narrow the lens without owning the rig: 1 is the ordinary 65
+-- degrees, and horde mode's iron sights ease it down toward 40 while the
+-- player is looking down them (lib/HordeGun). Kept here rather than in
+-- the caller because the fov is folded into the orbit blend below, and
+-- because signature() has to know -- a lens that narrows while the player
+-- stands still still has to re-fit the shadow box.
+FirstPerson.fovScale = 1
+
 local wasEngaged = false
 local stick = { x = 0, y = 0 }        -- right stick, latest event values
 local mouseDX, mouseDY = 0, 0         -- relative counts since last update
@@ -133,21 +150,62 @@ end
 
 -- ------- gates
 
--- Whether the 1ST rung is selected and the 3D pass can carry it.
+-- Whether a free-roam rung -- 1ST or 3RD -- is selected and the 3D pass can
+-- carry it. Both stand the camera with the player, so both read the look
+-- inputs, both walk free, and both turn the cards; how far behind the head
+-- the eye ends up is ThirdPerson's business alone.
 function FirstPerson.engaged()
-  return Voxel.isFirstPerson(Voxel.level) and Voxel3D.available()
+  return Voxel.isFreeCam(Voxel.level) and Voxel3D.available()
+end
+
+-- Whether the overworld is what the player is looking at: nothing pushed
+-- over it, so the buttons are free-roam's. Shared with everything else in
+-- the mod that asks the same question of the same stack (CamControl's
+-- zooms above all), rather than each restating the pcall.
+function FirstPerson.onTop()
+  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
 
 -- 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
+  return FirstPerson.engaged() and FirstPerson.onTop()
+end
+
+-- The right stick's live X, for a camera that is not this one: while a
+-- battle is staged the free-roam look is not driving, but the axes are
+-- still arriving on the wrap below (which records whatever the rung), and
+-- the battle's orbit wants them. Reading them here rather than wrapping
+-- the same seam twice.
+function FirstPerson.stickX()
+  return stick.x or 0
+end
+
+function FirstPerson.stickY()
+  return stick.y or 0
+end
+
+-- ------- lending the look finger out
+--
+-- A pinch needs both fingers on the screen, and one of them is very likely
+-- the finger this module claimed as the look drag. Rather than have the
+-- pinch fight for it, CamControl asks for it: dropLook while the gesture
+-- runs, reseatLook on whichever finger survives it. Re-seating rather than
+-- simply releasing is what stops the view snapping by however far the
+-- pinch travelled -- the finger carries on as the look drag from where it
+-- now is, which is what it looks like it should do.
+function FirstPerson.dropLook()
+  lookTouch = nil
+end
+
+function FirstPerson.reseatLook(id, x, y)
+  if id == nil then lookTouch = nil return end
+  lookTouch = { id = id, x = x, y = y }
 end
 
 -- The eased blend, 0 at the orbit and 1 in the head.
@@ -178,7 +236,16 @@ end
 -- 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.
+--
+-- Never while 3RD's boom is genuinely out, whatever the blend: the whole
+-- point of a boom is that the character it is booming away from is on
+-- screen. (Nor the silhouette that rides the same answer -- seeing your own
+-- outline through the building you just walked behind is what a
+-- third-person camera owes the player.) A boom SQUEEZED into the head by a
+-- wall answers false there and the card comes out again, because at that
+-- range it is the first-person problem word for word.
 function FirstPerson.hidePlayer()
+  if ThirdPerson.showsPlayer() then return false end
   return FirstPerson.cardBlend() > 0.9
 end
 
@@ -193,17 +260,79 @@ function FirstPerson.lookBy(dyaw, dpitch)
                                 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)
+-- A bearing as one of the grid's four directions -- the 45-degree
+-- quantisation every facing in this file is made with, in one place so the
+-- compass, the body and the card frames can never disagree about where a
+-- boundary is.
+local function facingOf(a)
+  local s, c = math.sin(a), math.cos(a)
   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 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()
+  return facingOf(FirstPerson.yaw)
+end
+
+-- Which way the BODY points, as a continuous world bearing, given the
+-- world-space direction it is walking (0, 0 while standing). In the head,
+-- the body is the head: you face what you look at. On the boom you can see
+-- yourself, and a character sliding sideways while facing the lens reads as
+-- a bug rather than as a strafe -- so a walking body turns to face its own
+-- travel, and a standing one comes back round to the camera's bearing,
+-- which is the one A talks along.
+function FirstPerson.bodyBearing(wx, wz)
+  if ThirdPerson.extended() and wx and wz and (wx ~= 0 or wz ~= 0) then
+    return math.atan2(wx, wz)
+  end
+  return FirstPerson.yaw
+end
+
+-- The same answer as one of the four facings, which is what the grid game
+-- (and the sprite sheet) reasons in.
+function FirstPerson.bodyFacing(wx, wz)
+  return facingOf(FirstPerson.bodyBearing(wx, wz))
+end
+
+-- ------- the body's live bearing
+--
+-- The bearing the player's own body is actually pointing along RIGHT NOW,
+-- or nil whenever the free walk is not the thing pointing it (a scripted
+-- move, a cutscene, the grid walk with the rung off). FreeMove maintains
+-- it; only the player's own card reads it.
+--
+-- It exists because the card's frame is chosen by the angle BETWEEN the
+-- body and the eye, and quantising the body to a compass direction first
+-- throws away exactly the precision that choice needs. A standing body is
+-- pointed along the camera's own yaw, so the true angle between them is a
+-- flat 180 degrees and the card should show its back and nothing else --
+-- but snap the body to one of four directions on the game tick, then
+-- measure it against an eye that has kept turning since, and the pair can
+-- read as 135 degrees and pick the PROFILE frame instead. Spin the camera
+-- fast and the character flicks to a mirrored side view for a frame or
+-- two. Keeping the bearing continuous gives the measurement a full 45
+-- degrees of slack before it can cross a boundary, which no frame's worth
+-- of turning comes close to spending.
+FirstPerson.bodyYaw = nil
+
+-- Point the body along the direction it is walking (or, standing, along
+-- the camera): records the continuous bearing and hands back the compass
+-- facing the caller wants for p.facing.
+function FirstPerson.pointBody(wx, wz)
+  FirstPerson.bodyYaw = FirstPerson.bodyBearing(wx, wz)
+  return facingOf(FirstPerson.bodyYaw)
+end
+
+-- Hand the body back to whatever else is turning it.
+function FirstPerson.releaseBody()
+  FirstPerson.bodyYaw = nil
+end
+
 -- The unit look direction, and its flat (ground-plane) part.
 local function lookDir()
   local cp = math.cos(FirstPerson.pitch)
@@ -234,21 +363,43 @@ function FirstPerson.cardYaw(wx, wz)
   return math.atan2(dx, dz)
 end
 
+-- Which of the four sprite frames a body at world bearing `phi` shows an
+-- eye looking at (wx, wz): the bearing rotated into the viewer's own frame,
+-- quantised. nil when there is no rig to be seen from.
+local function frameFor(phi, wx, wz)
+  local eye = rig and rig.eye
+  if not (eye and phi) then return nil end
+  local dx, dz = eye[1] - wx, eye[3] - wz
+  if dx * dx + dz * dz < 1e-9 then return nil 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
+
 -- 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.
+--
+-- An NPC's facing IS one of the four and nothing finer, so this is the
+-- whole story for everyone in the world except the one body the camera is
+-- attached to -- see playerFacing.
 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]
+  return frameFor(FACING_ANGLE[facing], wx, wz) or facing
+end
+
+-- The PLAYER's own card, which is the one case where the body's bearing is
+-- known to better than a compass point (bodyYaw, above) -- and the one case
+-- where it matters, because the eye is derived FROM that bearing rather
+-- than independent of it. Measured continuously, a standing body reads as
+-- a flat 180 degrees from its own camera and shows its back, steadily,
+-- however fast the camera is spun. Falls back to the four-direction answer
+-- whenever something other than the free walk is turning the body.
+function FirstPerson.playerFacing(facing, wx, wz)
+  return frameFor(FirstPerson.bodyYaw, wx, wz)
+         or FirstPerson.apparentFacing(facing, wx, wz)
 end
 
 -- ------- the move intent
@@ -344,6 +495,12 @@ function FirstPerson.update(dt)
     rig = nil
   end
 
+  -- the boom, on the same tick and for the same reason: it has to keep
+  -- easing after 3RD is left, and it needs the blend to know whether a
+  -- change of rung is a SLIDE (already inside the world, 1ST <-> 3RD) or
+  -- part of the dive in from the orbit, which carries the eye anyway
+  ThirdPerson.update(dt, FirstPerson.blend)
+
   -- 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
@@ -444,6 +601,12 @@ function FirstPerson.frame(me, cx, cy, vw, vh)
                     head[2] + ly * FirstPerson.FOCUS_DIST,
                     head[3] + lz * FirstPerson.FOCUS_DIST }
 
+  -- 3RD: the eye walks back off the head along the very direction it looks,
+  -- as far as the world allows. Fully in (1ST, and every frame of the
+  -- diorama) this hands back the head and the focus untouched, so the two
+  -- rungs are one rig with one number between them.
+  local camEye, camFocus = ThirdPerson.place(head, lx, ly, lz, fpFocus)
+
   local oEye, oFocus, oFov, oUp = orbitRig(cx, cy, vh)
   local function mix(p, q)
     return { p[1] + (q[1] - p[1]) * e,
@@ -462,8 +625,8 @@ function FirstPerson.frame(me, cx, cy, vw, vh)
   local k = WorldCurve.k(vh) * (1 - e)
 
   rig = {
-    eye = mix(oEye, head),
-    focus = mix(oFocus, fpFocus),
+    eye = mix(oEye, camEye),
+    focus = mix(oFocus, camFocus),
     fov = oFov + (FirstPerson.FOV - oFov) * e,
     up = up,
     curve = k,
@@ -503,6 +666,9 @@ function FirstPerson.signature()
     math.floor(b * 64),
     math.floor(FirstPerson.yaw * 64),
     math.floor(FirstPerson.pitch * 64),
+    -- and how far back the boom stands the eye: a wall shortening it moves
+    -- the camera the sun's box is fitted around, standing still or not
+    ThirdPerson.signature(),
   }, ",")
 end
 
@@ -595,11 +761,30 @@ function FirstPerson.install()
   -- 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.
+  --
+  -- HORDE MODE re-reads the same two buttons as a weapon: left fires,
+  -- right holds the sights. Claimed BEFORE the A/B mapping below rather
+  -- than on top of it, so a click during the mode never also lands as a
+  -- GB button -- otherwise the A that ends the GAME OVER card would be
+  -- spent by the shot that ended the run.
   local mouseHeld = {}
   local MOUSE_BTN = { [1] = "a", [2] = "b" }
+  local function hordeMouse(button, down)
+    local Horde = V.require("Horde")
+    if not Horde.playing() then return false end
+    if button == 1 then
+      if down then V.require("HordeGun").fire() end
+      return true
+    elseif button == 2 then
+      V.require("HordeGun").setAds(down)
+      return true
+    end
+    return false
+  end
   do
     local inner = love.mousepressed
     love.mousepressed = function(x, y, button, istouch, presses)
+      if captured and not istouch and hordeMouse(button, true) then return end
       if captured and not istouch and MOUSE_BTN[button] then
         local Input = require("src.core.Input")
         mouseHeld[button] = true
@@ -612,6 +797,9 @@ function FirstPerson.install()
   do
     local inner = love.mousereleased
     love.mousereleased = function(x, y, button, istouch, presses)
+      -- a release always reaches whoever owns the press: the horde's
+      -- aim-hold has to let go even if the mode ended mid-click
+      if not mouseHeld[button] and hordeMouse(button, false) then return end
       if mouseHeld[button] then
         local Input = require("src.core.Input")
         mouseHeld[button] = nil
@@ -651,6 +839,14 @@ function FirstPerson.install()
         local onControl = nil
         pcall(function() onControl = TouchControls:hitTest(x, y) end)
         if not onControl and not lookTouch then
+          -- HORDE MODE: a tap on open screen is a SHOT, fired on the press
+          -- rather than on a release that turned out not to be a drag --
+          -- a shooter that waits to find out whether you meant it is a
+          -- shooter that misses. The same finger still becomes the look
+          -- drag below, so aiming and firing are one gesture.
+          if V.require("Horde").playing() then
+            V.require("HordeGun").fire()
+          end
           lookTouch = { id = id, x = x, y = y }
           return
         end

lib/FreeMove.lua

@@ -1,11 +1,16 @@
--- Voxel world mode: free movement for the first-person rung.
+-- Voxel world mode: free movement for the free-roam rungs.
 --
 -- 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.
+-- input locked mid-step. Inside a camera that stands with the player that
+-- gait reads as riding a rail, so while 1ST or 3RD 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.
+--
+-- Both rungs walk identically: the boom behind the shoulder (3RD) changes
+-- where the eye stands, not which way it points, and the walk was always
+-- rotated by the YAW. The one thing it does change is which way the body
+-- POINTS while it moves -- see bodyFacing in the tick.
 --
 -- 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
@@ -73,6 +78,11 @@ end
 
 function FreeMove.drop()
   pos = nil
+  -- and the body with it: while something else is walking the player --
+  -- a scripted move, a ledge hop, the grid walk off the rung -- the
+  -- engine's own four-direction facing is the whole truth about which way
+  -- they point, so the card must stop reading our finer one
+  FirstPerson.releaseBody()
 end
 
 -- named for the suite: the module's live position, nil while dropped
@@ -177,12 +187,21 @@ 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.
+-- crossing, the ledge hop, the boulder shove, and the route-gate warp
+-- fired by collision. 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.
+--
+-- The one verb NOT restated here is the bonk. On the grid a blocked step
+-- is a discrete event -- you pressed a direction, the game refused, and
+-- the bump answers you once. A free walk has no such moment: the body
+-- SLIDES along whatever it grazes, so a player walking a fence line or
+-- rounding a doorframe is blocked on one axis continuously, and the same
+-- sound comes out as a rattle for as long as they keep walking. It is
+-- feedback for a refusal that is not happening. The grid walk keeps its
+-- own bump (the engine's, in OverworldController) untouched.
 local function pushSpecials(state, dir, why)
   local p = state.player
   p.facing = dir      -- the handlers read the push off the facing
@@ -199,13 +218,14 @@ local function pushSpecials(state, dir, why)
       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
+  -- and NO bonk. The grid walk's collision sound marks a discrete event:
+  -- you pressed a direction, the step was refused, nothing happened. A
+  -- free walk has no such moment -- the body slides along every wall it
+  -- grazes, continuously, and a corridor taken at a slight angle is a
+  -- steady graze from end to end. Rate-limited or not, that came out as a
+  -- machine-gun of bonks for walking normally down a hallway. The wall
+  -- stopping you is the feedback; the sound only ever said so twice a
+  -- second whether or not anything had changed.
   return false
 end
 
@@ -231,14 +251,26 @@ function FreeMove.tick(state)
   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()
+  -- which way a bonk points. (A body that is WALKING may turn along its
+  -- travel instead -- see below, once there is a travel to turn along; a
+  -- standing one always faces where the camera looks, which is what makes
+  -- A predictable.) pointBody rather than compassFacing, so the card also
+  -- gets the CONTINUOUS bearing behind that compass point.
+  p.facing = FirstPerson.pointBody(0, 0)
 
-  if input:wasPressed("a") then
+  -- HORDE MODE takes both of these away for as long as it runs: there is
+  -- no pausing (START), and nobody stops to read a sign with the horde
+  -- coming (A, which is also the button the mode's own GAME OVER card
+  -- wants left unspent). Everything below -- the walk, the wall slide and
+  -- the blocked-push verbs, warps included -- keeps working, because the
+  -- crowd has to be able to follow the player through a door.
+  local suppressed = V.require("Horde").suppressWorldInput()
+
+  if not suppressed and input:wasPressed("a") then
     state:interact()
     return
   end
-  if input:wasPressed("start") then
+  if not suppressed and input:wasPressed("start") then
     require("src.core.Sound").play(Game.data, "Start_Menu")
     require("src.ui.Screens").push(Game, "StartMenu")
     return
@@ -266,6 +298,16 @@ function FreeMove.tick(state)
 
   if not moving then return end
 
+  -- and once there IS a direction of travel, the body may point along it
+  -- rather than along the head: on the boom (3RD) you can see yourself, so
+  -- a strafe has to look like walking sideways. In the head it is the head
+  -- either way -- bodyBearing says so.
+  p.facing = FirstPerson.pointBody(wx, wz)
+
+  -- the engine's own bonk clock, kept draining while the free walk has the
+  -- wheel: nothing here rings it (see pushSpecials), but stepping back onto
+  -- the grid must not inherit a cooldown frozen at whatever it held when
+  -- the rung was picked
   state.bumpCooldown = math.max(0, (state.bumpCooldown or 0) - 1)
 
   local speed = (Game.save and Game.save.onBike) and FreeMove.BIKE
@@ -307,8 +349,8 @@ function FreeMove.tick(state)
       FreeMove.drop()
       return
     end
-    -- the push handlers may have turned the facing; the head still rules
-    p.facing = FirstPerson.compassFacing()
+    -- the push handlers may have turned the facing; the walk still rules
+    p.facing = FirstPerson.pointBody(wx, wz)
   end
 end
 

lib/Horde.lua

@@ -0,0 +1,707 @@
+-- HORDE MODE: the code, the dark, and the way back.
+--
+-- Up Up Down Down Left Right Left Right B A, standing in the overworld,
+-- and Kanto turns on you: the sky goes to a starless violet night, the
+-- Lavender Town theme comes up, the camera locks into the player's own
+-- head, a handgun appears in their right hand, and waves of people walk
+-- out of the dark to kill them. Score goes up per kill; when the health
+-- runs out a GAME OVER screen offers a score and PRESS A, and pressing it
+-- puts everything back exactly as it was.
+--
+-- WHAT THIS FILE OWNS: the code detector, the state machine, the snapshot
+-- and its restore, and every hook that holds the world still while the
+-- mode runs. The gun is lib/HordeGun, the crowd is lib/HordeMobs, the
+-- readout is lib/HordeHud, the sounds are lib/HordeSfx and the ending is
+-- lib/HordeGameOver.
+--
+-- IT IS NOT A STACK STATE, and that is the load-bearing decision. Pushing
+-- a state over the overworld stops StateStack ticking the overworld,
+-- which stops OverworldState:handleInput, which stops FreeMove -- the
+-- player would be unable to walk. So horde mode is a MODE FLAG driven
+-- from the voxel pipeline's update hook, exactly as lib/OverworldBattle
+-- rides it: the one tick that keeps running through menus, transitions
+-- and battles. The GAME OVER screen IS a pushed state, because by then
+-- the walking is over and freezing the world under it is the point.
+--
+-- THE CODE IS READ OFF GAME BOY BUTTONS, not off keys. Every input device
+-- the engine has -- keyboard, gamepad, raw joystick, the touch overlay,
+-- and the VR controllers (lib/VR.driveControls feeds Input:overlayPressed
+-- and the stick path) -- lands in src/core/Input as one of eight buttons.
+-- One detector on that abstraction is therefore a detector on ALL of
+-- them, which is why the code works on a headset with no keyboard in the
+-- room. It reads Input.pressQueue from the `input.step` hook, the fixed
+-- step's own boundary, so it sees every edge exactly once whatever the
+-- frame rate did.
+--
+-- THE DARK is not a new renderer. DayNight is pinned to NIGHT and then
+-- its two public colour functions are WRAPPED and multiplied down toward
+-- violet -- so the sky bands, the world tint, the flat 2D world (DayTint
+-- paints the same multiply), the water's reflection and the shadow rig
+-- all darken together, because every one of them already reads those two
+-- functions. Wrapped rather than edited in place because both memoise
+-- into file-local caches this module cannot reach.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Voxel = V.require("VoxelState")
+local Voxel3D = V.require("Voxel3D")
+local DayNight = V.require("DayNight")
+local FirstPerson = V.require("FirstPerson")
+local HordeSfx = V.require("HordeSfx")
+
+local Horde = {}
+
+-- lib modules that require THIS one back (the mobs read the session, the
+-- gun reports kills). Loaded on first use rather than at the top, so the
+-- require cycle never closes.
+local Mobs, Gun, Hud
+local function parts()
+  Mobs = Mobs or V.require("HordeMobs")
+  Gun = Gun or V.require("HordeGun")
+  Hud = Hud or V.require("HordeHud")
+  return Mobs, Gun, Hud
+end
+
+-- ------- tuning
+--
+-- Every number the mode is balanced on, in one place.
+
+Horde.MAX_HP = 100
+Horde.CONTACT_DAMAGE = 9        -- one mob's touch
+Horde.INTRO_TIME = 3.6          -- the beat before the first wave
+Horde.DYING_TIME = 1.1          -- from the last hit to the GAME OVER card
+Horde.SONG = "Music_Lavender"
+
+-- how far down NIGHT is dragged. The sky's bands and the world tint are
+-- multiplied by these; the third is how much of the colour is pulled out
+-- on the way (1 keeps it, 0 is greyscale) -- a little desaturation is
+-- what turns "dark" into "grim".
+Horde.GLOOM_SKY = { 0.34, 0.30, 0.46 }
+Horde.GLOOM_WORLD = { 0.42, 0.38, 0.56 }
+Horde.GLOOM_INDOOR = { 0.55, 0.50, 0.68 }
+Horde.GLOOM_SAT = 0.72
+Horde.SHADOW_BOOST = 1.45       -- the moon presses harder than it should
+
+-- ------- state
+
+Horde.active = false            -- every hook in this file gates on it
+Horde.state = "idle"            -- idle | intro | active | dying | gameover
+Horde.session = nil
+
+-- Whether the combat is live: mobs move, the gun fires, damage lands.
+-- False during the intro beat, the death fade, the GAME OVER card -- and
+-- while ANYTHING is on the stack above the overworld, which is what
+-- stops the trigger from firing into a world the player has stopped
+-- looking at while the exit prompt asks them a question.
+function Horde.playing()
+  if not (Horde.active and Horde.state == "active") then return false end
+  local ok, live = pcall(function()
+    local G = require("src.core.Game")
+    local ow = G.overworld
+    return G.stack and ow and G.stack:top() == ow and not ow.transitioning
+  end)
+  return ok and live == true
+end
+
+-- Whether the mode owns the camera rung right now, which is the whole of
+-- what "locked to first person" means: main.lua's cycleVoxel refuses
+-- while this is true, and that one function is what the 3 key, the pad's
+-- SELECT and the VR stick click all call.
+function Horde.viewLocked()
+  return Horde.active
+end
+
+-- Whether the free walk should skip its A (talk) and START (menu)
+-- branches. Nobody stops to read a sign mid-firefight, and START has a
+-- different job here (see askExit).
+function Horde.suppressWorldInput()
+  return Horde.active
+end
+
+local function game()
+  local ok, G = pcall(require, "src.core.Game")
+  return ok and G or nil
+end
+
+local function overworld(G)
+  G = G or game()
+  return G and G.overworld or nil
+end
+
+-- The way out, on demand. START -- the pad's, the keyboard's ESCAPE, the
+-- touch overlay's -- and the VR left stick click all ask this, and it
+-- asks the player. Nothing here ends the mode; the prompt does that
+-- through Horde.finish if the answer is yes.
+--
+-- Refused while anything is already on top of the overworld, so the
+-- question cannot stack on itself or arrive over the GAME OVER card.
+--
+-- BELOW the two helpers above, deliberately: a Lua local is only in
+-- scope after its declaration, so a function written above them captures
+-- the GLOBAL of that name instead -- which is nil, and only says so when
+-- somebody presses the button.
+function Horde.askExit(G)
+  G = G or game()
+  if not (Horde.active and Horde.state ~= "gameover") then return false end
+  local ow = overworld(G)
+  if not (G and G.stack and ow and G.stack:top() == ow) then return false end
+  if ow.transitioning then return false end
+  local pushed = false
+  pcall(function()
+    require("src.ui.Screens").push(G, "HordeExitPrompt")
+    pushed = true
+  end)
+  return pushed
+end
+
+-- ------- the code
+--
+-- Advance on the expected button; on a wrong one, fall back to the
+-- longest run already entered that is still a valid start of the code,
+-- and try again from there. That fallback is why this is a table rather
+-- than a counter: the code STARTS with a repeat, so a player who presses
+-- Up three times has, on the third, still entered "Up Up" -- and a naive
+-- "wrong button, back to the beginning" rule would throw one of them
+-- away and refuse a code that was in fact typed correctly. (It is the
+-- prefix function from Knuth-Morris-Pratt, over ten buttons.)
+--
+-- The timeout is in fixed steps, 60 to the second: a code is a deliberate
+-- act, and a stray Up a minute ago should not be half of one.
+
+local SEQUENCE = { "up", "up", "down", "down",
+                   "left", "right", "left", "right", "b", "a" }
+local IDLE_STEPS = 150          -- two and a half seconds between buttons
+
+-- FALLBACK[n] = how much of the code is still entered after n matched
+-- buttons and then a wrong one
+local FALLBACK = { [0] = 0, [1] = 0 }
+do
+  local k = 0
+  for i = 2, #SEQUENCE do
+    while k > 0 and SEQUENCE[k + 1] ~= SEQUENCE[i] do k = FALLBACK[k] end
+    if SEQUENCE[k + 1] == SEQUENCE[i] then k = k + 1 end
+    FALLBACK[i] = k
+  end
+end
+
+local progress = 0
+local sinceLast = 0
+
+-- Named for the suite: how far into the code the detector has got.
+function Horde._progress()
+  return progress
+end
+
+local function resetCode()
+  progress, sinceLast = 0, 0
+end
+
+-- Can the mode start from where the player is standing? The overworld has
+-- to be the live state (not a menu, not a battle, not a transition wipe),
+-- the 3D pass has to exist to put a camera inside, and the world has to be
+-- free-roaming rather than mid-cutscene.
+--
+-- MID-STEP IS ALLOWED, and that is not an oversight. Six of the code's ten
+-- buttons are directions, so entering it on a d-pad walks the player four
+-- cells across the map -- and at the moment the closing A lands they are
+-- very often still animating the last of those steps. Refusing a code for
+-- being mid-step would refuse most of the codes anyone actually enters.
+-- The snapshot records the cell the step began from, which is where the
+-- restore puts them back.
+function Horde.canStart(G)
+  G = G or game()
+  if not G or Horde.active then return false end
+  local ow = overworld(G)
+  if not (ow and ow.map and ow.player) then return false end
+  if not (G.stack and G.stack:top() == ow) then return false end
+  if ow.transitioning or ow.scripted or ow.engaging then return false end
+  if ow.player.inputLocked then return false end
+  if not Voxel3D.available() then return false end
+  return true
+end
+
+-- One fixed step of the detector, over the edges about to be promoted.
+-- Separated from the hook so the suite can drive it with a plain list.
+function Horde.feed(queue)
+  if Horde.active then
+    resetCode()
+    return false
+  end
+  sinceLast = sinceLast + 1
+  if progress > 0 and sinceLast > IDLE_STEPS then resetCode() end
+  local fired = false
+  for _, btn in ipairs(queue or {}) do
+    sinceLast = 0
+    while progress > 0 and SEQUENCE[progress + 1] ~= btn do
+      progress = FALLBACK[progress]
+    end
+    if SEQUENCE[progress + 1] == btn then
+      progress = progress + 1
+      if progress >= #SEQUENCE then
+        resetCode()
+        fired = true
+      end
+    end
+  end
+  return fired
+end
+
+-- ------- the snapshot
+--
+-- Everything the mode changes, read back before it changes any of it.
+-- Presentational settings included: the rung, the two engine FX levels the
+-- rung clearing would zero, and the clock -- a player who was watching a
+-- CYCLE sunset gets their sunset back.
+
+local function snapshot(G)
+  local ow = overworld(G)
+  local p = ow.player
+  local Pipelines = require("src.render.Pipelines")
+  local opts = G.save and G.save.options or {}
+  local snap = {
+    mapId = ow.map.id,
+    cellX = p.cellX, cellY = p.cellY,
+    px = p.px, py = p.py,
+    facing = p.facing,
+    viewLevel = Pipelines.level("voxel"),
+    tilt = opts.tilt or 0,
+    gbcfx = opts.gbcfx or 0,
+    fpYaw = FirstPerson.yaw,
+    fpPitch = FirstPerson.pitch,
+    dayIndex = DayNight.setting:read(),
+    dayClock = DayNight.clock,
+  }
+  return snap
+end
+
+-- ------- the gloom
+--
+-- Installed once and inert while the mode is off: each wrapper calls
+-- through and returns the base answer untouched unless Horde.active.
+
+local gloomInstalled = false
+
+local function desaturate(r, g, b, keep)
+  local lum = 0.30 * r + 0.59 * g + 0.11 * b
+  return lum + (r - lum) * keep,
+         lum + (g - lum) * keep,
+         lum + (b - lum) * keep
+end
+
+local function installGloom()
+  if gloomInstalled then return end
+  gloomInstalled = true
+
+  -- The sky's bands. Sky.bands caches BY COLOUR VALUE, so darkening what
+  -- this returns rebuilds the band ramp on its own -- and puts it back the
+  -- same way when the mode ends.
+  do
+    local base = DayNight.palette
+    local cacheIn, cacheOut = nil, nil
+    DayNight.palette = function(t)
+      local pal = base(t)
+      if not Horde.active then return pal end
+      if cacheIn == pal then return cacheOut end
+      local k = Horde.GLOOM_SKY
+      local out = {}
+      for i, c in ipairs(pal) do
+        local r, g, b = c[1] * k[1], c[2] * k[2], c[3] * k[3]
+        r, g, b = desaturate(r, g, b, Horde.GLOOM_SAT)
+        out[i] = { math.floor(r), math.floor(g), math.floor(b) }
+      end
+      cacheIn, cacheOut = pal, out
+      return out
+    end
+  end
+
+  -- The world multiply -- the voxel shader's tint uniform AND, through
+  -- DayTint, the flat 2D world. Indoors normally returns neutral white;
+  -- under the horde it does not, because a Pokemon Centre with the horde
+  -- in it should not look like a Pokemon Centre.
+  do
+    local base = DayNight.tint
+    local cacheIn, cacheOut, cacheOutdoor = nil, nil, nil
+    DayNight.tint = function(outdoor, t)
+      local c = base(outdoor, t)
+      if not Horde.active then return c end
+      if cacheIn == c and cacheOutdoor == outdoor then return cacheOut end
+      local k = outdoor and Horde.GLOOM_WORLD or Horde.GLOOM_INDOOR
+      local r, g, b = c[1] * k[1], c[2] * k[2], c[3] * k[3]
+      r, g, b = desaturate(r, g, b, Horde.GLOOM_SAT)
+      cacheIn, cacheOutdoor, cacheOut = c, outdoor, { r, g, b }
+      return cacheOut
+    end
+  end
+
+  -- and the shadows press harder: applyRig writes SHADOW_ALPHA from the
+  -- hour, so the boost goes on after it has had its say
+  do
+    local base = DayNight.applyRig
+    DayNight.applyRig = function(outdoor)
+      local t = base(outdoor)
+      if Horde.active then
+        Voxel3D.SHADOW_ALPHA = math.min(0.75,
+          (Voxel3D.SHADOW_ALPHA or 0) * Horde.SHADOW_BOOST)
+      end
+      return t
+    end
+  end
+end
+
+-- ------- starting
+
+-- The banner over the world: text, and how long it holds before fading.
+function Horde.banner(text, hold)
+  local s = Horde.session
+  if not s then return end
+  s.bannerText = text
+  s.bannerT = 0
+  s.bannerHold = hold or 2.2
+end
+
+function Horde.begin(G)
+  G = G or game()
+  if not Horde.canStart(G) then return false end
+  local Pipelines = require("src.render.Pipelines")
+  local mobs, gun = parts()
+
+  local snap = snapshot(G)
+  Horde.session = {
+    hp = Horde.MAX_HP, maxHp = Horde.MAX_HP,
+    score = 0, wave = 0, kills = 0,
+    t = 0, introT = Horde.INTRO_TIME, dyingT = 0,
+    damageFlash = 0, hitMarker = 0, hurtCooldown = 0,
+    bannerText = nil, bannerT = 0, bannerHold = 0,
+    snapshot = snap,
+    spawned = {},          -- mapId -> { [objIndex] = true }, for the scrub
+    mobs = {},
+    waveRemaining = 0, waveGap = 0, spawnGap = 0, followQueue = 0,
+    startedAt = os and os.time and os.time() or 0,
+  }
+  Horde.active = true
+  Horde.state = "intro"
+
+  -- the rung, forced and then held: FP_LEVEL is the one rung with a camera
+  -- inside the world, and cycleVoxel refuses to leave it while active
+  Pipelines.setLevel("voxel", Voxel.FP_LEVEL)
+  Pipelines.syncOptions(G.save.options)
+  G.save.options.tilt, G.save.options.gbcfx = 0, 0
+  pcall(function() require("src.render.Tilt").setLevel(0) end)
+  pcall(function() require("src.render.GBCFX").setLevel(0) end)
+  pcall(G.writeOptions, G)
+
+  -- night, pinned; the gloom wrappers do the rest on top of it
+  local nightIndex = 3          -- DayNight.setting values: sync/day/NIGHT/...
+  for i, v in ipairs(DayNight.setting.values) do
+    if v == "night" then nightIndex = i end
+  end
+  DayNight.setting:setIndex(nightIndex, G)
+
+  pcall(function()
+    require("src.core.Music").play(G.data, Horde.SONG, true,
+                                   { reason = "horde" })
+  end)
+
+  gun.reset()
+  mobs.begin(G)
+  Horde.banner("A DARKNESS APPROACHES", 2.6)
+  return true
+end
+
+-- ------- damage and score
+
+function Horde.addScore(n)
+  local s = Horde.session
+  if not s then return end
+  s.score = s.score + (n or 0)
+end
+
+-- A mob reached the player. Returns true when the hit landed (it is on a
+-- cooldown, so a crowd of six does not delete the player in one frame).
+function Horde.damage(n)
+  local s = Horde.session
+  if not (s and Horde.playing()) then return false end
+  if s.hurtCooldown > 0 then return false end
+  s.hurtCooldown = 0.55
+  s.hp = math.max(0, s.hp - (n or Horde.CONTACT_DAMAGE))
+  s.damageFlash = 1
+  HordeSfx.play(HordeSfx.HURT)
+  if s.hp <= 0 then
+    Horde.state = "dying"
+    s.dyingT = Horde.DYING_TIME
+    pcall(function() require("src.core.Sound").stopLoop("Low_Health_Alarm") end)
+  end
+  return true
+end
+
+-- ------- the ending
+
+local function pushGameOver(G)
+  Horde.state = "gameover"
+  local s = Horde.session
+  local best = 0
+  pcall(function() best = V.mod.save:get("hordeBest", 0) or 0 end)
+  if s.score > best then
+    best = s.score
+    pcall(function() V.mod.save:set("hordeBest", best) end)
+  end
+  s.best = best
+  pcall(function() require("src.core.Music").stop() end)
+  pcall(function()
+    require("src.ui.Screens").push(G, "HordeGameOver")
+  end)
+end
+
+-- Put everything back. Called from the GAME OVER card's A press.
+--
+-- Order matters: active goes false FIRST, so the music hook, the gloom
+-- wrappers and the mob spawner have all stood down before anything is
+-- restored under them. The warp home is taken even when the player never
+-- left the map they started on -- setMap rebuilds the cast from the map
+-- record, which is what puts every NPC the horde ate back on its feet.
+function Horde.finish(G)
+  G = G or game()
+  local s = Horde.session
+  if not s then return false end
+  local mobs = parts()
+  local snap = s.snapshot or {}
+
+  Horde.active = false
+  Horde.state = "idle"
+  resetCode()
+
+  mobs.cleanup(G)
+  pcall(function() require("src.core.Sound").stopLoop("Low_Health_Alarm") end)
+
+  -- the clock, back to the hour and the setting the player kept
+  if snap.dayIndex then DayNight.setting:setIndex(snap.dayIndex, G) end
+  if snap.dayClock then DayNight.clock = snap.dayClock end
+
+  -- the rung and the two FX levels the rung clearing zeroed
+  pcall(function()
+    local Pipelines = require("src.render.Pipelines")
+    Pipelines.setLevel("voxel", snap.viewLevel or 0)
+    Pipelines.syncOptions(G.save.options)
+    G.save.options.tilt = snap.tilt or 0
+    G.save.options.gbcfx = snap.gbcfx or 0
+    require("src.render.Tilt").setLevel(snap.tilt or 0)
+    require("src.render.GBCFX").setLevel(snap.gbcfx or 0)
+    G:writeOptions()
+  end)
+
+  if snap.fpYaw then FirstPerson.yaw = snap.fpYaw end
+  if snap.fpPitch then FirstPerson.pitch = snap.fpPitch end
+
+  Horde.session = nil
+
+  -- home, through the engine's own warp: a fade, a setMap, and the map's
+  -- own music coming back up on the other side (the hook that was forcing
+  -- Lavender is inert now)
+  local ow = overworld(G)
+  if ow and snap.mapId then
+    pcall(function()
+      ow:startWarpTo(snap.mapId, snap.cellX, snap.cellY, snap.facing or "down",
+                     function()
+                       -- the pixel position and the facing, restated on
+                       -- the far side of the fade. setMap already placed
+                       -- both, but the free walk owns them while the rung
+                       -- is still easing out of the head, and the head was
+                       -- looking wherever the last shot was aimed
+                       local p = overworld(G) and overworld(G).player
+                       if not p then return end
+                       if snap.px then p.px, p.py = snap.px, snap.py end
+                       if snap.facing then p.facing = snap.facing end
+                     end,
+                     { via = "warp" })
+    end)
+  end
+  return true
+end
+
+-- ------- the tick
+--
+-- Rides the voxel pipeline's update hook, which Game:update calls every
+-- frame whatever the level and whatever is on the stack -- so the mode
+-- keeps thinking through a warp's transition wipe and under the GAME OVER
+-- card, which is exactly what a mode that owns the whole screen needs.
+
+function Horde.update(dt)
+  if not Horde.active then return end
+  local s = Horde.session
+  if not s then
+    Horde.active = false
+    return
+  end
+  dt = math.min(dt or 0, 0.1)         -- a hitch must not teleport the wave
+  local G = game()
+  local mobs, gun, hud = parts()
+
+  s.t = s.t + dt
+  s.damageFlash = math.max(0, s.damageFlash - dt * 2.2)
+  s.hitMarker = math.max(0, s.hitMarker - dt * 4)
+  s.hurtCooldown = math.max(0, s.hurtCooldown - dt)
+  if s.bannerText then
+    s.bannerT = s.bannerT + dt
+    if s.bannerT > s.bannerHold + 1.1 then s.bannerText = nil end
+  end
+  hud.update(dt)
+
+  if Horde.state == "intro" then
+    s.introT = s.introT - dt
+    if s.introT <= 0 then
+      Horde.state = "active"
+      mobs.nextWave(G)
+    end
+    return
+  end
+
+  if Horde.state == "dying" then
+    s.dyingT = s.dyingT - dt
+    mobs.update(dt, G)             -- the crowd keeps coming while you fall
+    if s.dyingT <= 0 then pushGameOver(G) end
+    return
+  end
+
+  if Horde.state ~= "active" then return end
+
+  -- the world only ticks while the overworld is actually the live state:
+  -- during a warp's wipe there is no map under the mobs to walk on
+  local ow = overworld(G)
+  local live = G and G.stack and ow and G.stack:top() == ow
+                 and not ow.transitioning
+  gun.update(dt, live)
+  if live then mobs.update(dt, G) end
+
+  -- the siren the game already owns, for the last third of the health bar
+  local low = s.hp <= s.maxHp * 0.3
+  if low ~= s.alarmOn then
+    s.alarmOn = low
+    pcall(function()
+      local Sound = require("src.core.Sound")
+      if low then Sound.startLoop(G.data, "Low_Health_Alarm")
+      else Sound.stopLoop("Low_Health_Alarm") end
+    end)
+  end
+end
+
+-- ------- the seams
+--
+-- Every engine and mod hook the mode needs, installed once. main.lua
+-- calls this AFTER FreeMove.install and the SELECT wrap, so the
+-- handleInput wrap this adds sits outside both of theirs.
+
+local installed = false
+
+function Horde.install()
+  if installed then return end
+  installed = true
+  local mod = V.mod
+
+  installGloom()
+
+  -- THE CODE. `input.step` runs once per fixed step, immediately before
+  -- Input:step promotes the queue into this step's edges -- so pressQueue
+  -- is exactly "the buttons that were pressed since last time", in order,
+  -- from every device at once. Read, never consumed: the game still gets
+  -- every one of them.
+  mod.hooks:wrap("input.step", function(next, G, dt)
+    local inp = G and G.input
+    if inp and inp.pressQueue and Horde.feed(inp.pressQueue) then
+      pcall(Horde.begin, G)
+    elseif Horde.playing() and inp and inp.pressQueue then
+      -- B is a trigger while the horde is up (the pad's B, the keyboard's,
+      -- the touch overlay's). Read here rather than in the frame tick
+      -- because THIS is the boundary that sees each press exactly once.
+      for _, btn in ipairs(inp.pressQueue) do
+        if btn == "b" then
+          local _, gun = parts()
+          gun.fire()
+        end
+      end
+    end
+    return next(G, dt)
+  end)
+
+  -- Lavender, and it stays Lavender. Every song choice in the engine goes
+  -- through this hook, so a door into a building cannot change the record.
+  mod.hooks:wrap("music.select", function(next, chosen, ctx)
+    if Horde.active and Horde.state ~= "gameover" then
+      return next(Horde.SONG, ctx)
+    end
+    return next(chosen, ctx)
+  end)
+
+  -- no wild encounters: returning nil from this hook suppresses the roll
+  -- outright, which is the documented way to do it
+  mod.hooks:wrap("encounter.roll", function(next, encDef, ctx)
+    if Horde.active then return nil end
+    return next(encDef, ctx)
+  end)
+
+  -- and no trainer walking up to talk. Wrapped rather than set through
+  -- self.engaging, which would also freeze the player's own input.
+  do
+    local OverworldState = require("src.world.OverworldController")
+    if not OverworldState.dramaticShapeHordeSight then
+      local inner = OverworldState.checkTrainerSight
+      function OverworldState:checkTrainerSight(...)
+        if Horde.active then return end
+        return inner(self, ...)
+      end
+      OverworldState.dramaticShapeHordeSight = true
+    end
+  end
+
+  -- THE BUTTONS THE WORLD MAY NOT HAVE. A, START, SELECT and B are the
+  -- mode's, and this wrap is where they are taken -- the OUTERMOST wrap on
+  -- handleInput, installed after FreeMove's and after the SELECT hook, so
+  -- the edges are gone before either of them looks.
+  --
+  -- It has to be here rather than inside the free walk, because the free
+  -- walk is not always the one reading: the rung is forced to 1ST at the
+  -- moment the code completes, but the camera takes a few frames to blend
+  -- into the head, and until it does the GRID walk still owns the frame.
+  -- That is not a corner case -- it is the very first frame of every run,
+  -- and the code's own closing A was landing in it and opening a dialogue
+  -- with whoever the player happened to be standing next to.
+  --
+  -- The EDGE is cleared, not the hold: pressed[] is rebuilt from scratch
+  -- every fixed step, so this reaches exactly this step's presses and
+  -- nothing downstream of it can revive one.
+  do
+    local OverworldState = require("src.world.OverworldController")
+    if not OverworldState.dramaticShapeHordeInput then
+      local inner = OverworldState.handleInput
+      function OverworldState:handleInput(...)
+        if Horde.active then
+          local G = game()
+          local inp = G and G.input
+          if inp and inp.pressed then
+            -- START is the way out, and it is asked rather than taken:
+            -- read here, BEFORE the edge is cleared, so the engine's own
+            -- START menu never sees it
+            if inp.pressed.start then Horde.askExit(G) end
+            inp.pressed.a = nil        -- no talking
+            inp.pressed.b = nil        -- the trigger, already read
+            inp.pressed.start = nil    -- and no start menu
+            inp.pressed.select = nil   -- no changing the view
+          end
+        end
+        return inner(self, ...)
+      end
+      OverworldState.dramaticShapeHordeInput = true
+    end
+  end
+
+  -- the crowd follows the player through the door: a warp lands a new map
+  -- with none of the old one's actors on it, so the roster is re-seeded on
+  -- the far side (lib/HordeMobs)
+  mod.events:on("map.entered", function(payload)
+    if not Horde.active then return end
+    local mobs = parts()
+    pcall(mobs.onMapEntered, payload)
+  end)
+end
+
+return Horde

lib/HordeExitPrompt.lua

@@ -0,0 +1,94 @@
+-- HORDE MODE: the way out.
+--
+-- START (the pad's, the keyboard's ESCAPE, the touch overlay's) and the
+-- VR left stick click all land here: a plain yes/no over the frozen
+-- world, asking whether to leave. YES hands over to Horde.finish, which
+-- is the same restore the GAME OVER card runs -- the map, the cell, the
+-- facing, the camera rung, the hour, the music and every NPC put back
+-- exactly as they were. NO drops the player straight back into the
+-- firefight.
+--
+-- Pushing a state is what pauses the mode, and it is the only thing that
+-- can: horde mode rides the pipeline's update hook rather than the state
+-- stack precisely so that nothing on the stack stops it, but the combat
+-- inside Horde.update is gated on the overworld actually being the live
+-- state, so this prompt freezes the crowd and the gun for as long as it
+-- is up. That is the correct behaviour for a confirmation and it is why
+-- "no pausing" does not extend to this one.
+--
+-- Drawn the way the game draws a yes/no: a white bordered box with black
+-- text and the filled arrow beside the row (see Theme.choiceBox, which
+-- is where the original's own YES_NO_MENU sits). Black on white because
+-- that is what the font IS -- the sheets are black glyphs on transparent
+-- and no colour can lighten one.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Horde = V.require("Horde")
+
+local HordeExitPrompt = {}
+HordeExitPrompt.__index = HordeExitPrompt
+
+-- the question's box, and the choice box under it, in 8px tiles
+local ASK = { tx = 1, ty = 6, tw = 18, th = 4 }
+local PICK = { tx = 13, ty = 10, tw = 6, th = 6 }
+
+function HordeExitPrompt.new(game)
+  local self = setmetatable({}, HordeExitPrompt)
+  self.game = game
+  -- NOT opaque: the horde is still standing out there behind this, which
+  -- is most of what makes the question feel like a decision
+  self.isOpaque = false
+  self.index = 2          -- NO, the way every dangerous prompt starts
+  self.done = false
+  return self
+end
+
+local function sfx(game, name)
+  pcall(function()
+    require("src.core.Sound").play(game.data, name)
+  end)
+end
+
+function HordeExitPrompt:update()
+  if self.done then return end
+  local input = self.game and self.game.input
+  if not input then return end
+
+  if input:wasPressed("up") or input:wasPressed("down") then
+    self.index = self.index == 1 and 2 or 1
+  elseif input:wasPressed("a") then
+    self.done = true
+    sfx(self.game, "Press_AB")
+    self.game.stack:pop()
+    if self.index == 1 then pcall(Horde.finish, self.game) end
+  elseif input:wasPressed("b") or input:wasPressed("start") then
+    -- B and START both mean "no": the button that opened this closes it,
+    -- which is the one thing a player who opened it by accident will try
+    self.done = true
+    sfx(self.game, "Press_AB")
+    self.game.stack:pop()
+  end
+end
+
+function HordeExitPrompt:draw()
+  local ok, Font = pcall(require, "src.render.Font")
+  if not ok then return end
+  local okT, Theme = pcall(require, "src.ui.Theme")
+
+  Font.drawBox(ASK.tx, ASK.ty, ASK.tw, ASK.th)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw("EXIT MINI GAME?", (ASK.tx + 2) * 8, (ASK.ty + 2) * 8)
+
+  Font.drawBox(PICK.tx, PICK.ty, PICK.tw, PICK.th)
+  love.graphics.setColor(0, 0, 0, 1)
+  Font.draw("YES", (PICK.tx + 2) * 8, (PICK.ty + 2) * 8)
+  Font.draw("NO", (PICK.tx + 2) * 8, (PICK.ty + 4) * 8)
+  local cursor = okT and Theme.cursor or 0xED
+  Font.drawCode(cursor, (PICK.tx + 1) * 8,
+                (PICK.ty + 2 + (self.index - 1) * 2) * 8)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+return HordeExitPrompt

lib/HordeGameOver.lua

@@ -0,0 +1,107 @@
+-- HORDE MODE: the card at the end.
+--
+-- A stack state, unlike the mode itself -- and for the opposite reason.
+-- Horde mode cannot be a pushed state because pushing one stops the
+-- overworld ticking and the player could not walk; the GAME OVER card
+-- WANTS exactly that. Pushed, it freezes the world underneath, takes the
+-- buttons, and stands there until A.
+--
+-- It draws in the engine's own 160x144 UI canvas with the game's own
+-- font, which is what makes it work in VR for free: with a headset live
+-- and something other than the overworld on top of the stack, lib/VR
+-- already puts the flat screen on the floating panel (or on the Pokedex
+-- in the player's left hand). A card drawn the way the game draws cards
+-- arrives there with no VR code at all.
+--
+-- A pops it and hands over to Horde.finish, which is what puts the world
+-- back: the map, the cell, the facing, the camera rung, the hour, the
+-- music, and every NPC the horde had turned into a mob.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Horde = V.require("Horde")
+
+local W, H = 160, 144
+
+local HordeGameOver = {}
+HordeGameOver.__index = HordeGameOver
+
+function HordeGameOver.new(game)
+  local self = setmetatable({}, HordeGameOver)
+  self.game = game
+  self.isOpaque = true
+  self.t = 0
+  -- the session is read ONCE, here: Horde.finish clears it, and this card
+  -- outlives that by a frame or two while the warp home fades
+  local s = Horde.session or {}
+  self.score = math.floor(s.score or 0)
+  self.best = math.floor(s.best or 0)
+  self.wave = math.max(1, s.wave or 1)
+  self.kills = s.kills or 0
+  self.done = false
+  return self
+end
+
+function HordeGameOver:update(dt)
+  self.t = self.t + (dt or 0)
+  if self.done then return end
+  -- a beat of dead air before the prompt takes input, so the button that
+  -- was being mashed at the moment of death does not dismiss the card
+  if self.t < 0.6 then return end
+  local input = self.game and self.game.input
+  if input and input:wasPressed("a") then
+    self.done = true
+    pcall(function()
+      require("src.core.Sound").play(self.game.data, "Press_AB")
+    end)
+    self.game.stack:pop()
+    pcall(Horde.finish, self.game)
+  end
+end
+
+-- THE CARD IS DRAWN THE WAY THE GAME DRAWS CARDS: a bordered white box
+-- with black text in it (Font.drawBox then setColor(0,0,0)), exactly as
+-- HallOfFame and every menu do. That is not decoration -- the UI canvas
+-- is a FOUR-SHADE Game Boy screen, and an arbitrary colour drawn into it
+-- has nowhere to land. A first cut of this card painted a dark red on
+-- near-black and composited as a rectangle of pure black, with the score
+-- in it and invisible.
+local function centred(Font, str, y, scale)
+  scale = scale or 1
+  local w = Font.width(str) * scale
+  love.graphics.push()
+  love.graphics.translate(math.floor((W - w) / 2), y)
+  love.graphics.scale(scale, scale)
+  Font.draw(str, 0, 0)
+  love.graphics.pop()
+end
+
+function HordeGameOver:draw()
+  local ok, Font = pcall(require, "src.render.Font")
+  if not ok then return end
+
+  -- the whole screen as one box: isOpaque keeps the stack from drawing
+  -- the world under it, but the canvas still holds whatever was there
+  Font.drawBox(0, 0, 20, 18)
+
+  love.graphics.setColor(0, 0, 0, 1)
+  centred(Font, "GAME OVER", 3 * 8, 2)
+
+  centred(Font, ("SCORE  %d"):format(self.score), 8 * 8)
+  centred(Font, ("WAVE %d"):format(self.wave), 10 * 8)
+  centred(Font, ("KILLS %d"):format(self.kills), 11 * 8)
+
+  if self.best > 0 then
+    centred(Font, (self.score >= self.best) and "NEW BEST!"
+                  or ("BEST  %d"):format(self.best), 13 * 8)
+  end
+
+  -- the prompt blinks the way every "press a button" in this game blinks
+  if self.t > 0.6 and (self.t % 1.0) < 0.62 then
+    centred(Font, "PRESS A", 15 * 8)
+  end
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+return HordeGameOver

lib/HordeGun.lua

@@ -0,0 +1,511 @@
+-- HORDE MODE: the handgun.
+--
+-- A voxel model in the player's right hand, authored here in METRES the
+-- way lib/Pokedex authors the device in the left one -- because the VR
+-- mapping's scale is what turns metres into world pixels, a mesh built
+-- this way is the right size in the hand at every scale the mod has, and
+-- the same mesh serves the flat screen's view model.
+--
+-- IN VR the gun rides the tracked right hand through VRRig.propMatrix,
+-- pointed by the runtime's AIM pose where one exists (the pose a runtime
+-- defines as "where the user is pointing") and by the grip pose where it
+-- does not. You aim it by pointing it. The iron sights are real geometry,
+-- and lining them up is how you shoot accurately, because the shot is
+-- traced down the model's own barrel axis.
+--
+-- ON THE FLAT SCREEN there is no hand to track, so the gun is carried by
+-- the camera: a model matrix built from the first-person eye and its yaw
+-- and pitch, with the gun hanging at the hip until the player aims. AIM
+-- DOWN SIGHTS slides it to the centre of the screen with the sight line
+-- ON the eye axis -- the model is authored with its rear notch at the
+-- origin precisely so that offset is (0, 0, forward) -- and narrows the
+-- field of view, which is the whole of what aiming does here.
+--
+-- THE SHOT IS A RAY, traced the same way in both modes: march it in world
+-- pixels, let terrain height stop it (a wall is a tall cell, so a cell
+-- whose ground is above the ray's height is a wall the bullet hits), and
+-- test every live mob against it as a standing cylinder. Nearest wins,
+-- and a hit above the shoulder line counts double.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Mat4 = V.require("Mat4")
+local Voxel3D = V.require("Voxel3D")
+local VRRig = V.require("VRRig")
+local FirstPerson = V.require("FirstPerson")
+local Horde = V.require("Horde")
+local HordeSfx = V.require("HordeSfx")
+
+local HordeGun = {}
+
+-- ------- tuning
+
+HordeGun.MAG = 8
+HordeGun.RELOAD_TIME = 1.5
+HordeGun.FIRE_COOLDOWN = 0.17      -- semi-auto, and it fits the reload clicks
+HordeGun.RANGE = 220               -- world pixels: about fourteen cells
+HordeGun.HIT_RADIUS = 6            -- a person is about twelve pixels wide
+HordeGun.ADS_TIME = 0.13
+HordeGun.ADS_FOV = math.rad(40)
+
+-- Where the gun sits relative to the EYE, in metres, hip and aimed. The
+-- model's own origin is its rear sight notch, so the aimed offset is a
+-- pure push forward: nothing to line up, it is already lined up.
+HordeGun.HIP = { -0.115, -0.125, 0.30 }
+HordeGun.ADS = { 0, -0.002, 0.34 }
+
+-- Where it sits relative to the tracked hand, in METRES and in the POSE's
+-- own axes -- so with the barrel pointed away from the player (see below)
+-- -Z is forward, and this nudges the gun a little down and forward of the
+-- pose origin so the hand is behind it rather than inside it.
+HordeGun.HAND_OFFSET = { 0, -0.012, -0.02 }
+
+-- THE BARREL, AND WHICH WAY IS FORWARD.
+--
+-- OpenXR's AIM pose -- the one this rides where the runtime offers it --
+-- is defined with its **-Z axis pointing the way the user is aiming**.
+-- The model below is authored with its barrel along **+Z**, because that
+-- is what the flat screen's view model wants (Ry(yaw)*Rx(pitch) carries
+-- +Z onto the look direction). Half a turn about Y is what reconciles
+-- them, and it is the whole of the attachment.
+--
+-- Getting this wrong does not read as "slightly off": the first cut
+-- copied the Pokedex's quarter-turn about X, which lays a flat slab along
+-- the controller's body and is exactly right for a slab -- on a gun it
+-- pointed the muzzle at the player's own face.
+HordeGun.HAND_YAW = math.pi
+
+-- AND A PITCH, because a hand is not a tripod. A controller held the way
+-- you hold a pistol -- fist closed, wrist cocked -- has its own aim axis
+-- running up and forward out of the top of your fist, well above the line
+-- your hand FEELS like it is pointing along. A model laid flat on that
+-- axis reads as a gun held by somebody with a broken wrist.
+--
+-- So the gun tips its muzzle down 45 degrees off the pose, which puts the
+-- barrel back on the line the grip implies. The shot follows: the ray is
+-- read off the finished matrix's own +Z column (see place), so it comes
+-- out of the barrel as drawn rather than off the pose it was hung on --
+-- point the gun, hit the thing.
+HordeGun.HAND_PITCH = math.rad(45)
+
+-- ------- the model
+--
+-- One voxel is 8mm, so the pistol below comes out about 18cm long -- a
+-- compact service automatic. Authored around the REAR SIGHT NOTCH at the
+-- origin, barrel down +Z, up +Y. (+X is the viewer's LEFT: the world runs
+-- +X east and +Z south, so a body facing +Z has its right hand toward
+-- -X, which is why the hip offset's x is negative.)
+
+local VOX = 0.008
+
+local COLORS = {
+  { 60, 62, 72 },      -- 1 slide
+  { 30, 31, 38 },      -- 2 frame / shadowed
+  { 46, 40, 40 },      -- 3 grip
+  { 104, 108, 122 },   -- 4 highlight
+  { 248, 240, 176 },   -- 5 sight dot
+  { 18, 18, 22 },      -- 6 bore
+  { 132, 136, 148 },   -- 7 trigger
+  { 255, 246, 196 },   -- 8 flash core
+  { 255, 168, 56 },    -- 9 flash edge
+}
+
+local paletteTex, bodyMesh, flashMesh = nil, nil, nil
+
+local function palette()
+  if paletteTex then return paletteTex end
+  if not (love.image and love.image.newImageData
+          and love.graphics and love.graphics.newImage) then return nil end
+  local ok, data = pcall(love.image.newImageData, #COLORS, 1)
+  if not (ok and data) then return nil end
+  for i, c in ipairs(COLORS) do
+    pcall(data.setPixel, data, i - 1, 0,
+          c[1] / 255, c[2] / 255, c[3] / 255, 1)
+  end
+  local built, img = pcall(love.graphics.newImage, data)
+  if not built then return nil end
+  pcall(img.setFilter, img, "nearest", "nearest")
+  paletteTex = img
+  return img
+end
+
+-- one solid box, in voxels, straight into the shared vertex format
+local function box(verts, indices, x, y, z, w, h, d, color)
+  local u = (color - 0.5) / #COLORS
+  local ox, oy, oz = x * VOX, y * VOX, z * VOX
+  local sx, sy, sz = w * VOX, h * VOX, d * VOX
+  for face = 1, 6 do
+    local corners = Voxel3D.FACE_CORNERS[face]
+    local shade = Voxel3D.FACE_SHADE[face]
+    local n = #verts / 4
+    for _, c in ipairs(corners) do
+      verts[#verts + 1] = { ox + c[1] * sx, oy + c[2] * sy, oz + c[3] * sz,
+                            u, 0.5, shade }
+    end
+    Voxel3D.pushQuad(indices, n)
+  end
+end
+
+local function buildBody()
+  if bodyMesh then return bodyMesh end
+  local v, i = {}, {}
+  -- slide, and the bore's dark eye at the end of it
+  box(v, i, -2, -5, -1, 4, 4, 18, 1)
+  box(v, i, -2, -2, -1, 4, 0.6, 18, 4)        -- the light along the top edge
+  box(v, i, -1, -4, 16.6, 2, 2, 0.6, 6)
+  -- frame under the slide, and the dust cover forward of the guard
+  box(v, i, -1.8, -8, 0.5, 3.6, 3.2, 12, 2)
+  -- the grip, three blocks stepping back: a raked butt without a hull
+  box(v, i, -1.8, -11, -1.2, 3.6, 3.2, 5, 3)
+  box(v, i, -1.8, -14, -2.6, 3.6, 3.2, 5, 3)
+  box(v, i, -1.8, -16.8, -3.8, 3.6, 3, 5, 2)
+  -- trigger guard: the bar under, the post in front
+  box(v, i, -1.4, -11.4, 3.6, 2.8, 1, 4.4, 2)
+  box(v, i, -1.4, -11.4, 7.4, 2.8, 3.4, 1, 2)
+  box(v, i, -0.9, -10.8, 4.6, 1.8, 2, 1, 7)   -- the trigger itself
+  -- IRON SIGHTS. Two rear posts with a notch between them at the origin,
+  -- one front post at the muzzle: look through the gap, put the front
+  -- post's dot in it, and the barrel is pointing where you are looking.
+  box(v, i, -2, -1, -0.2, 0.9, 1.3, 1.4, 2)
+  box(v, i, 1.1, -1, -0.2, 0.9, 1.3, 1.4, 2)
+  box(v, i, -1.95, -0.2, 0.3, 0.5, 0.5, 0.5, 5)
+  box(v, i, 1.45, -0.2, 0.3, 0.5, 0.5, 0.5, 5)
+  box(v, i, -0.45, -1, 15.2, 0.9, 1.5, 1, 2)
+  box(v, i, -0.3, 0.1, 15.4, 0.6, 0.6, 0.6, 5)
+  bodyMesh = Voxel3D.newMesh(v, i)
+  return bodyMesh
+end
+
+-- the muzzle flash: a bright cross of boxes off the bore, drawn for two
+-- frames after a shot and never lit by anything
+local function buildFlash()
+  if flashMesh then return flashMesh end
+  local v, i = {}, {}
+  box(v, i, -1.6, -4.6, 17.4, 3.2, 3.2, 2.6, 8)
+  box(v, i, -3.4, -3.8, 17.6, 6.8, 1.6, 1.8, 9)
+  box(v, i, -0.9, -6.4, 17.6, 1.8, 6.4, 1.8, 9)
+  box(v, i, -1.1, -4.1, 19.6, 2.2, 2.2, 2.2, 9)
+  flashMesh = Voxel3D.newMesh(v, i)
+  return flashMesh
+end
+
+-- ------- state
+
+local gun = {
+  ammo = HordeGun.MAG,
+  reloading = false,
+  reloadT = 0,
+  reloadStage = 0,
+  cooldown = 0,
+  ads = false,
+  adsBlend = 0,
+  kick = 0,
+  flash = 0,
+  frame = nil,        -- the VR hand's model matrix for this frame
+  ray = nil,          -- the VR aim ray in world space, if there is one
+}
+
+HordeGun.state = gun
+
+function HordeGun.reset()
+  gun.ammo = HordeGun.MAG
+  gun.reloading, gun.reloadT, gun.reloadStage = false, 0, 0
+  gun.cooldown, gun.kick, gun.flash = 0, 0, 0
+  gun.ads, gun.adsBlend = false, 0
+  gun.frame, gun.ray = nil, nil
+end
+
+-- how far into the aim the sights are, 0..1 -- read by the HUD (the
+-- crosshair goes away) and by the camera (the field of view narrows)
+function HordeGun.adsBlend()
+  return gun.adsBlend
+end
+
+function HordeGun.ammo()
+  return gun.ammo, HordeGun.MAG, gun.reloading
+end
+
+function HordeGun.setAds(on)
+  gun.ads = on and true or false
+end
+
+-- ------- the shot
+
+-- The eye and the direction it is looking, in world pixels. In VR this is
+-- the gun's own barrel (set by the VR frame); on the flat screen it is
+-- the camera, because the gun follows the camera exactly.
+local function ray(G)
+  if gun.ray then return gun.ray end
+  local ow = G and G.overworld
+  if not (ow and ow.player and ow.map) then return nil end
+  local p = ow.player
+  local gh = 0
+  pcall(function()
+    gh = V.require("VoxelScene").groundAt(ow.map, p.cellX, p.cellY) or 0
+  end)
+  local cp = math.cos(FirstPerson.pitch)
+  return {
+    p.px + 8, gh + FirstPerson.EYE_HEIGHT, p.py + 8,
+    math.sin(FirstPerson.yaw) * cp,
+    -math.sin(FirstPerson.pitch),
+    math.cos(FirstPerson.yaw) * cp,
+  }
+end
+
+-- How far the ray travels before terrain stops it. A wall in this world
+-- is a cell whose ground stands taller than the ray does where it crosses
+-- it, which is the same test for a fence you can shoot over, a building
+-- you cannot, and a doorway you can shoot through.
+local function occlusion(map, r)
+  local VoxelScene = V.require("VoxelScene")
+  local step = 3
+  local t = step
+  while t <= HordeGun.RANGE do
+    local x = r[1] + r[4] * t
+    local y = r[2] + r[5] * t
+    local z = r[3] + r[6] * t
+    local cx, cy = math.floor(x / 16), math.floor(z / 16)
+    if not map:inBounds(cx, cy) then return t end
+    local gh = 0
+    local ok, got = pcall(VoxelScene.groundAt, map, cx, cy)
+    if ok and got then gh = got end
+    if y < gh - 0.5 then return t end
+    if y < 0 then return t end
+    t = t + step
+  end
+  return HordeGun.RANGE
+end
+
+-- The nearest mob the ray reaches, and whether it caught the head.
+local function pick(G, r, maxT)
+  local Mobs = V.require("HordeMobs")
+  local VoxelScene = V.require("VoxelScene")
+  local ow = G and G.overworld
+  if not (ow and ow.map) then return nil end
+  local flat = r[4] * r[4] + r[6] * r[6]
+  if flat < 1e-6 then return nil end
+  local best, bestT, bestHead = nil, maxT, false
+  for _, e in ipairs(Mobs.list()) do
+    local npc = e.npc
+    if npc and not e.dead and e.mapId == ow.map.id then
+      local mx, mz = npc.px + 8, npc.py + 8
+      local t = ((mx - r[1]) * r[4] + (mz - r[3]) * r[6]) / flat
+      if t > 0 and t < bestT then
+        local hx = r[1] + r[4] * t - mx
+        local hz = r[3] + r[6] * t - mz
+        if hx * hx + hz * hz <= HordeGun.HIT_RADIUS * HordeGun.HIT_RADIUS then
+          local gh = 0
+          local ok, got = pcall(VoxelScene.groundAt, ow.map,
+                                npc.cellX, npc.cellY)
+          if ok and got then gh = got end
+          local y = r[2] + r[5] * t
+          if y >= gh - 2 and y <= gh + 17 then
+            best, bestT, bestHead = e, t, y >= gh + 11
+          end
+        end
+      end
+    end
+  end
+  return best, bestHead
+end
+
+-- Pull the trigger. Every input device funnels here (see Horde.install,
+-- FirstPerson's mouse and touch wraps, and VR.driveControls), so the
+-- cooldown below is also what keeps two devices reporting the same press
+-- from spending two rounds.
+function HordeGun.fire()
+  if not Horde.playing() then return false end
+  if gun.cooldown > 0 or gun.reloading then return false end
+  if gun.ammo <= 0 then
+    gun.cooldown = 0.35
+    HordeSfx.play(HordeSfx.DRY)
+    HordeGun.reload()
+    return false
+  end
+  local G = require("src.core.Game")
+  gun.ammo = gun.ammo - 1
+  gun.cooldown = HordeGun.FIRE_COOLDOWN
+  gun.kick = 1
+  gun.flash = 0.05
+  HordeSfx.shot()
+
+  local r = ray(G)
+  if r then
+    local ow = G.overworld
+    local maxT = ow and ow.map and occlusion(ow.map, r) or HordeGun.RANGE
+    local hit, head = pick(G, r, maxT)
+    if hit then
+      local Mobs = V.require("HordeMobs")
+      local result = Mobs.hit(hit, head and 2 or 1)
+      local s = Horde.session
+      if s then
+        s.hitMarker = 1
+        if result == "kill" and head then Horde.addScore(50) end
+      end
+    end
+  end
+  if gun.ammo <= 0 then HordeGun.reload() end
+  return true
+end
+
+function HordeGun.reload()
+  if gun.reloading or gun.ammo >= HordeGun.MAG then return false end
+  gun.reloading = true
+  gun.reloadT = 0
+  gun.reloadStage = 0
+  return true
+end
+
+-- ------- the frame
+
+function HordeGun.update(dt, live)
+  if not Horde.active then
+    FirstPerson.fovScale = 1        -- give the lens back on the way out
+    return
+  end
+  gun.cooldown = math.max(0, gun.cooldown - dt)
+  gun.kick = math.max(0, gun.kick - dt * 7)
+  gun.flash = math.max(0, gun.flash - dt)
+
+  local target = (gun.ads and live) and 1 or 0
+  local astep = dt / HordeGun.ADS_TIME
+  if gun.adsBlend < target then
+    gun.adsBlend = math.min(target, gun.adsBlend + astep)
+  else
+    gun.adsBlend = math.max(target, gun.adsBlend - astep)
+  end
+  -- the lens narrows with the sights. Half of what aiming does here is
+  -- the model coming to the centre of the screen; the other half is this
+  local e = gun.adsBlend * gun.adsBlend * (3 - 2 * gun.adsBlend)
+  FirstPerson.fovScale = 1 - (1 - HordeGun.ADS_FOV / FirstPerson.FOV) * e
+
+  if gun.reloading then
+    local was = gun.reloadT
+    gun.reloadT = gun.reloadT + dt
+    -- three clicks on their own clock: the magazine out, the fresh one
+    -- in, the slide home. Staged by time rather than animated frames so
+    -- the sound and the dip below stay in step at any frame rate.
+    local marks = { { 0.10, HordeSfx.MAG_OUT }, { 0.62, HordeSfx.MAG_IN },
+                    { 1.15, HordeSfx.RACK } }
+    for _, m in ipairs(marks) do
+      if was < m[1] and gun.reloadT >= m[1] then HordeSfx.play(m[2]) end
+    end
+    if gun.reloadT >= HordeGun.RELOAD_TIME then
+      gun.reloading = false
+      gun.reloadT = 0
+      gun.ammo = HordeGun.MAG
+    end
+  end
+end
+
+-- ------- VR placement
+--
+-- Called from the VR frame with the same mapping the eyes got. `pose` is
+-- the tracked right hand -- the runtime's aim pose where it has one.
+
+function HordeGun.place(pose, pivot, anchor, scale, yaw)
+  if not (Horde.active and pose) then
+    HordeGun.clear()
+    return
+  end
+  local m = VRRig.propMatrix(pose, pivot, anchor, scale, yaw)
+  m = Mat4.mul(m, Mat4.translate(HordeGun.HAND_OFFSET[1],
+                                 HordeGun.HAND_OFFSET[2],
+                                 HordeGun.HAND_OFFSET[3]))
+  m = Mat4.mul(m, Mat4.rotateY(HordeGun.HAND_YAW))
+  m = Mat4.mul(m, Mat4.rotateX(HordeGun.HAND_PITCH))
+  -- the recoil, up and back along the gun's own axes
+  local k = gun.kick
+  if k > 0 then
+    m = Mat4.mul(m, Mat4.translate(0, 0, -0.05 * k))
+    m = Mat4.mul(m, Mat4.rotateX(-0.30 * k))
+  end
+  gun.frame = m
+
+  -- the barrel, in world pixels: the shot goes where the gun points, so
+  -- lining the sights up with an eye is what aims it
+  local o = { m[4], m[8], m[12] }
+  local dx, dy, dz = m[3], m[7], m[11]        -- the model's +Z column
+  local len = math.sqrt(dx * dx + dy * dy + dz * dz)
+  if len > 1e-6 then
+    gun.ray = { o[1], o[2], o[3], dx / len, dy / len, dz / len }
+  else
+    gun.ray = nil
+  end
+end
+
+function HordeGun.clear()
+  gun.frame, gun.ray = nil, nil
+end
+
+-- ------- drawing
+--
+-- Runs inside VoxelScene's drawScene, once per eye in VR and once per
+-- frame flat, after the world -- so the gun composites with real depth
+-- and leaning it into a wall occludes honestly.
+
+-- Should the gun be drawn at all this frame? Keyed on the first-person
+-- rig's own IDENTITY rather than on the rung's number, because a staged
+-- VR battle places a camera through the same seam and the gun has no
+-- business in it.
+function HordeGun.visible()
+  if not Horde.active then return false end
+  if gun.frame then return true end
+  return FirstPerson.cardBlend() > 0.35
+end
+
+-- The flat screen's view model matrix: carried by the camera, offset to
+-- the hip or the sight line, with the recoil on top.
+local function flatModel()
+  local cam = Voxel3D.camera
+  local eye = cam and cam.eye
+  if not eye then return nil end
+  local a = gun.adsBlend
+  a = a * a * (3 - 2 * a)
+  local hip, ads = HordeGun.HIP, HordeGun.ADS
+  local ox = hip[1] + (ads[1] - hip[1]) * a
+  local oy = hip[2] + (ads[2] - hip[2]) * a
+  local oz = hip[3] + (ads[3] - hip[3]) * a
+  -- the reload dip: the gun swings down and out of the shot while the
+  -- hands are busy, easing back as the slide comes home
+  if gun.reloading then
+    local t = math.min(1, gun.reloadT / HordeGun.RELOAD_TIME)
+    local dip = math.sin(math.min(1, t * 1.15) * math.pi)
+    oy = oy - 0.09 * dip
+    ox = ox - 0.03 * dip
+  end
+  local k = gun.kick
+  oz = oz - 0.045 * k
+
+  local m = Mat4.translate(eye[1], eye[2], eye[3])
+  m = Mat4.mul(m, Mat4.rotateY(FirstPerson.yaw))
+  m = Mat4.mul(m, Mat4.rotateX(FirstPerson.pitch - 0.34 * k))
+  m = Mat4.mul(m, Mat4.scale(VRRig.FP_SCALE, VRRig.FP_SCALE, VRRig.FP_SCALE))
+  m = Mat4.mul(m, Mat4.translate(ox, oy, oz))
+  if gun.reloading then
+    local t = math.min(1, gun.reloadT / HordeGun.RELOAD_TIME)
+    m = Mat4.mul(m, Mat4.rotateX(-0.55 * math.sin(math.min(1, t * 1.15)
+                                                  * math.pi)))
+  end
+  return m
+end
+
+function HordeGun.draw()
+  if not HordeGun.visible() then return end
+  local model = gun.frame or flatModel()
+  if not model then return end
+  local body, pal = buildBody(), palette()
+  if not (body and pal) then return end
+  Voxel3D.draw(body, pal, model)
+  if gun.flash > 0 then
+    local flash = buildFlash()
+    if flash then Voxel3D.draw(flash, pal, model) end
+  end
+end
+
+function HordeGun.invalidate()
+  paletteTex, bodyMesh, flashMesh = nil, nil, nil
+end
+
+return HordeGun

lib/HordeHud.lua

@@ -0,0 +1,484 @@
+-- HORDE MODE: the readout.
+--
+-- Health, ammunition, score, wave, the crosshair, the hit marker, the red
+-- that closes in when something reaches you, and the banners -- "A
+-- DARKNESS APPROACHES", then "WAVE 1" and every wave after it.
+--
+-- IT IS DRAWN TWICE, INTO TWO DIFFERENT PLACES, and that is not
+-- duplication for its own sake. The flat screen's HUD goes into the SCENE
+-- canvas through Voxel3D.beginOverlay -- the same seam the overworld's FX
+-- bubbles use -- because that canvas is what the window composites. A
+-- headset never sees that canvas: with VR live the window's world pass
+-- short-circuits to the mirror, and the eyes are rendered on their own in
+-- lib/VR. So the eye canvases get their own pass, at the same instant the
+-- VR frame paints its fade over them, in the same 2D idiom.
+--
+-- Both call the same draw with a different scale and a different safe
+-- area: a headset wants everything well inside the lens rather than
+-- pinned to the corners, because the corners of a VR frame are off the
+-- edge of the visible world.
+--
+-- EVERY WORD IS ON A WHITE PLATE, and that is not a style choice -- it is
+-- what the font is. The Game Boy font sheets are BLACK glyphs on
+-- transparent, so setColor cannot make a letter pale: multiplying black
+-- by white is still black. That is why every box in the game is drawn
+-- white first and its text black on top (Font.drawBox, then
+-- setColor(0,0,0)), and it is why a first cut of this HUD -- pale text,
+-- straight onto the night -- composited as black letters on a black
+-- street and could not be read at all. Plates also happen to be the right
+-- answer aesthetically: the game already talks to the player in white
+-- boxes, and a horde mode that shouts in the same voice belongs to it.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Horde = V.require("Horde")
+
+local HordeHud = {}
+
+local Font = nil
+local function font()
+  if Font then return Font end
+  local ok, F = pcall(require, "src.render.Font")
+  if ok then Font = F end
+  return Font
+end
+
+-- the pulse under the low-health plate and the banner's own breathing
+local blink = 0
+
+function HordeHud.update(dt)
+  blink = (blink + (dt or 0)) % 1.0
+end
+
+-- named for the suite: the banner's line breaking, which is the part with
+-- an answer worth pinning
+HordeHud._layout = nil        -- assigned below, once `layout` exists
+
+-- ------- pieces
+--
+-- Every helper takes a scale `s` and draws in GB pixels multiplied by it,
+-- so one layout serves a 4x window and a headset's eye buffer alike.
+
+local PAD = 3           -- plate padding, in GB pixels
+
+-- A white plate with a dark edge: the surface a black glyph can be read
+-- on. Returns the interior origin, so a caller lays text out from there.
+local function plate(x, y, w, h, s, alpha)
+  love.graphics.setColor(0.06, 0.05, 0.09, (alpha or 1) * 0.92)
+  love.graphics.rectangle("fill", x - s, y - s, w + 2 * s, h + 2 * s)
+  love.graphics.setColor(0.93, 0.94, 0.90, alpha or 1)
+  love.graphics.rectangle("fill", x, y, w, h)
+  return x + PAD * s, y + PAD * s
+end
+
+local function textWidth(str, s)
+  local F = font()
+  if not F then return 0 end
+  return F.width(str) * s
+end
+
+-- Black glyphs at `s` times their size. Black because that is the only
+-- colour the font has (see the header).
+local function text(str, x, y, s)
+  local F = font()
+  if not F then return 0 end
+  love.graphics.setColor(0, 0, 0, 1)
+  love.graphics.push()
+  love.graphics.translate(math.floor(x), math.floor(y))
+  love.graphics.scale(s, s)
+  F.draw(str, 0, 0)
+  love.graphics.pop()
+end
+
+-- One line of text on its own plate, anchored left or right.
+local function label(str, x, y, s, align)
+  local tw = textWidth(str, s)
+  local pw, ph = tw + PAD * 2 * s, 8 * s + PAD * 2 * s
+  local px = (align == "right") and (x - pw) or x
+  local ix, iy = plate(px, y, pw, ph, s)
+  text(str, ix, iy, s)
+  return pw, ph
+end
+
+-- The health bar: a plate with a red bar inside it, so the red reads
+-- against white rather than against a night street.
+local function healthBar(x, y, w, h, s, fill, flash)
+  local ix, iy = plate(x, y, w, h, s)
+  local iw, ih = w - PAD * 2 * s, h - PAD * 2 * s
+  love.graphics.setColor(0.80, 0.80, 0.78, 1)
+  love.graphics.rectangle("fill", ix, iy, iw, ih)
+  local r, g, b = 0.78, 0.12, 0.16
+  if flash then r, g, b = 1, 0.45, 0.35 end
+  love.graphics.setColor(r, g, b, 1)
+  love.graphics.rectangle("fill", ix, iy, math.max(0, iw * fill), ih)
+end
+
+-- The crosshair: four ticks around a gap that opens as the gun kicks, and
+-- gone entirely down the sights, where the iron sights ARE the crosshair.
+-- Drawn as a dark pair under a light pair so it survives both a white
+-- wall and a black doorway.
+local function crosshair(cx, cy, s, spread, alpha)
+  local gap = (3 + spread * 4) * s
+  local len = 4 * s
+  local t = math.max(1, s)
+  local function ticks(o, thick, r, g, b, a)
+    love.graphics.setColor(r, g, b, a)
+    love.graphics.rectangle("fill", cx - gap - len - o, cy - thick / 2 - o,
+                            len + 2 * o, thick + 2 * o)
+    love.graphics.rectangle("fill", cx + gap - o, cy - thick / 2 - o,
+                            len + 2 * o, thick + 2 * o)
+    love.graphics.rectangle("fill", cx - thick / 2 - o, cy - gap - len - o,
+                            thick + 2 * o, len + 2 * o)
+    love.graphics.rectangle("fill", cx - thick / 2 - o, cy + gap - o,
+                            thick + 2 * o, len + 2 * o)
+  end
+  ticks(math.max(1, s * 0.5), t, 0, 0, 0, alpha * 0.85)
+  ticks(0, t, 0.98, 0.98, 1, alpha)
+end
+
+local function hitMarker(cx, cy, s, amount)
+  if amount <= 0 then return end
+  love.graphics.setColor(1, 0.30, 0.26, amount)
+  local o = 5 * s
+  local len = 5 * s
+  local t = math.max(1, s)
+  for _, d in ipairs({ { -1, -1 }, { 1, -1 }, { -1, 1 }, { 1, 1 } }) do
+    love.graphics.push()
+    love.graphics.translate(cx + d[1] * o, cy + d[2] * o)
+    love.graphics.rotate(math.pi / 4 * (d[1] * d[2] > 0 and 1 or -1))
+    love.graphics.rectangle("fill", -t / 2, -len / 2, t, len)
+    love.graphics.pop()
+  end
+end
+
+-- How wide a run of glyphs comes out at `bs` pixels per font pixel, with
+-- `track` of air after each one.
+local function runWidth(F, codes, bs, track)
+  local total = 0
+  for _, code in ipairs(codes) do
+    total = total + F.advanceOf(code) * bs + track
+  end
+  return total - track
+end
+
+-- The banner's lines, and the size to draw them at.
+--
+-- THE SCALE IS NEGOTIATED, not assumed. The caller's scale comes from the
+-- window's own zoom, so a player zoomed well in gets a large `s` -- and
+-- "A DARKNESS APPROACHES" at twice a large scale is wider than the
+-- screen, which is how the words ran off both edges. So: shrink until the
+-- longest single WORD fits, then wrap the words into as many lines as
+-- that leaves. Wrapping first and shrinking only when a word alone cannot
+-- fit keeps the announcement as big as the frame can carry it.
+local function layout(F, str, scale, maxW)
+  local words = {}
+  for word in tostring(str):gmatch("%S+") do words[#words + 1] = word end
+  if #words == 0 then return nil end
+
+  local bs = math.max(1, scale * 2)
+  local function track(size) return math.max(1, math.floor(size / 2)) end
+  while bs > 1 do
+    local widest = 0
+    for _, word in ipairs(words) do
+      local ww = runWidth(F, F.encode(word), bs, track(bs))
+      if ww > widest then widest = ww end
+    end
+    if widest <= maxW then break end
+    bs = bs - 1
+  end
+
+  local tr = track(bs)
+  local spaceW = runWidth(F, F.encode(" "), bs, tr) + tr
+  local lines, line, lineW = {}, nil, 0
+  for _, word in ipairs(words) do
+    local ww = runWidth(F, F.encode(word), bs, tr)
+    if not line then
+      line, lineW = word, ww
+    elseif lineW + spaceW + ww <= maxW then
+      line, lineW = line .. " " .. word, lineW + spaceW + ww
+    else
+      lines[#lines + 1] = { text = line, width = lineW }
+      line, lineW = word, ww
+    end
+  end
+  lines[#lines + 1] = { text = line, width = lineW }
+  return lines, bs, tr
+end
+
+HordeHud._layout = layout
+
+-- The banner: a plate across the middle of the frame with the words on
+-- it, as big as the frame can carry. It fades in and out rather than
+-- cutting -- an announcement, not a notification -- and the plate fades
+-- with it.
+local function banner(w, h, scale)
+  local sess = Horde.session
+  if not (sess and sess.bannerText) then return end
+  local t, hold = sess.bannerT, sess.bannerHold
+  local alpha
+  if t < 0.4 then alpha = t / 0.4
+  elseif t < hold then alpha = 1
+  else alpha = math.max(0, 1 - (t - hold) / 1.1) end
+  if alpha <= 0 then return end
+
+  local F = font()
+  if not F then return end
+  local margin = 6 * scale
+  local lines, bs, tr = layout(F, sess.bannerText, scale, w - margin * 2)
+  if not lines then return end
+
+  local lineH = 8 * bs
+  local gap = math.max(1, math.floor(bs * 0.4))
+  local pad = PAD * 2 * scale
+  local ph = #lines * lineH + (#lines - 1) * gap + pad * 2
+  local y = math.floor(h * 0.30 - ph / 2)
+  -- the plate runs the full width: a band across the world, which reads
+  -- as the game interrupting itself rather than as a label on it
+  plate(0, y, w, ph, scale, alpha)
+  local iy = y + pad
+
+  love.graphics.setColor(0, 0, 0, alpha)
+  for i, line in ipairs(lines) do
+    local pen = math.floor((w - line.width) / 2)
+    local ly = iy + (i - 1) * (lineH + gap)
+    for _, code in ipairs(F.encode(line.text)) do
+      love.graphics.push()
+      love.graphics.translate(pen, ly)
+      love.graphics.scale(bs, bs)
+      F.drawCode(code, 0, 0)
+      love.graphics.pop()
+      pen = pen + F.advanceOf(code) * bs + tr
+    end
+  end
+end
+
+-- ------- the whole thing
+--
+-- `inset` is how far off the edges the corners sit, which is the one real
+-- difference between a window and a headset.
+
+local function draw(w, h, s, inset)
+  local sess = Horde.session
+  if not sess then return end
+  local Gun = V.require("HordeGun")
+  local ammo, mag, reloading = Gun.ammo()
+  local ads = Gun.adsBlend()
+
+  love.graphics.push("all")
+  love.graphics.setBlendMode("alpha")
+
+  -- The red. A VIGNETTE rather than a wash over everything: a full-screen
+  -- fill strong enough to register at a glance also hides the thing that
+  -- just hit you, which in a mode about being surrounded is the one thing
+  -- it must not do. Bands closing in from the edges instead, so the
+  -- middle of the frame stays readable and the alarm arrives in the
+  -- corner of the eye.
+  local hurt = sess.damageFlash
+  local low = 1 - math.min(1, sess.hp / (sess.maxHp * 0.35))
+  local wash = math.max(hurt * 0.9, low * 0.6
+                        * (0.7 + 0.3 * math.sin(blink * math.pi * 2)))
+  if wash > 0 then
+    local band = math.min(w, h) * 0.38
+    local steps = 8
+    for i = 1, steps do
+      local t = i / steps
+      local d = band * t
+      love.graphics.setColor(0.60, 0.02, 0.06, wash * 0.13)
+      love.graphics.rectangle("fill", 0, 0, w, d)
+      love.graphics.rectangle("fill", 0, h - d, w, d)
+      love.graphics.rectangle("fill", 0, 0, d, h)
+      love.graphics.rectangle("fill", w - d, 0, d, h)
+    end
+  end
+
+  -- health, top left
+  local barW, barH = 60 * s, 8 * s + PAD * 2 * s
+  healthBar(inset, inset, barW, barH, s, sess.hp / sess.maxHp, hurt > 0.3)
+  label(("%d"):format(math.ceil(sess.hp)), inset, inset + barH + 3 * s, s)
+
+  -- score and wave, top right
+  label(("SCORE %d"):format(math.floor(sess.score)), w - inset, inset, s,
+        "right")
+  label(("WAVE %d"):format(math.max(1, sess.wave)),
+        w - inset, inset + (8 * s + PAD * 2 * s) + 3 * s, s, "right")
+
+  -- ammunition, bottom right: the rounds as pips over the count, which
+  -- reads at a glance in a firefight where a number does not
+  local ammoStr = reloading and "RELOADING" or ("%d / %d"):format(ammo, mag)
+  local _, ah = label(ammoStr, w - inset, h - inset - (8 * s + PAD * 2 * s), s,
+                      "right")
+  local pipW, pipH, pipGap = 3 * s, 7 * s, 2 * s
+  local pipsW = mag * (pipW + pipGap) - pipGap
+  local px = w - inset - pipsW
+  local py = h - inset - ah - pipH - 5 * s
+  love.graphics.setColor(0.06, 0.05, 0.09, 0.85)
+  love.graphics.rectangle("fill", px - 2 * s, py - 2 * s,
+                          pipsW + 4 * s, pipH + 4 * s)
+  for i = 1, mag do
+    if i <= ammo and not reloading then
+      love.graphics.setColor(0.98, 0.86, 0.36, 1)
+    else
+      love.graphics.setColor(0.32, 0.30, 0.36, 1)
+    end
+    love.graphics.rectangle("fill", px + (i - 1) * (pipW + pipGap), py,
+                            pipW, pipH)
+  end
+  if reloading then
+    local t = math.min(1, Gun.state.reloadT / Gun.RELOAD_TIME)
+    love.graphics.setColor(0.55, 0.78, 0.98, 1)
+    love.graphics.rectangle("fill", px, py + pipH + 1 * s, pipsW * t, 2 * s)
+  end
+
+  -- the sight picture
+  local cx, cy = w / 2, h / 2
+  if ads < 0.6 then
+    crosshair(cx, cy, s, Gun.state.kick, (1 - ads / 0.6) * 0.9)
+  end
+  hitMarker(cx, cy, s, sess.hitMarker)
+
+  banner(w, h, s)
+
+  love.graphics.pop()
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+-- ------- the two callers
+
+-- The flat window. Called from the voxel pipeline's overlay block, into
+-- the scene canvas -- which is at the window's PIXEL size and may be
+-- supersampled on top of that, so the caller's scale carries both.
+--
+-- The caller's scale is CAPPED against the canvas rather than taken as
+-- given, because that scale is the world's zoom: zoom in far enough and
+-- the health bar was a metre wide and half of it off the top of the
+-- screen. A readout is not part of the world and should not zoom with
+-- it -- so it sizes off the frame it is drawn in, which keeps its
+-- apparent size the same at every zoom and grows it honestly on a bigger
+-- display (and with supersampling, which is in both numbers).
+function HordeHud.drawFlat(w, h, scale)
+  if not Horde.active then return end
+  local cap = math.max(1, math.floor(h / 260))
+  local s = math.max(1, math.min(math.floor((scale or 1) + 0.5), cap))
+  draw(w, h, s, 8 * s)
+end
+
+-- ------- and the headset's, which is not a screen overlay at all
+--
+-- A VR eye gets NO 2D overlay. An earlier cut drew this same HUD into
+-- both eye canvases and it came out torn down the middle: the eye frusta
+-- are ASYMMETRIC, so the same canvas pixel is a different ANGLE in each
+-- eye, and the two images never fuse. Nor is there a crosshair to draw --
+-- the gun is a real object with real sights and the shot goes down its
+-- barrel, so a dot painted at the centre of the frame would be pointing
+-- at something else entirely.
+--
+-- What the headset gets instead is this: the readout as a TEXTURE, which
+-- lib/VR puts on the POKEDEX in the player's left hand -- already
+-- tracked, already lit, and already the surface this mod shows
+-- information on. Geometry in the world, so both eyes see it from their
+-- own position and the stereo is correct by construction. (It rode the
+-- gun for one revision and that was worse: a screen on the slide sits
+-- exactly where the iron sights have to be looked through.)
+--
+-- Sized to the device's own screen, which is the GB frame's 10:9.
+
+local panelCanvas = nil
+local PANEL_W, PANEL_H = 160, 144
+
+function HordeHud.panelTexture()
+  if not Horde.active then return nil end
+  if not (love.graphics and love.graphics.newCanvas) then return nil end
+  local sess = Horde.session
+  if not sess then return nil end
+  local F = font()
+  if not F then return nil end
+
+  if not panelCanvas then
+    local ok, c = pcall(love.graphics.newCanvas, PANEL_W, PANEL_H)
+    if not ok then return nil end
+    panelCanvas = c
+    pcall(panelCanvas.setFilter, panelCanvas, "nearest", "nearest")
+  end
+
+  local Gun = V.require("HordeGun")
+  local ammo, mag, reloading = Gun.ammo()
+
+  local ok = pcall(function()
+    love.graphics.push("all")
+    love.graphics.setCanvas(panelCanvas)
+    love.graphics.setBlendMode("alpha")
+    love.graphics.clear(0.93, 0.94, 0.90, 1)
+
+    -- the health bar, framed, across the top
+    love.graphics.setColor(0, 0, 0, 1)
+    love.graphics.rectangle("fill", 8, 8, PANEL_W - 16, 20)
+    love.graphics.setColor(0.80, 0.80, 0.78, 1)
+    love.graphics.rectangle("fill", 11, 11, PANEL_W - 22, 14)
+    love.graphics.setColor(0.78, 0.12, 0.16, 1)
+    love.graphics.rectangle("fill", 11, 11,
+                            (PANEL_W - 22) * math.max(0, sess.hp / sess.maxHp),
+                            14)
+
+    love.graphics.setColor(0, 0, 0, 1)
+    F.draw(("HP %d"):format(math.ceil(sess.hp)), 8, 34)
+    F.draw(reloading and "RELOADING" or ("AMMO %d/%d"):format(ammo, mag),
+           8, 50)
+
+    -- the round pips, so ammunition reads without counting digits
+    local pipW, gap = 9, 5
+    for i = 1, mag do
+      if i <= ammo and not reloading then
+        love.graphics.setColor(0.85, 0.65, 0.10, 1)
+      else
+        love.graphics.setColor(0.72, 0.73, 0.70, 1)
+      end
+      love.graphics.rectangle("fill", 8 + (i - 1) * (pipW + gap), 66, pipW, 12)
+    end
+
+    love.graphics.setColor(0, 0, 0, 1)
+    F.draw(("WAVE %d"):format(math.max(1, sess.wave)), 8, 86)
+    F.draw(("%d"):format(math.floor(sess.score)), 8, 102)
+
+    -- and the banner, wrapped to the panel rather than to the frame.
+    -- BLACK on the panel's own white, like everything else here: the font
+    -- sheets are black glyphs on transparent, so a pale letter is not a
+    -- thing that can be drawn (see the header).
+    if sess.bannerText then
+      local lines, bs, tr = layout(F, sess.bannerText, 1, PANEL_W - 8)
+      if lines then
+        local top = PANEL_H - 8 * bs * #lines - 5
+        love.graphics.setColor(0, 0, 0, 1)
+        love.graphics.rectangle("fill", 0, top - 2, PANEL_W, 1)
+        for i, line in ipairs(lines) do
+          local pen = math.floor((PANEL_W - line.width) / 2)
+          local ly = PANEL_H - 8 * bs * (#lines - i + 1) - 3
+          for _, code in ipairs(F.encode(line.text)) do
+            love.graphics.push()
+            love.graphics.translate(pen, ly)
+            love.graphics.scale(bs, bs)
+            F.drawCode(code, 0, 0)
+            love.graphics.pop()
+            pen = pen + F.advanceOf(code) * bs + tr
+          end
+        end
+      end
+    end
+
+    love.graphics.setCanvas()
+    love.graphics.pop()
+  end)
+  pcall(love.graphics.setCanvas)
+  if not ok then return nil end
+  return panelCanvas
+end
+
+-- window resize / hot reload
+function HordeHud.invalidate()
+  if panelCanvas and panelCanvas.release then
+    pcall(panelCanvas.release, panelCanvas)
+  end
+  panelCanvas = nil
+end
+
+return HordeHud

lib/HordeMobs.lua

@@ -0,0 +1,553 @@
+-- HORDE MODE: the crowd.
+--
+-- Waves of people who want to touch you, walking the same grid the game
+-- walks, wearing the overworld's own character sheets. Every mob IS a
+-- real engine NPC (OverworldState:addRuntimeObject), which is what buys
+-- the whole feature for nothing: the engine interpolates their steps,
+-- the collision system lets them jostle, the voxel pass billboards them
+-- with the right frame for the angle you see them from, and the flat 2D
+-- path draws them too. Nothing here draws a character.
+--
+-- THEY ARE DRIVEN, NOT SCRIPTED. OverworldState:scriptMove would be the
+-- obvious way to walk one, and it is a trap: a queued script move sets
+-- `scripted` on the state, which blocks the PLAYER's input for as long as
+-- it runs. So mobs are spawned with movement = "STAY" (which leaves
+-- NPC:update's wander branch inert) and this file writes facing / target /
+-- moving / progress directly, once per step. NPC:update then does the
+-- pixel interpolation and the cell commit exactly as it does for a
+-- wandering shopkeeper.
+--
+-- PATHING IS A FLOW FIELD, not A* per mob. One breadth-first sweep out
+-- from the player's cell, over the map's walkable cells, gives EVERY mob
+-- its next step at once -- and gives it correctly through doorways and
+-- around buildings, which is what "gang up on the player" actually
+-- requires. Rebuilt a few times a second rather than per frame; between
+-- rebuilds a mob just walks downhill on the numbers. It also answers two
+-- other questions for free: how far a cell is from the player (so a spawn
+-- point can be picked at a fair distance and be guaranteed REACHABLE),
+-- and whether a mob is adjacent enough to swing.
+--
+-- The sweep ignores entity occupancy on purpose. Mobs are solid to each
+-- other, so a pack funnelling down a corridor will jam -- and the fix for
+-- that is not a cleverer path, it is that a mob whose downhill step is
+-- occupied tries its second choice and otherwise waits. That is what
+-- makes them pool around the player instead of forming a queue.
+--
+-- FOLLOWING THROUGH DOORS. A warp tears down every NPC on the old map, so
+-- the roster cannot survive one. What survives is the COUNT: the number
+-- still alive when the player ran, re-spawned on the far side over the
+-- next few seconds, from the cells nearest the door they came in by. From
+-- the player's chair that is the horde coming through the door after them.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Horde = V.require("Horde")
+local HordeSfx = V.require("HordeSfx")
+
+local HordeMobs = {}
+
+-- ------- tuning
+
+-- Wave n throws this many at you, and no more than CAP stand at once.
+local function waveSize(n) return 4 + 3 * n end
+local CAP = 14
+local SPAWN_INTERVAL = 0.75      -- seconds between arrivals inside a wave
+local WAVE_GAP = 4.0             -- the breather, and the banner's window
+local FOLLOW_INTERVAL = 0.55     -- how fast they pour through a door
+
+-- Frames per cell. The engine's own walk is 16; the horde is quicker than
+-- a shopkeeper and gets quicker as the waves stack, floored so it never
+-- outruns the player's own free walk.
+local function stepFrames(n)
+  return math.max(9, 15 - math.floor(n / 2))
+end
+
+local function mobHp(n) return math.min(4, 1 + math.floor(n / 3)) end
+local function killScore(n) return 100 + 25 * (n - 1) end
+local function waveBonus(n) return 250 * n end
+
+-- How close a mob comes before it stops walking and starts swinging, in
+-- CELLS, and how close it has to be to land the hit, in world pixels.
+--
+-- The standoff is the difference between a horde and a wall. Nothing
+-- stops a mob taking the cell next to the player -- and when it does, a
+-- sixteen-pixel figure a cell away fills a sixty-five-degree lens edge to
+-- edge, so being surrounded looks like a texture rather than like people.
+-- Two cells back they read as figures closing in, the ring holds a dozen
+-- of them, and the player can still see what they are shooting at.
+local STANDOFF = 2
+local REACH = 40
+
+-- The cast. Overworld sprite sheets that read as a threat coming out of
+-- the dark; anything missing from the loaded game is dropped at spawn.
+local CAST = {
+  "SPRITE_ROCKET", "SPRITE_CHANNELER", "SPRITE_SCIENTIST", "SPRITE_BIKER",
+  "SPRITE_GUARD", "SPRITE_SUPER_NERD", "SPRITE_HIKER", "SPRITE_SWIMMER",
+  "SPRITE_GYM_GUIDE", "SPRITE_BLACK_HAIR_BOY_1", "SPRITE_GIRL",
+  "SPRITE_MIDDLE_AGED_MAN", "SPRITE_FISHER", "SPRITE_GAMBLER",
+}
+
+local OWNER = "DRAMATIC_SHAPE"
+
+-- ------- the flow field
+--
+-- dist[cy * w + cx] = steps from the player, over walkable cells only.
+-- Nil where the sweep never reached, which is the same answer as "no way
+-- there from here" -- an island across water, a room behind a locked door.
+
+local field = { mapId = nil, w = 0, h = 0, dist = nil, at = nil, age = 0 }
+
+local REBUILD_EVERY = 0.28
+
+local function passable(map, cx, cy)
+  if not map:inBounds(cx, cy) then return false end
+  if not map:isWalkableCell(cx, cy) then return false end
+  -- a warp cell is walkable but standing on one takes the warp; mobs may
+  -- cross them (that IS the door they follow you through) so they stay in
+  return true
+end
+
+-- fixed order, so a tie between two equally good steps always breaks the
+-- same way -- a mob that dithers between two cells reads as broken, and a
+-- pairs() walk over a hash would give a different answer every run
+local DIRS = { "right", "left", "down", "up" }
+local DX = { right = 1, left = -1, down = 0, up = 0 }
+local DY = { right = 0, left = 0, down = 1, up = -1 }
+
+local function rebuildField(map, px, py)
+  local w, h = map.widthCells, map.heightCells
+  local dist = {}
+  -- a plain array queue: BFS on a grid never revisits a cell, so no heap
+  -- and no priority is needed and the whole sweep is one pass
+  local qx, qy = { px }, { py }
+  local head = 1
+  dist[py * w + px] = 0
+  while head <= #qx do
+    local cx, cy = qx[head], qy[head]
+    head = head + 1
+    local d = dist[cy * w + cx] + 1
+    for i = 1, 4 do
+      local dir = DIRS[i]
+      local nx, ny = cx + DX[dir], cy + DY[dir]
+      local key = ny * w + nx
+      if dist[key] == nil and passable(map, nx, ny) then
+        dist[key] = d
+        qx[#qx + 1], qy[#qy + 1] = nx, ny
+      end
+    end
+  end
+  field.mapId, field.w, field.h, field.dist = map.id, w, h, dist
+  field.at = { px, py }
+  field.age = 0
+end
+
+local function distAt(cx, cy)
+  if not field.dist then return nil end
+  if cx < 0 or cy < 0 or cx >= field.w or cy >= field.h then return nil end
+  return field.dist[cy * field.w + cx]
+end
+
+-- named for the suite: the sweep, and the distance it wrote to a cell
+HordeMobs._dist = distAt
+HordeMobs._rebuild = rebuildField
+
+-- ------- spawning
+
+local function liveSprites(G)
+  local out = {}
+  local sprites = G and G.data and G.data.sprites
+  for _, key in ipairs(CAST) do
+    if sprites and sprites[key] then out[#out + 1] = key end
+  end
+  if #out == 0 and sprites then
+    -- a total conversion with none of the vanilla sheets: take whatever
+    -- walker it does have rather than spawning nothing at all
+    local keys = {}
+    for key, def in pairs(sprites) do
+      if def and def.walker then keys[#keys + 1] = key end
+    end
+    table.sort(keys)
+    for i = 1, math.min(6, #keys) do out[i] = keys[i] end
+  end
+  return out
+end
+
+-- Cells at a fair distance from the player that the flow field says are
+-- actually reachable, preferring the far end of the band so the horde
+-- arrives from off in the dark rather than on top of you.
+local function spawnCells(map, near, far, want)
+  local out = {}
+  if not field.dist then return out end
+  for key, d in pairs(field.dist) do
+    if d >= near and d <= far then
+      local cy = math.floor(key / field.w)
+      local cx = key - cy * field.w
+      out[#out + 1] = { cx, cy, d }
+    end
+  end
+  -- shuffle, then bias toward distance: sorting outright would file every
+  -- mob in from the same corner
+  for i = #out, 2, -1 do
+    local j = love.math.random(i)
+    out[i], out[j] = out[j], out[i]
+  end
+  table.sort(out, function(a, b) return a[3] > b[3] end)
+  while #out > (want or 16) do table.remove(out) end
+  return out
+end
+
+local function occupiedCell(state, cx, cy)
+  local Collision = require("src.world.Collision")
+  return Collision.occupied(state.entities, cx, cy, nil) ~= nil
+end
+
+-- One mob, on a cell, on the live map. Returns the roster entry or nil.
+local function spawnAt(G, state, cx, cy, wave)
+  local s = Horde.session
+  if not s then return nil end
+  local sprites = liveSprites(G)
+  if #sprites == 0 then return nil end
+  local def = {
+    x = cx, y = cy,
+    sprite = sprites[love.math.random(#sprites)],
+    movement = "STAY",
+    range = "DOWN",
+    name = "HORDE",
+    hordeMob = true,
+  }
+  local mapId = state.map.id
+  local okAdd, npcId = pcall(state.addRuntimeObject, state, mapId, def, OWNER)
+  if not (okAdd and npcId) then return nil end
+  s.spawned[mapId] = s.spawned[mapId] or {}
+  s.spawned[mapId][def.index] = true
+
+  local npc = nil
+  for _, e in ipairs(state.npcs) do
+    if e.id == npcId then npc = e break end
+  end
+  if not npc then return nil end
+  npc.wanders = false
+  npc.stepFrames = stepFrames(wave)
+  local entry = {
+    npc = npc, id = npcId, mapId = mapId,
+    hp = mobHp(wave), attackT = 0,
+  }
+  s.mobs[#s.mobs + 1] = entry
+  return entry
+end
+
+-- ------- removal
+--
+-- Targeted, because the engine's own removeRuntimeObject walks every map
+-- in the game to find one object and a firefight calls this several times
+-- a second.
+
+local function dropNpc(state, npcId)
+  for _, list in ipairs({ state.npcs or {}, state.entities or {} }) do
+    for i = #list, 1, -1 do
+      if list[i].id == npcId then table.remove(list, i) end
+    end
+  end
+  if state.npcPool then state.npcPool[npcId] = nil end
+end
+
+-- Take this mode's objects back out of a map record. Runtime objects live
+-- in Game.data.maps[id].objects until removed, and setMap respawns from
+-- that list -- so a def left behind is a mob waiting on the far side of a
+-- door long after the mode ended.
+local function scrubMap(G, mapId, indices)
+  local def = G and G.data and G.data.maps and G.data.maps[mapId]
+  if not def or not def.objects then return end
+  for i = #def.objects, 1, -1 do
+    local obj = def.objects[i]
+    if obj and obj.hordeMob and (not indices or indices[obj.index]) then
+      table.remove(def.objects, i)
+    end
+  end
+end
+
+-- ------- the roster's own step
+
+local function faceToward(npc, cx, cy)
+  local dx, dy = cx - npc.cellX, cy - npc.cellY
+  if math.abs(dx) > math.abs(dy) then
+    return dx > 0 and "right" or "left"
+  end
+  return dy > 0 and "down" or "up"
+end
+
+-- Walk one mob downhill on the flow field. The best neighbour is the one
+-- with the lowest distance; when it is taken, the second best is tried,
+-- and when both are taken the mob waits a beat -- which is what makes a
+-- pack pool around the player instead of queueing behind one another.
+local function stepMob(state, entry)
+  local npc = entry.npc
+  if npc.moving then return end
+  local here = distAt(npc.cellX, npc.cellY)
+  -- close enough: stand and swing rather than crowding into the lens
+  if here and here <= STANDOFF then
+    local p = state.player
+    npc.facing = faceToward(npc, p.cellX, p.cellY)
+    return
+  end
+  local best, bestD, second, secondD = nil, nil, nil, nil
+  for i = 1, 4 do
+    local dir = DIRS[i]
+    local tx, ty = npc.cellX + DX[dir], npc.cellY + DY[dir]
+    local d = distAt(tx, ty)
+    -- the standoff is enforced on the cell being ENTERED, not the one
+    -- being stood on: a mob that checked only where it was would still
+    -- finish the step it was already taking and end up in the lens
+    if d and d < STANDOFF then d = nil end
+    if d and (not here or d < here) then
+      if not bestD or d < bestD then
+        second, secondD = best, bestD
+        best, bestD = { dir, tx, ty }, d
+      elseif not secondD or d < secondD then
+        second, secondD = { dir, tx, ty }, d
+      end
+    end
+  end
+  for _, pick in ipairs({ best, second }) do
+    if pick then
+      local dir, tx, ty = pick[1], pick[2], pick[3]
+      if not occupiedCell(state, tx, ty) then
+        npc.facing = dir
+        npc.targetX, npc.targetY = tx, ty
+        npc.moving = true
+        npc.progress = 0
+        return
+      end
+    end
+  end
+  -- boxed in: keep facing the player so the pack still reads as a threat
+  local p = state.player
+  npc.facing = faceToward(npc, p.cellX, p.cellY)
+end
+
+-- ------- the public surface
+
+function HordeMobs.begin(G)
+  local s = Horde.session
+  if not s then return end
+  local state = G and G.overworld
+  if not (state and state.map) then return end
+  field.mapId = nil
+  s.wave, s.waveRemaining, s.waveGap, s.spawnGap = 0, 0, 0, 0
+  HordeMobs.convertLocals(state)
+end
+
+-- Everyone already standing on the map joins in. Their sprite, their
+-- position, their business -- now walking at the player. Nothing is
+-- stored to undo it, because the restore warps through setMap, which
+-- rebuilds every one of them from the map record (see Horde.finish).
+function HordeMobs.convertLocals(state)
+  local s = Horde.session
+  if not (s and state and state.npcs) then return end
+  local known = {}
+  for _, e in ipairs(s.mobs) do known[e.npc] = true end
+  for _, npc in ipairs(state.npcs) do
+    if not known[npc] and not npc.passable then
+      npc.wanders = false
+      npc.frozen = false
+      npc.stepFrames = stepFrames(math.max(1, s.wave))
+      s.mobs[#s.mobs + 1] = {
+        npc = npc, id = npc.id, mapId = state.map.id,
+        hp = mobHp(math.max(1, s.wave)), attackT = 0, local_ = true,
+      }
+    end
+  end
+end
+
+function HordeMobs.nextWave(G)
+  local s = Horde.session
+  if not s then return end
+  s.wave = s.wave + 1
+  s.waveRemaining = waveSize(s.wave)
+  s.spawnGap = 0
+  Horde.banner(("WAVE %d"):format(s.wave), 1.6)
+  HordeSfx.play(HordeSfx.WAVE)
+  for _, e in ipairs(s.mobs) do
+    e.npc.stepFrames = stepFrames(s.wave)
+  end
+end
+
+-- A mob took a bullet. Returns "kill", "hit", or nil.
+function HordeMobs.hit(entry, damage)
+  local s = Horde.session
+  if not (s and entry) then return nil end
+  entry.hp = entry.hp - (damage or 1)
+  if entry.hp > 0 then
+    HordeSfx.play(HordeSfx.HIT)
+    return "hit"
+  end
+  entry.dead = true
+  s.kills = s.kills + 1
+  Horde.addScore(killScore(math.max(1, s.wave)))
+  HordeSfx.randomCry()
+  return "kill"
+end
+
+-- Every live mob, for the gun's ray to test against.
+function HordeMobs.list()
+  local s = Horde.session
+  return s and s.mobs or {}
+end
+
+function HordeMobs.update(dt, G)
+  local s = Horde.session
+  if not s then return end
+  local state = G and G.overworld
+  if not (state and state.map and state.player) then return end
+  local p = state.player
+
+  -- the flow field, rebuilt on a clock and whenever the player changes
+  -- cell far enough that the old numbers point at where they used to be
+  field.age = field.age + dt
+  local moved = field.at
+    and (math.abs(field.at[1] - p.cellX) + math.abs(field.at[2] - p.cellY)) or 99
+  if field.mapId ~= state.map.id or field.age >= REBUILD_EVERY or moved >= 2 then
+    rebuildField(state.map, p.cellX, p.cellY)
+  end
+
+  -- the dead, collected before anything walks
+  for i = #s.mobs, 1, -1 do
+    local e = s.mobs[i]
+    if e.dead or not e.npc then
+      if e.npc then dropNpc(state, e.id) end
+      table.remove(s.mobs, i)
+    end
+  end
+
+  -- the living
+  local pcx, pcy = p.px + 8, p.py + 8
+  for _, e in ipairs(s.mobs) do
+    local npc = e.npc
+    e.attackT = math.max(0, e.attackT - dt)
+    stepMob(state, e)
+    local dx, dz = (npc.px + 8) - pcx, (npc.py + 8) - pcy
+    if dx * dx + dz * dz <= REACH * REACH then
+      if e.attackT <= 0 then
+        e.attackT = 0.8
+        npc.facing = faceToward(npc, p.cellX, p.cellY)
+        Horde.damage()
+      end
+    end
+  end
+
+  if not Horde.playing() then return end
+
+  -- the crowd that followed the player through a door, arriving
+  if s.followQueue > 0 then
+    s.spawnGap = s.spawnGap - dt
+    if s.spawnGap <= 0 and #s.mobs < CAP then
+      s.spawnGap = FOLLOW_INTERVAL
+      local cells = spawnCells(state.map, 2, 9, 8)
+      local cell = cells[1]
+      if cell and spawnAt(G, state, cell[1], cell[2], s.wave) then
+        s.followQueue = s.followQueue - 1
+      else
+        s.followQueue = s.followQueue - 1   -- nowhere to put them; let it go
+      end
+    end
+    return
+  end
+
+  -- the wave itself
+  if s.waveRemaining > 0 then
+    s.spawnGap = s.spawnGap - dt
+    if s.spawnGap <= 0 and #s.mobs < CAP then
+      s.spawnGap = SPAWN_INTERVAL
+      local cells = spawnCells(state.map, 7, 18, 10)
+      if #cells == 0 then cells = spawnCells(state.map, 3, 30, 10) end
+      local cell = cells[1]
+      if cell and spawnAt(G, state, cell[1], cell[2], s.wave) then
+        s.waveRemaining = s.waveRemaining - 1
+      else
+        s.spawnGap = 1.5     -- no room right now; try again shortly
+      end
+    end
+  elseif #s.mobs == 0 then
+    s.waveGap = s.waveGap + dt
+    if s.waveGap == dt then
+      Horde.addScore(waveBonus(s.wave))
+      Horde.banner(("WAVE %d CLEAR"):format(s.wave), 1.8)
+    end
+    if s.waveGap >= WAVE_GAP then
+      s.waveGap = 0
+      HordeMobs.nextWave(G)
+    end
+  end
+end
+
+-- ------- the door
+--
+-- map.entered fires after setMap has rebuilt the world, which means every
+-- mob instance from the old map is already gone. What is left to do is
+-- take our defs off the old map (or they respawn if the player ever comes
+-- back), remember how many were chasing, and let update() walk them in.
+
+function HordeMobs.onMapEntered(payload)
+  local s = Horde.session
+  if not s then return end
+  local G = require("src.core.Game")
+  local state = G.overworld
+  if not (state and state.map) then return end
+  local newId = state.map.id
+
+  local following = 0
+  for _, e in ipairs(s.mobs) do
+    if e.mapId ~= newId and not e.local_ then following = following + 1 end
+  end
+  -- the old map's records, and any instance the pool kept
+  for mapId, indices in pairs(s.spawned) do
+    if mapId ~= newId then
+      scrubMap(G, mapId, indices)
+      s.spawned[mapId] = nil
+    end
+  end
+  for i = #s.mobs, 1, -1 do
+    if s.mobs[i].mapId ~= newId then table.remove(s.mobs, i) end
+  end
+
+  field.mapId = nil
+  s.followQueue = math.max(s.followQueue, following)
+  s.spawnGap = math.min(s.spawnGap, 0.4)
+  HordeMobs.convertLocals(state)
+end
+
+-- ------- the end
+--
+-- Every def this mode wrote, off every map it wrote one to. The live
+-- instances go too, though the restore's own warp would have taken them:
+-- cleanup has to leave a consistent world even when it is called from a
+-- path that never warps.
+
+function HordeMobs.cleanup(G)
+  G = G or require("src.core.Game")
+  local s = Horde.session
+  local state = G.overworld
+  if s then
+    for _, e in ipairs(s.mobs) do
+      if state and not e.local_ then dropNpc(state, e.id) end
+    end
+    for mapId, indices in pairs(s.spawned) do
+      scrubMap(G, mapId, indices)
+    end
+    s.mobs, s.spawned = {}, {}
+    s.followQueue, s.waveRemaining = 0, 0
+  else
+    -- a session that vanished under us (a reload mid-mode): sweep every
+    -- map for this mode's marker rather than leaving actors behind
+    for mapId in pairs((G.data and G.data.maps) or {}) do
+      scrubMap(G, mapId, nil)
+    end
+  end
+  field.mapId, field.dist, field.at = nil, nil, nil
+end
+
+-- named for the suite, down here because the walk is defined above it
+HordeMobs._stepMob = stepMob
+
+return HordeMobs

lib/HordeSfx.lua

@@ -0,0 +1,262 @@
+-- HORDE MODE: the gun, in Game Boy hardware.
+--
+-- Every sound this mode makes is SYNTHESIZED on the same emulated APU the
+-- rest of the game speaks through -- no sample files ship with the mod.
+-- That is a deliberate aesthetic choice as much as a legal one: Lavender
+-- Town is playing, the cries are the real cries, and a 44kHz foley
+-- gunshot dropped on top would read as a different program running in the
+-- same window. Authored here with ChipAsm (src/audio/ChipAsm.lua), which
+-- assembles note tables into the channel bytecode ChipAudio interprets.
+--
+-- WHAT A GUNSHOT IS, on this hardware. Channel 4 is a noise generator
+-- whose `parameter` byte is NR43: the high nibble is the shift clock (LOW
+-- values are BRIGHT, high values are low rumble), bit 3 picks the short
+-- 7-bit LFSR (metallic and pitched) over the long 15-bit one (white
+-- hiss), and the low three bits divide. A real gunshot is a bright crack
+-- collapsing into a body and then a room tail, so each sound here is a
+-- STAGED program: three or four noise notes marching down the parameter
+-- byte, each shorter-lived than the last. `len` is in frames of 1/60s,
+-- `volume` is 0-15, and `fade` is the envelope period -- 1 decays fastest,
+-- 7 slowest, 0 holds for the note's whole length.
+--
+-- The shot also gets two frames of channel 1 underneath it: a square note
+-- swept hard downward, which is the only way to put a low thump on this
+-- chip. It costs the music its lead channel for 1/30s per shot, which is
+-- inaudible as interference and is most of what makes the shot feel like
+-- it has weight.
+--
+-- THREE SHOT VARIANTS, round-robined. Sound.play caches ONE Source per
+-- registered name and restarts it (stop then play), so firing twice on
+-- one name cuts the first shot's tail off. Three names means three
+-- Sources, so a fast trigger finger overlaps its own echoes the way a
+-- real one does -- and the variants differ slightly in their tails, which
+-- takes the machine-gun sameness off a repeated sound.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local HordeSfx = {}
+
+-- the registered names, in the shape the rest of the mode asks for them
+HordeSfx.SHOTS = { "DS_HORDE_SHOT_1", "DS_HORDE_SHOT_2", "DS_HORDE_SHOT_3" }
+HordeSfx.DRY = "DS_HORDE_DRY"
+HordeSfx.MAG_OUT = "DS_HORDE_MAG_OUT"
+HordeSfx.MAG_IN = "DS_HORDE_MAG_IN"
+HordeSfx.RACK = "DS_HORDE_RACK"
+HordeSfx.HIT = "DS_HORDE_HIT"
+HordeSfx.HURT = "DS_HORDE_HURT"
+HordeSfx.WAVE = "DS_HORDE_WAVE"
+
+-- ------- the programs
+
+-- The shot's noise stage list: bright crack, body, tail, room. `tail`
+-- lets the three variants differ in how the last stage rings out without
+-- restating the whole program.
+local function shotNoise(tail)
+  return {
+    -- the crack: one frame, full volume, brightest parameter the chip has
+    { noiseNote = { len = 1, volume = 15, fade = 1, parameter = 0x00 } },
+    -- the body: the shift clock drops, the 7-bit LFSR gives it a metallic
+    -- edge -- this is the part that reads as "a mechanism did that"
+    { noiseNote = { len = 2, volume = 13, fade = 2, parameter = 0x2C } },
+    -- the tail: lower, softer, longer
+    { noiseNote = { len = 3, volume = 8, fade = 3, parameter = tail[1] } },
+    -- the room: a low breath of noise fading under everything
+    { noiseNote = { len = tail[2], volume = 4, fade = 4, parameter = tail[3] } },
+  }
+end
+
+-- The thump under the crack: channel 1's frequency register swept down
+-- hard. 0x600 is around 250Hz; the sweep drags it into the floor over the
+-- two frames it lives, which is a kick drum by another name.
+local THUMP = {
+  { pitchSweep = { pace = 2, subtract = true, shift = 3 } },
+  { squareNote = { len = 2, volume = 12, fade = 2, frequency = 0x600 } },
+}
+
+local function shot(tail)
+  return {
+    channels = {
+      { hw = 1, program = THUMP },
+      { hw = 4, program = shotNoise(tail) },
+    },
+  }
+end
+
+-- The reload, in three separate sounds the gun fires on its own clock:
+-- the magazine dropping out, the fresh one seating, and the slide coming
+-- back and going home. Noise only -- these are mechanical clicks, and
+-- keeping them off the tone channels leaves the music alone.
+local PROGRAMS = {
+  [HordeSfx.SHOTS[1]] = shot({ 0x55, 5, 0x76 }),
+  [HordeSfx.SHOTS[2]] = shot({ 0x54, 6, 0x77 }),
+  [HordeSfx.SHOTS[3]] = shot({ 0x65, 4, 0x86 }),
+
+  -- the hammer falling on nothing: one dull tick, no tail
+  [HordeSfx.DRY] = {
+    channels = {
+      { hw = 4, program = {
+        { noiseNote = { len = 1, volume = 7, fade = 1, parameter = 0x38 } },
+        { noiseNote = { len = 1, volume = 3, fade = 1, parameter = 0x54 } },
+      } },
+    },
+  },
+
+  -- the magazine leaving: a click and a soft drop away from it
+  [HordeSfx.MAG_OUT] = {
+    channels = {
+      { hw = 4, program = {
+        { noiseNote = { len = 1, volume = 10, fade = 1, parameter = 0x1A } },
+        { noiseNote = { len = 2, volume = 5, fade = 2, parameter = 0x58 } },
+      } },
+    },
+  },
+
+  -- the fresh magazine seating: a firmer, lower clack with a bit of body
+  [HordeSfx.MAG_IN] = {
+    channels = {
+      { hw = 4, program = {
+        { noiseNote = { len = 1, volume = 13, fade = 1, parameter = 0x18 } },
+        { noiseNote = { len = 2, volume = 8, fade = 2, parameter = 0x46 } },
+        { noiseNote = { len = 2, volume = 3, fade = 3, parameter = 0x67 } },
+      } },
+    },
+  },
+
+  -- the slide: back (bright scrape), a frame of nothing, then home (hard)
+  [HordeSfx.RACK] = {
+    channels = {
+      { hw = 4, program = {
+        { noiseNote = { len = 2, volume = 9, fade = 2, parameter = 0x25 } },
+        { rest = 1 },
+        { noiseNote = { len = 1, volume = 14, fade = 1, parameter = 0x11 } },
+        { noiseNote = { len = 2, volume = 6, fade = 2, parameter = 0x44 } },
+      } },
+    },
+  },
+
+  -- a bullet arriving: short, bright, gone -- the hit marker's own sound
+  [HordeSfx.HIT] = {
+    channels = {
+      { hw = 4, program = {
+        { noiseNote = { len = 1, volume = 11, fade = 1, parameter = 0x14 } },
+        { noiseNote = { len = 1, volume = 5, fade = 2, parameter = 0x42 } },
+      } },
+    },
+  },
+
+  -- being hit: a low ugly thud on the noise channel with a square groan
+  -- under it, sweeping DOWN -- the sound of losing something
+  [HordeSfx.HURT] = {
+    channels = {
+      { hw = 1, program = {
+        { pitchSweep = { pace = 3, subtract = true, shift = 4 } },
+        { squareNote = { len = 6, volume = 11, fade = 3, frequency = 0x480 } },
+      } },
+      { hw = 4, program = {
+        { noiseNote = { len = 2, volume = 12, fade = 2, parameter = 0x66 } },
+        { noiseNote = { len = 4, volume = 6, fade = 3, parameter = 0x78 } },
+      } },
+    },
+  },
+
+  -- a wave arriving: two rising square stabs, deliberately not a fanfare
+  [HordeSfx.WAVE] = {
+    channels = {
+      { hw = 1, program = {
+        { squareNote = { len = 3, volume = 10, fade = 2, frequency = 0x5C0 } },
+        { rest = 1 },
+        { squareNote = { len = 6, volume = 12, fade = 3, frequency = 0x680 } },
+      } },
+    },
+  },
+}
+
+-- ------- registration
+
+-- Assemble every program and put it in the sfx registry. Called once from
+-- main.lua at load. A malformed note table raises inside ChipAsm; each is
+-- assembled under pcall so one bad program is one missing sound rather
+-- than a mod that fails to load.
+function HordeSfx.register(mod)
+  local ok, ChipAsm = pcall(require, "src.audio.ChipAsm")
+  if not (ok and ChipAsm) then return false end
+  local n = 0
+  for name, spec in pairs(PROGRAMS) do
+    local built, out = pcall(ChipAsm.sfx, spec)
+    if built and out and out.chip then
+      local reg = pcall(function()
+        mod.content.sfx:register(name, { chip = out.chip })
+      end)
+      if reg then n = n + 1 end
+    elseif mod.log then
+      mod.log:error("horde: sfx %s did not assemble: %s", name, tostring(out))
+    end
+  end
+  return n > 0
+end
+
+-- ------- playback
+--
+-- One indirection so callers never touch Sound directly and a headless
+-- run (no love.audio) costs a pcall rather than an error.
+
+local function play(name)
+  pcall(function()
+    local Game = require("src.core.Game")
+    require("src.core.Sound").play(Game.data, name)
+  end)
+end
+
+HordeSfx.play = play
+
+local shotIndex = 0
+
+-- The next shot in the round-robin, so consecutive rounds overlap rather
+-- than cutting each other off (see the header).
+function HordeSfx.shot()
+  shotIndex = shotIndex % #HordeSfx.SHOTS + 1
+  play(HordeSfx.SHOTS[shotIndex])
+end
+
+-- ------- the cries
+--
+-- Every mob that dies screams as something from the national dex. The
+-- list is built once from the live cry registry -- whatever the game and
+-- whatever mods are loaded have between them -- so this needs no data of
+-- its own and picks up a total conversion's roster for free.
+
+local cryList = nil
+
+local function cries()
+  if cryList then return cryList end
+  local out = {}
+  pcall(function()
+    local Game = require("src.core.Game")
+    local table_ = Game.data and Game.data.audio and Game.data.audio.cries
+    for species in pairs(table_ or {}) do out[#out + 1] = species end
+  end)
+  table.sort(out)   -- love.math.random over a stable order, not hash order
+  cryList = out
+  return out
+end
+
+-- A random cry, at a random-ish pitch. Nothing is more Pokemon than the
+-- wrong animal noise coming out of a man in a suit.
+function HordeSfx.randomCry()
+  local list = cries()
+  if #list == 0 then return nil end
+  local species = list[love.math.random(#list)]
+  pcall(function()
+    local Game = require("src.core.Game")
+    require("src.core.Sound").playCry(Game.data, species)
+  end)
+  return species
+end
+
+-- a fresh boot (or a hot reload) rebuilds the species list
+function HordeSfx.invalidate()
+  cryList = nil
+end
+
+return HordeSfx

lib/OverworldBattle.lua

@@ -249,6 +249,31 @@ OverworldBattle.TEXT_RECT = {
   mimic = { 0, 56, 128, 40 },
 }
 
+-- How far apart the two anchors are: the spacing every move animation was
+-- authored against, and so the yardstick the live pair is measured with.
+OverworldBattle.ANCHOR_SPAN = math.sqrt(
+  (OverworldBattle.ANCHOR.enemy[1] - OverworldBattle.ANCHOR.player[1]) ^ 2
+  + (OverworldBattle.ANCHOR.enemy[2] - OverworldBattle.ANCHOR.player[2]) ^ 2)
+
+-- The effects layer's scale for this shot: how far apart the two mons
+-- actually are on screen, over how far apart the slots they were authored
+-- for were. Clamped hard at both ends -- an effect is pixel art and a wild
+-- factor is worse than a slightly wrong one -- and held at exactly 1 when
+-- the marks coincide, which is a projection about to degenerate rather
+-- than a pair that has genuinely closed up.
+OverworldBattle.ANIM_SCALE_MIN = 0.5
+OverworldBattle.ANIM_SCALE_MAX = 2.0
+
+function OverworldBattle.animScale(shot, px, py)
+  if not (shot and shot.enemy and px and py) then return 1 end
+  local dx, dy = shot.enemy[1] - px, shot.enemy[2] - py
+  local span = math.sqrt(dx * dx + dy * dy)
+  if not (span > 1) then return 1 end
+  local k = span / OverworldBattle.ANCHOR_SPAN
+  return math.max(OverworldBattle.ANIM_SCALE_MIN,
+                  math.min(OverworldBattle.ANIM_SCALE_MAX, k))
+end
+
 function OverworldBattle.textRects(battle)
   if not battle or battle.blankForAskName then return {} end
   local r = OverworldBattle.TEXT_RECT
@@ -326,6 +351,10 @@ end
 -- not nest.
 local session = nil
 
+local function isIOS()
+  return love.system and love.system.getOS and love.system.getOS() == "iOS"
+end
+
 local function game()
   return require("src.core.Game")
 end
@@ -474,6 +503,19 @@ function OverworldBattle.update(dt)
     return
   end
 
+  -- Whether the shot is the player's to steer at all. BACK SPRITES pins
+  -- their own mon to the GB's slot on the menu while the foe stands out on
+  -- the map, and there is no angle that half-framed, half-solid
+  -- composition survives -- so under it the camera holds the shot the rig
+  -- was solved for (the slow drift aside, which was always there). Polled
+  -- per frame rather than latched at battle start: the row is reachable
+  -- from the mod manager's page mid-session.
+  BattleCam.steerable = not OverworldBattle.backPinned()
+  -- the right stick, read as a rate before the rig is built from it: the
+  -- wheel, the keys, the mouse and a drag all arrive as events and have
+  -- already landed, but a stick is a HELD position and only a tick can
+  -- turn it into travel (CamControl, which owns every one of those inputs)
+  pcall(V.require("CamControl").tick, dt)
   BattleCam.update(dt)
   -- the battle only exists once it has been pushed; a session opened at
   -- pushBattle time has it, one opened from battle.started was handed it
@@ -540,11 +582,15 @@ function OverworldBattle.update(dt)
     -- reason the scene is: it binds a canvas of its own. After the frost, so
     -- the glass is frosted from the world alone and never from the glyphs
     -- about to sit on it.
-    local okHud, up = pcall(OverworldBattle.snapHUDs, session.battle, shot)
+    local ios = isIOS()
+    local okHud, up = false, false
+    if not ios then
+      okHud, up = pcall(OverworldBattle.snapHUDs, session.battle, shot)
+    end
     session.snapped = (okHud and up) and true or false
     -- once per battle, not once per frame: a driver that cannot do this cannot
     -- do it sixty times a second either, and the fallback is silent and fine
-    if not okHud and not session.hudWarned then
+    if not ios and not okHud and not session.hudWarned then
       session.hudWarned = true
       V.mod.log:warn("overworld battle HUD snap failed: %s -- the HUDs draw "
                      .. "in the battle frame this battle", tostring(up))
@@ -1090,6 +1136,7 @@ function OverworldBattle.install()
   local innerText = BattleState.drawTextArea
   function BattleState:drawTextArea()
     if not self.dramaticShapeShot then return innerText(self) end
+    if isIOS() 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()
@@ -1111,16 +1158,36 @@ function OverworldBattle.install()
     -- give them. They ride to where the PAIR went: the midpoint of the two
     -- 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.
+    --
+    -- And they ride the pair's SEPARATION as well, because the mons
+    -- themselves do. Both are geometry standing on the map, so the camera
+    -- sizes them: zoom in and they grow, swing round to side-on and the two
+    -- marks close up as the axis foreshortens. A layer that only slid would
+    -- have held the authored 106-pixel spacing through all of it -- a beam
+    -- fired between two mons that are no longer that far apart, ending in
+    -- the air beside the one it was aimed at. Scaling about the same
+    -- midpoint keeps every authored offset the same fraction of the gap it
+    -- was authored as.
     local a = OverworldBattle.ANCHOR
     -- BACK SPRITES leaves the player's mon exactly where the GB put it, so that side
     -- contributes no movement at all and the pair's centre has gone half as
     -- far as the foe's mark did.
     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
+    local cx, cy = (shot.enemy[1] + px) / 2, (shot.enemy[2] + py) / 2
+    local ax = (a.enemy[1] + a.player[1]) / 2
+    local ay = (a.enemy[2] + a.player[2]) / 2
     love.graphics.push()
-    love.graphics.translate(math.floor(dx + 0.5), math.floor(dy + 0.5))
+    love.graphics.translate(cx - ax, cy - ay)
+    -- Clamped, and skipped outright if the marks ever coincide: a
+    -- degenerate projection must leave the effects the size they were
+    -- rather than collapse them to nothing or blow them across the screen.
+    local k = OverworldBattle.animScale(shot, px, py)
+    if k ~= 1 then
+      love.graphics.translate(ax, ay)
+      love.graphics.scale(k, k)
+      love.graphics.translate(-ax, -ay)
+    end
     local ok, err = pcall(innerAnim, self, colorized)
     love.graphics.pop()
     if not ok then error(err, 0) end
@@ -1315,6 +1382,17 @@ function OverworldBattle.drawHudPanels(battle)
   local shot = battle.dramaticShapeShot
   battle.dramaticShapeDark = nil
   if not shot then return end
+  if isIOS() then
+    local slide = (battle.introSlide or 0) * 4
+    local enemy, player = OverworldBattle.hudLive(battle, slide)
+    local rect = OverworldBattle.HUD_RECT
+    love.graphics.setColor(1, 1, 1, 0.84)
+    if enemy then love.graphics.rectangle("fill", rect.enemy[1], rect.enemy[2], rect.enemy[3], rect.enemy[4]) end
+    if player then love.graphics.rectangle("fill", rect.player[1], rect.player[2], rect.player[3], rect.player[4]) end
+    love.graphics.setColor(1, 1, 1, 1)
+    battle.dramaticShapeDark = nil
+    return
+  end
   if snapped() then
     battle.dramaticShapeDark = session and session.dark or nil
     return

lib/PixelCanvas.lua

@@ -0,0 +1,9 @@
+local V = ...
+
+local PixelCanvas = {}
+
+function PixelCanvas.new(w, h)
+  return pcall(love.graphics.newCanvas, w, h, { dpiscale = 1 })
+end
+
+return PixelCanvas

lib/ShadowMap.lua

@@ -186,7 +186,7 @@ end
 local function getCanvas(res)
   if canvas == false then return nil end
   if canvas and canvasRes == res then return canvas end
-  local ok, c = pcall(love.graphics.newCanvas, res, res)
+  local ok, c = V.require("PixelCanvas").new(res, res)
   if not (ok and c) then
     canvas = false
     return nil
@@ -221,6 +221,9 @@ end
 -- where the canvas cannot be made -- VoxelScene then keeps the flat decal
 -- shadows, which need nothing but a quad.
 function ShadowMap.available()
+  if love.system and love.system.getOS and love.system.getOS() == "iOS" then
+    return false
+  end
   if not (love.graphics and love.graphics.newCanvas
           and love.graphics.setDepthMode) then
     return false

lib/Structures.lua

@@ -3289,6 +3289,83 @@ end
 
 -- ---- tall grass ----
 
+-- ---- closing a standee's sides ----
+--
+-- The grass tufts and the flowers are both built the same way: each row of
+-- the 8x8 drawing becomes a horizontal RUN of lit pixels, stood up as a
+-- front face and a back face one voxel apart, with a lid on top. What that
+-- leaves open is the two ENDS of every run -- so the slab was a pair of
+-- billboards rather than a solid, and from any angle off square you looked
+-- in through the edge and straight out the other side. At the low cameras
+-- this mod has grown (1ST, 3RD, the battle's floor-level seat) that is
+-- most of the time.
+--
+-- A wall goes on an end only where the pixel beyond it is actually clear,
+-- which for a run's end it is by construction -- except where two runs on
+-- the same row meet across a gap of nothing, which cannot happen, and at
+-- the tile's border, where the neighbouring tile's own standee may or may
+-- not continue the shape. The border is closed anyway: tufts sit on their
+-- own half-cells with a gap between them, so an open border edge is a hole
+-- in the open, not a seam with anything.
+--
+-- Each wall samples ONE texel at its centre -- the end pixel it is closing
+-- off -- so it wears that pixel's own colour, which is the nearest coloured
+-- pixel to the surface being filled. Sampling a single texel is also what
+-- carries the animation: when a frame keys that pixel out, the wall's own
+-- fragments discard with the faces either side of it, so a swaying tuft
+-- never leaves a wall standing where its blade no longer is.
+-- `everyPixel` is for a standee whose silhouette ANIMATES. The mesh is
+-- built once, over the UNION of every frame's mask, and each frame is cut
+-- out again in texture space -- so a run that is six pixels wide in the
+-- union may be two pixels wide in the frame on screen, and the four pixels
+-- that dropped out took the union's end walls with them. What is left
+-- exposed is an interior boundary, which had no wall because in the union
+-- it was not a boundary at all. That is the gap that survived closing the
+-- run ends: the first frame looked solid and every other frame did not.
+--
+-- So an animated standee gets a wall on BOTH sides of EVERY pixel. A wall
+-- between two lit pixels is enclosed by the front and back faces and never
+-- seen; the moment its neighbour is keyed out it becomes the edge, already
+-- in place and already wearing the right colour. Each is inset a hair into
+-- its own pixel so the two that meet at a boundary are not coplanar -- the
+-- voxel pass draws with culling off, and two quads in the same plane would
+-- z-fight rather than politely take turns.
+local SIDE_INSET = 0.03
+
+local function sideQuads(quads, ix, ix2, yBot, yTop, zB, zF,
+                         ax0, ay0, atlasW, atlasH, py, lit, everyPixel)
+  local function texel(px)
+    return (ax0 + px + 0.5) / atlasW, (ay0 + py + 0.5) / atlasH
+  end
+  local function left(px, at)
+    local u, v = texel(px)
+    quads[#quads + 1] = {                 -- facing -X
+      { at, yBot, zB }, { at, yBot, zF },
+      { at, yTop, zF }, { at, yTop, zB },
+      uv = { { u, v }, { u, v }, { u, v }, { u, v } },
+      shade = OBJ_SHADE.side,
+    }
+  end
+  local function right(px, at)
+    local u, v = texel(px)
+    quads[#quads + 1] = {                 -- facing +X
+      { at, yBot, zF }, { at, yBot, zB },
+      { at, yTop, zB }, { at, yTop, zF },
+      uv = { { u, v }, { u, v }, { u, v }, { u, v } },
+      shade = OBJ_SHADE.side,
+    }
+  end
+  if everyPixel then
+    for px = ix, ix2 do
+      left(px, px + SIDE_INSET)
+      right(px, px + 1 - SIDE_INSET)
+    end
+    return
+  end
+  if not lit(ix - 1, py) then left(ix, ix) end
+  if not lit(ix2 + 1, py) then right(ix2, ix2 + 1) end
+end
+
 -- A tall-grass CELL is four tufts: 2x2 tiles, and each 8x8 tile is one
 -- whole clump of grass. Each tile stands as its own thin per-pixel slab
 -- at ITS OWN depth -- the cell's north tile row in the north half of the
@@ -3359,6 +3436,20 @@ local function grassTemplate(map, data, tileId)
             shade = 1,
           }
         end
+        -- and underneath, where a blade ends in mid-air over the ground
+        if not opaque(ix, iy + 1) then
+          quads[#quads + 1] = {
+            { ix, yBot, zF }, { ix2 + 1, yBot, zF },
+            { ix2 + 1, yBot, zB }, { ix, yBot, zB },
+            uv = { { u0, v1 }, { u1, v1 }, { u1, v1 }, { u0, v1 } },
+            shade = OBJ_SHADE.bottom,
+          }
+        end
+        -- and the run's two end walls, which is what makes a blade a solid
+        -- thing rather than two billboards you can see between (sideQuads
+        -- above argues it, and why each wall wears its end pixel's colour)
+        sideQuads(quads, ix, ix2, yBot, yTop, zB, zF,
+                  ax0, ay0, atlasW, atlasH, iy, opaque)
         ix = ix2 + 1
       else
         ix = ix + 1
@@ -3526,17 +3617,51 @@ local function flowerTemplate(map, data, tileId)
           uv = { { u1, v1 }, { u0, v1 }, { u0, v0 }, { u1, v0 } },
           shade = OBJ_SHADE.back,
         }
-        -- petal tips: a top strip where the row above is clear. The
-        -- strip samples its own row's texel, so a tip that is not in
-        -- the current frame discards with the face beneath it
-        if not on(ix, py - 1) then
-          quads[#quads + 1] = {
-            { ix, yTop, zB }, { ix2 + 1, yTop, zB },
-            { ix2 + 1, yTop, zF }, { ix, yTop, zF },
-            uv = { { u0, v0 }, { u1, v0 }, { u1, v0 }, { u0, v0 } },
+        -- ------- the shell, closed on all four remaining faces
+        --
+        -- A flower SWAYS: the geometry spans the union of every animation
+        -- frame's mask and each frame is cut back out of it in texture
+        -- space (see the header). So "is there a pixel next door" has two
+        -- different answers -- one in the union this mesh was built from,
+        -- and one in the frame actually on screen -- and only the second
+        -- decides what is exposed.
+        --
+        -- Closing the union's own edges is therefore not enough, and was
+        -- the bug the first cut of this shipped: the base frame looked
+        -- solid and every other frame still had gaps, because a pixel that
+        -- drops out of a frame takes the union's wall with it and leaves an
+        -- interior boundary that never had one.
+        --
+        -- So every pixel gets a cap on all four of its remaining faces,
+        -- whatever its neighbours do. A cap between two lit pixels sits
+        -- inside the slab, enclosed by the front and back faces, and is
+        -- never seen; the moment its neighbour is keyed out it IS the edge,
+        -- already there and already wearing the right colour. Each samples
+        -- its own pixel's texel, so it appears and vanishes with the pixel
+        -- it belongs to rather than with the one it is closing off.
+        --
+        -- Inset a hair into its own pixel, because the voxel pass draws
+        -- with culling off: the two caps that meet at a boundary would be
+        -- coplanar and z-fight rather than politely take turns.
+        for px = ix, ix2 do
+          local tu = (ax0 + px + 0.5) / atlasW
+          local tv = (ay0 + py + 0.5) / atlasH
+          local xa, xb = px, px + 1
+          local yT = yTop - SIDE_INSET
+          local yB = yBot + SIDE_INSET
+          quads[#quads + 1] = {           -- the pixel's own lid
+            { xa, yT, zB }, { xb, yT, zB }, { xb, yT, zF }, { xa, yT, zF },
+            uv = { { tu, tv }, { tu, tv }, { tu, tv }, { tu, tv } },
             shade = OBJ_SHADE.top,
           }
+          quads[#quads + 1] = {           -- and its floor
+            { xa, yB, zF }, { xb, yB, zF }, { xb, yB, zB }, { xa, yB, zB },
+            uv = { { tu, tv }, { tu, tv }, { tu, tv }, { tu, tv } },
+            shade = OBJ_SHADE.bottom,
+          }
         end
+        sideQuads(quads, ix, ix2, yBot, yTop, zB, zF,
+                  ax0, ay0, atlasW, atlasH, py, on, true)
         ix = ix2 + 1
       else
         ix = ix + 1

lib/ThirdPerson.lua

@@ -0,0 +1,407 @@
+-- Voxel world mode: the third-person camera -- the 3RD rung.
+--
+-- 3RD is 1ST with the eye pulled off the back of the head. Everything that
+-- makes the first-person rung work -- the steered attitude, the placed
+-- camera on Voxel3D's seam, the cards that turn to face the eye, the
+-- continuous camera-relative walk -- is already general over WHERE the eye
+-- stands, so this module adds exactly one thing to it: a BOOM.
+--
+-- What the boom owns:
+--
+--   the LENGTH    how far behind the pivot the eye sits, eased in and out
+--                 so stepping between 1ST and 3RD slides rather than cuts,
+--                 and clamped every frame by what the world will allow.
+--
+--   the COLLISION a march back along the boom line through the terrain
+--                 height field and the map's own walkability, so backing
+--                 into a wall walks the camera in toward the player's
+--                 shoulders instead of through the wall into the void.
+--                 The recovery is deliberately slower than the intrusion:
+--                 a camera must never be a frame late leaving geometry,
+--                 and must never snap back out the instant a corner clears.
+--
+--   the SHOULDER  the small lateral rail offset that keeps the character
+--                 off dead centre, faded out with the boom so a camera
+--                 jammed against a wall does not also slide sideways into
+--                 it.
+--
+-- Deliberately NOT here: the attitude, the look inputs, the blend, the
+-- move intent (all lib/FirstPerson.lua, which drives this module and reads
+-- its answer while building the frame's rig), and movement itself
+-- (lib/FreeMove.lua, unchanged -- the walk is camera-relative either way,
+-- and the camera's yaw is the same number on both rungs).
+--
+-- Nothing here is required for the rung to draw: with no overworld to ask
+-- (a headless run, the test suite) every query answers "clear" and the boom
+-- extends to its full length over an empty world.
+
+-- the mod namespace (see main.lua): V.require loads a sibling module
+local V = ...
+
+local Voxel = V.require("VoxelState")
+
+local ThirdPerson = {}
+
+-- ------- the boom's numbers
+--
+-- BOOM is world pixels behind the pivot at full extension. A cell is 16 and
+-- a character card is 16 tall, so 48 stands the camera three cells back:
+-- with the first-person lens (65 degrees vertical) that frames the player
+-- at roughly a quarter of the frame height -- the modern action-game
+-- middle ground, close enough to read the four-frame sprite and far enough
+-- to see the cell you are about to walk into.
+--
+-- PIVOT_LIFT raises the orbit point above the first-person eye, so the
+-- boom looks slightly DOWN across the player's shoulder rather than
+-- straight through the back of their head.
+--
+-- SHOULDER is the lateral rail offset, in world pixels, positive to the
+-- camera's right -- which puts the player left of centre, leaving the
+-- larger half of the frame in front of them.
+ThirdPerson.BOOM = 48
+ThirdPerson.PIVOT_LIFT = 4
+ThirdPerson.SHOULDER = 4
+
+-- how long the eye takes to slide out to the boom (and back into the head
+-- when 1ST is picked), in seconds -- the same order as FirstPerson's own
+-- dive so stepping 75 -> 1ST -> 3RD reads as one continuous camera
+ThirdPerson.BOOM_TIME = 0.35
+
+-- ------- the player's own zoom
+--
+-- A multiplier on BOOM, stepped by the wheel, Q/E or a pinch (see
+-- CamControl, which owns every one of those and decides which camera a
+-- given input is aimed at). The range is deliberately wider IN than OUT:
+-- close is the shot people reach for, and far enough out the character is
+-- a few pixels and the rung may as well be an orbit rung.
+--
+-- Stepped in fractions rather than world pixels so a notch feels the same
+-- at both ends -- the near end of a linear step would crawl and the far
+-- end would leap.
+ThirdPerson.ZOOM_MIN = 0.45           -- ~22px: over the shoulder, close
+ThirdPerson.ZOOM_MAX = 2.4            -- ~115px: the character in a landscape
+ThirdPerson.ZOOM_STEP = 1.18          -- one wheel notch / key press
+ThirdPerson.ZOOM_TIME = 0.18          -- how fast the eye eases to a new one
+
+ThirdPerson.zoom = 1                  -- eased, what place() actually uses
+ThirdPerson.zoomGoal = 1              -- what the input asked for
+
+-- Step the zoom by `notches` (positive pulls the camera OUT). Returns true
+-- when the goal actually moved, so a caller can tell "zoomed" from "already
+-- at the stop" and let the input fall through.
+function ThirdPerson.stepZoom(notches)
+  local was = ThirdPerson.zoomGoal
+  local goal = was * (ThirdPerson.ZOOM_STEP ^ (notches or 0))
+  ThirdPerson.zoomGoal = math.max(ThirdPerson.ZOOM_MIN,
+                          math.min(ThirdPerson.ZOOM_MAX, goal))
+  return ThirdPerson.zoomGoal ~= was
+end
+
+-- Scale the zoom by a continuous factor -- what a pinch hands over, where
+-- the gesture's own scale IS the answer and there are no notches.
+function ThirdPerson.scaleZoom(factor)
+  if not (factor and factor > 0) then return false end
+  return ThirdPerson.stepZoom(math.log(factor) / math.log(ThirdPerson.ZOOM_STEP))
+end
+
+-- ------- the collision's numbers
+--
+-- STEP is how far apart the samples along the boom line are, in world
+-- pixels, and REFINE how many bisections narrow the first blocked one --
+-- four halvings of a 4px step lands the eye within a quarter pixel of the
+-- face, which is finer than the boom ever needs to be.
+--
+-- PAD is the clearance kept between the eye and whatever stopped it. It
+-- has to beat the placed camera's near plane (|eye - focus| * 0.05, which
+-- at full extension is about 3.6 world pixels -- see Voxel3D) or the near
+-- plane clips a hole in the very wall the boom stopped at.
+--
+-- CLEAR is how high above a cell's ground the eye must be to pass OVER
+-- something unwalkable rather than being stopped by it: a fence, a kerb or
+-- a plant pot should not shove the camera in, a building should. Roughly
+-- head height, so the eye clears the props and never the walls.
+ThirdPerson.STEP = 4
+ThirdPerson.REFINE = 4
+ThirdPerson.PAD = 5
+ThirdPerson.CLEAR = 20
+
+-- How fast the boom is allowed to grow BACK once whatever shortened it is
+-- out of the way, in world pixels per second. Shortening is instant (a
+-- camera inside a wall is a hole in the frame); lengthening is rationed,
+-- so rounding a corner eases the eye back out instead of snapping it.
+ThirdPerson.RETURN = 150
+
+-- ------- state
+--
+-- `out` is the eased extension, 0 in the head and 1 fully boomed -- the
+-- number that carries 1ST into 3RD. `len` is the boom's actual length in
+-- world pixels after the world has had its say, which is what place()
+-- stands the eye at and update() eases back toward `want`.
+ThirdPerson.out = 0
+ThirdPerson.len = 0
+ThirdPerson.want = 0
+
+local function ease(t)
+  return t * t * (3 - 2 * t)
+end
+
+-- ------- gates
+
+-- Whether the 3RD rung is the one selected. Not "is the boom out" -- that
+-- is extended() below, which stays true through the ease after the rung is
+-- left, the same way FirstPerson.blend outlives its own rung.
+--
+-- A live headset declines the boom outright: VR builds its own eye cameras
+-- from the tracked pose and never asks place() where to stand, and a
+-- headset that seats its wearer three cells behind their own body is a
+-- well-known way to make people ill. Answering false here is what keeps
+-- everything ELSE the extension decides -- the player's own card, the body
+-- that turns as it walks -- honest about the head VR actually puts you in.
+-- Required lazily and guarded: VR reaches this module through FirstPerson,
+-- and a headless run has no VR module worth loading at all.
+local function headset()
+  local ok, on = pcall(function() return V.require("VR").active() end)
+  return ok and on or false
+end
+
+function ThirdPerson.selected()
+  return Voxel.isThirdPerson(Voxel.level) and not headset()
+end
+
+-- The eased extension, 0 at the head and 1 at the full boom.
+function ThirdPerson.extension()
+  return ease(ThirdPerson.out)
+end
+
+-- Whether the boom is out far enough to be a third-person camera at all --
+-- read off the TARGET extension rather than the live length, so it is
+-- steady while the world shoves the eye about. What the body reads to
+-- decide whether it turns along its own travel.
+function ThirdPerson.extended()
+  return ThirdPerson.extension() > 0.5
+end
+
+-- How far back the eye must ACTUALLY be, in world pixels, for the player's
+-- own card to be worth drawing: a shade under a cell, which is the point
+-- where a 16-pixel card stops being a character and starts being a wall of
+-- pixels across the lens.
+ThirdPerson.SHOW_AT = 14
+
+-- Whether the player's own card belongs in the frame. Not the same
+-- question as extended(): back into a fence and the boom collapses into
+-- the head whatever the rung says, and a card drawn there fills the lens
+-- from inside exactly as it would in first person -- so it comes out, and
+-- the rung reads as first person for as long as the world insists on it.
+function ThirdPerson.showsPlayer()
+  return ThirdPerson.extension() > 0 and ThirdPerson.len >= ThirdPerson.SHOW_AT
+end
+
+-- ------- the world the boom has to fit through
+--
+-- Everything below asks the live overworld and pcall-guards the asking:
+-- with no map (headless, the suite, a frame mid-warp) the boom simply
+-- extends to its full length, which is the right answer for a world with
+-- nothing in it.
+
+local function overworld()
+  local ok, ow = pcall(function()
+    return require("src.core.Game").overworld
+  end)
+  if not ok or not ow or not ow.map then return nil end
+  return ow
+end
+
+-- Which map, and which of its cells, covers a world point. The player's own
+-- map first, then the neighbours the scene streams in around it (same ox/oy
+-- offsets VoxelScene draws them at) -- without that pass the boom would
+-- shorten against "off the map" every time the player walked within three
+-- cells of a route connection, which is most of the time.
+--
+-- nil means no map covers it: genuinely off the world, where the border
+-- ring is drawn and the camera has no business going.
+local function cellAt(ow, wx, wz)
+  local map = ow.map
+  local cx, cy = math.floor(wx / 16), math.floor(wz / 16)
+  if map:inBounds(cx, cy) then return map, cx, cy end
+  for _, nb in ipairs(ow.neighbors or {}) do
+    if nb.map then
+      local nx = math.floor((wx - (nb.ox or 0)) / 16)
+      local ny = math.floor((wz - (nb.oy or 0)) / 16)
+      if nb.map:inBounds(nx, ny) then return nb.map, nx, ny end
+    end
+  end
+  return nil
+end
+
+-- Whether the eye may not stand at this world point. Two refusals, and
+-- they are different questions:
+--
+--   the GROUND is the terrain height field the mesh is actually built from
+--   (VoxelScene.groundAt -- the same answer a character stands on), so a
+--   ledge, a raised bank or a cliff stops the boom exactly where it stops
+--   the geometry, at any pitch.
+--
+--   the WALKABILITY is the map's own, and stands in for everything built
+--   ON the ground that the height field does not describe: house walls,
+--   trees, signs, counters. Held to CLEAR above that cell's ground so the
+--   short furniture of the world is passed over rather than bumped into.
+local function occupied(ow, wx, y, wz)
+  local map, cx, cy = cellAt(ow, wx, wz)
+  if not map then return true end
+  local VoxelScene = V.require("VoxelScene")
+  local okG, gh = pcall(VoxelScene.groundAt, map, cx, cy)
+  gh = (okG and gh) or 0
+  if y < gh + ThirdPerson.PAD then return true end
+  local okW, walkable = pcall(function() return map:isWalkableCell(cx, cy) end)
+  if okW and not walkable and y < gh + ThirdPerson.CLEAR then return true end
+  return false
+end
+
+ThirdPerson._occupied = occupied       -- named for the suite
+
+-- How far back along (bx, by, bz) from `pivot` the eye can stand, up to
+-- `want`. March at STEP, and when a sample refuses, bisect back into the
+-- gap between it and the last clear one -- so the answer is the face's own
+-- position rather than the sampling grid's, and walking toward a wall
+-- draws the camera in smoothly instead of in four-pixel jerks. PAD comes
+-- off whatever survives.
+function ThirdPerson.reach(ow, pivot, bx, by, bz, want)
+  if not ow or want <= 0 then return math.max(0, want) end
+  local function clear(t)
+    return not occupied(ow, pivot[1] + bx * t, pivot[2] + by * t,
+                        pivot[3] + bz * t)
+  end
+  local lo = 0
+  local steps = math.ceil(want / ThirdPerson.STEP)
+  local hi = nil
+  for i = 1, steps do
+    local t = math.min(want, i * ThirdPerson.STEP)
+    if clear(t) then
+      lo = t
+    else
+      hi = t
+      break
+    end
+  end
+  if not hi then return want end
+  for _ = 1, ThirdPerson.REFINE do
+    local mid = (lo + hi) / 2
+    if clear(mid) then lo = mid else hi = mid end
+  end
+  return math.max(0, lo - ThirdPerson.PAD)
+end
+
+-- ------- the tick
+--
+-- Rides FirstPerson.update, which is itself on the pipeline's own update
+-- hook, so this runs every frame whatever the rung -- the extension has to
+-- keep easing back in after 3RD is left. `blend` is FirstPerson's dive into
+-- the head: while it is fully out (the diorama), the extension SNAPS to its
+-- target rather than easing, so picking 3RD from an orbit rung is one
+-- motion (the dive) rather than two (a dive, then a slide backwards).
+function ThirdPerson.update(dt, blend)
+  -- the player's own zoom FIRST, so everything below measures itself
+  -- against the boom length this frame actually wants. A step is a request
+  -- rather than a jump: three notches of wheel should read as one glide.
+  local zg = ThirdPerson.zoomGoal
+  if ThirdPerson.zoom ~= zg then
+    local k = math.min(1, dt / ThirdPerson.ZOOM_TIME)
+    local z = ThirdPerson.zoom + (zg - ThirdPerson.zoom) * k
+    ThirdPerson.zoom = (math.abs(zg - z) < 1e-4) and zg or z
+  end
+
+  local target = ThirdPerson.selected() and 1 or 0
+  if (blend or 0) <= 0 then
+    ThirdPerson.out = target
+    ThirdPerson.len = ThirdPerson.reachFor() * target
+    -- and the wanted length with it: place() is what normally maintains it
+    -- and it does not run at all while the rig is out of the frame, so a
+    -- stale want left here would have the recovery below creeping the boom
+    -- back out over a camera that is not on screen
+    ThirdPerson.want = ThirdPerson.len
+  else
+    local step = dt / ThirdPerson.BOOM_TIME
+    if ThirdPerson.out < target then
+      ThirdPerson.out = math.min(target, ThirdPerson.out + step)
+    elseif ThirdPerson.out > target then
+      ThirdPerson.out = math.max(target, ThirdPerson.out - step)
+    end
+  end
+
+  -- the rationed recovery: place() already pulled `len` in to whatever the
+  -- world allowed this frame, and this is the only thing that lets it back
+  -- out again
+  if ThirdPerson.len < ThirdPerson.want then
+    ThirdPerson.len = math.min(ThirdPerson.want,
+                               ThirdPerson.len + ThirdPerson.RETURN * dt)
+  end
+end
+
+-- The boom's full length right now, before the world has its say: BOOM at
+-- the player's own zoom. Named so the collision march and the shoulder
+-- fade measure themselves against the same number.
+function ThirdPerson.reachFor()
+  return ThirdPerson.BOOM * ThirdPerson.zoom
+end
+
+-- ------- the eye
+--
+-- Where the camera stands, given the pivot the first-person rig would have
+-- put the eye at and the unit look direction it would have looked along.
+-- Returns the eye and the focus: both slide by the shoulder offset, so the
+-- view direction is untouched and only the frame's contents shift.
+--
+-- With the boom fully in this is exactly the first-person answer, to the
+-- pixel -- which is what makes 1ST and 3RD one rig with a number between
+-- them rather than two cameras to keep in sync.
+function ThirdPerson.place(pivot, lx, ly, lz, focus)
+  local e = ThirdPerson.extension()
+  if e <= 0 then
+    ThirdPerson.want, ThirdPerson.len = 0, 0
+    return pivot, focus
+  end
+
+  local up = ThirdPerson.PIVOT_LIFT * e
+  local orbit = { pivot[1], pivot[2] + up, pivot[3] }
+
+  local want = ThirdPerson.reachFor() * e
+  ThirdPerson.want = want
+  local room = ThirdPerson.reach(overworld(), orbit, -lx, -ly, -lz, want)
+  -- in instantly, out only as fast as update() allows
+  ThirdPerson.len = math.min(ThirdPerson.len, room)
+  local len = ThirdPerson.len
+
+  -- the rail offset, faded with how much boom actually survived: a camera
+  -- squeezed against a wall gives up its shoulder before it gives up its
+  -- distance. Right of the look, flat: cross(look, worldUp) normalized,
+  -- which for a look of (sin y, *, cos y) is (-cos y, 0, sin y) -- the same
+  -- right hand FirstPerson.moveWorld strafes along.
+  -- The rail rides the ZOOM as well, so it stays the same fraction of the
+  -- frame at every distance: a fixed four pixels would swamp the close shot
+  -- and vanish from the wide one.
+  local flat = math.sqrt(lx * lx + lz * lz)
+  local sx, sz = 0, 0
+  if flat > 1e-6 then
+    local s = ThirdPerson.SHOULDER * ThirdPerson.zoom * e
+              * (len / math.max(want, 1e-6))
+    sx, sz = -lz / flat * s, lx / flat * s
+  end
+
+  local eye = { orbit[1] - lx * len + sx,
+                orbit[2] - ly * len,
+                orbit[3] - lz * len + sz }
+  local aim = focus and { focus[1] + sx, focus[2] + up, focus[3] + sz }
+              or nil
+  return eye, aim
+end
+
+-- What a shadow signature has to include about the boom: the sun's box is
+-- fitted around this camera, so sliding the eye back (or having a wall
+-- shove it in) re-fits it even standing still.
+function ThirdPerson.signature()
+  if ThirdPerson.extension() <= 0 then return "" end
+  return math.floor(ThirdPerson.len) .. "/" ..
+         math.floor(ThirdPerson.extension() * 64)
+end
+
+return ThirdPerson

lib/TiltShift.lua

@@ -25,6 +25,7 @@
 -- failure -- headless, no shader support) apply() hands the canvas back
 -- untouched, so every other path is byte-for-byte what it always was.
 
+local V = ...
 local TiltShift = {}
 
 TiltShift.level = 0
@@ -85,9 +86,10 @@ end
 
 local function getCanvases(w, h)
   if not ping or cw ~= w or ch ~= h then
-    local ok, a = pcall(love.graphics.newCanvas, w, h)
+    local PixelCanvas = V.require("PixelCanvas")
+    local ok, a = PixelCanvas.new(w, h)
     if not ok then return nil end
-    local okB, b = pcall(love.graphics.newCanvas, w, h)
+    local okB, b = PixelCanvas.new(w, h)
     if not okB then return nil end
     -- the gaussian's fractional tap offsets need linear filtering
     a:setFilter("linear", "linear")

lib/VR.lua

@@ -59,6 +59,25 @@ local VR = {}
 -- spoken for, and a headset is not something to toggle by accident.
 VR.setting = ModSetting.new("vr", "VR", { false, true }, { "OFF", "ON" })
 
+-- How the right stick turns you in first person. OFF is the 45-degree
+-- SNAP this mod shipped with and the reason for it is comfort, not
+-- taste: a software turn moves the world past a head that did not move,
+-- which is vection with no vestibular signal to match it, and it is the
+-- single most reliable way to make somebody ill in a headset. A snap
+-- gives the inner ear nothing to disagree with.
+--
+-- But snap turning is not free either -- it costs continuity, and the
+-- players who have their sea legs generally want the stick. So it is a
+-- row rather than a decision: OFF by default, on for anyone who asks,
+-- and the row only exists while there is a headset to use it in.
+VR.smoothTurn = ModSetting.new("smoothturn", "SMOOTH TURN",
+                               { false, true }, { "OFF", "ON" })
+
+-- radians per second at full deflection, with a squared response so the
+-- first half of the throw aims and the rest turns -- the same curve
+-- FirstPerson gives the flat screen's right stick
+VR.SMOOTH_TURN_RATE = 2.2
+
 -- Where the diorama's UI panel floats vs first person's. These are the
 -- FALLBACK screens: wherever the pokedex is up and lit -- first
 -- person's menus, a battle's 2D scene -- no quad is submitted at all
@@ -181,6 +200,11 @@ local function shutdown(reason)
   BattleCam.still = false
   VoxelScene.spriteLean = nil
   Pokedex.clear()
+  -- the horde's gun too: its VR frame is a matrix built from a hand pose,
+  -- and a stale one left behind would pin the model to wherever the
+  -- controller was when the session died -- on the FLAT screen, where the
+  -- view model should have taken over
+  V.require("HordeGun").clear()
   zoom, heightOff = 1, 0
   fpYawOff, snapArmed = 0, true
   camMode, fadeAlpha = "explore", 0
@@ -257,6 +281,11 @@ local function renderWorld(views, ctl)
   VoxelScene.spriteLean = math.rad(75)
 
   local pivot, anchor, scale, mountYaw
+  -- Either free-roam rung puts the headset in the player's head: 3RD's boom
+  -- is a FLAT-SCREEN framing device, and a headset that stands its wearer
+  -- three cells behind their own body is a well-known way to make people
+  -- ill. The rung still changes the walk and the cards the same way; only
+  -- the eye stays where a head belongs.
   local fp = FirstPerson.engaged()
   local battle, battleFloor
   if camMode == "battle" then battle, battleFloor = battleStage() end
@@ -311,11 +340,46 @@ local function renderWorld(views, ctl)
       if scr then
         Pokedex.screen(scr[1], scr[2], scr[3], scr[4], scr[5])
       end
+    elseif V.require("Horde").active then
+      -- HORDE MODE's readout, on the device already in the player's left
+      -- hand. It cannot be a flat overlay: the eye buffers have
+      -- ASYMMETRIC frusta, so the same canvas pixel is a different ANGLE
+      -- in each eye and a 2D HUD drawn into both tears down the middle.
+      -- The Pokedex is real geometry both eyes see from their own
+      -- position, so the stereo is correct by construction -- and it is
+      -- already tracked, already lit, and already the thing this mod
+      -- puts information on. (The gun wore it briefly and that was
+      -- worse: a screen on the slide sits exactly where the iron sights
+      -- need to be looked through.)
+      --
+      -- The UV rect goes over the usual way up: v = 0 at the TOP, which
+      -- is how the device's screen quad reads every other texture it
+      -- wears. An inverted rect was tried first, on the theory that a
+      -- self-drawn canvas samples from the bottom -- it does not here,
+      -- and it stood the readout on its head.
+      local tex = V.require("HordeHud").panelTexture()
+      if tex then Pokedex.screen(tex, 0, 0, 1, 1) end
     end
   else
     Pokedex.clear()
   end
 
+  -- and the horde's gun on the tracked RIGHT hand, under the same
+  -- mapping. The AIM pose where the runtime offers one -- the barrel
+  -- should point where the player is pointing, not along their wrist --
+  -- and the grip pose as the fallback. Placed here rather than in the
+  -- draw because the shot is traced down the model's own axis, so the
+  -- matrix has to exist before anything can be hit with it.
+  do
+    local HordeGun = V.require("HordeGun")
+    local right = ctl and (ctl.aimr or ctl.handr) or nil
+    if right and fp and not battle and V.require("Horde").active then
+      HordeGun.place(right, pivot, anchor, scale, mountYaw)
+    else
+      HordeGun.clear()
+    end
+  end
+
   local eyes = {}
   for i = 1, 2 do
     local v = views[i]
@@ -339,7 +403,10 @@ local function renderWorld(views, ctl)
   end
 
   -- the snap's fade, over the finished eyes: plain black at this moment's
-  -- strength, drawn before the blit so the headset never sees the swap
+  -- strength, drawn before the blit so the headset never sees the swap.
+  -- A full-frame fill is the ONE 2D thing that is safe to draw into an
+  -- eye buffer -- it covers everything, so it does not matter that the
+  -- two frusta disagree about where any given pixel points.
   if fadeAlpha > 0 then
     pcall(function()
       for i = 1, 2 do
@@ -501,9 +568,25 @@ local function driveControls(ctl, dt, fp)
   if not (ok and Game.input) then return end
   local inp = Game.input
 
-  setGB(inp, "a", ctl.a)
-  setGB(inp, "b", ctl.b)
-  setGB(inp, "start", ctl.start)
+  -- HORDE MODE re-reads the right hand as a weapon: the trigger fires
+  -- (its own OpenXR action, suggested alongside START on the same input
+  -- -- see VRXR.setupInput), and B reloads. START is dropped rather than
+  -- forwarded, because the mode does not pause. Everything else -- the
+  -- stick's walk, the snap turn, A -- keeps working, so the player can
+  -- still move and look while they are being chased.
+  local Horde = V.require("Horde")
+  if Horde.playing() then
+    local Gun = V.require("HordeGun")
+    if ctl.fireChanged and ctl.fire then Gun.fire() end
+    if ctl.bChanged and ctl.b then Gun.reload() end
+    setGB(inp, "a", ctl.a)
+    setGB(inp, "b", false)
+    setGB(inp, "start", false)
+  else
+    setGB(inp, "a", ctl.a)
+    setGB(inp, "b", ctl.b)
+    setGB(inp, "start", ctl.start)
+  end
 
   -- the left stick, through the engine's OWN stick handler: it quantises
   -- to the grid d-pad for the diorama, and FirstPerson.moveVector reads
@@ -512,12 +595,32 @@ local function driveControls(ctl, dt, fp)
   inp:gamepadaxis(nil, "leftx", ctl.moveX or 0)
   inp:gamepadaxis(nil, "lefty", -(ctl.moveY or 0))
 
-  if ctl.toggleChanged and ctl.toggle then VR.stepView() end
+  -- the left stick click: the VOXEL ladder ordinarily, and the way out of
+  -- horde mode while it runs (the rung is locked there, so the click has
+  -- nothing else to do, and a headset has no ESCAPE key)
+  if ctl.toggleChanged and ctl.toggle then
+    if Horde.active then Horde.askExit() else VR.stepView() end
+  end
 
-  -- first person's snap turn: a flick of the right stick steps the view
-  -- 45 degrees, once per flick -- it re-arms only when the stick comes
-  -- back toward centre, so holding it turns exactly once
-  if fp and camMode ~= "battle" then
+  -- first person's turn on the right stick. SMOOTH TURN ON makes it a
+  -- rate -- hold and the world rotates under you -- and OFF (the
+  -- default) makes it a 45-degree snap per flick: see the row's own
+  -- reasoning where it is declared. Either way the offset turns the
+  -- MAPPING, so the eyes, the walk direction, the pokedex and the gun
+  -- all agree about which way the world now faces.
+  if fp and camMode ~= "battle" and VR.smoothTurn:get() == true then
+    local sx = ctl.lookX or 0
+    local a = math.abs(sx)
+    if a > 0.2 then
+      a = (a - 0.2) / 0.8
+      -- increasing yaw turns LEFT in this mod's compass, so a stick
+      -- pushed right subtracts -- the same sign the snap below uses
+      fpYawOff = wrapPi(fpYawOff
+                        - (sx > 0 and 1 or -1) * a * a
+                          * VR.SMOOTH_TURN_RATE * (dt or 0))
+    end
+    snapArmed = true       -- so a switch back to snap mid-flick re-arms
+  elseif fp and camMode ~= "battle" then
     local sx = ctl.lookX or 0
     if math.abs(sx) > 0.65 then
       if snapArmed then
@@ -675,6 +778,8 @@ function VR.invalidate()
   if dexCanvas and dexCanvas.release then pcall(dexCanvas.release, dexCanvas) end
   dexCanvas = nil
   Pokedex.invalidate()
+  V.require("HordeGun").invalidate()
+  V.require("HordeHud").invalidate()
   for k in pairs(fboCache) do fboCache[k] = nil end
 end
 

lib/VRXR.lua

@@ -528,6 +528,18 @@ local function setupInput()
     gripr = makeAction(set, "grip_r", XR.ACTION_TYPE_FLOAT, "Right Grip"),
     handl = makeAction(set, "hand_l", XR.ACTION_TYPE_POSE, "Left Hand"),
     handr = makeAction(set, "hand_r", XR.ACTION_TYPE_POSE, "Right Hand"),
+    -- HORDE MODE's two. `fire` is bound ALONGSIDE start on the right
+    -- trigger rather than instead of it: bindings are suggested once,
+    -- before the session attaches its action sets, so they cannot be
+    -- swapped when the mode starts -- and OpenXR is happy for two actions
+    -- to share an input. Outside the mode nothing reads `fire`, so the
+    -- trigger is START exactly as it always was; inside it, lib/VR reads
+    -- `fire` and drops START on the floor (there is no pausing anyway).
+    -- `aimr` is the pose a runtime defines as "where the user is
+    -- pointing", which is what a gun wants -- the grip pose points along
+    -- the controller's own body, which is a wrist, not a barrel.
+    fire = makeAction(set, "fire", XR.ACTION_TYPE_BOOLEAN, "Fire"),
+    aimr = makeAction(set, "aim_r", XR.ACTION_TYPE_POSE, "Right Aim"),
   }
 
   local function suggest(profile, list)
@@ -560,6 +572,8 @@ local function setupInput()
     { A.gripr, "/user/hand/right/input/squeeze/value" },
     { A.handl, "/user/hand/left/input/grip/pose" },
     { A.handr, "/user/hand/right/input/grip/pose" },
+    { A.fire, "/user/hand/right/input/trigger/value" },
+    { A.aimr, "/user/hand/right/input/aim/pose" },
   }
   -- Index has X/Y on no hand -- its A/B exist on BOTH -- so the two X/Y
   -- rows are swapped for left A/B there
@@ -582,6 +596,8 @@ local function setupInput()
     { A.gripr, "/user/hand/right/input/squeeze/click" },
     { A.handl, "/user/hand/left/input/grip/pose" },
     { A.handr, "/user/hand/right/input/grip/pose" },
+    { A.fire, "/user/hand/right/input/trigger/value" },
+    { A.aimr, "/user/hand/right/input/aim/pose" },
   })
   pcall(suggest, "/interaction_profiles/khr/simple_controller", {
     { A.a, "/user/hand/right/input/select/click" },
@@ -599,7 +615,11 @@ local function setupInput()
     check(xr.xrCreateActionSpace(session, info, out), "xrCreateActionSpace")
     return out[0]
   end
+  -- the aim pose gets a space of its own; a runtime that refused the
+  -- binding simply never locates it, and the gun falls back to the grip
   local spaces = { handl = handSpace(A.handl), handr = handSpace(A.handr) }
+  local okAim, aimSpace = pcall(handSpace, A.aimr)
+  if okAim and aimSpace then spaces.aimr = aimSpace end
 
   local sets = ffi.new("XrActionSet[1]")
   sets[0] = set
@@ -660,6 +680,7 @@ function VRXR.input(time)
     o.b, o.bChanged = readBool(A.b)
     o.start, o.startChanged = readBool(A.start)
     o.toggle, o.toggleChanged = readBool(A.toggle)
+    o.fire, o.fireChanged = readBool(A.fire)
     o.gripL = readFloat(A.gripl)
     o.gripR = readFloat(A.gripr)
 

lib/Voxel3D.lua

@@ -33,6 +33,7 @@ local WorldCurve = V.require("WorldCurve")
 local Sky = V.require("Sky")
 local DayNight = V.require("DayNight")
 local GlassMask = V.require("GlassMask")
+local PixelCanvas = V.require("PixelCanvas")
 
 local Voxel3D = {}
 
@@ -820,7 +821,7 @@ function Voxel3D.beginScene(w, h, cx, cy, vw, vh, sky, slot)
   local name = slot or "world"
   local slotHeld = slots[name]
   if not (slotHeld and slotHeld.w == w and slotHeld.h == h) then
-    local ok, c = pcall(love.graphics.newCanvas, w, h)
+    local ok, c = PixelCanvas.new(w, h)
     if not ok then return false end
     c:setFilter("nearest", "nearest")
     if slotHeld then releaseSlot(slotHeld) end

lib/VoxelScene.lua

@@ -226,8 +226,16 @@ end
 -- 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.
+-- The player's own card asks a different function for the same answer:
+-- their body's bearing is what the camera is derived FROM, so it is known
+-- continuously rather than as one of four directions, and measuring
+-- against the compass point instead flicks the card to a profile for a
+-- frame or two when the camera is spun fast (see playerFacing).
 local function viewFacing(p)
   if FirstPerson.cardBlend() > 0.5 then
+    if p.isPlayer then
+      return FirstPerson.playerFacing(p.facing, p.px + 8, p.py + 8)
+    end
     return FirstPerson.apparentFacing(p.facing, p.px + 8, p.py + 8)
   end
   return p.facing
@@ -1130,6 +1138,23 @@ function VoxelScene.render(state, w, h, vw, vh, paletteFor, eyes)
     Voxel3D.glass(true)
   end
 
+  -- HORDE MODE's handgun, in the same slot and for the same reasons: a
+  -- prop over the world with real depth, no wireframe and no glass. In VR
+  -- it rides the tracked right hand (lib/VR placed it this frame); on the
+  -- flat screen it is carried by the camera, which is why it draws here
+  -- rather than in the overlay -- a view model that is 2D cannot be
+  -- occluded by the wall the player just backed into.
+  do
+    local HordeGun = V.require("HordeGun")
+    if HordeGun.visible() then
+      Voxel3D.glass(false)
+      Voxel3D.seams(false)
+      HordeGun.draw()
+      Voxel3D.seams(true)
+      Voxel3D.glass(true)
+    end
+  end
+
   end   -- drawScene
 
   if not eyes then

lib/VoxelState.lua

@@ -33,17 +33,18 @@ local Voxel = {}
 -- 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.
 --
--- 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 }
+-- 1ST and 3RD are the other rungs that are more than an angle: the camera
+-- steps off its orbit entirely and stands with the player -- in their eyes
+-- (lib/FirstPerson.lua), or on a boom behind their shoulder
+-- (lib/ThirdPerson.lua) -- with free look and free movement on both. Their
+-- ANGLE entries are 75 -- the orbit rung they hand over from -- because the
+-- tween in and out 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 free-roam rig owns the actual camera.
+Voxel.ANGLES_DEG = { 0, 35, 15, 35, 50, 75, 75, 75 }
 Voxel.ANGLE_LABELS = { "OFF", "FULL", "15", "35", "50", "75",
-                       "1ST (EXPERIMENTAL)" }
+                       "1ST (EXPERIMENTAL)", "3RD (EXPERIMENTAL)" }
 Voxel.MAX_LEVEL = #Voxel.ANGLES_DEG - 1
 
 -- the rung FULL sits on, so nothing has to hunt for it by label
@@ -60,6 +61,23 @@ function Voxel.isFirstPerson(level)
   return (level or Voxel.level) == Voxel.FP_LEVEL
 end
 
+-- and the third-person one, which is the same rig with the eye boomed off
+-- the back of the head (lib/ThirdPerson.lua)
+Voxel.TP_LEVEL = 7
+
+function Voxel.isThirdPerson(level)
+  return (level or Voxel.level) == Voxel.TP_LEVEL
+end
+
+-- The two of them together: the rungs where the camera stands WITH the
+-- player rather than orbiting the view centre, which is what decides that
+-- the look inputs are read, the walk goes free and the cards turn to face
+-- the eye. Everything that used to ask isFirstPerson for those asks this.
+function Voxel.isFreeCam(level)
+  level = level or Voxel.level
+  return Voxel.isFirstPerson(level) or Voxel.isThirdPerson(level)
+end
+
 -- ------- what the hotkey walks
 --
 -- The ANGLE rungs only, with FULL left out. The key is a display-mode
@@ -69,11 +87,11 @@ end
 -- 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.
 --
--- 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
+-- 1ST and 3RD are on the path: they change the camera and only the camera,
+-- which is exactly what the key promises -- and the key is also the way back
+-- OUT of them 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
+Voxel.HOTKEY_ORDER = { 0, 2, 3, 4, 5, 6, 7 }  -- OFF,15,35,50,75,1ST,3RD
 
 -- The rung a press moves to from `level`.
 --

main.lua

@@ -24,10 +24,11 @@
 -- below.  This file declares; lib/ draws.
 --
 -- Voxel mode is presentational: it changes what the world LOOKS like and
--- nothing about what it IS.  ONE rung is the deliberate exception. 1ST --
--- 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.
+-- nothing about what it IS.  TWO rungs are the deliberate exception. 1ST
+-- (the camera in the player's own eyes) and 3RD (the same rig, boomed back
+-- behind their shoulder) replace the grid WALK with a free,
+-- camera-relative one while either is selected (lib/FreeMove.lua), because
+-- a camera you can steer with a mouse demands feet that go where it looks.
 -- Even there the game is untouched: the walk asks the engine's own
 -- collision the same questions a grid step asks, keeps the player's
 -- logical cell synced, and fires the engine's own landing pipeline per
@@ -92,7 +93,15 @@ local Water = V.require("Water")
 local AntiAlias = V.require("AntiAlias")
 local FirstPerson = V.require("FirstPerson")
 local FreeMove = V.require("FreeMove")
+local CamControl = V.require("CamControl")
 local VR = V.require("VR")
+-- HORDE MODE: the konami code's minigame. Horde owns the state machine and
+-- every hook; the other four are the gun, the crowd, the readout and the
+-- chip-synthesized sounds it fires. See lib/Horde.lua for the whole design.
+local Horde = V.require("Horde")
+local HordeGun = V.require("HordeGun")
+local HordeHud = V.require("HordeHud")
+local HordeSfx = V.require("HordeSfx")
 
 -- Forward declaration: the voxel pipeline's update hook (registered below)
 -- calls this, and it is defined further down with the settings it drives.
@@ -191,6 +200,12 @@ mod.content.render_pipelines:register("voxel", {
     -- and the whole battle. Ahead of the active() gate below, because a 3D
     -- battle does not require the free-roam mode to be switched on.
     OverworldBattle.update(dt)
+    -- The horde, on the same always-running tick and for the same reason:
+    -- it owns no pass of the frame, it is a MODE over the overworld, and
+    -- it has to keep thinking while a warp's wipe covers the screen (the
+    -- crowd follows the player through the door) and under the GAME OVER
+    -- card, which is a pushed state that stops everything below it.
+    Horde.update(dt)
     -- VOID FILL picks the block the border ring is made of, and in this
     -- mode that ring is BAKED INTO THE MESH rather than drawn each frame.
     -- So the option has to reach the cache or nothing happens on screen
@@ -256,6 +271,12 @@ mod.content.render_pipelines:register("voxel", {
       -- pixels, so only the scale needs saying.
       ctx.drawFx(function(wx, wy) return Voxel3D.project(wx, 0, wy) end,
                  ctx.scale * AntiAlias.factor())
+      -- the horde's readout rides the same overlay, over the FX: health,
+      -- ammunition, the crosshair and the banners, sized in the same
+      -- supersampled canvas pixels everything else here is drawn in. A
+      -- headset never reaches this line (drawWorld returns the mirror
+      -- above) -- lib/VR draws the same HUD onto each eye instead.
+      HordeHud.drawFlat(rw, rh, ctx.scale * AntiAlias.factor())
       Voxel3D.endOverlay()
     end
     -- and back to the window's own size, which is what the engine composites
@@ -445,14 +466,25 @@ local SETTINGS = {
     -- says why); off Windows -- mobile above all -- there is no VR to have
     -- and the row does not exist
     when = function() return VR.supported() end, full = true },
+  -- Under the VR row and only while it is ON: a comfort setting for a
+  -- device that is not plugged in decides nothing, and this one is read
+  -- exclusively by the headset's right stick.
+  { VR.smoothTurn,
+    "Turn smoothly with the right stick instead of snapping 45 degrees a "
+    .. "flick. OFF by default, and deliberately: a software turn moves the "
+    .. "world past a head that did not move, which is the most reliable way "
+    .. "to make somebody ill in a headset. Turn it on if you have your sea "
+    .. "legs and want the continuity.",
+    when = function() return VR.enabled() end, full = true },
 }
 
 local schema = {}
 for _, entry in ipairs(SETTINGS) do
-  -- the VR row is absent from the mod manager's page too where the
+  -- the VR rows are absent from the mod manager's page too where the
   -- platform cannot do VR at all -- the OPTIONS menu's `when` gates are
   -- situational (a row hidden for now), this one is existential
-  if entry[1] ~= VR.setting or VR.supported() then
+  local vrOnly = entry[1] == VR.setting or entry[1] == VR.smoothTurn
+  if not vrOnly or VR.supported() then
     schema[#schema + 1] = entry[1]:schema(entry[2])
   end
 end
@@ -507,6 +539,11 @@ local HOTKEYS = {
 -- the key has always delegated (see the wrap below for why).
 local function cycleVoxel(game)
   local Pipelines = require("src.render.Pipelines")
+  -- HORDE MODE holds the rung at 1ST for as long as it runs. Refused HERE
+  -- rather than at each caller because this one function IS every way a
+  -- player can step the ladder: the "3" key, the pad's SELECT, and the VR
+  -- left-stick click all come through it.
+  if Horde.viewLocked() then return false end
   local top = game.stack and game.stack:top()
   if not Pipelines.canToggle("voxel", top, game.overworld) then return false end
   Pipelines.setLevel("voxel", Voxel.nextHotkeyLevel(Pipelines.level("voxel")))
@@ -535,8 +572,29 @@ do
   local inner = Game.keypressed
 
   function Game:keypressed(key)
+    -- HORDE MODE owns the keyboard's spare keys while it runs: R reloads,
+    -- and the mode keys are swallowed rather than left to change the rung
+    -- or the post-processing out from under a locked camera.
+    if Horde.active then
+      if key == "r" then
+        HordeGun.reload()
+        return
+      end
+      if HOTKEYS[key] then return end
+    end
     local claim = HOTKEYS[key]
     local top = self.stack and self.stack:top()
+    -- Q and E work whichever camera is in front of the player -- the
+    -- battle's lens, the third-person boom, or the engine's own survey
+    -- zoom on an orbit rung. CamControl answers which, and answers "none"
+    -- for 1ST and for every screen with no camera of ours behind it, in
+    -- which case the key falls through untouched. Ahead of the hotkey
+    -- table because unlike those it is NOT free-roam only: a staged battle
+    -- is exactly where the zoom is most wanted.
+    if (key == "q" or key == "e")
+       and not (top and top.onKeyPressed) then
+      if CamControl.zoomBy(key == "q" and 1 or -1) then return end
+    end
     -- A screen with its own key handler gets the key first, exactly as the
     -- engine's first branch does: typing a nickname must not toggle a
     -- render mode. Only free-roam presses are ours to take.
@@ -633,6 +691,25 @@ end
 --
 -- Everything they did is still reachable: uninstall the mod and both rows are
 -- back, at whatever they were last set to.
+-- BATTLE BG rides the same reasoning, and comes off for a reason of its own.
+-- The row picks what fills the screen AROUND the battle's 160x144 field --
+-- WHITE paper, BLACK bars, or the frozen overworld dimmed behind it -- and
+-- all three were answers to the same question: what to do with the voids,
+-- given the battle is a small picture in the middle of a big window.
+--
+-- This mod answers that question differently and permanently. A staged fight
+-- fills the whole window with the map the fight is standing on, and the
+-- flat battle screen it composites over it is drawn on the mode's own
+-- surface; there are no voids left for the row to fill. WORLD is the worst
+-- of the three under it -- it makes the battle non-opaque so the engine
+-- draws the overworld underneath, which is a SECOND copy of the world drawn
+-- under the one the arena pass already put there, dimmed and at a different
+-- camera. BLACK bars over a diorama read as a letterboxed screenshot.
+--
+-- So the value is pinned at WHITE, which is the one the mode was composed
+-- against, and the row comes off the menu on the same reasoning as TILT and
+-- GBC FX: a row that no longer decides anything is worse than no row.
+-- Uninstall the mod and it is back, at whatever it was last set to.
 local function pinEngineFx(game)
   game = game or require("src.core.Game")
   local opts = game and game.save and game.save.options
@@ -641,7 +718,9 @@ local function pinEngineFx(game)
   local changed = false
   if opts then
     changed = (opts.tilt or 0) ~= 0 or (opts.gbcfx or 0) ~= 0
+                or (opts.battleBg or "white") ~= "white"
     opts.tilt, opts.gbcfx = 0, 0
+    opts.battleBg = "white"
   end
   pcall(Tilt.setLevel, 0)
   pcall(GBCFX.setLevel, 0)
@@ -659,6 +738,10 @@ mod.hooks:wrap("ui.options.rows", function(next, game, rows)
   pinEngineFx(game)
   dropRow(out, "tilt")
   dropRow(out, "gbcfx")
+  -- and BATTLE BG with them: this mode fills the window with the map, so
+  -- the row's whole question -- what to put in the voids around the battle
+  -- -- no longer has voids to be about (see pinEngineFx)
+  dropRow(out, "battleBg")
   -- BATTLE LAYOUT is the ENGINE's row, and this is the one place the mod takes
   -- one away. While a fight can be staged on the map, OG is the only layout it
   -- can be composed in (OverworldBattle.forceOG), so the value is pinned there
@@ -860,9 +943,11 @@ end
 -- so this file keeps naming every engine seam the mod touches.
 OverworldBattle.install()
 
--- ------- the first-person rung's inputs and its walk
+-- ------- the free-roam rungs' inputs and their walk
 --
--- 1ST needs two things no other rung does, and each is a named seam:
+-- 1ST and 3RD need two things no other rung does, and each is a named seam.
+-- Both rungs are one rig -- the boom behind the shoulder is a number inside
+-- it (lib/ThirdPerson.lua) -- so both are installed by the same two calls:
 --
 -- FirstPerson.install claims the LOOK inputs the engine ignores: the right
 -- stick's axes (Game:gamepadaxis passes them to Input, which returns early
@@ -874,11 +959,11 @@ OverworldBattle.install()
 -- 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.
+-- only while one of the two rungs 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
+-- Cycling Road pull lives behind. While either 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
@@ -886,6 +971,17 @@ OverworldBattle.install()
 FirstPerson.install()
 FreeMove.install()
 
+-- ------- the zooms, and the battle camera the player can steer
+--
+-- CamControl claims the wheel, Q/E, the mouse and the touch screen for
+-- whichever camera is actually in front of the player -- the staged
+-- battle's, the third-person boom, or the engine's own survey zoom -- and
+-- forwards everything else. Installed AFTER the two above deliberately: a
+-- wrap installed later is the OUTER one, so a fight gets first refusal on
+-- the mouse and the fingers, which is right, because while one is staged
+-- the free-roam look is not driving.
+CamControl.install()
+
 -- ------- SELECT walks the angle ladder
 --
 -- The same step the "3" key makes, on the pad's own button: a phone (and
@@ -918,6 +1014,15 @@ do
   end
 end
 
+-- ------- the konami code, and everything it turns on
+--
+-- Installed last of the input seams so its handleInput reasoning sits
+-- outside FreeMove's and SELECT's. The detector itself does not live on
+-- handleInput at all -- it reads the fixed step's own press queue, which
+-- is where keyboard, pad, touch and the VR controllers have all already
+-- become the same eight buttons. See lib/Horde.lua.
+Horde.install()
+
 -- ------- edge-anchored menus stay in the GB frame while a headset is live
 --
 -- The engine's zoom-aware anchoring (Renderer:setUIAnchor) docks the START
@@ -1044,7 +1149,7 @@ mod.hooks:wrap("world.tod", function(next, tod, ctx)
   return DayNight.tod()
 end)
 
-mod.exports.version = "1.5.2"
+mod.exports.version = "1.5.5"
 -- 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

manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "DRAMATIC_SHAPE",
   "name": "Dramatic Shape Voxel Mod",
-  "version": "1.5.2",
+  "version": "1.5.5",
   "api": 2,
   "entry": "main.lua",
   "profile": "content",

mod.card

@@ -17,13 +17,19 @@ return {
       "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 those two, which have no key and no row while this is loaded",
       "SELECT in free roam steps the VOXEL ladder exactly as hotkey 3 does -- the button has no overworld job in Gen 1, and phones and pads have no number row; menus keep it untouched",
-      "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",
+      "on the 1ST and 3RD rungs 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 and 3RD rungs 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",
+      "on the 3RD rung the character turns to face where they are walking rather than where the camera looks, so a strafe reads as one; standing still they come back round to the camera's bearing, which is the one A talks along",
+      "on 1ST and 3RD the wall-collision sound is gone: a free walk slides along every wall it grazes rather than refusing a discrete step, so the bonk rang twice a second for walking down a corridor",
+      "the BATTLE BG options row is taken OFF the menu and pinned to WHITE for as long as this mod is installed -- the mode fills the window with the map, so the row's own question (what to put in the voids around the battle) has no voids left to be about, and its WORLD setting drew a second dimmed copy of the overworld under the arena; uninstalling puts the row back",
+      "a staged battle's camera can be steered by the player -- right stick, touch drag or mouse to swing it around the arena and raise it, wheel / Q / E / pinch / stick click for the lens -- between the shot the rig was solved for and a side-on view of the arena, and it opens the lens as it goes so both Pokemon stay framed; the angle and lens carry into the next battle",
+      "with BACK SPRITES on the battle camera is held at the solved shot, because that setting pins your own Pokemon to the menu's slot while the foe stands on the map and no angle holds a half-framed, half-solid composition",
     },
     added = {
-      "VOXEL options row and hotkey 3 (OFF / 15 / 35 / 50 / 75 degrees / 1ST, a first-person camera with free look and free movement)",
+      "VOXEL options row and hotkey 3 (OFF / 15 / 35 / 50 / 75 degrees / 1ST / 3RD -- a first-person camera and a third-person one, both 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",
+      "Q and E zoom whichever camera is in front of you -- the third-person boom, a staged battle's lens, or the engine's own survey zoom on an orbit rung -- alongside the mouse wheel, a two-finger pinch, and the pad's left and right stick clicks (out and in). 1ST claims none of them: the eye is in the player's head and there is no distance to change",
       "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",
@@ -33,6 +39,9 @@ return {
       "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",
+      "SMOOTH TURN options row (OFF / ON, off by default, and only on the menu while VR is ON): turn continuously with the right stick instead of snapping 45 degrees a flick. The snap is the default because a software turn moves the world past a head that did not move, which is the reliable way to make somebody ill in a headset -- but it costs continuity, so the choice is the player's",
+      "HORDE MODE, on the konami code (Up Up Down Down Left Right Left Right B A) standing in the overworld: the sky drops to a starless violet night, the Lavender Town theme comes up, the camera locks into the player's own head (in VR too), a voxel handgun with working iron sights appears in the right hand, and waves of people -- the map's own NPCs among them -- walk out of the dark to kill you. Score per kill, a random Pokemon cry for each one that falls, no pausing; the horde follows you through doors. Health out is a GAME OVER card with the score and PRESS A, which puts the map, the cell, the facing, the camera rung, the hour, the music and every NPC back exactly as they were. Fire on left click, the pad's right trigger or B, a tap on a touch screen, or the right trigger in VR; reload on R, the pad's X, or B on the right controller; aim down the sights on right click or the left trigger",
+      "the horde's gunshot, dry fire, magazine and slide sounds, synthesized on the game's own emulated Game Boy sound hardware (no audio files ship with the mod)",
     },
     known = {
       "needs shader and depth-canvas support; without them the rows still cycle but the world stays 2D and battles draw plainly",
@@ -44,8 +53,10 @@ return {
       "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",
+      "1ST and 3RD need 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 and 3RD, 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",
+      "3RD's boom shortens against whatever stands behind the player, so backing into a wall walks the camera in to their shoulders; squeezed all the way in it draws as 1ST until they step clear",
+      "3RD in VR is 1ST in VR: a headset that seats its wearer three cells behind their own body is a well-known way to make people ill, so the boom is declined while a headset is live",
       "rooms have no ceilings, so a first-person look over an interior wall shows the void the diorama always had behind it",
       "VR is Windows x64 only (the shipped loader and the Win32 GL binding): on any other platform -- mobile above all -- the VR row is absent from the OPTIONS menu and the manager's page both, and a stored vr=true carried over in a save is ignored. On Windows it renders the scene once per eye (heavy with WATER FULL or AA up); pad/keyboard/mouse keep working alongside the XR controllers. The loader DLL is found wherever the mod was put -- the dev tree, an installed release's save directory, or an imported archive, from which it is copied once into the save directory so the FFI has a real disk path",
       "VR on and off are both the VR row's job (options menu or manager); no controller button does either",
@@ -53,6 +64,9 @@ return {
       "while the VR row is ON, 3D-BTL is held ON and BACK SPRITES held OFF (the headset's battle staging assumes both), and both rows leave the OPTIONS menu until VR goes off -- their stored values come back with them",
       "while a headset is live the battle HUDs keep their classic in-frame slots instead of snapping to the window's edges, and the engine's edge-anchored menus (the START menu above all) are held inside the frame the same way, on the flat mirror too -- both VR screens crop to the GB frame, and a block at the window's edge would be cropped away with it",
       "VR swapchains prefer plain RGBA8; a runtime that only offers sRGB shows slightly lifted colours",
+      "HORDE MODE needs the 3D pass, like every rung that has a camera in it: without one the code is refused and nothing happens",
+      "the horde's crowd are the overworld's own sprite billboards, so at close range they are flat cards the size of a person -- they hold two cells off the player for that reason, close enough to swing and far enough to be seen past",
+      "a run is not saved: the score and the best score ride the save slot, but the mode itself has no state to resume, and quitting mid-run simply ends it",
     },
   },
   credits = {

tests/cam_shots.lua

@@ -0,0 +1,211 @@
+-- Scratch driver: the cameras the player steers -- the third-person boom's
+-- zoom, and the battle shot's orbit, climb and lens, including the far
+-- stops (side-on, 45 degrees up) and what BACK SPRITES takes away.
+--
+--   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/cam_shots.lua \
+--   SHOT_DIR=.scratchpad/camshots 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/cam")
+
+  local handle = game.mods.exports["DRAMATIC_SHAPE"]
+  if not (handle and handle.lib) then
+    print("[cam] DRAMATIC_SHAPE mod not loaded")
+    return love.event.quit()
+  end
+  local V = handle.lib
+  local FirstPerson = V.require("FirstPerson")
+  local ThirdPerson = V.require("ThirdPerson")
+  local BattleCam = V.require("BattleCam")
+  local OverworldBattle = V.require("OverworldBattle")
+  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
+  -- The flower's animation frame, pinned per shot rather than left to the
+  -- clock: the mesh spans the union of every frame and each one is cut back
+  -- out in texture space, so a gap that only opens on frame 2 is invisible
+  -- to a driver that always photographs frame 0 -- which is exactly how the
+  -- first cut of the closed sides shipped looking correct.
+  local ANIM = { frame = 0 }
+  TileRenderer.animFrame = function() return ANIM.frame end
+  DayNight.setting:sync("day")
+
+  local function settle()
+    for _ = 1, 900 do
+      if ChunkMesher.pending() == 0 then break end
+      U.wait(1)
+    end
+    U.wait(40)
+  end
+
+  local shots = 0
+  local function shot(name)
+    if U.shot(game, ("%s/%s.png"):format(ROOT, name)) then
+      shots = shots + 1
+    end
+  end
+
+  -- ------- the boom's zoom
+  U.teleport(game, "PALLET_TOWN", 13, 14, "down")
+  Pipelines.setLevel("voxel", Voxel.TP_LEVEL)
+  Pipelines.setLevel("tiltshift", 0)
+  settle()
+  for _ = 1, 200 do
+    if FirstPerson.blend >= 1 then break end
+    U.wait(1)
+  end
+  FirstPerson.yaw = math.pi
+  U.wait(20)
+  for _, z in ipairs({ "min", "default", "max" }) do
+    ThirdPerson.zoomGoal = (z == "min" and ThirdPerson.ZOOM_MIN)
+                           or (z == "max" and ThirdPerson.ZOOM_MAX) or 1
+    for _ = 1, 90 do U.wait(1) end
+    print(("[cam] boom %-8s zoom %.2f  len %.1f"):format(z, ThirdPerson.zoom,
+                                                        ThirdPerson.len))
+    shot("boom_" .. z)
+  end
+  ThirdPerson.zoomGoal = 1
+  U.wait(60)
+
+  -- ------- the standees' closed sides
+  --
+  -- Pallet's flower beds and Route 1's tall grass, from a low camera close
+  -- in -- the angle that showed the slabs were open at the ends of every
+  -- run and let you see straight through them.
+  ThirdPerson.zoomGoal = ThirdPerson.ZOOM_MIN
+  for _, s in ipairs({
+    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi,
+      pitch = math.rad(6), label = "flowers_low" },
+    { map = "PALLET_TOWN", x = 13, y = 14, yaw = 3 * math.pi / 4,
+      pitch = math.rad(30), label = "flowers_angled" },
+    { map = "ROUTE_1", x = 10, y = 28, yaw = math.pi,
+      pitch = math.rad(8), label = "grass_low" },
+  }) do
+    U.teleport(game, s.map, s.x, s.y, "down")
+    settle()
+    FirstPerson.yaw, FirstPerson.pitch = s.yaw, s.pitch
+    U.wait(60)
+    -- EVERY animation frame, because a gap the union closed and a frame
+    -- reopens is only visible on that frame
+    for f = 0, 3 do
+      ANIM.frame = f
+      U.wait(6)
+      shot(("%s_f%d"):format(s.label, f))
+    end
+    ANIM.frame = 0
+  end
+  ThirdPerson.zoomGoal = 1
+  U.wait(60)
+
+  -- ------- the battle shot
+  --
+  -- Staged the way the game stages one, then steered to each stop with the
+  -- module's own entry points -- the same ones the wheel, the stick and a
+  -- drag reach.
+  Pipelines.setLevel("voxel", 4)
+  U.wait(60)
+  do
+    -- Somebody to fight WITH: a fresh driver save has an empty party, and
+    -- a trainer battle with nobody to send out ends on the frame it starts
+    -- -- which is what made every steered shot below sample a dead session.
+    local Pokemon = require("src.pokemon.Pokemon")
+    game.save.party = {
+      Pokemon.new(game.data, "CHARIZARD", 45),
+      Pokemon.new(game.data, "PIKACHU", 40),
+    }
+    game.save.player.name = "RED"
+    local BattleState = require("src.battle.BattleState")
+    local class = next(game.data.trainers)
+    local battle = BattleState.newTrainer(game, class, 1)
+    battle.onFinish = function() end
+    game.overworld:pushBattle(battle)
+  end
+  -- The wipe, then just enough of the send-out chatter to get both mons
+  -- standing on the arena -- and NOT one tap more. A is also FIGHT and then
+  -- the first move, so tapping past the intro starts an exchange and the
+  -- fight can be over before the camera has been steered anywhere.
+  U.wait(70)
+  for _ = 1, 40 do
+    if OverworldBattle.shot() then break end
+    U.tap(game, "a")
+    U.wait(10)
+  end
+  U.wait(60)
+  print(("[cam] staged: arena %s  shot %s  top %s")
+        :format(tostring(OverworldBattle.arena() ~= nil),
+                tostring(OverworldBattle.shot() ~= nil),
+                tostring(game.stack:top() ~= game.overworld)))
+  if not OverworldBattle.shot() then
+    print("[cam] no staged battle -- skipping the battle shots")
+    print(("[cam] %d shots into %s"):format(shots, ROOT))
+    return love.event.quit()
+  end
+
+  local function settleCam(label)
+    for _ = 1, 120 do U.wait(1) end
+    print(("[cam] battle %-20s orbit %.2f/%.2f  pitch %.2f/%.2f  "
+           .. "zoom %.2f/%.2f  steerable %s  live %s")
+          :format(label, BattleCam.orbit, BattleCam.orbitGoal,
+                  BattleCam.pitch, BattleCam.pitchGoal,
+                  BattleCam.zoom, BattleCam.zoomGoal,
+                  tostring(BattleCam.steerable),
+                  tostring(OverworldBattle.shot() ~= nil)))
+    shot("battle_" .. label)
+  end
+
+  BattleCam.recentre()
+  settleCam("home")
+
+  -- right to the stop: this must land SQUARE to the arena's axis
+  BattleCam.dragOrbit(10)
+  settleCam("side_on")
+
+  -- and there is nothing to the left of home
+  BattleCam.recentre()
+  BattleCam.dragOrbit(-10)
+  settleCam("left_stop")
+
+  -- up to the stop, and refusing to go below home
+  BattleCam.recentre()
+  BattleCam.dragPitch(10)
+  settleCam("high")
+  BattleCam.recentre()
+  BattleCam.dragPitch(-10)
+  settleCam("low_stop")
+
+  -- the lens at both ends
+  BattleCam.recentre()
+  for _ = 1, 40 do BattleCam.stepZoom(-1) end
+  settleCam("zoom_in")
+  BattleCam.recentre()
+  for _ = 1, 40 do BattleCam.stepZoom(1) end
+  settleCam("zoom_out")
+
+  -- everything at once, which is the shot a player would actually build
+  BattleCam.recentre()
+  BattleCam.dragOrbit(0.55)
+  BattleCam.dragPitch(0.5)
+  for _ = 1, 4 do BattleCam.stepZoom(-1) end
+  settleCam("steered")
+
+  -- What BACK SPRITES takes away is NOT shot here: the flag it works
+  -- through is re-derived from the row every frame
+  -- (OverworldBattle.update), so a driver cannot hold it down for the
+  -- hundred-odd frames a settled shot needs, and a picture that claimed to
+  -- show a locked camera while the camera was in fact free would be worse
+  -- than no picture. The suite asserts it instead, on both axes and the
+  -- lens, and on the RIG as well as on the inputs.
+  BattleCam.recentre()
+
+  print(("[cam] %d shots into %s"):format(shots, ROOT))
+  love.event.quit()
+end

tests/dramatic_shape_test.lua

@@ -49,14 +49,16 @@ T.eq(defs._owners and defs._owners.voxel, "DRAMATIC_SHAPE",
 
 -- ------- the ladders the engine drives
 
-T.eq(#defs.voxel.levels, 7, "voxel exposes a seven-rung ladder")
+T.eq(#defs.voxel.levels, 8, "voxel exposes an eight-rung ladder")
 T.eq(defs.voxel.levels[1], "OFF", "rung 0 is OFF")
 T.eq(defs.voxel.levels[2], "FULL",
   "FULL is the first rung after OFF -- the order those two get used in")
 T.eq(defs.voxel.levels[6], "75", "rung 5 is the 75-degree camera")
 T.eq(defs.voxel.levels[7], "1ST (EXPERIMENTAL)",
-  "the top rung is the first-person camera, labelled as the experiment it is")
-T.eq(Pipelines.maxLevel("voxel"), 6, "the engine reads the ladder height")
+  "rung 6 is the first-person camera, labelled as the experiment it is")
+T.eq(defs.voxel.levels[8], "3RD (EXPERIMENTAL)",
+  "and the top rung is the third-person one, labelled the same way")
+T.eq(Pipelines.maxLevel("voxel"), 7, "the engine reads the ladder height")
 T.eq(Pipelines.levelLabel("voxel", 3), "35", "the engine reads the rung labels")
 
 -- ------- gating: inert until switched on, and inert without a GPU
@@ -1084,12 +1086,14 @@ local Curve = run.loader.exports.DRAMATIC_SHAPE.lib.require("WorldCurve")
 -- with nothing on screen saying a keypress had done it.
 Pipelines.setLevel("voxel", 0)
 local walk = {}
-for _ = 1, 7 do
+for _ = 1, 8 do
   Game.keypressed(keyGame, "3")
   walk[#walk + 1] = Pipelines.levelLabel("voxel")
 end
-T.eq(table.concat(walk, ","), "15,35,50,75,1ST (EXPERIMENTAL),OFF,15",
-  "3 walks OFF -> 15 -> 35 -> 50 -> 75 -> 1ST and wraps, never touching FULL")
+T.eq(table.concat(walk, ","),
+  "15,35,50,75,1ST (EXPERIMENTAL),3RD (EXPERIMENTAL),OFF,15",
+  "3 walks OFF -> 15 -> 35 -> 50 -> 75 -> 1ST -> 3RD and wraps, never "
+  .. "touching FULL")
 
 -- FULL is 35 degrees, so a press from it goes ON to 50 rather than back to
 -- the rung that shows the same camera -- the key never appears to do nothing.
@@ -1176,8 +1180,8 @@ T.eq(GBCFX.level, 0, "and on the live renderer")
 -- TILT with or without us. Park the ladder on its top rung and turn both
 -- back on, so the single press under test is the one that wraps to OFF --
 -- where nothing else is going to clear them.
--- 6 is the "1ST" rung, the last one the key walks before it wraps to OFF
-Pipelines.setLevel("voxel", 6)
+-- 3RD is the last rung the key walks before it wraps to OFF
+Pipelines.setLevel("voxel", VoxelState.TP_LEVEL)
 Tilt.setLevel(3)
 GBCFX.setLevel(4)
 keyGame.save.options.tilt = 3
@@ -3674,6 +3678,440 @@ FirstPerson.blend = 0
 VoxelState.reset()
 end
 
+-- ------- the third-person rung
+--
+-- 3RD is 1ST with the eye on a boom, so what the suite has to hold still is
+-- the boom: where it stands the eye behind a pivot, the march through the
+-- world that shortens it when something is in the way, and the two things
+-- its extension decides that 1ST decides the other way -- the player's own
+-- card being drawn, and the body turning to face where it walks.
+
+do
+local FirstPerson =
+  run.loader.exports.DRAMATIC_SHAPE.lib.require("FirstPerson")
+local ThirdPerson =
+  run.loader.exports.DRAMATIC_SHAPE.lib.require("ThirdPerson")
+local VoxelState = run.loader.exports.DRAMATIC_SHAPE.lib.require("VoxelState")
+local Voxel3D = run.loader.exports.DRAMATIC_SHAPE.lib.require("Voxel3D")
+
+T.eq(VoxelState.TP_LEVEL, 7, "3RD is the eighth rung")
+T.check(VoxelState.isThirdPerson(7), "and isThirdPerson answers for it")
+T.check(not VoxelState.isThirdPerson(6), "but not for 1ST")
+T.check(VoxelState.isFreeCam(6) and VoxelState.isFreeCam(7),
+  "both rungs that stand the camera with the player answer isFreeCam")
+T.check(not VoxelState.isFreeCam(5), "the 75-degree orbit does not")
+T.eq(VoxelState.ANGLE_LABELS[VoxelState.TP_LEVEL + 1], "3RD (EXPERIMENTAL)",
+  "the rung wears the experimental label")
+T.eq(VoxelState.ANGLES_DEG[VoxelState.TP_LEVEL + 1], 75,
+  "and hands the blend the same 75-degree orbit 1ST does")
+T.eq(VoxelState.HOTKEY_ORDER[#VoxelState.HOTKEY_ORDER], VoxelState.TP_LEVEL,
+  "the 3 key walks onto it, and off it back to OFF")
+
+-- the boom's own tween: picked from an orbit rung (blend fully out) the
+-- extension SNAPS, so the dive into the world is one motion rather than a
+-- dive followed by a slide; picked from inside the head it eases
+VoxelState.setLevel(VoxelState.TP_LEVEL)
+ThirdPerson.out, ThirdPerson.len = 0, 0
+ThirdPerson.update(1 / 60, 0)
+T.eq(ThirdPerson.out, 1, "picked from the diorama, the boom starts extended")
+ThirdPerson.out, ThirdPerson.len = 0, 0
+ThirdPerson.update(1 / 60, 1)
+T.check(ThirdPerson.out > 0 and ThirdPerson.out < 1,
+  "picked from inside the head, it slides out over the boom's own time")
+
+-- ------- the world the march asks
+--
+-- A stub map that refuses everything from x = 4 rightward, with no tileset
+-- for the height field to read -- so the ground answers 0 (the lookup is
+-- guarded for exactly this) and only the walkability speaks.
+local wall = { map = {
+  inBounds = function(_, cx, cy) return cx >= 0 and cy >= 0 end,
+  isWalkableCell = function(_, cx) return cx < 4 end,
+  cellTile = function() return 0 end,
+} }
+
+T.check(ThirdPerson._occupied(wall, 70, 10, 8),
+  "an unwalkable cell refuses the eye at head height")
+T.check(not ThirdPerson._occupied(wall, 70, 30, 8),
+  "but not one the eye stands well above -- a fence is not a wall")
+T.check(ThirdPerson._occupied(wall, 70, 2, 8),
+  "and the ground refuses it from below")
+T.check(ThirdPerson._occupied(wall, -20, 30, 8),
+  "off the world entirely there is nowhere to stand: the border ring")
+
+-- the march itself: the wall's face is at x = 64, the pivot at x = 40, so
+-- the eye may travel 24 east of it less the clearance pad -- the FACE's own
+-- position rather than the four-pixel sampling grid's
+local room = ThirdPerson.reach(wall, { 40, 10, 8 }, 1, 0, 0, ThirdPerson.BOOM)
+T.check(math.abs(room - (24 - ThirdPerson.PAD)) < 0.5,
+  "the boom stops a pad short of the face that blocked it")
+T.eq(ThirdPerson.reach(wall, { 40, 30, 8 }, 1, 0, 0, ThirdPerson.BOOM),
+  ThirdPerson.BOOM, "with nothing tall enough in the way it runs out full")
+T.eq(ThirdPerson.reach(nil, { 40, 10, 8 }, 1, 0, 0, ThirdPerson.BOOM),
+  ThirdPerson.BOOM, "and with no world to ask at all -- headless, mid-warp")
+
+-- ------- the eye
+--
+-- place() is pure arithmetic over the pivot and the look, given a world
+-- with nothing in it: the suite lends the overworld away for the length of
+-- the check so the march has nothing to shorten against.
+local Game = require("src.core.Game")
+local hadOw = Game.overworld
+Game.overworld = nil
+
+ThirdPerson.out, ThirdPerson.len = 1, ThirdPerson.BOOM
+local eye, aim = ThirdPerson.place({ 100, 20, 200 }, 0, 0, 1,
+                                   { 100, 20, 224 })
+T.check(math.abs(eye[3] - (200 - ThirdPerson.BOOM)) < 1e-6,
+  "looking south, the eye stands a full boom north of the pivot")
+T.eq(eye[2], 20 + ThirdPerson.PIVOT_LIFT,
+  "raised to the orbit point above the head")
+T.check(math.abs(eye[1] - (100 - ThirdPerson.SHOULDER)) < 1e-6,
+  "and slid along the rail to the camera's own right -- which is west "
+  .. "looking south, and puts the player left of centre")
+T.check(math.abs(aim[1] - eye[1]) < 1e-6
+        and math.abs(aim[3] - eye[3] - (ThirdPerson.BOOM + 24)) < 1e-6,
+  "the focus slides with it, so the rail moves the frame and not the look")
+
+ThirdPerson.out, ThirdPerson.len = 0, 0
+local head = { 100, 20, 200 }
+local focus = { 100, 20, 224 }
+T.eq(ThirdPerson.place(head, 0, 0, 1, focus), head,
+  "with the boom fully in, the eye IS the head -- 1ST to the pixel")
+
+-- ------- what the extension decides
+--
+-- The rig is built through FirstPerson exactly as 1ST's is; the boom moves
+-- the eye, and everything keyed to where the eye stands follows it.
+ThirdPerson.out, ThirdPerson.len = 1, ThirdPerson.BOOM
+FirstPerson.yaw, FirstPerson.pitch = 0, 0
+FirstPerson.blend = 1
+FirstPerson.frame({ px = 100, py = 200, gh = 0, lift = 0 }, 500, 600, 320, 288)
+T.check(FirstPerson.cardBlend() == 1,
+  "the boomed rig turns the cards to face it, exactly as the head does")
+T.check(not FirstPerson.hidePlayer(),
+  "but the player's own card is DRAWN -- it is what the camera is watching")
+T.eq(FirstPerson.apparentFacing("down", 108, 208), "up",
+  "and it shows the camera behind it its back")
+
+-- and a boom a wall has squeezed back into the head takes the card out
+-- again: at that range it is the first-person problem word for word
+ThirdPerson.len = ThirdPerson.SHOW_AT - 1
+T.check(FirstPerson.hidePlayer(),
+  "backed into a fence, the collapsed boom stops drawing the card")
+ThirdPerson.len = ThirdPerson.SHOW_AT
+T.check(not FirstPerson.hidePlayer(), "and draws it again the moment it clears")
+ThirdPerson.len = ThirdPerson.BOOM
+
+T.eq(FirstPerson.bodyFacing(1, 0), "right",
+  "a body walking east turns east, whichever way the camera is pointed")
+T.eq(FirstPerson.bodyFacing(0, -1), "up", "and north walking north")
+T.eq(FirstPerson.bodyFacing(0, 0), FirstPerson.compassFacing(),
+  "standing still it comes back round to the camera's bearing, which is "
+  .. "the one A talks along")
+
+-- ------- the spin-flicker guard
+--
+-- The player's card is the one whose body the camera is derived FROM: the
+-- body is pointed along the camera's own yaw, so the angle between them is
+-- a flat 180 degrees and the card should show its back and nothing else,
+-- at every bearing.
+--
+-- Quantise the body to a compass point first and that stops being true.
+-- The shoulder rail stands the eye a few degrees off the exact rear axis,
+-- and the round trip through four directions has no margin to spare for
+-- it: in a band just short of each 45-degree boundary the pair measures as
+-- 135 degrees and picks the mirrored PROFILE frame. Standing perfectly
+-- still. Spin the camera and you sweep four of those bands a revolution --
+-- the character flicking sideways for a split second, which is the bug
+-- this pair of checks exists to hold shut.
+--
+-- 44 degrees is inside the first band. No lag anywhere: the body is
+-- pointed exactly where the camera looks, which is what standing still IS.
+FirstPerson.yaw, FirstPerson.pitch = math.rad(44), 0
+FirstPerson.frame({ px = 100, py = 200, gh = 0, lift = 0 }, 500, 600, 320, 288)
+FirstPerson.bodyYaw = FirstPerson.yaw
+T.eq(FirstPerson.apparentFacing("down", 108, 208), "right",
+  "measured off the compass point, a standing body picks the profile -- "
+  .. "the flicker, reproduced with the camera perfectly still")
+T.eq(FirstPerson.playerFacing("down", 108, 208), "up",
+  "measured off the body's own bearing, the card keeps its back turned")
+
+-- and the whole revolution, which is the assertion that actually matters:
+-- there is no bearing at all where a standing body shows anything but its
+-- back
+;(function()
+  local wrong = {}
+  for deg = 0, 359 do
+    FirstPerson.yaw = math.rad(deg)
+    FirstPerson.frame({ px = 100, py = 200, gh = 0, lift = 0 },
+                      500, 600, 320, 288)
+    FirstPerson.bodyYaw = FirstPerson.yaw
+    if FirstPerson.playerFacing(FirstPerson.compassFacing(), 108, 208)
+       ~= "up" then
+      wrong[#wrong + 1] = deg
+    end
+  end
+  T.eq(#wrong, 0,
+    "a standing body shows its back at every one of 360 bearings (bad: "
+    .. table.concat(wrong, ",") .. ")")
+end)()
+
+-- and with nothing holding a bearing -- a scripted walk, a cutscene, the
+-- grid walk -- the player falls back to the four-direction answer with
+-- everybody else
+FirstPerson.releaseBody()
+T.eq(FirstPerson.bodyYaw, nil, "releasing the body drops the bearing")
+T.eq(FirstPerson.playerFacing("down", 108, 208),
+  FirstPerson.apparentFacing("down", 108, 208),
+  "and the card reads exactly as an NPC's would")
+T.eq(FirstPerson.pointBody(0, 0), FirstPerson.compassFacing(),
+  "pointing it again hands back the compass facing p.facing wants")
+T.eq(FirstPerson.bodyYaw, FirstPerson.yaw, "and records the bearing behind it")
+FirstPerson.yaw, FirstPerson.pitch = 0, 0
+FirstPerson.frame({ px = 100, py = 200, gh = 0, lift = 0 }, 500, 600, 320, 288)
+
+ThirdPerson.out, ThirdPerson.len = 0, 0
+T.eq(FirstPerson.bodyFacing(1, 0), "down",
+  "in the head the body is the head, whichever way it walks")
+T.check(FirstPerson.hidePlayer(),
+  "and the card the camera stands inside is left out of the frame again")
+
+-- everything the section borrowed, put back
+Game.overworld = hadOw
+FirstPerson.blend = 0
+ThirdPerson.out, ThirdPerson.len, ThirdPerson.want = 0, 0, 0
+Voxel3D.camera = nil
+VoxelState.reset()
+end
+
+-- ------- the cameras the player steers
+--
+-- Three cameras take the same four inputs -- a wheel, Q/E, a pinch, a
+-- stick -- and the whole of CamControl is the answer to "which one is this
+-- aimed at". So the suite pins that routing table, then each camera's own
+-- stops: the boom's zoom, and the battle's orbit, climb and lens.
+
+do
+local CamControl = run.loader.exports.DRAMATIC_SHAPE.lib.require("CamControl")
+local ThirdPerson =
+  run.loader.exports.DRAMATIC_SHAPE.lib.require("ThirdPerson")
+local BattleCam = run.loader.exports.DRAMATIC_SHAPE.lib.require("BattleCam")
+local VoxelState = run.loader.exports.DRAMATIC_SHAPE.lib.require("VoxelState")
+local Voxel3D = run.loader.exports.DRAMATIC_SHAPE.lib.require("Voxel3D")
+
+-- ------- the boom's own zoom
+ThirdPerson.zoom, ThirdPerson.zoomGoal = 1, 1
+T.eq(ThirdPerson.reachFor(), ThirdPerson.BOOM,
+  "at zoom 1 the boom reaches exactly its own length")
+T.check(ThirdPerson.stepZoom(1), "a notch out moves the goal")
+T.check(ThirdPerson.zoomGoal > 1, "outward, which is what positive means")
+T.check(ThirdPerson.stepZoom(-2), "and back in past where it started")
+T.check(ThirdPerson.zoomGoal < 1, "inward")
+for _ = 1, 40 do ThirdPerson.stepZoom(-1) end
+T.eq(ThirdPerson.zoomGoal, ThirdPerson.ZOOM_MIN, "it stops coming in")
+T.check(not ThirdPerson.stepZoom(-1),
+  "and says so, so the input can fall through instead of being eaten")
+for _ = 1, 60 do ThirdPerson.stepZoom(1) end
+T.eq(ThirdPerson.zoomGoal, ThirdPerson.ZOOM_MAX, "and stops going out")
+
+-- the ease: a step is a request, and the eye takes ZOOM_TIME to answer it
+ThirdPerson.zoom, ThirdPerson.zoomGoal = 1, 1
+ThirdPerson.stepZoom(2)
+ThirdPerson.update(1 / 60, 1)
+T.check(ThirdPerson.zoom > 1 and ThirdPerson.zoom < ThirdPerson.zoomGoal,
+  "one frame later the eye is on its way but not there")
+for _ = 1, 120 do ThirdPerson.update(1 / 60, 1) end
+T.eq(ThirdPerson.zoom, ThirdPerson.zoomGoal, "and it arrives")
+T.check(math.abs(ThirdPerson.reachFor()
+                 - ThirdPerson.BOOM * ThirdPerson.zoom) < 1e-9,
+  "the boom it reaches for is the length at that zoom")
+ThirdPerson.zoom, ThirdPerson.zoomGoal = 1, 1
+
+-- the same control with no notches, for a gesture whose own scale IS the
+-- answer. It scales the BOOM, so the inversion a pinch needs (spread the
+-- fingers, pull the camera in) belongs to the gesture, not to this
+T.check(ThirdPerson.scaleZoom(2), "a continuous factor moves it too")
+T.check(math.abs(ThirdPerson.zoomGoal - 2) < 1e-6,
+  "and scales the boom by exactly that factor")
+ThirdPerson.zoom, ThirdPerson.zoomGoal = 1, 1
+
+-- ------- which camera an input is aimed at
+--
+-- Needs a 3D pass and a free-roam stack, neither of which a headless run
+-- has; both are lent for the length of the check and handed back.
+;(function()
+  local Game = require("src.core.Game")
+  local hadAvail = Voxel3D.available
+  local hadStack, hadOw = Game.stack, Game.overworld
+  local ow = {}
+  Voxel3D.available = function() return true end
+  Game.overworld = ow
+  Game.stack = { top = function() return ow end }
+
+  VoxelState.setLevel(0)
+  T.eq(CamControl.zoomTarget(), nil, "with the mode off, no camera of ours")
+  VoxelState.setLevel(3)
+  T.eq(CamControl.zoomTarget(), "survey",
+    "on an orbit rung a zoom is the engine's own survey zoom")
+  VoxelState.setLevel(VoxelState.FP_LEVEL)
+  T.eq(CamControl.zoomTarget(), nil,
+    "in 1ST nothing zooms -- the eye is in the player's head")
+  VoxelState.setLevel(VoxelState.TP_LEVEL)
+  T.eq(CamControl.zoomTarget(), "boom", "and in 3RD it is the boom")
+
+  ThirdPerson.zoomGoal = 1
+  T.check(CamControl.zoomBy(1) and ThirdPerson.zoomGoal > 1,
+    "so a wheel notch on that rung lets the boom out")
+  ThirdPerson.zoomGoal = 1
+  T.check(CamControl.pinchBy(2) and ThirdPerson.zoomGoal < 1,
+    "and spreading two fingers pulls it IN -- the gesture is the inversion")
+  ThirdPerson.zoomGoal = 1
+  T.check(CamControl.pinchBy(0.5) and ThirdPerson.zoomGoal > 1,
+    "pinching them together pushes it out again")
+  ThirdPerson.zoom, ThirdPerson.zoomGoal = 1, 1
+
+  -- 1ST is the rung that deliberately swallows nothing: a pinch there
+  -- would silently wind the survey zoom for whenever the player stepped
+  -- back out to an orbit rung
+  VoxelState.setLevel(VoxelState.FP_LEVEL)
+  T.check(not CamControl.zoomBy(1), "1ST claims no wheel notch")
+  T.check(not CamControl.pinchBy(2), "and no pinch")
+  VoxelState.setLevel(VoxelState.TP_LEVEL)
+
+  -- a screen over the overworld takes every one of them back
+  Game.stack = { top = function() return {} end }
+  T.eq(CamControl.zoomTarget(), nil,
+    "with anything pushed over the overworld, nothing is ours to zoom")
+
+  Voxel3D.available = hadAvail
+  Game.stack, Game.overworld = hadStack, hadOw
+  VoxelState.reset()
+end)()
+
+-- ------- the battle's orbit
+--
+-- The stop that matters is the far one: swung fully right, the eye must be
+-- SQUARE to the arena's axis -- the side-on shot -- and not a degree past
+-- it. Measured off the rig rather than off the constant, because the
+-- constant is computed from the rig's own stance.
+;(function()
+  local arena = { mid = { 100, 200 }, player = { 100, 216 },
+                  enemy = { 100, 184 } }
+  local function bearing()
+    local rig = BattleCam.rig(arena, 0)
+    return math.atan2(rig.eye[1] - arena.mid[1], rig.eye[3] - arena.mid[2])
+  end
+  BattleCam.recentre()
+  BattleCam.reset()
+  BattleCam.steerable = true
+
+  local home = bearing()
+  T.check(home > 0.4 and home < 0.6,
+    "the solved shot stands about 28 degrees off the arena's axis")
+  BattleCam.orbit = 1
+  T.check(math.abs(bearing() - math.pi / 2) < 1e-9,
+    "swung fully right, the eye is exactly square to the axis: side-on")
+  T.check(math.abs(BattleCam.orbitRange(arena) - (math.pi / 2 - home)) < 1e-9,
+    "which is precisely the room orbitRange said it had")
+
+  -- and the near one: there is nothing to the left of the solved shot
+  BattleCam.recentre()
+  T.check(not BattleCam.dragOrbit(-1), "a drag left of home does nothing")
+  T.eq(BattleCam.orbitGoal, 0, "the shot the composition was solved for IS "
+    .. "the left stop")
+  T.check(BattleCam.dragOrbit(0.2), "a drag right steers")
+  BattleCam.dragOrbit(10)
+  T.eq(BattleCam.orbitGoal, 1, "and stops at side-on however hard it is pushed")
+
+  -- ------- the climb
+  BattleCam.recentre()
+  local function elevation()
+    local rig = BattleCam.rig(arena, 0)
+    local vx = rig.eye[1] - rig.focus[1]
+    local vy = rig.eye[2] - rig.focus[2]
+    local vz = rig.eye[3] - rig.focus[3]
+    return math.atan2(vy, math.sqrt(vx * vx + vz * vz)),
+           math.sqrt(vx * vx + vy * vy + vz * vz)
+  end
+  local low, radius = elevation()
+  BattleCam.pitch = 1
+  local high, radius2 = elevation()
+  T.check(math.abs((high - low) - BattleCam.PITCH_RANGE) < 1e-6,
+    "raised fully, the seat is exactly 45 degrees above the solved one")
+  T.check(math.abs(radius2 - radius) < 1e-6,
+    "at the same distance -- climbing is not zooming")
+  BattleCam.recentre()
+  T.check(not BattleCam.dragPitch(-1), "and it will not tilt below home")
+  T.eq(BattleCam.pitchGoal, 0, "the rig's own low stance is the down stop")
+  BattleCam.dragPitch(10)
+  T.eq(BattleCam.pitchGoal, 1, "45 degrees is the up stop")
+
+  -- ------- the lens opening to keep the pair framed
+  --
+  -- Swinging round or climbing un-foreshortens the arena's axis, so the two
+  -- mons read further apart; left alone that threw them off the edges of
+  -- the frame at the far end of both ranges.
+  BattleCam.recentre()
+  T.check(math.abs(BattleCam.spread(arena) - 1) < 1e-9,
+    "at the solved shot the lens is the rig's own, exactly")
+  BattleCam.orbit = 1
+  T.check(BattleCam.spread(arena) > 1.8,
+    "side-on the pair reads nearly twice as far apart, and the lens opens "
+    .. "by the same amount")
+  BattleCam.orbit = 0
+  BattleCam.pitch = 1
+  T.check(BattleCam.spread(arena) > 1.5,
+    "and climbing spreads them too, on the other axis")
+  BattleCam.recentre()
+
+  local wide = BattleCam.rig(arena, 0).fov
+  T.check(BattleCam.stepZoom(-3), "three notches in")
+  BattleCam.zoom = BattleCam.zoomGoal
+  T.check(BattleCam.rig(arena, 0).fov < wide,
+    "and the lens is longer -- zoom is the FRAME, not the distance")
+  T.check(math.abs(BattleCam.frameH(arena)
+                   - BattleCam.rigFor(arena).frameH * BattleCam.zoom) < 1e-9,
+    "which is what the sun's box is fitted to as well")
+  for _ = 1, 40 do BattleCam.stepZoom(-1) end
+  T.eq(BattleCam.zoomGoal, BattleCam.ZOOM_MIN, "the lens has a near stop")
+  for _ = 1, 60 do BattleCam.stepZoom(1) end
+  T.eq(BattleCam.zoomGoal, BattleCam.ZOOM_MAX, "and a far one")
+
+  -- ------- what BACK SPRITES takes away
+  --
+  -- Not just the input: the RIG stands down too, so an angle stored from
+  -- before the row was switched on cannot leave the pinned composition
+  -- steered anyway.
+  BattleCam.recentre()
+  BattleCam.orbit, BattleCam.orbitGoal = 1, 1
+  BattleCam.pitch, BattleCam.pitchGoal = 1, 1
+  BattleCam.zoom, BattleCam.zoomGoal = 0.5, 0.5
+  BattleCam.steerable = false
+  T.check(math.abs(bearing() - home) < 1e-9,
+    "with the player's mon pinned to the menu, the shot holds its own angle")
+  T.eq(BattleCam.frameH(arena), BattleCam.rigFor(arena).frameH,
+    "and its own lens")
+  T.check(not BattleCam.dragOrbit(0.5), "and refuses to be steered")
+  T.check(not BattleCam.dragPitch(0.5), "on either axis")
+  T.check(not BattleCam.stepZoom(-1), "or zoomed")
+  BattleCam.steerable = true
+
+  -- ------- and what a new battle remembers
+  BattleCam.recentre()
+  BattleCam.dragOrbit(0.5)
+  BattleCam.dragPitch(0.5)
+  BattleCam.stepZoom(-1)
+  BattleCam.reset()
+  T.check(BattleCam.orbitGoal > 0 and BattleCam.pitchGoal > 0
+          and BattleCam.zoomGoal < 1,
+    "a new fight opens where the player left the camera, not where the rig "
+    .. "was solved -- an angle they chose is how they watch battles")
+  T.eq(BattleCam.t, 0, "only the drift's own phase starts over")
+  BattleCam.recentre()
+end)()
+end
+
 -- ------- the VR rig's arithmetic
 --
 -- VRRig is the deliberately pure half of the VR stack: headset poses in,
@@ -4151,6 +4589,346 @@ vrRigSection()
   Pipelines.setLevel("voxel", 0)
 end)()
 
+-- ------- HORDE MODE
+--
+-- The parts that can be judged without a screen: the code detector (which
+-- reads Game Boy buttons, so this is the same test the pad, the touch
+-- overlay and the VR controllers would pass), the registrations, the
+-- gloom's arithmetic, and the flow field the crowd chases along.
+;(function()
+  local lib = run.loader.exports.DRAMATIC_SHAPE.lib
+  local Horde = lib.require("Horde")
+  local Mobs = lib.require("HordeMobs")
+  local Gun = lib.require("HordeGun")
+
+  -- ------- the code
+
+  local KONAMI = { "up", "up", "down", "down",
+                   "left", "right", "left", "right", "b", "a" }
+
+  local function feedAll(list)
+    local fired = false
+    for _, btn in ipairs(list) do
+      if Horde.feed({ btn }) then fired = true end
+    end
+    return fired
+  end
+
+  T.eq(feedAll(KONAMI), true, "the konami code completes the detector")
+  T.eq(Horde._progress(), 0, "and the detector resets behind itself")
+
+  -- a wrong button in the middle is a wrong code
+  T.eq(feedAll({ "up", "up", "down", "down", "left", "left" }), false,
+    "a wrong button abandons the code")
+  T.eq(Horde._progress(), 0, "and leaves nothing part-entered")
+
+  -- the two Ups are two EDGES, which every device gives (the analog stick's
+  -- hysteresis is what guarantees it there): one held Up is not two
+  T.eq(feedAll({ "up", "up" }), false, "two Ups alone do not fire")
+  T.eq(Horde._progress(), 2, "but they do stand at two")
+  T.eq(feedAll({ "a" }), false, "a stray A after them is not the code")
+  T.eq(Horde._progress(), 0, "and drops the run entirely")
+
+  -- a false start re-enters on the first button rather than dying: pressing
+  -- Up three times still leaves a code in progress
+  feedAll({ "up", "up", "up" })
+  T.eq(Horde._progress(), 2,
+    "a third Up restarts the run rather than voiding it")
+  Horde.feed({})
+  feedAll({ "down", "down", "left", "right", "left", "right", "b" })
+  T.eq(Horde.feed({ "a" }), true, "and the code still completes from there")
+
+  -- every button in one step is still the code: the queue is ordered, and
+  -- a frame that swallowed several presses must not lose any of them
+  T.eq(Horde.feed(KONAMI), true, "the whole code inside one fixed step fires")
+
+  -- ------- it cannot start from nowhere
+  --
+  -- canStart is the gate between the code and the mode. With no overworld
+  -- in this harness it must refuse, which is also the "in a menu, in a
+  -- battle, mid-warp" answer.
+  T.eq(Horde.canStart(keyGame), false,
+    "the code does nothing outside a live overworld")
+  T.eq(Horde.active, false, "and the mode stays off")
+
+  -- ------- what got registered
+
+  T.check(type(Data.screens) == "table" and Data.screens.HordeGameOver ~= nil,
+    "the GAME OVER card is in the screens registry")
+  T.check(type(Data.screens) == "table" and Data.screens.HordeExitPrompt ~= nil,
+    "and so is the exit prompt START opens")
+  local sfx = Data.audio and Data.audio.sfx or {}
+  local HordeSfx = lib.require("HordeSfx")
+  for _, name in ipairs(HordeSfx.SHOTS) do
+    T.check(type(sfx[name]) == "table" and sfx[name].chip ~= nil,
+      "the gunshot " .. name .. " assembled into a chip program")
+  end
+  for _, name in ipairs({ HordeSfx.MAG_OUT, HordeSfx.MAG_IN, HordeSfx.RACK,
+                          HordeSfx.DRY, HordeSfx.HIT, HordeSfx.HURT }) do
+    T.check(type(sfx[name]) == "table" and sfx[name].chip ~= nil,
+      name .. " assembled into a chip program")
+  end
+  T.eq(#HordeSfx.SHOTS, 3,
+    "three shot variants, so a fast trigger overlaps its own echoes")
+  -- none of them may duck the music: a fanfare pauses the song, and
+  -- Lavender Town stopping every time the player fires is not the mode
+  local fanfares = Data.audio and Data.audio.fanfares or {}
+  for name in pairs(sfx) do
+    if name:find("^DS_HORDE") then
+      T.check(not fanfares[name] and not sfx[name].fanfare,
+        name .. " is an overlay sound, not a fanfare that pauses the song")
+    end
+  end
+
+  -- ------- the gloom
+  --
+  -- The mode pins NIGHT and then drags it down. Both wrappers must be
+  -- INERT with the mode off -- this mod is a display mod first, and a
+  -- horde-mode bug that tinted the ordinary game would be the worst kind.
+
+  local DayNight = lib.require("DayNight")
+  local litPal = DayNight.palette(DayNight.T.night)
+  local litTint = DayNight.tint(true, DayNight.T.night)
+  T.check(type(litPal) == "table" and #litPal > 0,
+    "the night palette is readable with the mode off")
+
+  Horde.active = true
+  local darkPal = DayNight.palette(DayNight.T.night)
+  local darkTint = DayNight.tint(true, DayNight.T.night)
+  local darkIn = DayNight.tint(false, DayNight.T.night)
+  Horde.active = false
+
+  local litSum, darkSum = 0, 0
+  for i = 1, #litPal do
+    for c = 1, 3 do
+      litSum = litSum + litPal[i][c]
+      darkSum = darkSum + darkPal[i][c]
+    end
+  end
+  T.check(darkSum < litSum * 0.6,
+    "the horde's sky is markedly darker than the night it is built on")
+  T.check(darkTint[1] < litTint[1] and darkTint[3] < litTint[3],
+    "and the world tint comes down with it")
+  T.check(darkTint[3] > darkTint[2],
+    "toward violet rather than flat grey -- blue survives the desaturation")
+  T.check(darkIn[1] < 1,
+    "indoors is darkened too: a building is not a refuge")
+
+  T.same(DayNight.palette(DayNight.T.night), litPal,
+    "and with the mode off the palette is byte-for-byte what it was")
+  T.same(DayNight.tint(true, DayNight.T.night), litTint,
+    "as is the world tint")
+
+  -- ------- the flow field
+  --
+  -- A room with a wall down the middle and one gap in it. Every mob's next
+  -- step comes off this sweep, so what is being pinned here is that the
+  -- crowd walks THROUGH THE DOORWAY rather than into the wall -- which is
+  -- the whole of "they path to you" and "they follow you inside".
+
+  local Map = require("src.world.Map")
+  local FLOOR, WALL = 1, 2
+  local WIDTH, HEIGHT = 6, 5              -- in blocks; cells are twice that
+  local blocks = {}
+  for i = 1, WIDTH * HEIGHT do blocks[i] = FLOOR end
+  local mapDef = {
+    id = "HORDE_TEST", width = WIDTH, height = HEIGHT,
+    blocks = blocks, borderBlock = WALL, tileset = "FIX_OUT",
+    objects = {}, warps = {}, signs = {},
+  }
+  -- the tileset says which collision tiles may be stood on; FLOOR may,
+  -- WALL may not
+  local tilesetDef = {
+    walkable = { FLOOR },
+    blockdefs = nil,
+  }
+  -- Map:cellTile reads the block layer through the tileset's blockdefs; the
+  -- fixture tileset has none, so stand in a cellTile that answers straight
+  -- off a grid this test owns
+  local walls = {}
+  local map = Map.new(mapDef, tilesetDef)
+  local W, H = map.widthCells, map.heightCells
+  function map:cellTile(cx, cy)
+    if cx < 0 or cy < 0 or cx >= W or cy >= H then return WALL end
+    return walls[cy * W + cx] and WALL or FLOOR
+  end
+  -- a wall along cx = 5, with a single gap at cy = 1
+  for cy = 0, H - 1 do
+    if cy ~= 1 then walls[cy * W + 5] = true end
+  end
+
+  Mobs._rebuild(map, 2, 2)                -- the player, west of the wall
+  T.eq(Mobs._dist(2, 2), 0, "the sweep starts on the player's own cell")
+  T.eq(Mobs._dist(3, 2), 1, "and counts outward a cell at a time")
+  T.eq(Mobs._dist(5, 2), nil, "the wall is not a cell anything stands on")
+
+  -- east of the wall the only way in is the gap, so the distance there has
+  -- to be the way ROUND, not the way through
+  local through = Mobs._dist(6, 2)
+  T.check(through ~= nil, "the far side of the wall is still reachable")
+  local direct = math.abs(6 - 2) + math.abs(2 - 2)
+  T.check(through > direct,
+    "and costs more than the straight line, because the wall is in the way")
+  T.eq(through, Mobs._dist(6, 1) + 1,
+    "the cheapest way there is through the gap")
+
+  -- a mob standing east of the wall must take a step that shortens the
+  -- walk -- which, from there, means heading for the doorway
+  local state = { map = map, entities = {}, player = { cellX = 2, cellY = 2 } }
+  local mob = { cellX = 7, cellY = 3, px = 112, py = 48,
+                facing = "down", moving = false, progress = 0 }
+  state.entities[1] = mob
+  Mobs._stepMob(state, { npc = mob })
+  T.eq(mob.moving, true, "a mob with a path takes a step")
+  local before = Mobs._dist(7, 3)
+  local after = Mobs._dist(mob.targetX, mob.targetY)
+  T.check(after and before and after < before,
+    "and the step it takes is one that shortens the walk to the player")
+
+  -- an occupied cell is stepped AROUND, not into: this is what makes a
+  -- pack spread out around the player instead of queueing single file
+  local blocker = { cellX = mob.targetX, cellY = mob.targetY }
+  local mob2 = { cellX = 7, cellY = 3, px = 112, py = 48,
+                 facing = "down", moving = false, progress = 0 }
+  state.entities = { blocker, mob2 }
+  Mobs._stepMob(state, { npc = mob2 })
+  if mob2.moving then
+    T.check(not (mob2.targetX == blocker.cellX
+                 and mob2.targetY == blocker.cellY),
+      "a mob never steps into a cell another one already holds")
+  else
+    T.check(true, "a boxed-in mob waits rather than walking through a body")
+  end
+
+  -- seal the gap and the east side is cut off entirely. A mob over there
+  -- has nowhere to walk that gets it any closer, and must stand rather
+  -- than guess -- an island across water is not a path.
+  walls[1 * W + 5] = true
+  Mobs._rebuild(map, 2, 2)
+  T.eq(Mobs._dist(6, 2), nil, "walling the gap cuts the far side off")
+  local stranded = { cellX = 7, cellY = 3, px = 112, py = 48,
+                     facing = "down", moving = false, progress = 0 }
+  state.entities = { stranded }
+  Mobs._stepMob(state, { npc = stranded })
+  T.eq(stranded.moving, false, "a mob with nowhere to go does not move")
+  T.eq(stranded.facing, "left",
+    "it turns toward the player instead, so the pack still reads as a threat")
+
+  -- ------- the way out
+  --
+  -- START is asked, not taken: the mode does not pause, but it does have
+  -- to be leavable, and every device's START (the pad's, the keyboard's
+  -- ESCAPE, the touch overlay's) lands on the same GB button.
+  T.eq(Horde.askExit(keyGame), false,
+    "there is nothing to exit with the mode off")
+
+  -- and asking while the mode IS on must not throw. Worth its own check:
+  -- askExit reaches for this module's own overworld helper, and a Lua
+  -- local declared BELOW the function that uses it is a nil global --
+  -- which says nothing at load, nothing in a headless suite that never
+  -- turns the mode on, and blows up the first time somebody presses
+  -- ESCAPE. That is exactly how it shipped the first time.
+  Horde.active, Horde.state = true, "active"
+  local askedOk, askErr = pcall(Horde.askExit, keyGame)
+  Horde.active, Horde.state = false, "idle"
+  T.eq(askedOk, true, "asking the way out never throws: " .. tostring(askErr))
+
+  -- ------- the banner wraps rather than running off the screen
+  --
+  -- The HUD's scale follows the window's zoom, so a player zoomed well in
+  -- gets glyphs twice a large scale -- and the announcement was wider
+  -- than the frame it was announcing over.
+  local Hud = lib.require("HordeHud")
+  local wrap = Hud._layout
+  T.check(type(wrap) == "function", "the banner exposes its layout")
+
+  -- a stand-in font of fixed-width glyphs: the real sheets are not in the
+  -- fixture set, and pinning the line breaks against exact advances is a
+  -- claim about the WRAPPING rather than about whatever art is loaded
+  local stub = {
+    encode = function(s)
+      local out = {}
+      for i = 1, #s do out[i] = s:byte(i) end
+      return out
+    end,
+    advanceOf = function() return 8 end,
+  }
+  local SHOUT = "A DARKNESS APPROACHES"
+
+  local wide = wrap(stub, SHOUT, 2, 4000)
+  T.eq(#wide, 1, "given room, the announcement is one line")
+
+  local narrow, smallBs = wrap(stub, SHOUT, 2, 300)
+  T.check(#narrow > 1, "and wraps onto more lines when the frame is narrow")
+  for _, line in ipairs(narrow) do
+    T.check(line.width <= 300,
+      ("every wrapped line fits the frame (%q is %d wide)")
+        :format(line.text, line.width))
+  end
+
+  -- A scale far past what the frame can carry shrinks the glyphs rather
+  -- than letting a word hang off the edge -- there is no wrap point
+  -- inside a word, so wrapping alone cannot save this case. This is the
+  -- one the player hit: the HUD's scale follows the window's zoom.
+  local tiny, tinyBs = wrap(stub, SHOUT, 40, 200)
+  for _, line in ipairs(tiny) do
+    T.check(line.width <= 200,
+      ("a scale the frame cannot carry shrinks to fit (%q is %d wide)")
+        :format(line.text, line.width))
+  end
+  T.check(tinyBs < smallBs,
+    "and that shrink really is a smaller glyph than the narrow case's")
+
+  -- the degenerate end: one unbreakable word and almost no room. The
+  -- glyph cannot go below one pixel, so this is allowed to overflow --
+  -- what it may NOT do is fail to lay out
+  local one = wrap(stub, "APPROACHES", 8, 4)
+  T.check(one and #one == 1, "a single word always lays out on one line")
+  T.eq(wrap(stub, "   ", 2, 100), nil, "and nothing but spaces lays out to nothing")
+
+  -- ------- SMOOTH TURN belongs to the headset
+  --
+  -- A comfort setting for a device that is not plugged in decides
+  -- nothing, so the row exists only while VR is ON -- and it is OFF by
+  -- default, because a software turn moves the world past a head that
+  -- did not move and that is how you make somebody ill in a headset.
+  local VRMod = lib.require("VR")
+  T.eq(VRMod.smoothTurn:get(), false, "SMOOTH TURN is off out of the box")
+
+  local function optionRows()
+    local out = Runtime.call("ui.options.rows", function(_, r) return r end,
+                             { data = Data }, { { id = "tilt" } })
+    local ids = {}
+    for _, row in ipairs(out) do ids[row.id] = row end
+    return ids
+  end
+
+  Pipelines.setLevel("voxel", 3)          -- off FULL, which owns other rows
+  VRMod.setting:sync(false)
+  T.check(not optionRows()["DRAMATIC_SHAPE:smoothturn"],
+    "with VR off the row is not on the OPTIONS menu")
+
+  VRMod.setting:sync(true)
+  local smoothRow = optionRows()["DRAMATIC_SHAPE:smoothturn"]
+  T.check(smoothRow ~= nil, "and with VR on it is")
+  if smoothRow then
+    T.eq(smoothRow.label, "SMOOTH TURN", "under its own name")
+    T.eq(smoothRow.value(), "OFF", "reading OFF until the player says otherwise")
+  end
+  VRMod.setting:sync(false)
+
+  -- ------- the gun's own bookkeeping
+
+  Gun.reset()
+  local ammo, mag, reloading = Gun.ammo()
+  T.eq(ammo, mag, "the gun starts with a full magazine")
+  T.eq(reloading, false, "and is not reloading")
+  T.eq(Gun.fire(), false, "and cannot be fired with no session running")
+  T.eq(select(1, Gun.ammo()), mag, "a refused shot spends no round")
+  T.eq(Gun.reload(), false, "nor reloaded when it is already full")
+  T.eq(Gun.visible(), false, "and it is not drawn with the mode off")
+end)()
+
 Pipelines.reset()
 run.release()
 

tests/horde_shots.lua

@@ -0,0 +1,329 @@
+-- Scratch driver: HORDE MODE, from the code to the card.
+--
+-- Enters the konami code the way a player does -- as Game Boy button
+-- edges on the fixed step, which is the same path the pad, the touch
+-- overlay and the VR controllers take -- then photographs the intro
+-- banner, the darkened sky, the gun at the hip and down the sights, a
+-- wave mid-chase, the muzzle flash, the reload, a run through a door with
+-- the crowd behind, and the GAME OVER card. Finishes by pressing A and
+-- checking that everything the mode changed came back.
+--
+--   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/horde_shots.lua \
+--   SHOT_DIR=.scratchpad/horde 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/horde")
+
+  local handle = game.mods.exports["DRAMATIC_SHAPE"]
+  if not (handle and handle.lib) then
+    print("[horde] DRAMATIC_SHAPE mod not loaded")
+    return love.event.quit()
+  end
+  local V = handle.lib
+  local Horde = V.require("Horde")
+  local Mobs = V.require("HordeMobs")
+  local Gun = V.require("HordeGun")
+  local FirstPerson = V.require("FirstPerson")
+  local ChunkMesher = V.require("ChunkMesher")
+  local Voxel = V.require("VoxelState")
+
+  pcall(os.execute, 'mkdir -p "' .. ROOT .. '" 2>/dev/null')
+  pcall(os.execute, 'mkdir "' .. ROOT:gsub("/", "\\") .. '" 2>nul')
+
+  local TileRenderer = require("src.render.TileRenderer")
+  TileRenderer.tick = function() end
+  TileRenderer.animFrame = function() return 0 end
+
+  local shots = 0
+  local function shot(name)
+    if U.shot(game, ("%s/%s.png"):format(ROOT, name)) then
+      shots = shots + 1
+    end
+  end
+
+  local function settle(frames)
+    for _ = 1, 900 do
+      if ChunkMesher.pending() == 0 then break end
+      U.wait(1)
+    end
+    U.wait(frames or 30)
+  end
+
+  -- ------- the code, entered as edges
+  --
+  -- One button per fixed step, exactly as a device delivers them: the
+  -- driver writes the queue Input:step is about to drain, which is the
+  -- same array a keypress lands in.
+  --
+  -- Each one is RELEASED after. A synthetic inject has no source behind
+  -- it, so Input:step latches it held (see the branch there) and nothing
+  -- ever lets go -- which leaves all four directions down for the rest of
+  -- the run and the player walking into a wall forever. U.tap does the
+  -- same clear for the same reason.
+  local function pressCode()
+    local KONAMI = { "up", "up", "down", "down",
+                     "left", "right", "left", "right", "b", "a" }
+    for _, btn in ipairs(KONAMI) do
+      table.insert(game.input.pressQueue, btn)
+      U.wait(2)
+      game.input.state[btn] = false
+    end
+  end
+
+  -- ------- before
+  U.teleport(game, "PALLET_TOWN", 13, 14, "down")
+  Pipelines.setLevel("voxel", 3)          -- the 35-degree diorama
+  Pipelines.setLevel("tiltshift", 0)
+  settle(40)
+  local ow = game.stack:top()
+  local p = ow.player
+  local was = {
+    map = ow.map.id, cellX = p.cellX, cellY = p.cellY, facing = p.facing,
+    level = Pipelines.level("voxel"),
+    npcs = #ow.npcs,
+  }
+  shot("00_before")
+  print(("[horde] before: %s (%d,%d) rung %d, %d npcs")
+        :format(was.map, was.cellX, was.cellY, was.level, was.npcs))
+
+  -- ------- the code lands
+  pressCode()
+  U.wait(4)
+  print("[horde] active: " .. tostring(Horde.active)
+        .. "  state: " .. tostring(Horde.state))
+  if not Horde.active then
+    print("[horde] the code did not take -- nothing else here can run")
+    return love.event.quit()
+  end
+  U.wait(20)
+  shot("01_darkness_approaches")          -- the banner, over the darkening
+
+  -- and the same announcement at the zoom that used to run it off both
+  -- edges of the screen: it has to wrap (or shrink) rather than overflow
+  local Zoom = require("src.render.Zoom")
+  pcall(function()
+    game.save.options.zoom = 3
+    Zoom.applyOptions(game.save.options)
+  end)
+  Horde.banner("A DARKNESS APPROACHES", 2.6)
+  U.wait(30)
+  shot("01b_banner_zoomed")
+  pcall(function()
+    game.save.options.zoom = 0
+    Zoom.applyOptions(game.save.options)
+  end)
+  U.wait(10)
+  print(("[horde] rung is now %d (%s)"):format(Pipelines.level("voxel"),
+        Pipelines.levelLabel("voxel")))
+
+  -- the rung must be locked: the key, SELECT and the VR click all call the
+  -- one function this refuses through
+  local Game = require("src.core.Game")
+  Game.keypressed(game, "3")
+  print(("[horde] after pressing 3 the rung is %d -- locked: %s")
+        :format(Pipelines.level("voxel"),
+                tostring(Pipelines.level("voxel") == Voxel.FP_LEVEL)))
+
+  -- ------- the first wave
+  for _ = 1, 900 do
+    if Horde.state == "active" and #Horde.session.mobs >= 5 then break end
+    U.wait(1)
+  end
+  FirstPerson.yaw = math.pi                -- look north up the street
+  U.wait(30)
+  shot("02_wave_hip")
+  print(("[horde] wave %d, %d mobs standing")
+        :format(Horde.session.wave, #Horde.session.mobs))
+
+  -- ------- START asks the way out
+  --
+  -- The same GB button the pad's START, the keyboard's ESCAPE and the
+  -- touch overlay all press, so this one tap covers every device except
+  -- the VR stick click (which calls the same Horde.askExit).
+  U.tap(game, "start")
+  U.wait(10)
+  local prompt = game.stack:top()
+  print(("[horde] START opened a prompt: %s (still active: %s)")
+        :format(tostring(prompt ~= game.overworld), tostring(Horde.active)))
+  shot("02b_exit_prompt")
+  -- NO, and back to the fight
+  U.tap(game, "b")
+  U.wait(10)
+  print(("[horde] answered NO: back on the overworld %s, active %s")
+        :format(tostring(game.stack:top() == game.overworld),
+                tostring(Horde.active)))
+
+  -- ------- the sights
+  Gun.setAds(true)
+  U.wait(20)
+  shot("03_ads")
+  Gun.setAds(false)
+  U.wait(14)
+
+  -- ------- the shot
+  --
+  -- Aimed deliberately at the nearest mob rather than fired into the
+  -- street: what is being checked is that the ray finds a body, that the
+  -- body dies, and that the kill is worth something.
+  local function aimAtNearest()
+    local best, bestD
+    for _, e in ipairs(Horde.session.mobs) do
+      local dx = (e.npc.px + 8) - (p.px + 8)
+      local dz = (e.npc.py + 8) - (p.py + 8)
+      local d = dx * dx + dz * dz
+      if not bestD or d < bestD then best, bestD = e, d end
+    end
+    if not best then return nil end
+    local dx = (best.npc.px + 8) - (p.px + 8)
+    local dz = (best.npc.py + 8) - (p.py + 8)
+    FirstPerson.yaw = math.atan2(dx, dz)
+    FirstPerson.pitch = 0
+    return best, math.sqrt(bestD)
+  end
+
+  local scoreWas, killsWas = Horde.session.score, Horde.session.kills
+  local target, range = aimAtNearest()
+  print(("[horde] aiming at a mob %s px away, yaw %.2f")
+        :format(range and ("%.0f"):format(range) or "?", FirstPerson.yaw))
+  U.wait(6)
+  Gun.fire()
+  U.wait(1)
+  shot("04_muzzle_flash")
+  -- a mob takes more than one round as the waves stack; keep firing at
+  -- whatever is nearest until something dies or the magazine is out
+  for _ = 1, 7 do
+    if Horde.session.kills > killsWas then break end
+    U.wait(16)
+    aimAtNearest()
+    Gun.fire()
+  end
+  U.wait(20)
+  print(("[horde] fired: ammo %d, score %d -> %d, kills %d -> %d")
+        :format(select(1, Gun.ammo()), scoreWas, Horde.session.score,
+                killsWas, Horde.session.kills))
+
+  -- ------- the reload, caught mid-dip
+  for _ = 1, 8 do
+    Gun.fire()
+    U.wait(12)
+  end
+  Gun.reload()
+  U.wait(45)
+  shot("05_reloading")
+  print("[horde] reloading: " .. tostring(select(3, Gun.ammo())))
+  for _ = 1, 200 do
+    if not select(3, Gun.ammo()) then break end
+    U.wait(1)
+  end
+  print(("[horde] reloaded to %d"):format(select(1, Gun.ammo())))
+
+  -- ------- through a door, with the crowd behind
+  local before = #Horde.session.mobs
+  U.teleport(game, "REDS_HOUSE_1F", 3, 6, "down")
+  settle(60)
+  for _ = 1, 400 do
+    if #Horde.session.mobs > 0 then break end
+    U.wait(1)
+  end
+  U.wait(60)
+  shot("06_indoors_followed")
+  print(("[horde] indoors: %d mobs followed (was %d outside)")
+        :format(#Horde.session.mobs, before))
+
+  -- ------- the end
+  --
+  -- Drained rather than played out, so the driver finishes in seconds and
+  -- the card is photographed from the same path a real death takes.
+  Horde.session.hp = 1
+  Horde.session.hurtCooldown = 0
+  Horde.damage(50)
+  for _ = 1, 400 do
+    if Horde.state == "gameover" then break end
+    U.wait(1)
+  end
+  U.wait(40)
+  shot("07_game_over")
+  print(("[horde] game over at score %d, wave %d, %d kills")
+        :format(Horde.session and Horde.session.score or -1,
+                Horde.session and Horde.session.wave or -1,
+                Horde.session and Horde.session.kills or -1))
+
+  -- ------- and back
+  U.tap(game, "a")
+  for _ = 1, 600 do
+    if not Horde.active and not game.stack:top().transitioning then break end
+    U.wait(1)
+  end
+  settle(60)
+  local now = game.stack:top()
+  local np = now.player
+  print(("[horde] restored: %s (%d,%d) facing %s, rung %d, %d npcs")
+        :format(now.map.id, np.cellX, np.cellY, np.facing,
+                Pipelines.level("voxel"), #now.npcs))
+  print(("[horde] matches start: map %s cell %s facing %s rung %s npcs %s")
+        :format(tostring(now.map.id == was.map),
+                tostring(np.cellX == was.cellX and np.cellY == was.cellY),
+                tostring(np.facing == was.facing),
+                tostring(Pipelines.level("voxel") == was.level),
+                tostring(#now.npcs == was.npcs)))
+  -- nothing of the mode may be left on any map
+  local left = 0
+  for _, def in pairs(game.data.maps) do
+    for _, obj in ipairs(def.objects or {}) do
+      if obj.hordeMob then left = left + 1 end
+    end
+  end
+  print(("[horde] horde objects left behind: %d"):format(left))
+  shot("08_after")
+
+  -- ------- and out the other door
+  --
+  -- The same restore, reached the other way: enter the code again and
+  -- leave through START -> YES rather than by dying. This is the path a
+  -- player who just wants their game back actually takes.
+  pressCode()
+  U.wait(6)
+  if not Horde.active then
+    print("[horde] second activation refused -- the exit path is untested")
+    print(("[horde] %d shots into %s"):format(shots, ROOT))
+    return love.event.quit()
+  end
+  for _ = 1, 400 do
+    if Horde.state == "active" then break end
+    U.wait(1)
+  end
+  U.tap(game, "start")
+  U.wait(10)
+  U.tap(game, "up")            -- NO -> YES
+  U.wait(6)
+  shot("09_exit_yes")
+  U.tap(game, "a")
+  for _ = 1, 600 do
+    if not Horde.active and not game.stack:top().transitioning then break end
+    U.wait(1)
+  end
+  settle(60)
+  local out = game.stack:top()
+  local op = out.player
+  print(("[horde] exited via START/YES: active %s, %s (%d,%d) facing %s, rung %d")
+        :format(tostring(Horde.active), out.map.id, op.cellX, op.cellY,
+                op.facing, Pipelines.level("voxel")))
+  print(("[horde] matches start: map %s cell %s facing %s rung %s npcs %s")
+        :format(tostring(out.map.id == was.map),
+                tostring(op.cellX == was.cellX and op.cellY == was.cellY),
+                tostring(op.facing == was.facing),
+                tostring(Pipelines.level("voxel") == was.level),
+                tostring(#out.npcs == was.npcs)))
+  local left2 = 0
+  for _, def in pairs(game.data.maps) do
+    for _, obj in ipairs(def.objects or {}) do
+      if obj.hordeMob then left2 = left2 + 1 end
+    end
+  end
+  print(("[horde] horde objects left behind: %d"):format(left2))
+
+  print(("[horde] %d shots into %s"):format(shots, ROOT))
+  love.event.quit()
+end

tests/tp_shots.lua

@@ -0,0 +1,198 @@
+-- Scratch driver: shots of the 3RD (third-person) rung -- the eye boomed
+-- off the back of the player's head, the player's own card drawn and turned
+-- to face it, the boom shortening against walls indoors, and the body
+-- turning to face where it walks.
+--
+--   POKEPORT_DRIVER=mods/DramaticShapeVoxelMod/tests/tp_shots.lua \
+--   SHOT_DIR=.scratchpad/tpshots 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/tp")
+
+  local handle = game.mods.exports["DRAMATIC_SHAPE"]
+  if not (handle and handle.lib) then
+    print("[tp] DRAMATIC_SHAPE mod not loaded")
+    return love.event.quit()
+  end
+  local V = handle.lib
+  local FirstPerson = V.require("FirstPerson")
+  local ThirdPerson = V.require("ThirdPerson")
+  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
+
+  -- the nearest WALKABLE cell (fp_shots' helper): a guessed coordinate
+  -- inside a building footprint buries the pivot in the geometry
+  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(("[tp] (%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: the player's own card seen from behind, in
+    -- each compass direction plus a diagonal (the off-grid case, where a
+    -- south-facing card would be edge-on to any orbit camera)
+    { 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: the boom over water, reflecting the player
+    { map = "PALLET_TOWN", x = 9, y = 12, yaw = 0, label = "pallet_water" },
+    -- pitched down, the classic third-person framing; and up, where the
+    -- boom has to shorten rather than bury the eye in the ground
+    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi,
+      pitch = math.rad(35), label = "pallet_down" },
+    { map = "PALLET_TOWN", x = 13, y = 14, yaw = math.pi,
+      pitch = -math.rad(40), label = "pallet_skyward" },
+    -- Route 1: grass and ledges, with the character in frame for scale
+    { map = "ROUTE_1", x = 10, y = 28, yaw = math.pi, label = "route1_north" },
+    -- interiors: the one place a 48px boom cannot fit, so the collision
+    -- march is the whole shot
+    { map = "VIRIDIAN_POKECENTER", x = 3, y = 5, yaw = math.pi,
+      label = "center_north" },
+    { map = "REDS_HOUSE_1F", x = 3, y = 4, yaw = math.pi,
+      label = "reds_house" },
+  }
+
+  local shots = 0
+  for _, s in ipairs(SCENES) do
+    place(s.map, s.x, s.y)
+    Pipelines.setLevel("voxel", Voxel.TP_LEVEL)
+    Pipelines.setLevel("tiltshift", 0)
+    settle()
+    FirstPerson.yaw = s.yaw
+    FirstPerson.pitch = s.pitch or FirstPerson.PITCH_DEFAULT
+    U.wait(20)
+    print(("[tp] %-16s boom %.1f of %.1f"):format(s.label, ThirdPerson.len,
+                                                  ThirdPerson.BOOM))
+    if U.shot(game, ("%s/%s.png"):format(ROOT, s.label)) then
+      shots = shots + 1
+    end
+  end
+
+  -- the slide from 1ST to 3RD: the eye walks out of the head rather than
+  -- cutting, so the halfway frame is a real camera position
+  place("PALLET_TOWN", 13, 14)
+  Pipelines.setLevel("voxel", Voxel.FP_LEVEL)
+  settle()
+  if U.shot(game, ROOT .. "/from_1st.png") then shots = shots + 1 end
+  Pipelines.setLevel("voxel", Voxel.TP_LEVEL)
+  for _ = 1, 300 do
+    if ThirdPerson.out >= 0.5 then break end
+    U.wait(1)
+  end
+  if U.shot(game, ROOT .. "/boom_mid.png") then shots = shots + 1 end
+  U.wait(60)
+  if U.shot(game, ROOT .. "/boom_out.png") then shots = shots + 1 end
+
+  -- ------- the free walk, with the body turning
+  --
+  -- Hold forward with the head yawed off-grid: the player must GLIDE (off
+  -- the 16px grid, which no grid step can do) and the body must end up
+  -- facing its own travel rather than the lens.
+  place("PALLET_TOWN", 13, 14)
+  Pipelines.setLevel("voxel", Voxel.TP_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 = p.px, p.py
+  U.hold(game, "up", 90)
+  local moved = math.abs(p.px - x0) + math.abs(p.py - y0)
+  print(("[tp] walk moved %.1f px; off-grid: %s; body faces %s (camera %s)")
+        :format(moved,
+                tostring(p.px % 16 ~= 0 or p.py % 16 ~= 0),
+                tostring(p.facing), tostring(FirstPerson.compassFacing())))
+  if U.shot(game, ROOT .. "/walked.png") then shots = shots + 1 end
+
+  -- strafing: the one case the body facing exists for. Hold RIGHT with the
+  -- head due north and the character must walk east showing its flank.
+  place("PALLET_TOWN", 13, 14)
+  settle()
+  FirstPerson.yaw = math.pi
+  U.hold(game, "right", 40)
+  print(("[tp] strafe: body faces %s, camera looks %s")
+        :format(tostring(p.facing), tostring(FirstPerson.compassFacing())))
+  if U.shot(game, ROOT .. "/strafe.png") then shots = shots + 1 end
+
+  -- ------- the spin, sampled
+  --
+  -- Stand still and turn the camera fast, sampling the frame the player's
+  -- own card actually draws every rendered frame. A standing body is
+  -- pointed along the camera's own yaw, so it must show its back the whole
+  -- way round; anything else is the sideways flick. Sampled through the
+  -- live rig, so this measures the real thing rather than the arithmetic.
+  place("PALLET_TOWN", 13, 14)
+  Pipelines.setLevel("voxel", Voxel.TP_LEVEL)
+  settle()
+  ow = game.stack:top()
+  p = ow.player
+  local seen, frames = {}, 0
+  for _ = 1, 240 do
+    FirstPerson.lookBy(math.rad(7), 0)      -- ~420 deg/s, a hard flick
+    U.wait(1)
+    local f = FirstPerson.playerFacing(p.facing, p.px + 8, p.py + 8)
+    seen[f] = (seen[f] or 0) + 1
+    frames = frames + 1
+  end
+  local report = {}
+  for f, n in pairs(seen) do
+    report[#report + 1] = ("%s x%d"):format(f, n)
+  end
+  table.sort(report)
+  print(("[tp] spin: %d frames, card frames seen: %s")
+        :format(frames, table.concat(report, ", ")))
+
+  print(("[tp] %d shots into %s"):format(shots, ROOT))
+  love.event.quit()
+end