asterobot:alarms

Raise an event of your own from a script for the alarms' rules to take, such as an item found under a price, and hear every event of the bot as it happens: a member of staff, a whisper, the character's name said, the chat module's events, a trigger's, and the game messages the rules hook.

asterobot:alarms connects your script to the bot's alarms. It raises events of its own, which the rules on the Alarms page take like any other, and it hears every event of the bot as it happens, whatever the rules say.

import { raise, onAlarm, offAlarm } from "asterobot:alarms";

These are the module's only exports.

raise()

raise(name, text?) raises the event script:<name> for the bot, its fields name and text. A rule taking script:<name>, or Every script event (script), fires on it, and its reactions read {name} and {text}.

import { raise } from "asterobot:alarms";

// A script scanning the marketplace found what it looks for.
raise("cheapItem", "Wheat at 8 k");

On the Alarms page, a rule with Events script:cheapItem and the reaction Notify shows "Bot-Name: script:cheapItem" with "Wheat at 8 k" in every open Asteroboard. The script decides what's worth an alarm; the person decides what follows.

onAlarm() and offAlarm()

onAlarm(handler) has handler hear every event of the bot, until offAlarm(subscription) or the end of the script, whether a rule takes it or not, except the events this script raised itself with raise(): a handler that raises what it hears can't loop. Each event is an object:

A game message is an event only while a rule on the Alarms page hooks it (game:<Message>): its fields are the message's, named as in the protocol with dots for nested ones, and json the whole message. To follow a message no rule hooks, listen to it with on() instead.

The handler only observes: what it returns is ignored, and it can be async. A handler that throws stops the script. The script hears its own raise() too.

import { onAlarm } from "asterobot:alarms";
import { stopTravel } from "asterobot:movement";
import { botWarn } from "asterobot:bot";

// Stop walking as soon as a member of staff shows up on the map, whatever the
// rules on the Alarms page do.
onAlarm(({ name, fields }) => {
  if (name !== "staff" || fields.reason !== "map") return;

  botWarn(`${fields.who} is on the map: standing still`);
  stopTravel();
});

While Asterobot reads declarations

When Asterobot reads a package's settings, steps and conditions, it runs the top level of its modules without a bot (see Declarations). Every function of asterobot:alarms then throws, since there's no bot to raise an event for.

Errors