Settings in dependencies

A package can use other packages of the library, its dependencies, and each of them can declare settings and actions of its own. A script only reads the settings of its own package, and a bot's Settings tab shows each package's settings apart. Dependencies covers declaring and importing them.

Each package reads its own settings

Every package gets its own copy of asterobot:parameters. Whichever file imports it, values holds the settings declared in the index.js of the package that file belongs to:

• In your package, values holds your settings, never a dependency's.
• In a dependency, values holds the dependency's settings, never yours.
• An onChange() handler registered by a dependency only hears about the dependency's settings.

No package can read or change the settings of another one. A dependency declares its settings the way Declare settings describes, in its own index.js.

On the bot's page

Under Package settings, on the bot's Settings tab, there's one card per package of the bot's script that declares at least one setting or action: the bot's own package and each of its dependencies, down to the dependencies of dependencies. A card's title gives the package's name, its version and a count such as "2 setting(s) · 1 action(s)".

• A card only appears for a package whose code the script loads. A dependency listed in the manifest that no file imports declares nothing, so it has no card.
• A package that declares no setting and no action has no card either.
• The first card is open and the others are closed. The cards don't come in a fixed order, so the bot's own package isn't necessarily the first one.
• Apply and Reset work card by card: applying one card leaves the others untouched.
• A dependency's actions are in its own card, and run the dependency's own run functions.

The Add a bot dialog shows the same cards, without Apply and without actions, as soon as a library package is picked.

Saved under the dependency's name

A bot saves a dependency's settings under the dependency's name, the same way it saves yours. So, on one bot:

• Every package that uses a given dependency reads the same values for it. When the bot moves from one of these packages to another, the dependency's settings come along.
• The values carry over between versions of the dependency, under the rules in Read settings.
• Another bot has values of its own.

Write a package for others to use

A package meant to be a dependency is an ordinary package. What sets it apart is what its index.js exports: functions and values for the packages that import it, and usually no default export.

Here is a small one, chat-tools, with one setting and one function:

import { values } from "asterobot:parameters";

/** @type {BehaviorParameters} */
export const parameters = {
  showChannel: {
    type: "bool",
    label: "Show the channel",
    default: true,
  },
};

export function formatChat(payload) {
  const line = `${payload.senderName}: ${payload.content}`;
  // Read at each call, so an applied change counts from the next line.
  return values.showChannel ? `[${payload.channel}] ${line}` : line;
}

A package named chat-logger uses it. Its manifest declares the dependency, as Dependencies shows:

{
  "dependencies": {
    "chat-tools": { "version": "1.0.0" }
  }
}

And its index.js imports formatChat() by the name it declared:

import { session, botInfo } from "asterobot:bot";
import { on, send } from "asterobot:protocol";
import { formatChat } from "chat-tools";

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

    botInfo(formatChat(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,
    });
  }
}

A bot set to chat-logger shows a single card, chat-tools, with Show the channel: chat-logger declares nothing itself. Turning the switch off and clicking Apply changes the next chat line the bot's console shows.

Some advice for packages like chat-tools:

• Decide who chooses each value. What the person running the bot decides belongs in your settings. What the package using yours decides belongs in the arguments of the functions you export, since that package can't change your settings.
• Label your settings clearly. They appear under your package's name on every bot whose package uses yours, and the person reading them may never have heard of your package.
• Several packages on one bot share your settings. Don't design a setting whose right value depends on which of them uses it.
• Leave out the default export if the package isn't meant to run on its own. It's still listed in the library and can still be picked for a bot, but its start then fails with an error containing has no unambiguous default export. Say what the package is for in its description when you publish it.
• Keep the top level of index.js to imports, declarations and function definitions. It runs at every start of every package that uses yours, and each time Asterobot reads their settings.

Next, the Packages chapter describes the manifest, starting with every field of asterobot.json.