Declare actions

An action is a button your package adds to the bot's page. Clicking it calls a function of the running script, with values the person can fill in first. Actions suit one-off things someone decides while the bot plays: report something, say something, move on to the next step. For a choice that should last, declare a setting instead.

Declare an action

Actions are declared next to settings, as an object exported as actions from index.js. Each key is the action's name, and each value describes the button and holds the function it runs.

import { session, botInfo } from "asterobot:bot";
import { on, send } from "asterobot:protocol";

// The last pods the game reported, for the report action.
let lastWeight;

/** @type {BehaviorActions} */
export const actions = {
  reportPods: {
    label: "Report pods",
    description: "Writes the character's pods to the bot's console.",
    run() {
      if (!lastWeight) {
        botInfo("The game hasn't reported the pods since the script started.");
        return;
      }

      botInfo(`Pods: ${lastWeight.inventoryWeight} / ${lastWeight.weightMax}`);
    },
  },
  say: {
    label: "Say in chat",
    description: "Sends a chat message as the character.",
    args: {
      text: { type: "string", label: "Message", placeholder: "Hello!" },
      channel: {
        type: "string",
        label: "Channel",
        choices: [
          { value: "GLOBAL", label: "General" },
          { value: "GUILD", label: "Guild" },
          { value: "PARTY", label: "Party" },
        ],
      },
    },
    async run({ text, channel }) {
      // A failed action is reported to the person who clicked, and the script
      // keeps running, so there's no need to catch errors here.
      if (text === "") throw new Error("Type a message first");

      await send("ChatChannelMessageRequest", { channel, content: text });
    },
  },
};

export default async function behavior(launch) {
  on("InventoryWeightEvent", (traffic) => {
    // A message Asterobot couldn't decode has no payload, and an error
    // thrown in a handler stops the whole script.
    if (traffic.payload) lastWeight = traffic.payload;
  });

  // A new game connection starts with this message. MITM bots never launch
  // with "initial": the Dofus client has already identified their session.
  if (launch.reason === "initial") {
    await send("IdentificationRequest", {
      ticketKey: session.gameToken,
      languageCode: session.language,
    });
  }
}

Actions follow the same rules as settings about where they're declared: only the actions export of index.js counts, the buttons keep the order you write them in, and /** @type {BehaviorActions} */ gives completion and checks on the fields. A package can export parameters, actions or both.

Fields

Other fields are ignored. An action without run, a run that isn't a function, or args that isn't an object of objects is a mistake in the shape of the export: the script doesn't start at all, and the Problems alert shows a text starting with read declarations of. Declarations lists those texts.

run and its arguments

run receives a single object holding every argument you declared:

• The value from the dialog, checked against the argument's declaration with the same rules as a setting: the type, the choices, min and max.
• The argument's default, for an argument that wasn't sent. An argument declared without a default gets its type's zero value or its first choice, which is why channel above starts at GLOBAL.
• An action without args receives {}.

Arguments are never saved. The dialog opens with the declared defaults every time, whatever was typed the last time.

run can be async. Asterobot reports the result once its promise settles, not when the call returns. Whatever run returns is ignored.

run runs inside the script like a message handler: it shares the script's variables, can use every function of the built-in modules, and waits for its turn while the script handles other events. The code of run that runs without awaiting has the same 250 ms limit as a handler. Past it, the action fails with JavaScript execution deadline exceeded, and the script keeps running.

Asterobot checks the arguments against the declaration of the package the bot is set to play, as it's saved in your library. If that declaration can't be read, the values go to run unchecked.

What the person clicking sees

1. The buttons are under Actions, in your package's card on the bot's Settings tab, in the Package settings section. Each one has a lightning bolt.
2. For an action with arguments, a dialog opens, titled with the action's label, with one field per argument, and Cancel and Run buttons.
3. Once the action is handed to the script, a toast says Action started.
4. When run returns, or its promise settles, a second toast gives the action's key followed by finished, or followed by failed with the error. A failure toast stays until someone closes it.

The toasts name the action by its key, such as say failed, not by its label. Choose keys a person can recognize.

An error in run never stops the script. When the action can't even be handed to the script, Couldn't start the action appears instead, with the reason. The two you'll meet most while writing a package are an argument that doesn't fit, such as count: 0 is below the minimum 1, and an action the running script doesn't have. Error messages lists them all.

When actions can be used

• Only while a script runs on the bot. Otherwise the buttons are disabled, and resting the pointer on one shows The bot has to be playing a behavior before an action can run.
• A button calls the action of the script that's running, while the card describes the package the bot is set to play, as saved in your library. After you add, rename or change an action in the editor, save and start the script again, with Run for example. Until then, a new action fails with the running behavior declares no action "<action>" on package "<package>", and a changed run still runs the old code.
• Asterobot finds the actions when the script loads, before it calls your default export. The buttons work while the entry function is still awaiting something, and after it has returned.
• The actions of a dependency are in the dependency's card, and run the dependency's own functions. See Settings in dependencies.
• The actions of an inline script can't be used: the Settings tab never shows its declarations.

When a setting or an argument breaks a rule, Package settings shows Couldn't read this package's settings instead of the cards, so no button can be clicked until the declaration is fixed. Declare settings explains those errors.

Next, Settings in dependencies.