Events

nexSys announces changes as they happen, such as an affliction gained, a balance recovered, or a queue firing. Your scripts and other packages can listen and react.

Listening

Packages and Nexus reflex scripts listen through the Nexus eventStream global:

eventStream.registerEvent(
  "nexsys4.aff.got",
  (payload) => {
    console.log(payload.name);
  },
  { id: "my-package:aff-got", tags: ["my-package"] },
);

Remove it again with eventStream.removeListener("nexsys4.aff.got", "my-package:aff-got"). To run setup code once nexSys is ready, listen for nexsys4.system.loaded, or see Customizing nexSys.

Every payload includes topic and at, the time it was published. Events with a scoped variant can also be targeted by appending the value shown in angle brackets. For example, nexsys4.aff.got.asthma fires only for asthma, while nexsys4.aff.got fires for every affliction gained.

From JavaScript you can also listen with nexSys.events.on(topic, listener). It carries these events plus a few JavaScript-only ones, listed in All event topics.

The tables below are generated from nexSys's topic registry. If an event isn't listed here, it isn't part of nexSys's EventStream contract.

Runtime and system

Event	Scoped variants	Description
nexsys4.runtime.started	none	Runtime startup completed.
nexsys4.runtime.stopped	none	Runtime shutdown completed.
nexsys4.raw.gmcp	none	Raw GMCP payload observed at the adapter boundary.
nexsys4.system.vitals.changed	none	Character vitals changed.
nexsys4.system.health.changed	none	Health changed.
nexsys4.system.mana.changed	none	Mana changed.
nexsys4.system.rage.changed	none	Rage changed.
nexsys4.system.bleed.changed	none	Bleed changed.
nexsys4.system.status.changed	none	Character status snapshot changed.
nexsys4.system.class.changed	none	Character class changed.
nexsys4.system.target.changed	none	Current target changed.
nexsys4.system.pause.changed	none	Runtime pause state changed.
nexsys4.system.paused	none	Runtime paused.
nexsys4.system.unpaused	none	Runtime unpaused.
nexsys4.system.loaded	none	Startup game-state initialization completed.
nexsys4.system.death.detected	none	Death was detected from character state.
nexsys4.system.mount.changed	none	Mounted state changed.
nexsys4.system.wielded.changed	none	Wielded equipment changed.

Afflictions, defences, balances, and limbs

Event	Scoped variants	Description
nexsys4.aff.got	nexsys4.aff.got.<name>	Affliction became active.
nexsys4.aff.lost	nexsys4.aff.lost.<name>	Affliction was cured or removed.
nexsys4.aff.stack.changed	nexsys4.aff.stack.changed.<name>	Affliction stack count changed.
nexsys4.def.got	nexsys4.def.got.<id>	Defence became active.
nexsys4.def.lost	nexsys4.def.lost.<id>	Defence expired or was removed.
nexsys4.balance.got	nexsys4.balance.got.<id>	Balance became available.
nexsys4.balance.lost	nexsys4.balance.lost.<id>	Balance was consumed or lost.
nexsys4.balance.reset	nexsys4.balance.reset.<id>	Balance timing was reset.
nexsys4.balance.duration.observed	nexsys4.balance.duration.observed.<id>	Observed balance recovery duration changed.
nexsys4.eqbal.got	none	Balance and equilibrium are both available.
nexsys4.limb.updated	nexsys4.limb.updated.<limb>	Limb damage or break state changed.

Room and items

Event	Scoped variants	Description
nexsys4.room.changed	none	Current room identity changed synchronously at ingestion (id, name, exits).
nexsys4.room.features.changed	none	Current room walls, frozen ground, or catalog-relative completeness changed synchronously.
nexsys4.item.room.added	none	An item appeared in the current room.
nexsys4.item.room.removed	none	An item left the current room.
nexsys4.item.room.updated	none	A current-room item changed.
nexsys4.item.room.list	none	Current-room item list snapshot received.
nexsys4.item.inv.added	none	An item was added to inventory.
nexsys4.item.inv.removed	none	An item was removed from inventory.
nexsys4.item.inv.updated	none	An inventory item changed.
nexsys4.item.inv.list	none	Inventory item list snapshot received.

Cache, queues, rules, and serverside

Event	Scoped variants	Description
nexsys4.cache.amount.changed	none	Cached item counts changed.
nexsys4.cache.inventory.list	none	Inventory cache snapshot applied.
nexsys4.cache.rift.list	none	Rift cache snapshot applied.
nexsys4.queue.sent	nexsys4.queue.sent.<queueName>	A queue submission was accepted by the server.
nexsys4.queue.fired	nexsys4.queue.fired.<queueName>	A queue fire was acknowledged for a named queue.
nexsys4.queue.fired.ack	none	Queue fire acknowledgement was recorded.
nexsys4.serverside.aff.priority.set	nexsys4.serverside.aff.priority.set.<id>	Live serverside affliction priority confirmation was observed.
nexsys4.serverside.def.priority.set	nexsys4.serverside.def.priority.set.<id>	Live serverside defence priority confirmation was observed.
nexsys4.rule.activated	nexsys4.rule.activated.<id>	Declarative rule became active.
nexsys4.rule.deactivated	nexsys4.rule.deactivated.<id>	Declarative rule stopped being active.

Contract notes

• Base and scoped events receive the same payload object.
• Scoped events are available only where a scoped variant is listed.
• nexsys4.raw.gmcp is emitted only when nexSys is started with the publishRawGmcp option.
• Adapter-local events such as PromptEvent, NoticeEvent, TargetSetEvent, and TargetChanged are not nexSys4 events.