asterobot:bot

asterobot:bot gives a script what belongs to its own bot: the facts about the game session, the map its character stands on, a way to close the game connection, and the bot's console. The launch argument of the entry function is described on this page too, because session repeats its two values.

import { session, currentMap, disconnect, botDebug, botInfo, botWarn, botError } from "asterobot:bot";

These are the module's only exports. There's no bot object to import.

The launch object

Asterobot starts a script by calling the default export of the package's index.js with one argument, launch:

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

export default async function behavior(launch) {
  botInfo("Launch:", launch.reason, launch.generation);

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

On the first start of a Full socket bot, the console shows Launch: initial 1.

The default export must be a function that returns a promise, usually an async function. The entry function explains what to do for each reason.

session

session is a frozen object. Its values are set when the script starts and don't change while it runs.

Every function behaves the same whatever shared says. It exists so that a script that acts on its own, moving or fighting, can decide to stay passive while someone else is playing.

While Asterobot reads a package's declarations, there's no session yet. session then holds empty values: "" for the strings, 0 for serverId, "initial", 1n and false. See Declarations.

currentMap()

currentMap() returns the map the bot's character stands on, or undefined until the character has entered a map.

import { currentMap, botInfo } from "asterobot:bot";

const map = currentMap();

if (map?.cellId !== undefined) {
  botInfo("Map", map.mapId, "cell", map.cellId, "actors", map.actors.length);
}

For a character on cell 300 of map 154010883, next to a monster group, the console shows Map 154010883 cell 300 actors 2.

Asterobot follows the map itself, for the whole game session, from the messages the bot sends and receives: MapInformationRequest when the character arrives on a map, MapComplementaryInformationEvent for the actors already there, then GameRolePlayShowActorsEvent, MapMovementEvent and ContextRemoveElementEvent for the actors that come, walk and leave. So a script started or reloaded in the middle of a session reads where the character is, not only what it saw since it started. Each call returns a new object holding the values of that moment.

An actor's cellId is the cell its walk ends on from the moment the server grants the walk, before the actor gets there. When the character's own walk stops early, for example because the player clicked elsewhere on a MITM bot, the MapMovementCancelRequest sent for it moves the character to the cell where it stopped. Fights aren't followed.

disconnect()

disconnect() returns undefined.

It closes the bot's game connection and returns right away, without waiting for the connection to close. The script stops as a result, and the bot's page shows The behavior stopped with an error with the text behavior requested Game disconnect. Calling disconnect() again, or while the script is already stopping, does nothing.

Asterobot doesn't connect the bot again by itself. Disconnect, delete and restart describes what happens next from the player's side.

botDebug(), botInfo(), botWarn() and botError()

Each takes any number of values and returns undefined:

botInfo("Kamas:", traffic.payload?.kamas);
botWarn("Reply not delivered:", String(error));

The line goes to the bot's Console tab as a Script line, at the level the function names: debug, info, warn or error. Lines of every level show there, debug included. The values are joined with spaces. These functions never throw.

Asterobot turns each value into text on its own, and only strings, numbers and booleans come out the way JavaScript would print them:

To print an object readably, build the text yourself, for example with a template string. JSON.stringify() throws on any value that holds a BigInt, with the message Do not know how to serialize a BigInt, and message payloads often do.

When you open a bot's Console tab, it starts with the last 200 lines Asterobot kept for that bot.

Code at the top level of a module also runs while Asterobot reads the package's declarations. What these functions write at that moment is thrown away.

To write to Asterobot's own log instead, use asterobot:console. Logging and debugging compares the two and suggests a way to track down a problem.