asterobot:chat

Say things in the game chat from a script through the bot's chat guard, which waits out a channel's cooldown and keeps to the server's limits, with templates that pick random wording, fill in the character's level, map or kamas, and link items from its inventory; switch the bot's chat module and pick its chat profiles while the script runs; answer the private messages the bot gets, and hear what the module does.

asterobot:chat lets your script say things in the game chat through the bot's chat module, and set the module while it runs. Every message the bot sends goes through the module's guard, which keeps to the limits the game server sets and says: your script's messages, the ones typed in the bot's Console, the module's ads, replies and triggers' messages, and the alarms' lines.

import {
  say, whisper, pause, resume,
  setVariable, variables, setFlag, flags, setDryRun, dryRun,
  enable, disable, enabled, setParts, parts, setProfiles, profiles,
  onChat, offChat, onAnswer, offAnswer,
} from "asterobot:chat";

These are the module's only exports. There's no chat object grouping them.

say() and whisper() return a promise. The other functions are synchronous.

The guard

The guard is the bot's one queue for chat messages. It sends one message at a time, and waits for the server's answer before the next: the server saying the message back, a refusal, or 5 seconds without an answer, which count as sent.

The person's messages, typed in the Console, go first. A pause, a back-off or the limit doesn't hold them back: only a channel's cooldown does. The alarms' lines come next, and a pause doesn't hold them back either. Then come the answers to commands, the replies and the triggers' messages, and last your script's messages and the ads.

say() and whisper()

say(channel, text) says a message in a channel. whisper(name, text) whispers it to the character of that name.

The promise resolves once the server took the message, with { dryRun: false }, or { dryRun: true } in a dry run. It rejects with an Error whose reason says why the message wasn't sent:

import { say, setVariable } from "asterobot:chat";
import { botWarn } from "asterobot:bot";

setVariable("price", 12);

try {
  await say("SALES", "{Selling|WTS} {item:289} at {price} k each, /w me");
} catch (error) {
  if (error.reason === "missingItem") botWarn("No more wheat to sell");
  else throw error;
}

When the script stops, its messages that are still waiting are dropped. A message already sent waits for its answer.

Templates

A template is the text of a message with parts that are filled in each time it is said.

Nothing broken goes out: a message isn't sent when one of its variables has no value, an item it links isn't in the inventory, or, filled in, it's longer than the game's 256 characters or links more than 16 items. The length counts each item link as the game's code for it, which is longer than the item's name, so that the server never finds the message too long.

A template can't be read when a { has no } or the reverse, when {} is empty, when a part like {a {name}} nests without a |, or when it has a colon that isn't an item link, such as {a:b}.

pause() and resume()

pause(seconds) stops the module's and your scripts' messages for that many seconds. Without seconds, it lasts until resume(). The messages waiting are dropped with "paused", and so are the ones said while it lasts. The person's messages from the Console still go.

A pause outlives the script that set it, like a button the person pressed.

import { pause } from "asterobot:chat";

// Nothing more for ten minutes.
pause(600);

setVariable() and variables()

setVariable(name, value) sets a variable your messages read as {name}. A number or a boolean is written as text; null or undefined deletes the variable. variables() returns your variables, as a copy.

The character's own variables, such as {name} or {level}, win over yours of the same name, and yours win over the bot's chat profiles'. Your variables last until the script stops, or until a newer script, after a reload, sets its own. The module's ads read them too.

setFlag() and flags()

setFlag(name) sets a flag, which the flag test of the bot's chat profiles reads (Conditions); setFlag(name, false) clears it. flags() returns the names of the flags set. Your flags last until the script stops, or until a newer script sets its own.

import { setFlag } from "asterobot:chat";

// The profile's "shop open" ad runs from now on.
setFlag("shopOpen");

setDryRun() and dryRun()

setDryRun(true) writes the module's and your scripts' messages to the bot's console instead of sending them: Dry run: would say in Trade: Selling [Wheat] at 12 k each. Everything else goes on as if they were sent, the limit of 6 a minute included. The person's messages from the Console are always sent. dryRun() says whether a dry run is on.

The dry run lasts until the script stops, or until a newer script sets its own.

enable(), disable() and enabled()

enable() switches the bot's chat module on while the script runs, and disable() off: with the module off, the bot posts no ad, answers no private message, fires no trigger, obeys no command and leaves its status alone. enabled() says whether the module runs now. The switch the person saved on the Chat tab comes back when the script stops.

On a relayed session, only the person's switch counts: enable() and disable() change nothing there, and enabled() says what the person set.

setParts() and parts()

setParts(parts) switches the parts it names while the script runs, the others staying as they are: setParts({ ads: false }) keeps the module on but stops its ads. parts() returns every part, on or off: { ads, replies, triggers, commands, status }.

setProfiles() and profiles()

setProfiles(list) sets the bot's chat profiles while the script runs, in order, in place of the person's. Each item is the name of a profile, as the bot's Chat tab lists it, or a profile object in the chat profile format, which crosses into Asterobot as JSON.stringify() writes it and is checked as a saved profile is. profiles() returns the profiles in effect, as plain objects in that format, copies: changing one changes nothing until you pass it to setProfiles().

import { setProfiles, setVariable } from "asterobot:chat";

setVariable("price", 11);
setProfiles([
  "Sell wheat in Astrub",
  {
    version: 1,
    name: "Script ad",
    ads: [{ channels: ["SALES"], messages: ["{item:289} at {price} k"], every: { min: 300, max: 600 } }],
  },
]);

The ads of a new list start over: their sends counted from zero, their first send as soon as they can. Setting the same profiles again keeps their counts. A profile's warnings, such as a variable no profile sets, go to the bot's console as chat.setProfiles[1]: <warning>.

onChat() and offChat()

onChat(handler) has handler hear what the module does, in the order it happens, until offChat(subscription) or the end of the script. Each event is an object:

Each field without a value is left out. The handler only observes: what it returns is ignored, and it can be async. A handler that throws stops the script.

A trigger with the script action gives an event of its own when that action's turn comes, after the actions before it are done, { type: "trigger", name, line }: the trigger's name, and the line it fired on, { senderName, senderAccountId, senderCharacterId, content, channel }, the ids as BigInts. A trigger without that action fires without the script hearing it.

import { onChat, whisper } from "asterobot:chat";

onChat(async (event) => {
  if (event.type !== "trigger" || event.name !== "wtb") return;

  const wanted = event.line.content.match(/\d+/)?.[0] ?? "some";
  await whisper(event.line.senderName, `{Hi|Hello} ${event.line.senderName}, I can sell you ${wanted}`);
});

import { onChat } from "asterobot:chat";
import { botWarn } from "asterobot:bot";

onChat(({ type, where, detail }) => {
  if (type === "soldOut") botWarn(`${where}: ${detail} sold out, restocking`);
});

onAnswer() and offAnswer()

onAnswer(handler) has handler asked first about each private message the bot's replies get, until offAnswer(subscription) or the end of the script. It's asked with { kind: "reply", line }, line being the message: { senderName, senderAccountId, senderCharacterId, content, channel }, the ids as BigInts. It answers:

The handler can be async: the bot waits up to 30 seconds for its answer, the reading and typing time running meanwhile. Past that, or when it throws or answers something else, the reply rules decide and the console says so. Its answers aren't counted by the profiles' answers per player, so it can hold a conversation. It's never asked about a message from one of your own bots or from a member of staff.

It's also asked about a command a profile takes but doesn't know, with { kind: "command", line, command, args }: !sell 10 wheat from a trusted sender is command "sell", args ["10", "wheat"]. A text answers the sender; nothing leaves the command ignored.

import { onAnswer } from "asterobot:chat";
import { memory } from "asterobot:bot";

onAnswer(({ kind, line }) => {
  if (kind !== "reply" || !/price|prix/i.test(line.content)) return;

  return `{Hi|Hello} {sender}, ${memory.get("wheatPrice") ?? 12} k each`;
});

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:chat then throws, or rejects for say() and whisper(), since there's no chat module to talk through.

Errors

These are thrown at once, or reject the promise of say() and whisper():

The bot's Console shows these lines: