Declare settings

Settings let the people who run your package change what it does without touching its code. Add a setting showed the basics, and Declarations keeps the compact schema with the full list of error texts.

Where the declaration goes

A package declares its settings in one place: an object exported as parameters from its index.js. Each key is the name of a setting, the name your script reads later in values, and each value describes the setting.

/** @type {BehaviorParameters} */
export const parameters = {
  enabled: {
    type: "bool",
    label: "Answer in chat",
    default: true,
  },
  delay: {
    type: "double",
    label: "Wait before answering",
    unit: "seconds",
    default: 1.5,
    min: 0,
    max: 10,
  },
  maxAnswers: {
    type: "int",
    label: "Answers per player",
    description: "The bot stops answering a player after this many replies.",
    default: 3,
    min: 1,
  },
  tone: {
    type: "string",
    label: "Tone",
    choices: [
      { value: "polite", label: "Polite" },
      { value: "short", label: "Short" },
    ],
    default: "polite",
  },
  ignored: {
    type: "array",
    of: "string",
    label: "Ignored players",
    description: "Character names the bot never answers.",
  },
  replies: {
    type: "map",
    of: "string",
    label: "Replies",
    description: "What a player says on the left, what the bot answers on the right.",
    default: { "!hello": "Hello!", "!help": "Ask me anything." },
  },
};

A few rules decide what Asterobot picks up:

• Only an export of index.js counts. An export const parameters in another file of the package is ignored.
• Settings appear on the bot's page in the order you write them. The one exception comes from JavaScript itself: keys that look like whole numbers, such as "2", are always listed first.
• The object is ordinary JavaScript. A default can be a constant from another file of the package, or a value computed when the module runs.
• Asterobot reads the object by running the top level of your modules, without calling your default export and without a bot or a game session. At that moment values is empty and session holds empty values, so a declaration can't depend on either. The entry function lists what else behaves differently while Asterobot reads it.
• Each package declares its own settings, dependencies included. See Settings in dependencies.

The key is also the name Asterobot saves the value under for each bot. Renaming a setting in a later version loses the values people saved, as Read settings explains, so pick keys you won't want to change. An empty key is refused.

Fields

Asterobot is lenient with what it doesn't understand, which cuts both ways. A field it doesn't know is ignored without an error, so a typo such as lable 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. The JSDoc type described below catches most of these mistakes in the editor.

Some combinations have no effect either:

• min and max don't apply to a setting with choices, nor to the items of an array or a map.
• placeholder and unit aren't shown on a drop-down list, nor on the items of a list or a map.
• min greater than max is refused.

On the bot's page, min and max also limit the arrows of the number box. Asterobot checks the bounds again when someone clicks Apply, whatever was typed.

The six types

What each type accepts, for a default or for a value applied on the bot's page:

• bool takes true or false, nothing else.
• string takes a string. The number 5 isn't turned into "5".
• int takes a whole, finite number. 3.0 fits, and 3.5 is refused rather than rounded. The script reads it as a regular number, not as a BigInt like the 64-bit fields of game messages.
• double takes a finite number, so not NaN and not Infinity.
• array takes an array whose every item fits of.
• map takes an object whose every value fits of.

Lists and maps only hold the four scalar types: a list of lists can't be declared. On the bot's page, a new item starts at false, "" or 0, depending on of, and a map row whose key is left empty isn't saved. Clearing a number box doesn't store an empty value: the box keeps the last number typed in it.

Choices

choices turns a string or int setting into a drop-down list. Each choice is either a bare value, which is then its own label, or an object with a value and a label:

/** @type {BehaviorParameters} */
export const parameters = {
  slot: {
    type: "int",
    label: "Spell slot",
    choices: [1, 2, 3],
    default: 2,
  },
  tone: {
    type: "string",
    label: "Tone",
    choices: [
      { value: "polite", label: "Polite" },
      { value: "short", label: "Short" },
    ],
    default: "polite",
  },
};

The script reads the value, never the label: values.tone is "polite", not "Polite". The rules:

• Only string and int settings can have choices.
• Every value must fit the setting's type. "2" isn't a valid choice for an int.
• A choice object without a value is refused. A choice without a label shows its value.
• The default must be one of the values. Without a default, the setting starts at the first choice.

Defaults

The default is what a bot reads until someone applies another value.

• Without a default, or with default: null, a setting starts at its type's value from the last column of the table above, or at its first choice.
• The default has to fit the declaration exactly like a value typed on the bot's page. Asterobot never converts it: default: "20" on an int is refused, and so is a default below min or above max.
• A default can be any expression, as long as it doesn't need a setting's value or the session.

A default only matters while a bot has no saved value for the setting. Asteroboard saves every setting of a package at once, the untouched ones included, when someone clicks Apply and when a bot is added with the package, so a default you change in a later version doesn't reach those bots. Read settings goes through what happens to saved values.

When Asterobot checks the declaration

Asterobot reads and checks the declaration each time it needs it: when a bot's Settings tab shows Package settings, when someone picks the package in the Add a bot dialog, and at every start of the script. Saving in the editor checks nothing. After changing a declaration, save, then open Package settings on a bot set to your package and click Refresh.

Problems fall into two groups:

The reason names the package, then the setting, then what's wrong. With default: "friendly" on the tone setting above, Package settings shows:

chat-helper@1.0.0: read declarations: package "chat-helper" parameter "tone": parameter "tone" default: friendly is not one of polite, short

Declarations lists every text you can get.

Typing with JSDoc

Put /** @type {BehaviorParameters} */ on the line above export const parameters, as in the examples on this page. The editor then completes the field names, and marks as errors a field that doesn't exist and a type or of that isn't one of the allowed names: mistakes Asterobot would ignore silently, or only report once it reads the declaration. It doesn't check that a default fits its type, so Asterobot's own check still matters.

These types need no import:

Next, Read settings shows how the script uses the values. The arguments of actions are declared with the same fields.