Plugin events

A plugin listens with wt.on, inside onEnable: the name of a moment and a function to run. The function gets the event, e: who it is about (e.character), the event's own fields (e.place, e.amount), and for some events a way to change or stop what happens.

export default {
  onEnable(wt) {
    wt.on('place.enter', async (e) => {
      if (!e.place || !e.place.tags.includes('haunted')) return;
      await wt.gm.tell(e.character.name + ' feels the cold of a haunted place.');
    });
  },
};

A listener can wait on the world (await wt.places.get(...)); the turn waits for it, within the limits.

Each listener has a priority: lowest, low, normal (the default), high, highest or monitor. They run lowest first, so the highest has the last word, and each sees the event as the one before left it. Listeners at the same priority in different plugins run in the Plugins tab's run order.

• Cancelling. On an event that can be cancelled, e.cancel() stops what would have happened (a blow, a roll, a death), and e.uncancel() lets it happen after all. Calling e.cancel() on any other event is an error.
• Skipping cancelled events. The option ignoreCancelled: true skips your listener when an earlier one already cancelled the event.
• Monitor. A monitor listener sees the final event and can't change it: use it to keep records.

// a ward: blows taken in a warded place are halved, unless something already stopped them
wt.on('damage.before', { priority: 'high', ignoreCancelled: true }, async (e) => {
  if (e.dir !== 'taken') return;
  const here = await wt.places.here();
  if (here && here.tags.includes('warded')) e.amount = Math.floor(e.amount / 2);
});

// a monitor only watches: it sees the final amount
wt.on('damage.before', { priority: 'monitor' }, (e) => {
  wt.log('a blow of', e.amount, e.cancelled ? '(stopped)' : '');
});

What a listener changes is read back after it returns; the next listener sees it. The last column says whether the event fires inside a party fight's rounds (see below); a dash is a moment that isn't part of a fight.

place.enter and place.leave fire wherever a character moves: the storyteller moving them in a scene, a voyage, party travel, a plugin's moveTo, a landfall. What a listener tells the storyteller about a move made before a turn (a crossing that lands, a button that moves them) reaches that same turn; about the storyteller's own move in a scene, the next turn.

Plugins work together through events of their own. One announces a moment with wt.emit, named in dotted words (bounty.raised, guild.member-joined). Every other plugin that listens for that name hears it, in priority order, with e.character, the fields it carries, and e.from, the id of the plugin that sent it.

// the bounty ledger: a crime raises the bounty, and asks the other plugins what it comes to
const r = await wt.emit('bounty.raised', { amount: 120 });
if (!r.cancelled) c.store.bounty = (c.store.bounty || 0) + r.fields.amount;

// the harbour watch, another plugin: big bounties double, a pardoned pirate goes free
wt.on('bounty.raised', async (e) => {
  if (e.character.store.pardoned) return e.cancel();
  if (e.amount > 100) e.amount = e.amount * 2;
});

Listeners can change its fields or cancel it, just as with the game's own events, and the plugin that sent it reads back what they made of it: whether anyone heard (heard), whether one cancelled it (cancelled), and its fields. So an event can also ask a question: "may this pirate dock here?", answered by a port's plugin cancelling it or setting a price.

An event never comes back to the plugin that sent it, and events sent while another is being heard go at most three deep. Say in your plugin's description which events it sends and what they carry, so other plugins can listen. When you save, a listener on a name that is neither one of the game's events nor a dotted name of your own is refused, and one a letter away from the game's (turn.strat) asks if you meant that one.

A party fight is played in rounds: each hero acts, the blows land, then the round is told as one scene. Inside a round, plugins hear each hero's rolls (check.before, check.result, check.after), every blow before it lands (damage.before, npc.hurt), each foe's declared action (npc.turn: cancelling works, an extra action isn't told) and each hero's fall (death).

The events read from a told scene (turn.start, turn.end, moving between places, meetings, items, quests, defeats, a fight's start and end, story questions) are not fired for a round's shared scene. They fire again on the turns before and after the fight.

wt.gm.tell gives the storyteller a fact. Told before the scene is written (at turn.start, a roll, a blow, a death), it reaches this turn's storyteller. Told after the scene (turn.end and the other events read from it) or outside a turn (a new day, a timer, a button), it is held and told once, on that character's next turn.

wt.story(id, question, listener) asks a yes-or-no question about each scene. After each scene, the questions of every plugin in the world are judged together in one call, up to twelve; a clear yes runs that question's own listener and fires story. This is how a plugin notices what no tool marks: a contract taken, a revel joined, an order carried out.

wt.story('oath', 'Did the character swear an oath in this scene and mean it?', async (e) => {
  e.character.store.oaths = (e.character.store.oaths || 0) + 1;
  await wt.gm.remember('oaths', e.character.name + ' has sworn ' + e.character.store.oaths + ' oaths and is known to keep them.');
});

What a plugin does can set off moments for other plugins (a storyteller's tool that deals damage fires damage.before). These nest up to three deep; past that, the inner moments aren't fired.