@maka/maka-cli 5.133.0 → 5.135.0

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

@@ -0,0 +1,568 @@
+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, for the autopilot hook. */
+    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/companion-heel.js

@@ -1,22 +1,80 @@
+import { actorCell, standingRoomNear, onTheFloor, heelsTo } from './spots.js';
+/** Chebyshev distance in cells, or undefined when either has no cell. */
+function cellGap(room, a, b) {
+    const ca = actorCell(room, a);
+    const cb = actorCell(room, b);
+    if (!ca || !cb)
+        return undefined;
+    return Math.max(Math.abs(ca.x - cb.x), Math.abs(ca.y - cb.y), Math.abs(ca.z - cb.z));
+}
+/** Is the shell beside its master -- same room, same spot, and at most
+ *  one square away (or on a room with no grid to measure)? */
+export function atMastersSide(entry, master) {
+    const room = master.currentLocation;
+    if (entry.npc.currentLocation !== room || entry.npc.atSpot !== master.atSpot)
+        return false;
+    const gap = cellGap(room, entry.npc, master);
+    return gap === undefined || gap <= 1;
+}
+/** Put the shell on the nearest free square beside its master, at the
+ *  master's spot. */
+export function placeBeside(entry, master) {
+    const room = master.currentLocation;
+    if (entry.npc.currentLocation !== room)
+        entry.npc.currentLocation = room;
+    entry.npc.atSpot = master.atSpot;
+    const here = actorCell(room, master);
+    entry.npc.atCell = here ? standingRoomNear(room, here, entry.npc) : undefined;
+}
 /**
  * BRING A COMPANION TO HEEL (player ruling 2026-09-06: "recall" is
  * "return to me" -- the frame comes to your side and follows again;
  * putting it away is "stow"). The shell crosses to the master's room
- * and spot, its cell is released so seating finds it a place beside
- * them, and any HOLDING flag clears so the next "go" drags it along
- * like any companion. Returns whether it had anywhere to come from.
+ * and spot, takes the nearest free square beside them, and any HOLDING
+ * flag clears so the next move drags it along like any companion.
+ * Returns whether it had anywhere to come from -- judged by CELLS, not
+ * spot names: a frame eight squares off on the same open floor shares
+ * the spot name and is not "at your side" (transcript 2026-09-06).
  *
  * One function, used by Game.heelCompanion and by the tests that pin
  * recall, so a mock Game and the real one cannot disagree about it.
  */
 export function bringToHeel(entry, master) {
-    const here = master.currentLocation;
-    const moved = entry.npc.currentLocation !== here || entry.npc.atSpot !== master.atSpot || !!entry.holding;
-    if (entry.npc.currentLocation !== here)
-        entry.npc.currentLocation = here;
-    entry.npc.atSpot = master.atSpot;
-    entry.npc.atCell = undefined;
+    const moved = !!entry.holding || !atMastersSide(entry, master);
+    placeBeside(entry, master);
     entry.holding = false;
     return { moved };
 }
+/**
+ * COMPANIONS TRAIL THEIR MASTER ACROSS THE ROOM (playtest 2026-09-06:
+ * "It will follow to another room, but then just sit at the door").
+ * go.ts heels every shell on a ROOM change; nothing did on an in-room
+ * move, so a rigger who paced eight squares across the Neon Strip left
+ * the frame parked in the doorway. Called after every successful
+ * in-room move (move.ts): each shell of the mover's that is on the
+ * floor here, not HOLDING and not hired crew, is re-placed beside them.
+ * The frame answers to the meat body only (go.ts HEELS_ON): a rigger
+ * flying one frame does not drag the others around.
+ */
+export function trailMaster(master, entries) {
+    if (master.plane !== 'meat')
+        return [];
+    const room = master.currentLocation;
+    const moved = [];
+    for (const entry of entries) {
+        if (entry.holding || entry.kind === 'ally')
+            continue;
+        if (!heelsTo(entry.npc, master))
+            continue;
+        if (entry.npc.currentLocation !== room || !onTheFloor(entry.npc))
+            continue;
+        if (entry.npc.isIncapacitated() || entry.npc.inExchange)
+            continue;
+        if (atMastersSide(entry, master))
+            continue;
+        placeBeside(entry, master);
+        moved.push(entry.npc);
+    }
+    return moved;
+}
 //# sourceMappingURL=companion-heel.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 };