Class BodyMindSoulCombat

Get the set of token IDs for combatants that currently "have initiative" (no actions queued on any down of the tracker). Defeated combatants are excluded.

Get a map of token IDs → action type for combatants with an action at resolutionTime === 0 (i.e., currently resolving this down). Defeated combatants are excluded. Type is taken from the first action found for each combatant.

Answer a delegated GM request over the shared gm-write response socket. No-ops when the request carried no id (same-client / legacy callers).

Clear the pending-resolve indicator for an action on every client.

Forward an advance request to the lead GM when this client isn't it. Shared by advanceTracker and advanceToNextResolution, whose delegation preambles are otherwise identical apart from the socket message type.

Fire bms.actionResolved for a batch of just-resolved actions, if any. Shared by advanceTracker and advanceToNextResolution — both fire it identically once their advance cycle's resolve() call and post-resolve merge are complete. No-ops when resolvingActions is empty.

Shared pass-aware lifecycle for every CRUD-shaped tracker mutator (addEffectToDown, addEffectsToDowns, updateEffectInDown, addActionToDown's plain queue branch, removeEffectFromDown, removeCombatantEffects, removeActionFromDown's find/delete step). This is the generalized form of the pattern updateActionInDown proved out narrowly first — see that method's doc comment.

Acquires (or attaches to) this combat's shared ResolvePass, hands mutatorFn the pass's own live downs array to mutate in place, then flushes the result through _flushResolvePass with auto-diffed swept-id sets before releasing the pass. Any of these methods called from inside a trigger script (e.g. a bms.combatDown-hooked ActiveEffect outcome) while this same combat's own advance cycle still has a pass open attaches to that same pass instead of doing an independent live-document read-modify-write — closing the same "hook-during-advance write race" updateActionInDown was fixed for, for every other tracker mutator too.

Why this makes deletion safe by construction. ResolvePass#mergeFromLive cannot on its own tell "this id is genuinely new, not yet flushed" apart from "this id was just deleted by this operation and the deletion must stick" — both look identical (absent from the pass's downs, still present in a fresh live read) unless told which ids were deliberately removed. This helper closes that gap automatically: it diffs the action/effect ids present in pass.downs before and after mutatorFn runs, and any id that disappeared is added to sweptActionIds/sweptEffectIds and forwarded to _flushResolvePass/mergeFromLive, which then skips re-merging it in from the live read. No caller of this helper has to remember to compute or pass those sets itself.

Paint the pending-resolve (hourglass) indicator for an action on every client.

Emit a delegated combat request to the lead GM and await its acknowledgement. Non-lead clients (players and secondary GMs) use this instead of writing.

Resolve a single instant (resolutionTime 0) action that has already been committed to down 0, coalescing it with any instant resolution already in flight for this combat.

Ownership model: the first caller with no batch open becomes the batch owner — it drains its own and every joiner's resolve against the shared pass.downs (the same reference the commit step already mutated — no fresh snapshot taken here), then performs the one merge+write and fires bms.actionResolved once with the full absorbed set. Later callers join: they resolve against the same pass.downs (safe because ItemActionData#resolve treats downs as a pure write sink, only ever pushing follow-up swings), write nothing, and simply await the batch's completion.

This method may block for the length of a human prompt, so it must never be awaited from inside the socket request queue — see the deferResolve option on addActionToDown.

Resolve exactly one action against a mutable downs snapshot.

Shared by the advance cycle (resolve, via the module-level _resolveOnce wrapper — which guards by actionId, using the combat's shared ResolvePass, so the same action can never be resolved twice if an advance and an instant batch race to pick it up) and the instant-action batch (_resolveInstantAction's owner/joiner branches, which call this directly — their actionId was already claimed at commit time in addActionToDown/updateActionInDown, so routing through _resolveOnce would see that claim and skip itself). downs is a pure write sink here — the action's own system.resolve only ever pushes follow-up swing/channel entries into downs[0].actions, never reads or removes from it, which is what makes several actions safely share one snapshot. In every current call site downs is pass.downs — the combat's shared resolve-pass snapshot — not a call-local one.

Prompt/resolve aborts signal distinctly from success (v0.7.2 follow-up). BmsPromptAbort/BmsResolveAbort (a cancelled target picker, template placement, etc.) are still caught here — they must never propagate as a real error — but instead of returning undefined indistinguishably from a genuine completion, this now returns { aborted: true } so callers (_resolveOnce, and the instant-resolve owner/joiner branches in _resolveInstantAction) can skip marking the action resolved and leave it retryable. Any other error still propagates to the caller unchanged. The pending-resolve indicator for this action is always cleared, success, abort, or failure.

Add an action to a down on the combat tracker.

The commit write is unconditional and immediate — it never waits on any lock, so a player's action always appears on the tracker right away even while the GM is blocked on another action's prompt. Instant actions (resolutionTime === 0) then resolve via _resolveInstantAction, joining whatever instant batch is already in flight.

Force-mark a single down-0 action resolved WITHOUT running its actual resolve effects (never calls _resolveOneAction/system.resolve()). Escape hatch for a stuck or broken action, exposed via the tracker's "Mark Resolved" GM context action — the caller is responsible for warning the GM first (see combat-tracker.mjs's confirmation dialog), since this deliberately skips real resolution: any damage/triggers/ prompts the action would have fired never happen.

Claimed (mid-flight) actions — targeted force-abort (v0.7.2 GM-escape- hatch follow-up). If actionId is currently claimed on the shared ResolvePass — i.e. genuinely stuck inside _resolveOneAction, most commonly blocked on an interactive prompt (target picker, template placement, a compel check, etc.) — this used to silently return with zero feedback, exactly the "genuinely hung prompt" case this function exists to rescue. It now:

1. Calls cancelPendingRequestForAction (prompts.mjs) to find and reject only the pending prompt request tied to this specific actionId — never a blanket cancel of every in-flight prompt (that would also cancel unrelated prompts for other actions; see .claude/contexts/combat.md's "Advance-During-Pending-Prompt Race").
2. If no matching request is found (an inconsistent state — e.g. the claim is held by a long-running synchronous trigger outcome, not a prompt), notifies the GM with an explicit error and returns without marking anything resolved, rather than no-op-ing silently.
3. Otherwise awaits the claim actually being released — the rejected prompt promise only starts the unwind; the in-flight _resolveOneAction's BmsPromptAbort catch and _resolveOnce's finally (or the instant-resolve owner/joiner branches' equivalent) still need their own turns of the event loop to actually release the claim — see _awaitClaimReleased. Times out and notifies an error (again, without marking resolved) rather than proceeding on a claim that might not really be free. Only once the claim is confirmed free does this proceed with the normal mark-resolved logic below, identical to the already-unclaimed case.

Mirrors the claim/flush/release shape every other resolve path uses (acquire the combat's shared ResolvePass, claim the id, mark it resolved, flush, release) but stops short of calling _resolveOneAction. No internal lead-GM delegation guard — same as removeActionFromDown — callers must gate on game.user === getLeadGM() and delegate via the markActionResolved socket message otherwise (see combat-socket.mjs).

Queue an action from the character sheet into the combat tracker.

Queue an embedded item action (glyph or gear) from the actor sheet. Computes player visibility the same way queueSwing does: characters see their own actions, and applied effects with tracker.revealActions modifications can override visibility. Decrements quantity for usable non-equipable items after queueing.

Queue a single swing onto the combat tracker.

Resolve one or more actions whose resolution time has reached zero.

GM-centralised: all swing triggers execute on the lead GM client. Interactive dialogs (target pickers, templates, compel checks, etc.) route to the appropriate user via promptFor. Multiple resolves run in parallel — each system.resolve pushes any next-swing / channel-loop entries into pass.downs[0].actions (atomic Array.push, so the union is the final state even under interleaving).

Resolve only the down-0 actions that are already due (resolutionTime <= 0) and unresolved, without running any of _processCombatSteps's decrement/sweep/tick/round bookkeeping.

This is the safe counterpart to advanceTracker()/ advanceToNextResolution() for the case where down 0 already holds one or more due-but-unresolved actions — e.g. because a prior advanceTracker()/advanceToNextResolution() call got interrupted (GM browser refresh) after committing an action to resolutionTime: 0, resolved: false but before resolve() finished. Calling either advance method again in that state would unconditionally decrement the stuck action to -1 on the very next call and sweep it out of the persisted downs array — silent, permanent data loss if the next attempt is also interrupted. resolveCurrentDown() never runs that decrement/sweep loop at all, so it can be clicked any number of times across any number of interruptions without ever discarding an unresolved action. See "Resolve Mode vs Advance Mode" in .claude/contexts/combat.md for the full design and the UI gating that routes the tracker's advance button here.

Uses the same lock/pass/claim/flush/release lifecycle as advanceTracker(): _delegateAdvanceIfNotLeadGM first, then the shared _advanceLock (reused rather than a separate lock — resolveCurrentDown and advanceTracker/advanceToNextResolution are mutually exclusive by UI construction already, since the tracker only ever shows one button mode at a time, but sharing the lock is a cheap extra guard against any caller reaching them outside that gated UI path), then a ResolvePass acquired/released exactly like the other two advance methods.

A no-op (after acquiring and releasing the lock/pass) if down 0 has no due-unresolved actions when called — this can happen if the UI's resolve-mode gating raced with a concurrent operation that already resolved everything due; safe to call defensively.

Fires bms.combatStarted after Foundry core commits round/turn state. hookArgs = [combat: BodyMindSoulCombat] — no extra payload, mirrors bms.combatDown.

Update an existing action in a down, instant-resolving it if the edit lands it at down 0. Same commit-then-resolve split as addActionToDown.

Pass-aware (v0.7.2 follow-up — "hook-during-advance write race" fix). Always acquires (or attaches to) the combat's shared ResolvePass and mutates pass.downs directly, instead of reading a one-off this.system.toObject() snapshot and writing it straight back. This matters when this method is called from inside a trigger script (e.g. a bms.combatDown-hooked ActiveEffect outcome, awaited synchronously by advanceTracker()/advanceToNextResolution() before those methods' _processCombatSteps even runs) while that same combat's own advance cycle still has a pass open: a raw toObject()-then-update() write in that window is invisible to the open pass's in-memory downs, and ResolvePass#mergeFromLive deliberately keeps the pass's own field content for entries it already knows about (only takes bucket position from a fresh live read) — so the advance's own next flush would silently revert this call's field changes right back out. Mutating pass.downs here closes that window structurally. _acquireResolvePass is safe to call unconditionally: when no advance is in flight it just creates a fresh pass from a fresh live snapshot, equivalent to the old raw read. (This method's instant-branch bypass and the plain-queue branch above it manage the pass by hand because they need to hold the claim across the instant-resolve handoff; every other CRUD-shaped tracker mutator — addEffectToDown, addEffectsToDowns, updateEffectInDown, addActionToDown's plain queue branch, removeEffectFromDown, removeCombatantEffects, removeActionFromDown's find/delete step — now routes through the shared _mutateDowns helper below, which generalizes this exact acquire/mutate/flush/release shape and additionally auto-diffs swept ids so deletions are safe under mergeFromLive too.)