Skip to main content

Event reference

nexMap4 publishes canonical, lowercase, dot-delimited nexmap4.* topics through the required Nexus EventStream host contract. This is the public event surface for other packages and scripts. nexMap4 does not emit nexMap3-style flat names such as nexMapRoomChanged or nexMapPathingComplete.

Subscribing​

Register a listener through the host eventStream:

eventStream.registerEvent("nexmap4.pathing.start", (payload) => {
console.log(payload.sourceId, payload.targetId, payload.executionMode);
});

Payloads are JSON-serializable plain objects. Each event carries the fields listed below.

Public topics​

TopicPayloadRaised when
nexmap4.room.changed{ roomId, rawTopic, receipt, responseId, source, sequence, timestampMs }Each distinct room commits immediately, after internal updates and hook invalidation.
nexmap4.room.changed.<id>Same as nexmap4.room.changed (<id> is the numeric room id).Immediately after nexmap4.room.changed, scoped to a specific room.
nexmap4.mnemosyne.ghost.reconciled{ roomId, syntheticRoomId, sourceRoomId, direction }Raised once after the factual GMCP node has replaced its ghost and its exits, outgoing edges, and graph notification are complete.
nexmap4.area.changed{ gameAreaName, gmcpAreaId, roomId }The current GMCP area name changes (after the room events).
nexmap4.pathing.start{ operationId, sourceId, targetId, executionMode, segmentCount, totalWeight }A travel operation starts: the travel runtime accepts a new planned path.
nexmap4.pathing.reroutedSame as nexmap4.pathing.start, plus reason.The operation continues on a re-planned route (locked door, wormhole, Nur rift).
nexmap4.pathing.complete{ operationId, sourceId, targetId, segmentIndex, finalRoomId, elapsedMs }Terminal. Matching destination Room.Info completes the operation synchronously, before waiting for population or a prompt.
nexmap4.pathing.blocked{ operationId, sourceId, targetId, segmentIndex, finalRoomId, reason, error? }Terminal. nexMap cannot finish the operation.
nexmap4.pathing.stopped{ operationId, sourceId, targetId, segmentIndex, finalRoomId, reason }Terminal. The operation was ended on request; reason: "replaced" when a new travel request superseded it.
nexmap4.pathing.segment.failedValidated failed-run result (details below)Once per failed mechanic run; never terminal, and a cancellation is not a failure.
nexmap4.bootstrap.phase{ phase, attempts, ready, completed }A startup phase transition (after the host adapter exists).

Travel operations​

Every trip nexMap starts is one travel operation, named by its operationId. The same id is returned as value.operationId from nexMap.api.travel.goto, toRoom, and toArea, and every nexmap4.pathing.* event carries it.

  • An operation ends with exactly one terminal event: complete, blocked, or stopped.
  • A re-route — a locked door, a missing or drifted wormhole, a moved Nur rift, a proven exit or travel failure, a displacement — continues the same operation and raises rerouted. Every re-plan shares one allowance of three per operation; an identical repeated re-plan is a loop. A re-plan that finds no route, or fails, ends it blocked with its cause (no-route, reroute-limit, reroute-loop or the failure's reason).
  • A paused (chase) route is never re-planned; a blocking reaction ends it blocked.
  • Starting new travel while an operation is open ends the old one stopped with reason: "replaced".

To follow one trip, match operationId. To cancel only your own trip, pass it to nexMap.api.travel.stop(reason, { operationId }).

Scoped room events​

nexmap4.room.changed.<id> lets a listener watch one specific room without filtering the global stream. It carries the same payload as the unscoped event and fires immediately after it.

Ordering​

For each distinct Room.Info, within the raw callback and without waiting for a prompt:

  1. nexmap4.room.changed
  2. nexmap4.room.changed.<id>
  3. nexmap4.area.changed (only when the area actually changed)

Before these events, current/previous room, visit and synchronous observed mapping are committed, the map and walker state are projected, and displaced hooks are invalidated. Same-room metadata refreshes do not raise another room event; a changed nonempty area name can still raise area.changed.

Nested room packets commit immediately. Their notifications join a FIFO queue behind the earlier observation's unscoped/scoped/area notifications. An event payload identifies its original observation; a callback that introduces another packet also changes the current snapshot immediately. Subscriber errors are isolated and reported.

Room events do not promise item/player population or response completion. Status/vitals and room lists keep their response buffering; receipt identities are retained. Matching destination Room.Info emits one pathing.complete within the raw callback, after projection and before public room events. It does not wait for execution markers, response settlement, a final arrival hook, or the queued path stop that a tracker arrival submits to close the server tracker. An already-satisfied destination completes immediately at start. Intermediate hooks and execution checks remain in force; retained outstanding submissions may still hold later dispatch. Later movement cannot rewrite the committed terminal outcome.

nexBash consumes completion by entering updatingRoom and waits for the destination Room.Players before scanning. This handshake expects that player push after Room.Info and before the closing prompt; travel completion itself is not a population-ready signal.

Events vs. state​

An event payload explains a transition; nexMap.state provides the current snapshot. Integrations that need the full current model should use the event as a signal and then re-read the appropriate state branch:

eventStream.registerEvent("nexmap4.room.changed", () => {
const { location } = nexMap.state; // fresh, frozen snapshot
});

Internal runtime EventBus​

The optional in-process EventBus mirrors application events for local consumers. Core travel can use the adapter directly. Integrations use the public EventStream topics above.

Failure detail and acceptance​

nexmap4.pathing.segment.failed contains operationId, planRevision, sourceId, targetId, segmentIndex, mechanicId, edgeIds, run, outcome: "failure", reason, certainty, submissionIds and compact evidence. Applicable detail includes roomId, phase, stageIndex, edgeId, displayedExit, disposition and mechanic-specific detail. Failed action detail includes bounded detail.wait (action identity, command, state, timing and compact evidence), retaining a failed recovery child after its parent closes. The real payload validates against SegmentFailedEventSchema. One failed run emits once even when it restarts; cancellation emits no failed-run event. Every terminal's finalRoomId is the actual current room or null.

Owner installation after plan validation is the operation acceptance boundary. A pre-start command error or explicit no-route result accepts no operation and owes no terminal event. Accepted empty plans, shutdown, disposal and service exceptions still owe exactly one terminal. An all-queue clear stops affected operations with queue-cleared before releasing waiters; it never automatically resumes travel or proves executed effects cancelled.

Fallback publishes available facts without proving prompt completion and retains the response identity until a genuine prompt. Frame snapshots and compact source/transition facts publish before semantic reducers; admission runs last. A newer response number alone cannot settle an older action. nexMap.api.travel.getDiagnostics() reads current bounded accounting without recording output. Runtime EventBus integration is optional; core travel also works directly through the adapter.