@maka/maka-cli 5.167.0 → 5.170.0

package/bundle/typescript/src/commands/game/sideQuest/commands/move.js

@@ -16,6 +16,7 @@ import { rollPool, formatRoll } from '../utilities/dice.js';
 import { trailMaster } from '../utilities/companion-heel.js';
 import { spendMovementMeters, paceNote } from '../utilities/movement-cost.js';
 import { requirePhase } from '../utilities/action-cost.js';
+import { onTheWall, midClimbRefusal } from '../utilities/climb-state.js';
 /**
  * "walk to <spot>" / "run to <spot>" / "sprint to <spot>" -- crossing
  * the CURRENT room to one of its "at" spots (see utilities/spots.ts;
@@ -103,6 +104,339 @@ export class MoveCommand extends Command {
         }
         return `Spots are a meat-world concern -- on the grid there is no distance at all, so "go <room>" puts your persona anywhere by name.`;
     }
+    /**
+     * ONE WALL, ONE SET OF DICE, WHICHEVER WAY YOU ARE GOING ON IT.
+     *
+     * Everything a climb can do -- the Gymnastics + Strength test, the
+     * banked metres, the rappel row, the hold-on, the second chance, the
+     * fall -- lives here and nowhere else. execute() calls it for a
+     * crossing that climbs, and retreatFromClimb() calls it to come back
+     * off a wall part-way up (6SmvvRRtn9eEMZSbF: "when I'm 1m up, and I
+     * use 'descend', it says I'm already on the floor"). Two callers, one
+     * body: the reversal could not have been a second copy, because the
+     * copy that drifted would be the one that forgot the fall.
+     *
+     * `wall` describes THIS action's stretch of wall: the spot it is
+     * toward, its length, how much of it is already banked, which way
+     * gravity points, how high off the ground the actor is at the start,
+     * and how a partial result is recorded -- a forward climb banks
+     * toward its target, a retreat unwinds the bank toward the original
+     * one, and only the caller knows which.
+     */
+    resolveClimb(wall) {
+        const actor = this.actor;
+        const room = actor.currentLocation;
+        const { down, meters, banked } = wall;
+        const spotName = wall.spot;
+        // STRENGTH, NOT AGILITY (SR5 p.134, Climbing: the test is
+        // "Gymnastics + Strength [Physical]"). This rolled Agility, which
+        // is the reflex attribute every other Athletics use leans on --
+        // plausible, and wrong. Climbing is the one athletic act the book
+        // hangs on how much of your own weight you can haul.
+        //
+        // The SKILL stays `athletics`: this engine carries skill GROUPS
+        // where the book has members (see models/player.ts -- Summoning/
+        // Binding/Banishing collapse to `conjuring` the same way), and
+        // Gymnastics is the Athletics group's climbing member. That is a
+        // pre-existing, documented modelling choice, not something this
+        // roll invented; the attribute was a straightforward error.
+        // ASSISTED CLIMBING (p.134 Climbing Table: +2 dice, and 1 metre
+        // per hit instead of per two). The gear is the p.449 kit -- rope,
+        // harness, carabiners, crampons -- which this game has SOLD in the
+        // catalog all along (`climbing-gear`) while nothing read it. It
+        // was buyable and inert, the same shape as the hostility flag:
+        // wired at one end only.
+        //
+        // Carried, not worn: a kit in the pack is a kit you can rig.
+        const assisted = actor.inventory.getAllItems().some(i => /climbing gear|climbing kit|\brope\b|harness|carabiner|crampon|grapple gun/i.test(`${i.name} ${i.description ?? ''}`));
+        // SURFACE AND CONDITION (p.134), read off the room's own prose and
+        // the level's name -- see climbSurfaceModifier. Zero unless the
+        // fiction says otherwise, which is why adding this could not
+        // re-break the scenes the banking fix just made climbable.
+        const surface = climbSurfaceModifier(`${room.name} ${room.description ?? ''} ${(room.levels ?? []).map(l => `${l.name} ${l.kind ?? ''}`).join(' ')} ${spotName}`);
+        // RAPPELLING (p.134) IS ITS OWN ROW: "assisted climbing down" is
+        // not a scaled climb, it is Free-Fall + Body [Physical] (2) on a
+        // rope, descending 20 metres per Combat Turn. Routed here rather
+        // than folded into the climb rate, because folding it in would
+        // have made it a faster climb instead of a different act.
+        //
+        // THE CLOCK IS THE BOOK'S BOOKKEEPING, NOT THE RULE. Canon quotes
+        // the rate per Combat Turn and this engine has no combat-turn
+        // clock (the same gap named in getInitiativeDice and in the sprite
+        // sustain task). The RATE is what is canon: 20m per turn, +1m per
+        // net hit. Every vertical drop this engine can build is a handful
+        // of metres -- METERS_PER_LEVEL is 3 -- so a single turn covers
+        // any of them outright, and the honest translation is one test
+        // that either lands you or does not. No clock invented to host it.
+        if (down && assisted) {
+            // Free-Fall in canon, and now in this engine too -- the comment
+            // here used to end "...and has no Free-Fall skill", which was the
+            // reason it settled for `athletics`. The skill exists as of the
+            // athletics split, so the site rolls what it always wanted.
+            const ffSkill = actor.skillRating('free-fall');
+            const ffPool = Math.max(1, actor.body + (ffSkill > 0 ? ffSkill : -1) + actor.bonus('athletics') + surface.mod + actor.woundModifier - actor.sustainingPenalty);
+            const ff = rollPool(ffPool);
+            this.logger.meta(`  Rappel ${meters}m -- Free-Fall + Body (2)${surface.label ? ` [${surface.label}]` : ''}: ${formatRoll(ff)}`);
+            if (ff.hits >= 2) {
+                actor.climbProgress = undefined;
+                this.actor.performAction('rappels down to', spotName);
+                return { arrived: true, note: '' };
+            }
+            // "On an unsuccessful test you don't slow down" (p.134): the
+            // rope runs and you arrive hard rather than not at all.
+            const dv = fallDamageDVMeters(meters);
+            let descentNote = `You kick off and the line runs faster than you meant -- you come down the rope in a rush.`;
+            // Carried out to the arrival line, so a rushed rappel still
+            // lands you and the story of it rides WITH the arrival rather
+            // than replacing it. Lint caught this built-and-dropped -- the
+            // player would have taken the damage and been told nothing
+            // about where it came from.
+            if (dv > 0) {
+                const soak = rollPool(actor.getSoakPool());
+                const dealt = Math.max(0, dv - soak.hits);
+                this.logger.meta(`  Hard landing: DV ${dv}, Soak: ${formatRoll(soak)}`);
+                if (dealt > 0) {
+                    actor.takeDamage(dealt);
+                    descentNote += ` The landing costs you ${dealt} box${dealt === 1 ? '' : 'es'}: ${actor.conditionSummary()}`;
+                }
+                else {
+                    descentNote += ` You hit hard and the armor eats it.`;
+                }
+            }
+            else {
+                descentNote += ` It is not far enough to hurt.`;
+            }
+            actor.climbProgress = undefined;
+            this.actor.performAction('rappels down to', spotName);
+            // A rushed rappel still ARRIVES -- you are down either way.
+            return { arrived: true, note: descentNote };
+        }
+        // A RAPPEL IS NOT A CLIMB, so it does not run one. Everything
+        // below belongs to going UP, or to going down the hard way.
+        //
+        // GYMNASTICS: p.134 tests climbing as Gymnastics + Strength, which
+        // is the pairing this pool already had -- only the skill name was
+        // standing in for it.
+        const athleticsSkill = actor.skillRating('gymnastics');
+        const pool = Math.max(1, actor.strength + (athleticsSkill > 0 ? athleticsSkill : -1) + actor.bonus('athletics') + (assisted ? 2 : 0) + surface.mod + actor.woundModifier - actor.sustainingPenalty);
+        const climb = rollPool(pool);
+        // HITS BUY DISTANCE -- there is no threshold (p.134, Climbing
+        // Table: "Unassisted climbing upward, 1 meter per 2 hits"). This
+        // used to be a flat "2 hits or you fall", which is a rule the book
+        // does not have: it made a one-metre scramble and a three-storey
+        // face equally hard, and it made a strong climber's extra hits
+        // buy nothing.
+        //
+        // BANKED PROGRESS (p.134): hits buy metres per TEST, and a wall is
+        // climbed over successive actions. Anything already banked toward
+        // THIS spot counts; progress toward a different one does not
+        // transfer, or a player could bank a metre on one wall and cash it
+        // in across the room.
+        const remaining = Math.max(0, meters - banked);
+        // DOWN IS TWICE AS FAST (p.134: "Unassisted climbing down, 1 metre
+        // per hit"). The engine climbed down at the upward rate, so a
+        // runner picking their way off a catwalk paid the same toll as
+        // getting onto it -- the item's third gap.
+        const needed = climbHitsFor(remaining, assisted, down);
+        const gained = climbMetersFrom(climb.hits, assisted, down);
+        const reachedTotal = Math.min(meters, banked + gained);
+        // ARRIVAL IS DECIDED IN METRES, not in hits, because metres are
+        // what the rule buys. The two agree almost always and diverged on
+        // the rounding: `needed` is a CEILING, so a roll could carry you
+        // the full remaining distance and still fall a fraction short of
+        // the integer threshold. On a bench that printed "you get about
+        // 3m up" on a 3m wall and then, next attempt, "3m already banked,
+        // 1m to go" -- arrived and not arrived at once.
+        //
+        // `needed` stays for the ticker, where a whole number of hits is
+        // the useful thing to read.
+        const gotUp = !climb.glitch && (banked + gained) >= meters;
+        // Same one-rounding rule as the prose below: round the banked
+        // figure once and derive the remainder from it, or the ticker
+        // says "2m banked, 2m to go" on a 3m wall.
+        const shownBanked = Math.round(banked);
+        this.logger.meta(`  ${down ? 'Descend' : 'Climb'} ${meters}m${banked > 0 ? ` (${shownBanked}m already banked, ${Math.max(0, meters - shownBanked)}m to go)` : ''}${assisted ? ' -- ASSISTED (+2, 1m/hit)' : ''}${down && !assisted ? ' -- DOWN (1m/hit)' : ''}${surface.label ? ` [${surface.label}]` : ''} -- Gymnastics + Strength: ${formatRoll(climb)} (${needed} hits needed)`);
+        if (gotUp) {
+            // Over the lip: the wall is done with you.
+            actor.climbProgress = undefined;
+            return { arrived: true, note: '' };
+        }
+        // A FAILED CLIMB IS NOT A FALL (p.134, Climbing Failures and
+        // Glitches). Progress halts and you make a Reaction + Strength
+        // test to HOLD ON; only failing THAT drops you. Falling
+        // immediately was the engine's own invention, and it is the
+        // half of this that made climbing feel arbitrary -- one bad
+        // roll and gravity, with nothing in between.
+        const hold = rollPool(Math.max(1, actor.reaction + actor.strength + actor.woundModifier - actor.sustainingPenalty));
+        this.logger.meta(`  Hold on -- Reaction + Strength: ${formatRoll(hold)} (1 hit holds)`);
+        const reached = reachedTotal;
+        if (hold.hits >= 1) {
+            // YOU KEEP THE METRES. This used to end "and climb back down",
+            // throwing the whole attempt away -- which is what made a tall
+            // wall unclimbable rather than merely slow. Hanging on with
+            // progress banked is the book's own shape: another Complex
+            // Action, from where you got to.
+            actor.climbProgress = wall.progressFor(reached);
+            // THE TWO FIGURES HAVE TO ADD UP. Rounding each independently
+            // printed "about 2m up" and "about 2m still above you" on a
+            // 3m wall -- both are honest roundings of 1.5, and together
+            // they describe a 4m climb. Caught on a repro bench, where a
+            // reviewer would rightly have filed it as a maths bug.
+            //
+            // So the SHOWN height is rounded once and the remainder is
+            // derived from it. The banked progress keeps the exact value:
+            // the display is where the rounding belongs, not the state.
+            const shownUp = Math.round(reached);
+            const left = Math.max(0, meters - shownUp);
+            this.actor.performAction(down ? 'climbs partway down toward' : 'climbs partway toward', `the ${spotName}, and holds there`);
+            // A DESCENT IS NOT AN ASCENT WITH A DIFFERENT RATE, and this
+            // block is shared by both -- the rappel is routed away above,
+            // so an UNASSISTED climb down falls through to here.
+            //
+            // `reached` is distance TRAVELLED, so going down it measures
+            // how far you have come FROM THE TOP; height above the ground
+            // is the remainder. Every sentence here read `reached` as
+            // height and said "up" and "still above you" out loud, so a
+            // runner picking their way off a catwalk was told they were
+            // climbing it. Measured on a bench, descending a 3m ledge:
+            //   "You get about 1m up ... about 2m still above you."
+            // -- printed on the second of four `descend` commands.
+            return {
+                arrived: false,
+                text: down
+                    ? `You get about ${reached < 1 ? 'a body length' : `${shownUp}m`} down and it stops going anywhere -- ${climb.glitch ? 'a hold shears away under your weight' : 'no purchase left within reach'}. You hang on, boots wedged, ${left < 1 ? 'the ground within reach' : `about ${left}m still below you`}.${hint(` (Descend again to keep going${assisted ? '' : '; rope and a harness would let you rappel it'}.)`)}`
+                    : `You get about ${reached < 1 ? 'a body length' : `${shownUp}m`} up and it stops going anywhere -- ${climb.glitch ? 'a hold shears away under your weight' : 'no purchase left within reach'}. You hang on, boots wedged, ${left < 1 ? 'the lip within reach' : `about ${left}m still above you`}.${hint(` (Climb again to keep going${assisted ? '' : '; rope and a harness would double your rate'}.)`)}`,
+            };
+        }
+        // THE SECOND CHANCE (p.134 Climbing Failures and Glitches;
+        // 6SmvvRRtn9eEMZSbF). Canon: the hold-on fails, you start to
+        // fall, "and during the next Action Phase the character may
+        // attempt to stop with a Reaction + Strength Test at a -2 dice
+        // pool modifier". Two tests, not one, and this engine only ever
+        // rolled the first.
+        //
+        // COMPRESSED, AND SAYING SO. The book puts a phase between them
+        // because a fall takes time -- 20m per Combat Turn. Every drop
+        // this engine can build is a few metres (METERS_PER_LEVEL is 3),
+        // so there is no phase to wait for: the catch resolves in the
+        // same breath as the slip. The MECHANIC is canon -- a second
+        // attempt, at -2 -- and only the gap between them is missing,
+        // which is the same translation the rappel makes above.
+        //
+        // THE FILED ITEM'S FRAMING WAS WRONG and the correction belongs
+        // here: there is no general "arrest any fall" rule in SR5. The
+        // RAG is explicit that a mid-fall save exists in exactly two
+        // places, this one and a failed rappel. A character who walks
+        // off a roof does not get it, and giving them one would be
+        // inventing a rule the book does not have.
+        const catchIt = rollPool(Math.max(1, actor.reaction + actor.strength - 2 + actor.woundModifier - actor.sustainingPenalty));
+        this.logger.meta(`  Catch yourself -- Reaction + Strength -2: ${formatRoll(catchIt)} (1 hit stops the fall)`);
+        // HOW HIGH YOU ACTUALLY ARE -- the one figure both the prose and
+        // the damage below have to agree on, and the reason this is a
+        // named variable rather than `reached` inline in three places.
+        //
+        // Measured from where this stretch STARTED, in the direction it
+        // goes: a forward climb starts on the ground and `reached` is the
+        // height; a descent starts at the top and `reached` is what has
+        // been given up; a retreat starts wherever the bank left you. The
+        // caller supplies the start so this line does not have to know
+        // which of those it is.
+        const heightNow = Math.max(0, wall.heightAtStart + (down ? -reached : reached));
+        const shownHeight = heightNow < 1 ? 'a body length' : `${Math.round(heightNow)}m`;
+        if (catchIt.hits >= 1) {
+            actor.climbProgress = wall.progressFor(reached);
+            this.actor.performAction('slips on', `the ${spotName} climb, and catches themselves`);
+            return {
+                arrived: false,
+                text: `You come off -- and catch yourself a body length down, fingers screaming. You are still on the wall, about ${shownHeight} up.${hint(` (${down ? 'Descend' : 'Climb'} again to keep going.)`)}`,
+            };
+        }
+        // The grip goes: the wall takes back everything it gave.
+        actor.climbProgress = undefined;
+        // Fall from where you ACTUALLY ARE, not from the top -- and not
+        // from the distance travelled either. Canon buys distance with
+        // hits whether or not you finish, so a runner who barely left
+        // the floor does not take a storey's worth of landing.
+        //
+        // THIS READ `reached` AND WAS INVERTED ON THE WAY DOWN, which is
+        // the mechanical half of the descent bug: a runner 2m down a 3m
+        // wall is 1m up and was billed for a 2m fall, while one who
+        // slipped on the FIRST action of a descent was nearly a full
+        // storey up and billed for nothing. Invisible on a 3m ledge --
+        // both figures soak to zero damage, which is exactly how it
+        // survived -- and real the moment the drop is worth any DV.
+        const dv = fallDamageDVMeters(heightNow);
+        let fallNote = `Your grip goes, and there's nothing to catch -- you come off the wall about ${shownHeight} up.`;
+        if (dv > 0) {
+            const soak = rollPool(actor.getSoakPool());
+            const dealt = Math.max(0, dv - soak.hits);
+            this.logger.meta(`  Fall damage: DV ${dv} (${Math.round(heightNow)}m, AP -4), Soak: ${formatRoll(soak)}`);
+            if (dealt > 0) {
+                actor.takeDamage(dealt);
+                fallNote += ` The landing costs you ${dealt} box${dealt === 1 ? '' : 'es'}: ${actor.conditionSummary()}`;
+            }
+            else {
+                fallNote += ` You hit hard but the armor eats it.`;
+            }
+        }
+        else {
+            fallNote += ` It's a short drop -- you land badly and nothing breaks.`;
+        }
+        this.actor.performAction('falls from', `a climb toward the ${spotName}`);
+        return { arrived: false, text: fallNote };
+    }
+    /**
+     * BACK OFF THE WALL (6SmvvRRtn9eEMZSbF: "when I'm 1m up, and I use
+     * 'descend', it says I'm already on the floor").
+     *
+     * climb.ts picks destinations by STOREY -- "descend" wants a spot on
+     * a level below yours -- and a runner a metre up a wall is still, by
+     * spot, on the floor they started from. So the verb looked below the
+     * floor, found nothing, and reported the ground floor. True, and the
+     * opposite of useful: the one thing a person a metre up a sheer wall
+     * most wants is to get back down.
+     *
+     * This is that. The stretch to climb is the bank itself -- the
+     * metres already travelled, back toward the spot you left -- at
+     * canon's rate for that direction (down is 1m per hit, p.134; a rope
+     * makes it a rappel). It is the same resolveClimb as the forward
+     * climb, so a retreat can slip, hold, catch and fall exactly as an
+     * ascent can; what differs is only the bookkeeping. A PARTIAL retreat
+     * unwinds the bank rather than replacing it, so the elevation bar
+     * and the next "climb" both still know which wall you are on and how
+     * far up it.
+     */
+    async retreatFromClimb() {
+        const actor = this.actor;
+        const wall = onTheWall(actor);
+        if (!wall)
+            return `You're not on a wall.`;
+        // THE COMBAT TURN: coming back down is a Complex Action like going
+        // up (p.134), and it happens on your own Action Phase.
+        const phase = requirePhase(this.scene, actor);
+        if (phase)
+            return phase;
+        const down = wall.up; // retreating from an ascent is a descent
+        const target = wall.target;
+        const outcome = this.resolveClimb({
+            spot: wall.from,
+            meters: wall.travelled,
+            banked: 0,
+            down,
+            heightAtStart: wall.height,
+            // Unwind the bank toward the ORIGINAL target: part-way back down
+            // a wall you were climbing, you are still on that wall, lower.
+            progressFor: reached => ({ target, meters: Math.max(0, wall.travelled - reached) }),
+        });
+        if (!outcome.arrived)
+            return outcome.text;
+        actor.climbProgress = undefined;
+        this.logger.write(`MoveCommand: ${actor.name} climbs back ${down ? 'down' : 'up'} to ${wall.from} in ${actor.currentLocation.name}.`);
+        const note = outcome.note ? `${outcome.note} ` : '';
+        return down
+            ? `${note}You pick your way back down to the ${wall.from} -- boots on solid ground again.`
+            : `${note}You haul yourself back up onto the ${wall.from}.`;
+    }
     /** Your shells trail you across the room (companion-heel.ts
      *  trailMaster): after every in-room move they re-place themselves
      *  beside you. An NPC mover has no Game in its context and drags
@@ -162,6 +496,12 @@ export class MoveCommand extends Command {
             if (!room.ensureGrid()) {
                 return `There's no ground to pace off here.${hint(` ("go ${direction}" to leave.)`)}`;
             }
+            // ON A WALL, NOT ON THE FLOOR (6SmvvRRtn9eEMZSbF: "I'm able to
+            // move around the room while still climbing"). See the named-
+            // destination gate below for the whole of it.
+            const wall = midClimbRefusal(actor);
+            if (wall)
+                return wall;
             return await this.stepAcross(direction, count);
         }
         // GRAPPLED (p.195): held fast means no crossing the room either --
@@ -190,6 +530,28 @@ export class MoveCommand extends Command {
             }
             return [`Places in ${room.name}:`, ...describeSpotRoster(room, actor).map(l => `  • ${l}`), ...ways].join('\n');
         }
+        // ON A WALL, NOT ON THE FLOOR (6SmvvRRtn9eEMZSbF: "I'm able to move
+        // around the room while still climbing, I should have to descend
+        // first to move again").
+        //
+        // A climb banks its metres in climbProgress and leaves the SPOT
+        // where it was, so to this verb a runner a metre up a sheer wall
+        // was standing on the dock, free to stroll to the door -- and the
+        // walk quietly threw the bank away on arrival. The only crossing
+        // that makes sense from a wall is the one you are on: more of the
+        // same climb (the target spot, or the person standing on it).
+        // Everything else -- another spot, a doorway, a body on the floor
+        // -- is refused with both ways off the wall named. Coming back
+        // down is climb.ts's "descend", which routes to retreatFromClimb.
+        {
+            const wall = onTheWall(actor);
+            if (wall) {
+                const wanted = resolveSpot(room, words.join(' '))?.name
+                    ?? spotOf(this.resolveActorTarget(room, words.join(' ')) ?? actor);
+                if (wanted !== wall.target)
+                    return midClimbRefusal(actor);
+            }
+        }
         // A DOORWAY THE PLAYER NAMED BY DIRECTION COMES FIRST
         // (TqKCyEZ23ppb4w5BP -- "there's no location in Krow's Den to move
         // to the locked door").
@@ -356,267 +718,31 @@ export class MoveCommand extends Command {
         let descentNote = '';
         const climbSteps = mine !== undefined ? spotClimbSteps(room, mine, spot.name) : undefined;
         if (climbSteps !== undefined) {
-            // STRENGTH, NOT AGILITY (SR5 p.134, Climbing: the test is
-            // "Gymnastics + Strength [Physical]"). This rolled Agility, which
-            // is the reflex attribute every other Athletics use leans on --
-            // plausible, and wrong. Climbing is the one athletic act the book
-            // hangs on how much of your own weight you can haul.
-            //
-            // The SKILL stays `athletics`: this engine carries skill GROUPS
-            // where the book has members (see models/player.ts -- Summoning/
-            // Binding/Banishing collapse to `conjuring` the same way), and
-            // Gymnastics is the Athletics group's climbing member. That is a
-            // pre-existing, documented modelling choice, not something this
-            // roll invented; the attribute was a straightforward error.
-            // ASSISTED CLIMBING (p.134 Climbing Table: +2 dice, and 1 metre
-            // per hit instead of per two). The gear is the p.449 kit -- rope,
-            // harness, carabiners, crampons -- which this game has SOLD in the
-            // catalog all along (`climbing-gear`) while nothing read it. It
-            // was buyable and inert, the same shape as the hostility flag:
-            // wired at one end only.
-            //
-            // Carried, not worn: a kit in the pack is a kit you can rig.
-            // Narration from a rappel that got away, prepended to the arrival.
-            const assisted = actor.inventory.getAllItems().some(i => /climbing gear|climbing kit|\brope\b|harness|carabiner|crampon|grapple gun/i.test(`${i.name} ${i.description ?? ''}`));
-            // WHICH WAY. pathClimbSteps returns a magnitude, so direction is
+            // WHICH WAY. spotClimbSteps returns a magnitude, so direction is
             // read off the cells: canon prices down differently from up
             // (unassisted down is 1m per HIT, twice the rate of going up),
             // and rappelling is a different test entirely.
             const grid = room.ensureGrid();
-            const fromZ = mine !== undefined ? (grid?.spotCells.get(mine)?.z ?? 0) : 0;
+            const fromZ = grid?.spotCells.get(mine)?.z ?? 0;
             const toZ = grid?.spotCells.get(spot.name)?.z ?? 0;
             const down = toZ < fromZ;
-            // SURFACE AND CONDITION (p.134), read off the room's own prose and
-            // the level's name -- see climbSurfaceModifier. Zero unless the
-            // fiction says otherwise, which is why adding this could not
-            // re-break the scenes the banking fix just made climbable.
-            const surface = climbSurfaceModifier(`${room.name} ${room.description ?? ''} ${(room.levels ?? []).map(l => `${l.name} ${l.kind ?? ''}`).join(' ')} ${spot.name}`);
-            // RAPPELLING (p.134) IS ITS OWN ROW: "assisted climbing down" is
-            // not a scaled climb, it is Free-Fall + Body [Physical] (2) on a
-            // rope, descending 20 metres per Combat Turn. Routed here rather
-            // than folded into the climb rate, because folding it in would
-            // have made it a faster climb instead of a different act.
-            //
-            // THE CLOCK IS THE BOOK'S BOOKKEEPING, NOT THE RULE. Canon quotes
-            // the rate per Combat Turn and this engine has no combat-turn
-            // clock (the same gap named in getInitiativeDice and in the sprite
-            // sustain task). The RATE is what is canon: 20m per turn, +1m per
-            // net hit. Every vertical drop this engine can build is a handful
-            // of metres -- METERS_PER_LEVEL is 3 -- so a single turn covers
-            // any of them outright, and the honest translation is one test
-            // that either lands you or does not. No clock invented to host it.
-            if (down && assisted) {
-                // Free-Fall in canon, and now in this engine too -- the comment
-                // here used to end "...and has no Free-Fall skill", which was the
-                // reason it settled for `athletics`. The skill exists as of the
-                // athletics split, so the site rolls what it always wanted.
-                const ffSkill = actor.skillRating('free-fall');
-                const ffPool = Math.max(1, actor.body + (ffSkill > 0 ? ffSkill : -1) + actor.bonus('athletics') + surface.mod + actor.woundModifier - actor.sustainingPenalty);
-                const ff = rollPool(ffPool);
-                this.logger.meta(`  Rappel ${climbSteps * METERS_PER_LEVEL}m -- Free-Fall + Body (2)${surface.label ? ` [${surface.label}]` : ''}: ${formatRoll(ff)}`);
-                if (ff.hits >= 2) {
-                    actor.climbProgress = undefined;
-                    this.actor.performAction('rappels down to', spot.name);
-                    // Falls through to the normal arrival below.
-                }
-                else {
-                    // "On an unsuccessful test you don't slow down" (p.134): the
-                    // rope runs and you arrive hard rather than not at all.
-                    const dv = fallDamageDVMeters(climbSteps * METERS_PER_LEVEL);
-                    descentNote = `You kick off and the line runs faster than you meant -- you come down the rope in a rush.`;
-                    // Carried out to the arrival line below: a rushed rappel still
-                    // lands you, so the story of it has to ride WITH the arrival
-                    // rather than replacing it. Lint caught this built-and-dropped
-                    // -- the player would have taken the damage and been told
-                    // nothing about where it came from.
-                    if (dv > 0) {
-                        const soak = rollPool(actor.getSoakPool());
-                        const dealt = Math.max(0, dv - soak.hits);
-                        this.logger.meta(`  Hard landing: DV ${dv}, Soak: ${formatRoll(soak)}`);
-                        if (dealt > 0) {
-                            actor.takeDamage(dealt);
-                            descentNote += ` The landing costs you ${dealt} box${dealt === 1 ? '' : 'es'}: ${actor.conditionSummary()}`;
-                        }
-                        else {
-                            descentNote += ` You hit hard and the armor eats it.`;
-                        }
-                    }
-                    else {
-                        descentNote += ` It is not far enough to hurt.`;
-                    }
-                    actor.climbProgress = undefined;
-                    this.actor.performAction('rappels down to', spot.name);
-                    // A rushed rappel still ARRIVES -- you are down either way.
-                }
-                // A RAPPEL IS NOT A CLIMB, so it does not run one. Everything
-                // below belongs to going UP, or to going down the hard way.
-            }
-            else {
-                // GYMNASTICS: p.134 tests climbing as Gymnastics + Strength, which
-                // is the pairing this pool already had -- only the skill name was
-                // standing in for it.
-                const athleticsSkill = actor.skillRating('gymnastics');
-                const pool = Math.max(1, actor.strength + (athleticsSkill > 0 ? athleticsSkill : -1) + actor.bonus('athletics') + (assisted ? 2 : 0) + surface.mod + actor.woundModifier - actor.sustainingPenalty);
-                const climb = rollPool(pool);
-                // HITS BUY DISTANCE -- there is no threshold (p.134, Climbing
-                // Table: "Unassisted climbing upward, 1 meter per 2 hits"). This
-                // used to be a flat "2 hits or you fall", which is a rule the book
-                // does not have: it made a one-metre scramble and a three-storey
-                // face equally hard, and it made a strong climber's extra hits
-                // buy nothing.
-                const meters = climbSteps * METERS_PER_LEVEL;
-                // BANKED PROGRESS (p.134): hits buy metres per TEST, and a wall is
-                // climbed over successive actions. Anything already banked toward
-                // THIS spot counts; progress toward a different one does not
-                // transfer, or a player could bank a metre on one wall and cash it
-                // in across the room.
-                const banked = actor.climbProgress?.target === spot.name ? actor.climbProgress.meters : 0;
-                const remaining = Math.max(0, meters - banked);
-                // DOWN IS TWICE AS FAST (p.134: "Unassisted climbing down, 1 metre
-                // per hit"). The engine climbed down at the upward rate, so a
-                // runner picking their way off a catwalk paid the same toll as
-                // getting onto it -- the item's third gap.
-                const needed = climbHitsFor(remaining, assisted, down);
-                const gained = climbMetersFrom(climb.hits, assisted, down);
-                const reachedTotal = Math.min(meters, banked + gained);
-                // ARRIVAL IS DECIDED IN METRES, not in hits, because metres are
-                // what the rule buys. The two agree almost always and diverged on
-                // the rounding: `needed` is a CEILING, so a roll could carry you
-                // the full remaining distance and still fall a fraction short of
-                // the integer threshold. On a bench that printed "you get about
-                // 3m up" on a 3m wall and then, next attempt, "3m already banked,
-                // 1m to go" -- arrived and not arrived at once.
-                //
-                // `needed` stays for the ticker, where a whole number of hits is
-                // the useful thing to read.
-                const gotUp = !climb.glitch && (banked + gained) >= meters;
-                // Same one-rounding rule as the prose below: round the banked
-                // figure once and derive the remainder from it, or the ticker
-                // says "2m banked, 2m to go" on a 3m wall.
-                const shownBanked = Math.round(banked);
-                this.logger.meta(`  ${down ? 'Descend' : 'Climb'} ${meters}m${banked > 0 ? ` (${shownBanked}m already banked, ${Math.max(0, meters - shownBanked)}m to go)` : ''}${assisted ? ' -- ASSISTED (+2, 1m/hit)' : ''}${down && !assisted ? ' -- DOWN (1m/hit)' : ''}${surface.label ? ` [${surface.label}]` : ''} -- Gymnastics + Strength: ${formatRoll(climb)} (${needed} hits needed)`);
-                if (gotUp) {
-                    // Over the lip: the wall is done with you.
-                    actor.climbProgress = undefined;
-                }
-                if (!gotUp) {
-                    // A FAILED CLIMB IS NOT A FALL (p.134, Climbing Failures and
-                    // Glitches). Progress halts and you make a Reaction + Strength
-                    // test to HOLD ON; only failing THAT drops you. Falling
-                    // immediately was the engine's own invention, and it is the
-                    // half of this that made climbing feel arbitrary -- one bad
-                    // roll and gravity, with nothing in between.
-                    const hold = rollPool(Math.max(1, actor.reaction + actor.strength + actor.woundModifier - actor.sustainingPenalty));
-                    this.logger.meta(`  Hold on -- Reaction + Strength: ${formatRoll(hold)} (1 hit holds)`);
-                    const reached = reachedTotal;
-                    if (hold.hits >= 1) {
-                        // YOU KEEP THE METRES. This used to end "and climb back down",
-                        // throwing the whole attempt away -- which is what made a tall
-                        // wall unclimbable rather than merely slow. Hanging on with
-                        // progress banked is the book's own shape: another Complex
-                        // Action, from where you got to.
-                        actor.climbProgress = { target: spot.name, meters: reached };
-                        // THE TWO FIGURES HAVE TO ADD UP. Rounding each independently
-                        // printed "about 2m up" and "about 2m still above you" on a
-                        // 3m wall -- both are honest roundings of 1.5, and together
-                        // they describe a 4m climb. Caught on a repro bench, where a
-                        // reviewer would rightly have filed it as a maths bug.
-                        //
-                        // So the SHOWN height is rounded once and the remainder is
-                        // derived from it. The banked progress keeps the exact value:
-                        // the display is where the rounding belongs, not the state.
-                        const shownUp = Math.round(reached);
-                        const left = Math.max(0, meters - shownUp);
-                        this.actor.performAction(down ? 'climbs partway down toward' : 'climbs partway toward', `the ${spot.name}, and holds there`);
-                        // A DESCENT IS NOT AN ASCENT WITH A DIFFERENT RATE, and this
-                        // block is shared by both -- the rappel is routed away above,
-                        // so an UNASSISTED climb down falls through to here.
-                        //
-                        // `reached` is distance TRAVELLED, so going down it measures
-                        // how far you have come FROM THE TOP; height above the ground
-                        // is the remainder. Every sentence here read `reached` as
-                        // height and said "up" and "still above you" out loud, so a
-                        // runner picking their way off a catwalk was told they were
-                        // climbing it. Measured on a bench, descending a 3m ledge:
-                        //   "You get about 1m up ... about 2m still above you."
-                        // -- printed on the second of four `descend` commands.
-                        return down
-                            ? `You get about ${reached < 1 ? 'a body length' : `${shownUp}m`} down and it stops going anywhere -- ${climb.glitch ? 'a hold shears away under your weight' : 'no purchase left within reach'}. You hang on, boots wedged, ${left < 1 ? 'the ground within reach' : `about ${left}m still below you`}.${hint(` (Descend again to keep going${assisted ? '' : '; rope and a harness would let you rappel it'}.)`)}`
-                            : `You get about ${reached < 1 ? 'a body length' : `${shownUp}m`} up and it stops going anywhere -- ${climb.glitch ? 'a hold shears away under your weight' : 'no purchase left within reach'}. You hang on, boots wedged, ${left < 1 ? 'the lip within reach' : `about ${left}m still above you`}.${hint(` (Climb again to keep going${assisted ? '' : '; rope and a harness would double your rate'}.)`)}`;
-                    }
-                    // THE SECOND CHANCE (p.134 Climbing Failures and Glitches;
-                    // 6SmvvRRtn9eEMZSbF). Canon: the hold-on fails, you start to
-                    // fall, "and during the next Action Phase the character may
-                    // attempt to stop with a Reaction + Strength Test at a -2 dice
-                    // pool modifier". Two tests, not one, and this engine only ever
-                    // rolled the first.
-                    //
-                    // COMPRESSED, AND SAYING SO. The book puts a phase between them
-                    // because a fall takes time -- 20m per Combat Turn. Every drop
-                    // this engine can build is a few metres (METERS_PER_LEVEL is 3),
-                    // so there is no phase to wait for: the catch resolves in the
-                    // same breath as the slip. The MECHANIC is canon -- a second
-                    // attempt, at -2 -- and only the gap between them is missing,
-                    // which is the same translation the rappel makes above.
-                    //
-                    // THE FILED ITEM'S FRAMING WAS WRONG and the correction belongs
-                    // here: there is no general "arrest any fall" rule in SR5. The
-                    // RAG is explicit that a mid-fall save exists in exactly two
-                    // places, this one and a failed rappel. A character who walks
-                    // off a roof does not get it, and giving them one would be
-                    // inventing a rule the book does not have.
-                    const catchIt = rollPool(Math.max(1, actor.reaction + actor.strength - 2 + actor.woundModifier - actor.sustainingPenalty));
-                    this.logger.meta(`  Catch yourself -- Reaction + Strength -2: ${formatRoll(catchIt)} (1 hit stops the fall)`);
-                    // HOW HIGH YOU ACTUALLY ARE -- the one figure both the prose and
-                    // the damage below have to agree on, and the reason this is a
-                    // named variable rather than `reached` inline in three places.
-                    //
-                    // Going UP it is the distance climbed. Going DOWN it is what is
-                    // LEFT: `reached` counts travel from the top, so a runner two
-                    // metres down a three-metre wall is one metre off the deck, not
-                    // two. See the descent note in the hold-on branch above.
-                    const heightNow = down ? Math.max(0, meters - reached) : reached;
-                    const shownHeight = heightNow < 1 ? 'a body length' : `${Math.round(heightNow)}m`;
-                    if (catchIt.hits >= 1) {
-                        actor.climbProgress = { target: spot.name, meters: reached };
-                        this.actor.performAction('slips on', `the ${spot.name} climb, and catches themselves`);
-                        return `You come off -- and catch yourself a body length down, fingers screaming. You are still on the wall, about ${shownHeight} up.${hint(` (${down ? 'Descend' : 'Climb'} again to keep going.)`)}`;
-                    }
-                    // The grip goes: the wall takes back everything it gave.
-                    actor.climbProgress = undefined;
-                    // Fall from where you ACTUALLY ARE, not from the top -- and not
-                    // from the distance travelled either. Canon buys distance with
-                    // hits whether or not you finish, so a runner who barely left
-                    // the floor does not take a storey's worth of landing.
-                    //
-                    // THIS READ `reached` AND WAS INVERTED ON THE WAY DOWN, which is
-                    // the mechanical half of the descent bug: a runner 2m down a 3m
-                    // wall is 1m up and was billed for a 2m fall, while one who
-                    // slipped on the FIRST action of a descent was nearly a full
-                    // storey up and billed for nothing. Invisible on a 3m ledge --
-                    // both figures soak to zero damage, which is exactly how it
-                    // survived -- and real the moment the drop is worth any DV.
-                    const dv = fallDamageDVMeters(heightNow);
-                    let fallNote = `Your grip goes, and there's nothing to catch -- you come off the wall about ${shownHeight} up.`;
-                    if (dv > 0) {
-                        const soak = rollPool(actor.getSoakPool());
-                        const dealt = Math.max(0, dv - soak.hits);
-                        this.logger.meta(`  Fall damage: DV ${dv} (${Math.round(heightNow)}m, AP -4), Soak: ${formatRoll(soak)}`);
-                        if (dealt > 0) {
-                            actor.takeDamage(dealt);
-                            fallNote += ` The landing costs you ${dealt} box${dealt === 1 ? '' : 'es'}: ${actor.conditionSummary()}`;
-                        }
-                        else {
-                            fallNote += ` You hit hard but the armor eats it.`;
-                        }
-                    }
-                    else {
-                        fallNote += ` It's a short drop -- you land badly and nothing breaks.`;
-                    }
-                    this.actor.performAction('falls from', `a climb toward the ${spot.name}`);
-                    return fallNote;
-                }
-            }
+            const meters = climbSteps * METERS_PER_LEVEL;
+            // BANKED PROGRESS (p.134): anything already banked toward THIS
+            // spot counts; progress toward a different one does not transfer.
+            const banked = actor.climbProgress?.target === spot.name ? actor.climbProgress.meters : 0;
+            // The dice, the hold-on, the second chance and the fall all live
+            // in resolveClimb -- shared with retreatFromClimb, so coming back
+            // off a wall cannot drift from going up it.
+            const outcome = this.resolveClimb({
+                spot: spot.name, meters, banked, down,
+                // A forward climb starts on the ground; a descent starts at
+                // the top of the wall it is coming down.
+                heightAtStart: down ? meters : 0,
+                progressFor: reached => ({ target: spot.name, meters: reached }),
+            });
+            if (!outcome.arrived)
+                return outcome.text;
+            descentNote = outcome.note;
         }
         // BANKED CLIMB PROGRESS BELONGS TO ONE WALL. Anything that gets the
         // actor to a spot -- this move, a step, a walk across the floor --