Identify and run

A package does nothing until a bot plays it. Start by running the starter package on a bot, then send its output to the bot's page and add the lines that identify a Full socket bot on the game server.

Before you start

You need a bot whose header shows Connected to game server. The easiest is a MITM bot (man-in-the-middle: the bot relays the game session of the Dofus client you play). There's no Ankama account to store, and you can watch the result in your own game. Your first bot sets one up, and it shows Connected to game server once your Dofus client has connected through it. A Full socket bot works too: see Full socket mode.

Run the package

1. Open your package in the editor.
2. In the bot picker, choose your bot.
3. Click Run.

Asteroboard saves the package, stops whatever the bot was playing, loads your package on it and starts it. A toast says Running on followed by the bot's name.

Run also makes this package the bot's package. The bot's header now shows my-first-script@1.0.0, and Play on the bot's page starts it again later.

If the package doesn't start, the toast says Couldn't run the package instead. When something goes wrong explains where to look.

Where the output goes

The starter code writes with info() from asterobot:console, so its line lands in Server > Console: started (resume) on a MITM bot, or started (initial) the first time it starts on a Full socket bot's connection.

Scripts have two sets of output functions, and they write to different places:

That console is an object exported by asterobot:console: scripts have no global console, so it has to be imported like the rest.

While you write a script, the bot's console is almost always the one you want. Change index.js so its output lands there:

import { botInfo } from "asterobot:bot";

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

Click Run again, then open the bot's Console tab: the line is there. When you pass several values, the console joins them with spaces.

Identify a Full socket bot

In Full socket mode, Asterobot signs in, picks the game server and opens the game connection, then leaves the rest to the script. The first message on a new game connection has to be IdentificationRequest, carrying the ticket the login server issued for that connection. These are the lines every sample in these docs uses:

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

export default async function behavior(launch) {
  // 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,
    });
  }
}

The Dofus protocol reference writes these fields ticket_key and language_code. A script can send either spelling, and these docs use camelCase because that's how scripts read fields back.

When a script has message handlers, register them above this block, as the next pages do. Registering a handler sends nothing, so the identification is still the first message out, and handlers registered earlier already receive what arrives while send() is awaited.

A field the message doesn't have makes send() reject. Sending token instead of ticketKey, for example, fails with IdentificationRequest.token: unknown protobuf field, and the script stops with that error.

Identifying doesn't take the bot any further. Choosing a character and entering the game are up to scripts too: Asterobot doesn't do them for a Full socket bot.

Watch what your Dofus client sends

A MITM bot shows the messages your client exchanges with the game server, in the order they happen. To see what logging in to a character takes:

1. Before you launch Dofus, open your MITM bot's page, then Tools > Network > Settings.
2. Tick the messages you want to watch. The select button next to the filter ticks every message the filter shows.
3. Click Apply.
4. Open Traffic, then launch Dofus and log in to a character.
5. Read the list from the top. Out marks what your client sent and In what the server sent. Click a message to see its fields.

If Settings then shows a badge such as "12 message(s) dropped - the stream couldn't keep up", select fewer messages and log in again.

Why the check is harmless in MITM mode

The same package runs on both kinds of bot. On a MITM bot, your Dofus client identifies the session before any script starts, so Asterobot reports the script's first start as "resume", never "initial", and the if skips the identification.

Even a script without the check can't identify a relayed session a second time. Asterobot refuses to forward the message and writes Refused to forward a message that would re-authenticate a relayed session in the bot's console.

Launch reasons

launch.reason is "initial" on a Full socket bot's new game connection, until a script has started successfully on it. Every later start on that connection is "resume", and so is every start on a MITM bot. The entry function lists every reason and what each one asks of your script.

A start counts as successful once the default export's function has finished. If a script sends IdentificationRequest and its function then fails before finishing, the next start on that connection is "initial" again, and the script identifies a second time. Handle the errors that can happen after the identification so the first start succeeds.

Stop and play again

The bot's header has the controls for its package:

There's no Reload button. To restart a script with your latest code, click Run in the editor, or Stop and then Play on the bot's page: both start the code you last saved. Play, stop and reload explains what's kept between two starts and what starts over.

When something goes wrong

The error text starts with where the script failed. Sending token instead of ticketKey while the script starts gives:

initialize behavior module "library/my-first-script/1.0.0/index.js": Promise rejected: IdentificationRequest.token: unknown protobuf field

Dismiss hides the alert. A different error still shows up, even after you've dismissed the previous one.

Errors explains what stops a script and what doesn't, and Error messages lists the texts you can meet. Next, React to messages.