Declarations

A package puts settings and buttons on a bot's page by declaring them in its script. The complete schema is below. Declare settings and Declare actions walk through it with examples, and asterobot:parameters describes how a script reads the values.

Where declarations go

A package declares settings and actions as two named exports of its index.js:

export const parameters = {
  maxFights: { type: "int", label: "Stop after", default: 20, min: 1 },
};

export const actions = {
  recall: {
    label: "Recall to zaap",
    async run() {
      // What the button does.
    },
  },
};

• Both exports are optional. Exports with these names in other files of the package are ignored.
• Every package of the running script can declare its own: the bot's package, and each dependency the script really imports. A dependency listed in asterobot.json that nothing imports declares nothing.
• Settings and actions appear on the bot's page in the order you write them.
• These are ordinary JavaScript values, so a default can be computed or imported from another file.

How Asterobot reads them

Asterobot runs the top level of the package's modules without calling the default export, then reads the two exports. It does so when a bot's Settings tab shows Package settings, when you pick the package in the Add a bot dialog, and each time a script starts.

At that moment there's no bot and no game session, so some functions behave differently when the top level of a module calls them:

Reading also fails when a top-level await never settles, with package awaits at import time, which cannot be answered without a Game session, and when top-level code runs for more than 250 ms without awaiting, with JavaScript execution deadline exceeded. A rejected promise that nothing catches doesn't make reading fail.

So keep the top level of your modules to imports, declarations and quick computations.

Settings

export const parameters is an object. Each key is a setting's name, the name the script reads in values, and each value is an object with these fields:

Any other field is ignored without an error, so a misspelled field such as labell silently does nothing. A label, description, placeholder or unit that isn't a string is ignored too, and so is a min or max that isn't a number.

Types

A setting with choices shows a drop-down list, whatever its type, and its zero value is the first choice.

Values that fit

The default, and every value applied from the bot's page, has to fit the declaration. Asterobot never converts one type into another:

• bool takes true or false, nothing else.
• string takes a string. A number isn't turned into text.
• int takes a whole, finite number. 3.0 is fine, and 3.5 is refused rather than rounded.
• double takes a finite number: not NaN, not Infinity.
• array takes an array whose every item fits of.
• map takes an object whose every value fits of.
• With choices, the value has to be one of the choices.
• With min or max, an int or double value has to be within the bounds, the bounds themselves included. min and max don't apply to a setting that has choices, nor to the items of an array or a map.

A saved value that stops fitting after you change a declaration is ignored, and the setting falls back to its default.

Choices

choices takes bare values, objects with a value and a label, or a mix of both. A bare value is its own label.

export const parameters = {
  slot: { type: "int", label: "Slot", choices: [1, 2, 3], default: 2 },
  mode: {
    type: "string",
    label: "Strategy",
    choices: [
      { value: "safe", label: "Avoid groups" },
      { value: "greedy", label: "Fight everything" },
    ],
    default: "safe",
  },
};

Every choice's value has to fit the setting's type, and a default has to be one of the choices.

Actions

export const actions is an object. Each key is an action's name, and each value is an object with these fields:

run(args) receives an object holding every declared argument: the value typed in the dialog, or the argument's default when none was given. An action without args receives {}. run may be async.

import { send } from "asterobot:protocol";

export const actions = {
  say: {
    label: "Say something",
    args: { text: { type: "string", label: "Text", default: "Hello" } },
    async run({ text }) {
      await send("ChatChannelMessageRequest", { channel: "GLOBAL", content: text });
    },
  },
};

Here is what happens around an action:

• Its button is in the package's section of Package settings, on the bot's Settings tab. It can only be clicked while a script is running. Otherwise it's disabled, with the tooltip The bot has to be playing a behavior before an action can run.
• An action with arguments opens a dialog titled with its label, with one field per argument, reset to the defaults every time it opens, and Cancel and Run buttons.
• The arguments are checked against the declarations before anything runs. A value that doesn't fit shows Couldn't start the action with the reason, and run isn't called.
• Once the action is on its way, a toast says Action started. When run returns, or its promise settles, a second toast says the action's name followed by finished, or followed by failed with the error. A failure toast stays until you close it.
• An error in run never stops the script.
• Asterobot finds the actions before it calls the default export, so the buttons work even when the entry function never finishes.
• A button runs the action of the script that's running. After you change an action in the editor, start the script again to use the new code.

Types for the editor

The editor knows these types for declarations: BehaviorParameters, BehaviorActions, BehaviorParameter, BehaviorAction, BehaviorChoice, BehaviorParameterType and BehaviorScalarType. Name them in a JSDoc comment to get completion on the fields:

/** @type {BehaviorParameters} */
export const parameters = {
  enabled: { type: "bool", label: "Answer in chat", default: true },
};

Errors

When declarations can't be read, Package settings on the bot's Settings tab, and the package's settings in the Add a bot dialog, show Couldn't read this package's settings with the reason. The text starts with the package's name and version and read declarations:, such as:

my-first-script@1.0.0: read declarations: package "my-first-script" parameter "enabled": parameter "enabled" default: want a bool, got string

In the texts below, <package> is the package's name, <name> a setting's name, <action> an action's name and <argument> an argument's name.

Errors that also stop the script from starting

These say an export doesn't have the right shape. They also make every start fail, with the Problems alert showing read declarations of "<module>": followed by the same text.

Errors in a setting or an argument

These don't stop a start: the script starts, but with no settings at all. They begin with package "<package>" parameter "<name>": for a setting, or with package "<package>" action "<action>": argument "<argument>": for an action's argument.

Reasons a value doesn't fit

These reasons follow default: or choice <index>: in the errors above. The same texts appear when a value applied from the bot's page, or an action's argument, doesn't fit.

<type> is the name Asterobot gives the value's type: string, bool, int64 for a whole number written in the script, float64 for other numbers and for every number sent from the bot's page, []interface {} for an array and map[string]interface {} for an object.

Error messages lists the texts you can meet everywhere else.