Add a setting

The chat bot from Send messages has its trigger and its reply written in the code. Turn them into settings, and anyone who runs your package can change them from the bot's page, without editing code and without stopping the script.

Declare the settings

A package declares its settings by exporting an object named parameters from index.js. Each key is the name of a setting, and its value describes the setting:

export const parameters = {
  enabled: {
    type: "bool",
    label: "Answer in chat",
    default: true,
  },
  trigger: {
    type: "string",
    label: "Trigger",
    description: "The chat message the bot answers.",
    default: "!hello",
  },
  reply: {
    type: "string",
    label: "Reply",
    description: "What the bot says back.",
    default: "Hello from my first script",
  },
};

Settings can also have a placeholder, a unit, a min and a max, a list of choices, and, for lists and maps, an of type. Declare settings describes all of them and the rules they follow.

Asterobot reads these declarations by running the top level of your modules, without calling your default export. Keep the top level of index.js to imports and declarations: any other code placed there also runs when Asterobot reads the package's settings.

Use them in the script

This is the script from Send messages, reading its trigger and its reply from the settings:

import { session, botInfo, botWarn } from "asterobot:bot";
import { values, onChange } from "asterobot:parameters";
import { on, send, wait } from "asterobot:protocol";

export const parameters = {
  enabled: {
    type: "bool",
    label: "Answer in chat",
    default: true,
  },
  trigger: {
    type: "string",
    label: "Trigger",
    description: "The chat message the bot answers.",
    default: "!hello",
  },
  reply: {
    type: "string",
    label: "Reply",
    description: "What the bot says back.",
    default: "Hello from my first script",
  },
};

export default async function behavior(launch) {
  onChange(({ name, value }) => {
    botInfo(`Setting ${name} is now ${value}`);
  });

  on("ChatChannelMessageEvent", async (traffic) => {
    // Read on every message, so an applied change counts from the next line.
    if (!values.enabled || traffic.payload?.content !== values.trigger) return;

    // Kept for the whole exchange, because the setting can change meanwhile.
    const reply = values.reply;
    // A reply equal to the trigger would answer its own echo forever.
    if (reply === values.trigger) return;

    try {
      // The wait starts before the reply goes out, so a quick echo isn't missed.
      await Promise.all([
        wait(
          (echo) => echo.type === "ChatChannelMessageEvent" && echo.payload?.content === reply,
          { timeout: 5000 },
        ),
        send("ChatChannelMessageRequest", { channel: "GLOBAL", content: reply }),
      ]);
      botInfo("Reply delivered");
    } catch (error) {
      // An error that escapes a handler stops the whole script.
      botWarn("Reply not delivered:", String(error));
    }
  });

  // 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,
    });
  }
}

values, from asterobot:parameters, holds your package's current settings by name, so values.trigger is whatever the Trigger field says. It's live: when someone applies new settings on the bot's page, the running script reads the new values from then on, without restarting. That's why the handler reads values each time a message arrives instead of copying the settings once at the start. values is read-only, so don't assign to it or delete from it: assigning throws a TypeError with 'Set' on a dynamic object returned false, and deleting throws Could not delete property "<name>" of a dynamic object. Either way, the setting keeps the value set on the bot's page. A setting declared as int or double reads as a regular number, not as a BigInt.

onChange() is for doing something the moment a setting changes. Its handler runs once for each setting whose value changed, only for your own package's settings, and receives the setting's name and its new value. Like a message handler, an onChange() handler that throws an error stops the script.

Change the settings in Asteroboard

1. Run the package on your MITM bot.
2. On the bot's page, open Settings, then Package settings.
3. Your package's section lists Answer in chat, Trigger and Reply with their current values. Change Reply: Not applied appears next to the package's name.
4. Click Apply.

A toast says my-first-script settings applied, and the bot's Console shows Setting reply is now followed by your text. Say the trigger in the Dofus chat, and the bot answers with the new reply.

Reset throws away the changes you haven't applied. Settings are saved with the bot, even while no script is running, and the next start uses them.

Package settings shows the settings of the bot's package, the one that Run or Load a new package gave it, whether or not it's running. A bot without a package shows No package selected. When you change the declarations in the editor, save them and click Refresh in this section to see the new fields, then Run the package again so the running script gets them too.

When settings are refused

A package can also put buttons on the bot's page: see Declare actions. Next, Share your package.