@maka/maka-cli 5.134.0 → 5.136.0

package/bundle/typescript/src/commands/game/sideQuest/utilities/combat-turn.js

@@ -0,0 +1,571 @@
+import { rollInitiativeScore, formatInitiative, INITIATIVE_PASS_DROP, rollPool, formatRoll } from './dice.js';
+import { ActionBudget } from './action-budget.js';
+import { runNpcActionPhase } from './npc-combat-brain.js';
+export class CombatEncounter {
+    scene;
+    logger;
+    room;
+    /** The breath between phases so a fight reads as a fight. MAKA_NO_BEATS
+     *  zeroes it for harnesses. */
+    static BEAT_MS = 600;
+    /** A fight nobody can end (two immortal shells trading misses) is a
+     *  livelock, not a story: past this many Combat Turns the encounter
+     *  breaks off. Generous -- a real fight is over in three or four. */
+    static MAX_TURNS = 30;
+    turn = 0;
+    pass = 0;
+    ended = false;
+    participants = [];
+    /** Whose Action Phase is live, and their budget. */
+    phaseActor;
+    budget;
+    pairs = new Map();
+    surrenderSeenAt = new Map();
+    running = false;
+    /** Every human phase that began -- a seam for tests and for any future
+     *  phase clock; nothing plays the phase for a human (the fight
+     *  autopilot was retired 2026-09-07: a phase you commit with "end
+     *  turn" is yours to play). */
+    onHumanPhase;
+    constructor(scene, logger, room) {
+        this.scene = scene;
+        this.logger = logger;
+        this.room = room;
+    }
+    // ------------------------------------------------------------ setup ----
+    /**
+     * Opens the encounter: everyone rolls (surprise first, if it was an
+     * ambush), the order is announced, and the first pass runs until it
+     * reaches a human's Action Phase -- or the fight is already over.
+     */
+    async start(members, opts) {
+        this.turn = 1;
+        this.pass = 1;
+        for (const m of members)
+            this.addParticipant(m);
+        if (opts.target)
+            this.noteAttack(opts.aggressor, opts.target);
+        this.seedHostility();
+        const metaLines = ['Initiative (SR5 p.159):'];
+        const worldLines = [];
+        // SURPRISE (p.192): the ambushed side rolls Reaction + Intuition (3).
+        // Failure: -10 Initiative and no defense against the surprisers
+        // until their next Action Phase. The aggressor never rolls -- an
+        // ambusher is by definition not surprised (p.193).
+        if (opts.ambush) {
+            for (const p of this.participants) {
+                if (p.actor === opts.aggressor)
+                    continue;
+                if (this.sameSide(p.actor, opts.aggressor))
+                    continue;
+                const alerted = this.isNpc(p.actor) && p.actor.hostile ? 3 : 0;
+                const pool = Math.max(1, p.actor.reaction + p.actor.intuition + alerted + p.actor.woundModifier);
+                const roll = rollPool(pool);
+                if (roll.hits >= 3) {
+                    metaLines.push(`  ${p.actor.name} Surprise (Reaction + Intuition, 3): ${formatRoll(roll)} -- ready.`);
+                }
+                else {
+                    p.surprised = true;
+                    p.score -= INITIATIVE_PASS_DROP;
+                    metaLines.push(`  ${p.actor.name} Surprise (Reaction + Intuition, 3): ${formatRoll(roll)} -- SURPRISED (-10, no defense this pass).`);
+                    worldLines.push(`${p.actor.name} is caught flat-footed.`);
+                }
+            }
+        }
+        for (const p of this.order()) {
+            metaLines.push(`  ${p.actor.name}: ${formatInitiative(p.roll)}${p.score !== p.roll.score ? ` -> ${p.score}` : ''}`);
+        }
+        worldLines.push(`Combat Turn ${this.turn} -- ${this.orderLine()}.`);
+        this.scene.addWorldEvent(`A fight broke out in ${this.room.name}: ${this.participants.map(p => p.actor.name).join(', ')}.`);
+        await this.announce(worldLines, metaLines);
+        await this.run();
+    }
+    addParticipant(actor) {
+        const existing = this.participantOf(actor);
+        if (existing)
+            return existing;
+        const roll = rollInitiativeScore(actor.getInitiativeAttribute(), actor.getInitiativeDice());
+        // Rally (commands/lead.ts) is a banked +score bonus, consumed here;
+        // Combat Paralysis (p.80) halves the first score of a fresh fight.
+        let score = roll.score + (actor.rallyInitBonus ?? 0);
+        actor.rallyInitBonus = 0;
+        if (actor.paralysisFreeze) {
+            actor.paralysisFreeze = false;
+            score = Math.ceil(score / 2);
+        }
+        actor.resetMovementTurn();
+        actor.clearAim();
+        const p = {
+            actor, roll, score, woundAtSync: actor.woundModifier,
+            acted: false, delayed: false, surprised: false,
+        };
+        this.participants.push(p);
+        return p;
+    }
+    /**
+     * Someone walks into a running fight (p.160 Changing Initiative):
+     * roll as normal, minus 10 per pass already gone this turn.
+     */
+    join(actor) {
+        const p = this.addParticipant(actor);
+        const late = (this.pass - 1) * INITIATIVE_PASS_DROP;
+        if (late > 0)
+            p.score -= late;
+        this.logger.write(`Encounter ${this.room.name}: ${actor.name} joins at ${p.score} (pass ${this.pass}).`);
+        return p;
+    }
+    /**
+     * The seeded hostilities: every hostile NPC against every member of the
+     * party present; every party member against whoever their master's
+     * opponent is. Attacks add pairs as they happen (noteAttack).
+     */
+    seedHostility() {
+        const party = this.participants.filter(p => this.isPartySide(p.actor));
+        const street = this.participants.filter(p => !this.isPartySide(p.actor));
+        for (const s of street) {
+            if (!(this.isNpc(s.actor) && s.actor.hostile))
+                continue;
+            for (const p of party)
+                this.notePair(s.actor, p.actor);
+        }
+        for (const p of this.participants) {
+            const opp = p.actor.combatOpponent;
+            if (opp && this.participantOf(opp))
+                this.notePair(p.actor, opp);
+        }
+    }
+    // ---------------------------------------------------------- queries ----
+    participantOf(actor) {
+        return this.participants.find(p => p.actor === actor);
+    }
+    has(actor) {
+        return this.participantOf(actor) !== undefined;
+    }
+    isPhaseOf(actor) {
+        return !this.ended && this.phaseActor === actor;
+    }
+    budgetOf(actor) {
+        return this.isPhaseOf(actor) ? this.budget : undefined;
+    }
+    scoreOf(actor) {
+        return this.participantOf(actor)?.score ?? 0;
+    }
+    isSurprised(actor) {
+        return this.participantOf(actor)?.surprised === true;
+    }
+    fullDefenseActive(actor) {
+        return this.participantOf(actor)?.fullDefenseTurn === this.turn;
+    }
+    /** Present in the room, on their feet, still a participant. */
+    present(p) {
+        return p.actor.currentLocation === this.room && !p.actor.isIncapacitated();
+    }
+    isNpc(actor) {
+        return !this.scene.isHumanControlled(actor);
+    }
+    /** The party: humans and the shells bound to them. */
+    isPartySide(actor) {
+        if (this.scene.isHumanControlled(actor))
+            return true;
+        const ally = actor.allyOf;
+        return !!ally;
+    }
+    sameSide(a, b) {
+        return this.isPartySide(a) === this.isPartySide(b);
+    }
+    pairKey(a, b) {
+        return [a.name, b.name].sort().join('|');
+    }
+    notePair(a, b) {
+        if (a === b)
+            return;
+        const key = this.pairKey(a, b);
+        this.pairs.set(key, { a: a.name, b: b.name, notedAt: Date.now() });
+    }
+    /** An attack renews (or creates) the hostility between two actors. */
+    noteAttack(attacker, defender) {
+        if (!this.has(defender) && defender.currentLocation === this.room)
+            this.join(defender);
+        if (!this.has(attacker) && attacker.currentLocation === this.room)
+            this.join(attacker);
+        this.notePair(attacker, defender);
+    }
+    /**
+     * Is anyone still fighting anyone? A pair is live while both stand in
+     * the room, and neither has surrendered since the pair was last renewed
+     * by an attack -- hands up ends a fight unless somebody keeps shooting.
+     */
+    stillHostile() {
+        for (const pair of this.pairs.values()) {
+            const a = this.participants.find(p => p.actor.name === pair.a);
+            const b = this.participants.find(p => p.actor.name === pair.b);
+            if (!a || !b || !this.present(a) || !this.present(b))
+                continue;
+            if (this.surrenderBreaks(a.actor, pair) || this.surrenderBreaks(b.actor, pair))
+                continue;
+            return true;
+        }
+        return false;
+    }
+    surrenderBreaks(actor, pair) {
+        if (!actor.surrendered) {
+            this.surrenderSeenAt.delete(actor.name);
+            return false;
+        }
+        let seen = this.surrenderSeenAt.get(actor.name);
+        if (seen === undefined) {
+            seen = Date.now();
+            this.surrenderSeenAt.set(actor.name, seen);
+        }
+        return pair.notedAt <= seen;
+    }
+    /** The other side, present and standing, for a given actor. */
+    enemiesOf(actor) {
+        const out = [];
+        for (const pair of this.pairs.values()) {
+            if (pair.a !== actor.name && pair.b !== actor.name)
+                continue;
+            const otherName = pair.a === actor.name ? pair.b : pair.a;
+            const other = this.participants.find(p => p.actor.name === otherName);
+            if (!other || !this.present(other))
+                continue;
+            if (this.surrenderBreaks(other.actor, pair))
+                continue;
+            out.push(other.actor);
+        }
+        return out;
+    }
+    // ------------------------------------------------------------ order ----
+    /** ERIC (p.159): Edge, Reaction, Intuition, then a coin -- decided once
+     *  per participant so the order is stable across a pass. */
+    coin = new Map();
+    order() {
+        return [...this.participants].sort((x, y) => {
+            if (y.score !== x.score)
+                return y.score - x.score;
+            if (y.actor.edge !== x.actor.edge)
+                return y.actor.edge - x.actor.edge;
+            if (y.actor.reaction !== x.actor.reaction)
+                return y.actor.reaction - x.actor.reaction;
+            if (y.actor.intuition !== x.actor.intuition)
+                return y.actor.intuition - x.actor.intuition;
+            return this.coinFor(y) - this.coinFor(x);
+        });
+    }
+    coinFor(p) {
+        let c = this.coin.get(p.actor.name);
+        if (c === undefined) {
+            c = Math.random();
+            this.coin.set(p.actor.name, c);
+        }
+        return c;
+    }
+    orderLine() {
+        return this.order()
+            .filter(p => this.present(p))
+            .map(p => `${p.actor.name} ${p.score}`)
+            .join(', ');
+    }
+    /** The next participant owed an Action Phase this pass. */
+    nextActor() {
+        const ready = this.order().filter(p => this.present(p) && !p.acted && p.score > 0);
+        return ready.find(p => !p.delayed) ?? ready[0];
+    }
+    // ----------------------------------------------------- the pass loop ----
+    /**
+     * Advances the encounter until it needs a human (their Action Phase is
+     * live and waits for "end turn") or it is over. Re-entrant-safe: a
+     * nested call while a pass is already being driven returns at once.
+     */
+    async run() {
+        if (this.running || this.ended)
+            return;
+        this.running = true;
+        try {
+            while (!this.ended) {
+                this.syncWounds();
+                if (!this.stillHostile()) {
+                    await this.end('over');
+                    return;
+                }
+                if (this.phaseActor)
+                    return; // a human phase is live
+                const next = this.nextActor();
+                if (!next) {
+                    await this.endPass();
+                    continue;
+                }
+                await this.beginPhase(next);
+                if (this.scene.isHumanControlled(next.actor))
+                    return;
+                // An NPC's phase: the brain plays it, then the phase closes.
+                try {
+                    await runNpcActionPhase(this, next.actor);
+                }
+                catch (err) {
+                    this.logger.error(`Encounter: ${next.actor.name}'s phase failed: ${err}`);
+                }
+                this.closePhase(next);
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async beginPhase(p) {
+        this.phaseActor = p.actor;
+        this.budget = new ActionBudget();
+        p.surprised = false;
+        p.delayed = false;
+        p.actor.clearAim();
+        // Recoil resets the moment an Action Phase passes without firing --
+        // tracked by the phase, settled by attack.ts (p.175-176).
+        p.actor.firedThisPhase = false;
+        // p.162: "Running characters must use a Free Action in each
+        // Initiative Pass they are considered running." Already past the
+        // Walk Rate this turn means the phase opens with its Free Action
+        // spent on staying at a run.
+        if (p.actor.isRunningThisTurn)
+            this.budget.spend('free', 'Run (still running)');
+        const human = this.scene.isHumanControlled(p.actor);
+        if (human) {
+            const budgetLine = `Your Action Phase -- Combat Turn ${this.turn}, pass ${this.pass}, Initiative ${p.score}. ${this.budget.describe()}; ${this.movementLine(p.actor)}. "end turn" when you're done.`;
+            this.logger.log(`\n{cyan-fg}${budgetLine}{/cyan-fg}`, { actor: p.actor.name });
+            this.scene.updateStatus();
+            this.onHumanPhase?.(p.actor, this);
+            return;
+        }
+        await this.announce([`${p.actor.name} acts (Initiative ${p.score}).`], []);
+    }
+    movementLine(actor) {
+        const left = actor.movementLeftMeters;
+        const walkLeft = Math.max(0, actor.walkRateMeters - actor.movedMetersThisTurn);
+        return `${left} m of movement left this turn (${walkLeft} m at a walk)`;
+    }
+    /** The human typed "end turn" (or lost the phase -- fled, dropped). */
+    async endPhase(actor) {
+        const p = this.participantOf(actor);
+        if (!p || this.phaseActor !== actor)
+            return;
+        this.closePhase(p);
+        this.scene.updateStatus();
+        await this.run();
+    }
+    /** Delay (p.161): step back and act after the others this pass. */
+    async delayPhase(actor) {
+        const p = this.participantOf(actor);
+        if (!p || this.phaseActor !== actor)
+            return;
+        // Only meaningful if someone else is still to act this pass.
+        const others = this.order().filter(o => o !== p && this.present(o) && !o.acted && o.score > 0);
+        p.delayed = true;
+        this.phaseActor = undefined;
+        this.budget = undefined;
+        if (others.length === 0) {
+            // Nobody left to wait for -- the delayed phase is simply now.
+            p.delayed = false;
+            await this.beginPhase(p);
+            return;
+        }
+        this.scene.updateStatus();
+        await this.run();
+    }
+    closePhase(p) {
+        // A progressive-recoil phase without a shot resets the count (p.175).
+        if (!p.actor.firedThisPhase)
+            p.actor.recoilRoundsFired = 0;
+        p.acted = true;
+        p.delayed = false;
+        this.phaseActor = undefined;
+        this.budget = undefined;
+        this.scene.notifyExchangeSettled(this.participants.map(x => x.actor));
+    }
+    /** The phase actor has left the room or fallen: the pass moves on. */
+    async dropPhaseActor(actor) {
+        if (this.phaseActor !== actor)
+            return;
+        const p = this.participantOf(actor);
+        if (p)
+            this.closePhase(p);
+        await this.run();
+    }
+    /**
+     * An actor walks out of the room (commands/go.ts): they are no longer
+     * a participant. If it was their phase the pass moves on; if nobody
+     * left is fighting anybody, the encounter ends. Synchronous by design
+     * -- the caller is mid-move -- so the continuation is kicked off, not
+     * awaited; with no human left in the room nothing it prints is seen.
+     */
+    leave(actor) {
+        const p = this.participantOf(actor);
+        if (!p || this.ended)
+            return;
+        if (this.phaseActor === actor)
+            this.closePhase(p);
+        this.participants = this.participants.filter(x => x !== p);
+        actor.clearAim();
+        if (!this.stillHostile()) {
+            void this.end('left');
+            return;
+        }
+        void this.run();
+    }
+    /** p.159: everyone drops 10; anyone above zero goes again. */
+    async endPass() {
+        for (const p of this.participants) {
+            p.score -= INITIATIVE_PASS_DROP;
+            p.acted = false;
+            p.delayed = false;
+        }
+        const again = this.participants.filter(p => this.present(p) && p.score > 0);
+        if (again.length > 0) {
+            this.pass += 1;
+            await this.announce([], [`Initiative Pass ${this.pass}: everyone -10 -> ${this.orderLine()}.`]);
+            return;
+        }
+        await this.newTurn();
+    }
+    /** p.159 step 5: a fresh Combat Turn -- fresh rolls, fresh movement. */
+    async newTurn() {
+        if (this.turn >= CombatEncounter.MAX_TURNS) {
+            await this.end('burnout');
+            return;
+        }
+        this.turn += 1;
+        this.pass = 1;
+        const metaLines = [`Combat Turn ${this.turn} -- new Initiative (p.159):`];
+        for (const p of this.participants) {
+            p.roll = rollInitiativeScore(p.actor.getInitiativeAttribute(), p.actor.getInitiativeDice());
+            p.score = p.roll.score + (p.actor.rallyInitBonus ?? 0);
+            p.actor.rallyInitBonus = 0;
+            p.woundAtSync = p.actor.woundModifier;
+            p.acted = false;
+            p.delayed = false;
+            p.surprised = false;
+            p.actor.resetMovementTurn();
+            if (this.present(p))
+                metaLines.push(`  ${p.actor.name}: ${formatInitiative(p.roll)}`);
+        }
+        await this.announce([`Combat Turn ${this.turn} -- ${this.orderLine()}.`], metaLines);
+    }
+    // ------------------------------------------------- score adjustments ----
+    /**
+     * p.160: wound modifiers hit the Initiative Score the moment the wound
+     * lands. The attribute already carries woundModifier, so the score
+     * moves by the DIFFERENCE since the last look.
+     */
+    syncWounds() {
+        for (const p of this.participants) {
+            const now = p.actor.woundModifier;
+            if (now === p.woundAtSync)
+                continue;
+            p.score += now - p.woundAtSync;
+            p.woundAtSync = now;
+        }
+    }
+    /**
+     * An Interrupt Action (p.167-168): affordable only with enough score
+     * left -- "his Initiative Score is already in the negatives so he
+     * can't" (p.191). Returns the refusal, or undefined after paying.
+     */
+    spendInterrupt(actor, cost, label) {
+        const p = this.participantOf(actor);
+        if (!p)
+            return `${actor.name} isn't in this fight.`;
+        if (p.surprised)
+            return `${actor.name} is surprised -- no interrupt actions until their next Action Phase (SR5 p.192).`;
+        if (p.score < cost) {
+            return p.score <= 0
+                ? `${actor.name} has no Initiative Score left this turn -- ${label} needs ${cost} (SR5 p.168).`
+                : `${actor.name} has only ${p.score} Initiative left -- ${label} costs ${cost} (SR5 p.168).`;
+        }
+        p.score -= cost;
+        this.logger.meta(`  ${actor.name}: ${label} (-${cost} Initiative -> ${p.score})`, undefined, { room: this.room.name });
+        return undefined;
+    }
+    /** Full Defense (p.191): -10, Willpower to every defense this turn. */
+    declareFullDefense(actor) {
+        const p = this.participantOf(actor);
+        if (!p)
+            return `You're not in a fight.`;
+        if (p.fullDefenseTurn === this.turn)
+            return `You're already on Full Defense this Combat Turn.`;
+        const refusal = this.spendInterrupt(actor, 10, 'Full Defense');
+        if (refusal)
+            return refusal;
+        p.fullDefenseTurn = this.turn;
+        return undefined;
+    }
+    // -------------------------------------------------------------- end ----
+    async end(reason) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.phaseActor = undefined;
+        this.budget = undefined;
+        for (const p of this.participants) {
+            p.actor.clearAim();
+            p.actor.recoilRoundsFired = 0;
+            p.actor.firedThisPhase = false;
+        }
+        this.scene.endEncounter(this);
+        const line = reason === 'burnout'
+            ? `The fight in ${this.room.name} burns out -- nobody can land the finishing blow.`
+            : reason === 'left'
+                ? `The fight in ${this.room.name} is over -- nobody left to fight.`
+                : `The fight in ${this.room.name} is over.`;
+        await this.announce([line], []);
+        this.scene.updateStatus();
+        // Spirits whose services ran out depart once the dust settles.
+        this.scene.ownerGame?.settleSpiritServices?.();
+    }
+    // ------------------------------------------------------------ output ----
+    /** A human is present in the room to see it. */
+    witnessed() {
+        return this.scene.getPlayers().some(p => p.currentLocation === this.room);
+    }
+    async announce(lines, meta) {
+        if ((lines.length === 0 && meta.length === 0) || !this.witnessed())
+            return;
+        const scope = { room: this.room.name };
+        for (const m of meta)
+            this.logger.meta(m, undefined, scope);
+        if (lines.length > 0)
+            this.logger.log(`\n${lines.join('\n')}`, scope);
+        this.scene.updateStatus();
+        const beat = process.env.MAKA_NO_BEATS === '1' ? 0 : CombatEncounter.BEAT_MS;
+        if (beat > 0)
+            await new Promise(resolve => setTimeout(resolve, beat));
+    }
+    /** The initiative tracker, for the "initiative" verb. */
+    trackerLines() {
+        const out = [`Combat Turn ${this.turn}, Initiative Pass ${this.pass}${this.phaseActor ? ` -- ${this.phaseActor.name}'s Action Phase` : ''}`];
+        for (const p of this.order()) {
+            const state = !this.present(p) ? (p.actor.isIncapacitated() ? 'down' : 'gone')
+                : p.actor.surrendered ? 'surrendered'
+                    : p.acted ? 'acted' : p.delayed ? 'delaying' : p.score > 0 ? 'to act' : 'spent';
+            const marks = [
+                p.surprised ? 'surprised' : '',
+                p.fullDefenseTurn === this.turn ? 'full defense' : '',
+                p.actor.aimBonus > 0 ? `aiming +${p.actor.aimBonus}` : '',
+            ].filter(Boolean).join(', ');
+            out.push(`  ${p.actor === this.phaseActor ? '>' : ' '} ${p.actor.name.padEnd(18)} ${String(p.score).padStart(3)}  ${state}${marks ? ` (${marks})` : ''}`);
+        }
+        if (this.budget && this.phaseActor) {
+            out.push(`  Actions: ${this.budget.describe()} -- spent: ${this.budget.ledger()}.`);
+        }
+        return out;
+    }
+    /** The HUD line for one player. */
+    hudLine(player) {
+        const p = this.participantOf(player);
+        if (!p)
+            return undefined;
+        if (this.phaseActor === player && this.budget) {
+            return `{cyan-fg}⏱ YOUR PHASE{/cyan-fg} T${this.turn}/P${this.pass} Init ${p.score} · ${this.budget.describe()} · ${player.movementLeftMeters} m · "end turn"`;
+        }
+        const who = this.phaseActor ? `${this.phaseActor.name} acting` : 'resolving';
+        return `⏱ COMBAT T${this.turn}/P${this.pass} Init ${p.score} · ${who}${p.fullDefenseTurn === this.turn ? ' · FULL DEFENSE' : ''}`;
+    }
+}
+//# sourceMappingURL=combat-turn.js.map

package/bundle/typescript/src/commands/game/sideQuest/utilities/dice.js

@@ -34,6 +34,18 @@ export function scriptRolls(hits) {
 export function scriptedRollsRemaining() {
     return scriptedHits?.length ?? 0;
 }
+/**
+ * THE INITIATIVE SEAM, the summed-dice twin of scriptRolls: each entry
+ * is the dice TOTAL the next rollInitiativeScore call shows (the
+ * attribute is still added on top). A Combat Turn test that wants "the
+ * guard acts before the runner" pins two totals rather than spying on
+ * Math.random -- which would also pin every pool rolled in between.
+ * Engine code never calls this.
+ */
+let scriptedInitiative;
+export function scriptInitiative(totals) {
+    scriptedInitiative = totals ? [...totals] : undefined;
+}
 export function rollPool(pool, limit, opts = {}) {
     const size = Math.max(0, Math.floor(pool));
     const scripted = scriptedHits && scriptedHits.length > 0 ? scriptedHits.shift() : undefined;
@@ -106,6 +118,14 @@ export const MAX_INITIATIVE_DICE = 5;
 export function rollInitiativeScore(attribute, dice) {
     const attr = Math.max(0, Math.floor(attribute));
     const size = Math.min(MAX_INITIATIVE_DICE, Math.max(0, Math.floor(dice)));
+    const scripted = scriptedInitiative && scriptedInitiative.length > 0 ? scriptedInitiative.shift() : undefined;
+    if (scripted !== undefined) {
+        // Faces that add up to the scripted total (clamped to what the dice
+        // can show); the total is what every caller reads.
+        const total = Math.max(size, Math.min(size * 6, Math.floor(scripted)));
+        const rolls = Array.from({ length: size }, (_, i) => Math.min(6, Math.max(1, Math.floor(total / size) + (i < total % size ? 1 : 0))));
+        return { attribute: attr, dice: size, rolls, total: size === 0 ? 0 : total, score: attr + (size === 0 ? 0 : total) };
+    }
     const rolls = Array.from({ length: size }, () => 1 + Math.floor(Math.random() * 6));
     const total = rolls.reduce((sum, r) => sum + r, 0);
     return { attribute: attr, dice: size, rolls, total, score: attr + total };

package/bundle/typescript/src/commands/game/sideQuest/utilities/movement-cost.js

@@ -0,0 +1,80 @@
+import { Player } from '../models/player.js';
+import { rollPool, formatRoll } from './dice.js';
+import { physicalLimit } from './grapple.js';
+import { hint } from './hints.js';
+import { billAction, encounterOf } from './action-cost.js';
+/**
+ * GROUND COSTS IN A FIGHT (SR5 p.161-162, RAG-checked 2026-09-06).
+ *
+ * The rates are the Player's (walkRateMeters, runRateMeters, the
+ * whole-turn movedMetersThisTurn); this is the one place a crossing is
+ * BILLED against them, shared by move.ts, the melee reach in attack.ts,
+ * and the NPC brain so the three cannot drift:
+ *
+ *   - Up to the Walk Rate, movement is free of actions.
+ *   - "As soon as a character exceeds their Walk Rate they are
+ *     considered Running until the end of the Combat Turn" -- and
+ *     "Running characters must use a Free Action in each Initiative
+ *     Pass they are considered running" (p.162). The first crossing
+ *     that breaks the Walk Rate spends the phase's Free Action; the
+ *     encounter charges it again at the start of every later phase in
+ *     the turn (combat-turn.ts beginPhase). No Free Action left means
+ *     no breaking into a run this phase.
+ *   - Past the Run Rate needs a SPRINT: a Complex Action, Running +
+ *     Strength [Physical], +2 m per hit (+1 for dwarfs and trolls,
+ *     which this engine has no character for -- Player.SPRINT_METERS_PER_HIT).
+ *
+ * Out of combat everything here is a no-op returning undefined: a walk
+ * across a bar is not a Combat Turn.
+ */
+export function spendMovementMeters(scene, actor, meters, mode, logger) {
+    const enc = encounterOf(scene, actor);
+    if (!enc || enc.ended)
+        return undefined;
+    if (meters <= 0)
+        return undefined;
+    if (!enc.isPhaseOf(actor)) {
+        return `It's not your Action Phase -- movement happens on your turn (SR5 p.161).`;
+    }
+    // THE SPRINT (p.162): Complex Action, rolled when asked for, never
+    // applied silently to cover a shortfall.
+    if (mode === 'sprint' && actor.sprintMetersThisTurn === 0) {
+        const bill = billAction(scene, actor, 'complex', 'Sprint');
+        if (bill)
+            return bill;
+        const skill = actor.skillRating('running');
+        const roll = rollPool(Math.max(1, skill + actor.strength + actor.bonus('athletics') + actor.woundModifier), physicalLimit(actor));
+        const bought = roll.hits * Player.SPRINT_METERS_PER_HIT;
+        actor.sprintMetersThisTurn = bought;
+        logger?.meta(`Sprint (Running + Strength [Physical]): ${formatRoll(roll)} -- +${bought} m this turn`);
+    }
+    const left = actor.movementLeftMeters;
+    if (meters > left) {
+        return left <= 0
+            ? `You've covered all your ground this Combat Turn (${actor.runRateMeters} m at a dead run). Nothing left in the legs until the next turn.`
+            : `That's ${meters.toFixed(1)} m and you have ${left.toFixed(1)} m left this turn (Run Rate ${actor.runRateMeters} m).${hint(` ("sprint" buys more ground -- a Complex Action, Running + Strength.)`)}`;
+    }
+    // BREAKING INTO A RUN costs the phase's Free Action (p.162).
+    const wasRunning = actor.isRunningThisTurn;
+    const willRun = actor.movedMetersThisTurn + meters > actor.walkRateMeters;
+    if (willRun && !wasRunning) {
+        const bill = billAction(scene, actor, 'free', 'Run');
+        if (bill) {
+            const walkLeft = Math.max(0, actor.walkRateMeters - actor.movedMetersThisTurn);
+            return `${bill} Running takes a Free Action (SR5 p.162) -- you can still walk ${walkLeft.toFixed(1)} m.`;
+        }
+    }
+    actor.movedMetersThisTurn += meters;
+    return undefined;
+}
+/** A line for the player after a crossing that changed their pace. */
+export function paceNote(scene, actor, wasRunning) {
+    const enc = encounterOf(scene, actor);
+    if (!enc || enc.ended)
+        return '';
+    if (actor.isRunningThisTurn && !wasRunning) {
+        return ` You're RUNNING now -- -2 dice on everything else this Combat Turn, harder to hit at range (SR5 p.162).`;
+    }
+    return '';
+}
+//# sourceMappingURL=movement-cost.js.map