Class SohlEventQueue

In-memory trigger dispatcher for SoHL.

Accessible at runtime as sohl.events.

Overview

Documents subscribe to triggers — named lifecycle moments shared with Foundry's CONFIG.ActiveEffect.expiryEvents vocabulary (updateWorldTime, combatStart, combatEnd, roundStart, roundEnd, turnStart, turnEnd, plus any custom names registered via registerSohlTrigger). When a trigger fires, matching subscriptions dispatch by executing the action named by the subscription's actionName on the owning document's logic — the trigger context (with the subscription's payload) becomes the action's scope. An event therefore reuses the very same action a user could invoke manually.

Time scheduling is one trigger among many: a scheduleAt(uuid, actionName, fireAt, payload) call creates a one-shot subscription on updateWorldTime that fires when world time reaches fireAt.

Identity and overwrite semantics

Each subscription is uniquely identified by (uuid, actionName). Re-subscribing with the same identity overwrites the previous entry. Documents re-register their subscriptions on every preparation cycle, so only the most recent registration matters.

Populate everywhere, fire on the active GM only

The queue is a pure projection of document state: every client — GM or player — populates its own copy from its own document preparation, so subscribe / unsubscribe / scheduleAt run on all clients. A player's queue is therefore a permission-scoped subset of the active GM's (it holds only the subscriptions for documents that client can see), which is exactly enough to answer sheet-side date queries (nextFireTime / timeUntil) locally.

Only fire is gated to the active GM. Nothing else evolves schedule state, so no GM-only side effect can drift the clients out of sync — schedule changes flow through document updates (which replicate) and their re-preparation.

Single-pass dispatch (no cascade)

A fire(ctx) dispatches each matching subscription once, from a snapshot taken at the start of the call. For updateWorldTime, "matching" additionally requires the subscription be due (fireAt undefined or <= worldTime), and due subscriptions dispatch in ascending fireAt order. Subscriptions a handler adds mid-dispatch are not re-fired within the same call — they wait for the next fire.

The queue deliberately does not catch up recurring events over a large time jump. That is the consuming document's responsibility: its handler resolves every elapsed interval in (lastAnchor, worldTime] in one pass and persists the advanced anchor, and its finalize() re-registers the single next occurrence beyond worldTime. See the Event Queue reference doc for the contract.

Loop protection

Re-entrant fire(...) for the same trigger name is capped at MAX_TRIGGER_DEPTH (16); beyond that the call aborts with an error. This backstops non-time loops (e.g. a combatStart handler that fires combatStart). Because there is no cascade, no same-tick guard is needed: a handler that re-arms during dispatch simply schedules a subscription that the next fire sees.

Predicate error policy

Predicates that throw are caught and logged; that dispatch is skipped; the subscription is not removed. Predicates may legitimately fail on stale data (e.g., resolving an effect that was just deleted) and one bad tick should not permanently disarm a check.