Sessions

A script runs on one bot's game connection, its session. session, from asterobot:bot, describes it, and a few things work differently on a Full socket bot and on a MITM bot. How bots talk to Dofus explains both modes; this page covers what they change for your code.

session

import { session } from "asterobot:bot";

session is filled in when the script starts and doesn't change while it runs. It's frozen: assigning to one of its fields throws a TypeError. Each start gets a new session.

Keep the game ticket secret

The ticket can also show up where you don't expect it. With IdentificationRequest selected in the Network tool, Traffic shows ticketKey: the one your script sends on a Full socket bot, or the one your Dofus client sent on a MITM bot. Don't share screenshots or copies of those rows.

Full socket and MITM, for a script

The functions are the same on both kinds of bot, and a script written for one runs on the other. What differs is who else takes part:

On a MITM bot, Traffic in the Network tool warns when messages were skipped, with how many, saying that the bot's session discarded them because something reading the traffic couldn't keep up.

On either kind of bot, a script that falls too far behind the traffic stops with behavior event-loop queue overflow: see Listening.

Sharing a character

On a MITM bot (man-in-the-middle: the bot relays the game session of the Dofus client you play), the person playing and your script control the same character, and nothing coordinates them. They move, fight and open windows while your script runs, and the server receives messages from both.

• A script that only watches, built from on(), wait(), onTraffic() and logging, works the same on both kinds of bot and has nothing to check.
• A script that acts competes with the person playing. Check session.shared to leave the controls to them:

on("ChatChannelMessageEvent", async (traffic) => {
  // Someone is at the keyboard: let them do the talking.
  if (session.shared) return;

  // ...answer the message
});

• Everything the script sends goes out as their character, and other players see it.
• An interceptor makes each of their messages wait for your script, up to 50 ms: see Intercepting.
• Stopping the script doesn't touch their game: the session goes on without it.

When the connection ends

A script lives on one game connection. When the connection ends, because the server closed it, the network dropped, or the person playing closed Dofus, the script stops: its waits and sends reject, and the bot's page shows The behavior stopped with an error, with an error that starts with Game session closed:.

Nothing starts again on its own. Connect the bot again, or on a MITM bot wait for the next Dofus session, then start the script. Disconnect, delete and restart covers it from the bot's side.

disconnect()

import { disconnect } from "asterobot:bot";

disconnect();

disconnect() closes the bot's game connection. It returns right away, and calling it again does nothing. The script stops as soon as the connection is closed, so treat disconnect() as the last thing it does. The bot's page then shows The behavior stopped with an error, with behavior requested Game disconnect.

What it closes depends on the bot:

• On a Full socket bot, the bot leaves the game server. It doesn't reconnect on its own.
• On a MITM bot, it closes both sides of the relayed session.

This script disconnects a Full socket bot when its inventory is full, and only warns on a MITM bot:

import { session, botWarn, disconnect } from "asterobot:bot";
import { on, send } from "asterobot:protocol";

export default async function behavior(launch) {
  on("InventoryWeightEvent", (traffic) => {
    const weight = traffic.payload?.inventoryWeight;
    const max = traffic.payload?.weightMax;
    if (weight === undefined || !max || weight < max) return;

    // A full inventory ends this bot's session, never a player's.
    if (session.shared) {
      botWarn("Inventory full");
      return;
    }

    botWarn("Inventory full, disconnecting");
    disconnect();
  });

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

Next, After a game update explains what changes for scripts when Ankama patches Dofus, and the asterobot:bot reference has every signature.