How bots talk to Dofus

Dofus and the game servers talk by exchanging messages, and a bot talks to them the same way. A script is the part that decides what to send and what to do with what arrives. The words introduced here come back throughout the developer docs.

Messages, names and fields

A message is one piece of data sent between Dofus and a game server: a line of chat, a character moving, the contents of an inventory. Every message has a name and fields. When someone speaks in chat, a script receives something like this:

{
  type: "ChatChannelMessageEvent",
  direction: "inbound",
  kind: "event",
  payload: {
    channel: "GLOBAL",
    senderName: "Airelle",
    senderCharacterId: 123456789012n,
    content: "Anyone up for a dungeon?",
    // ...and the other fields of the message
  },
  // ...and a few more properties
}

type is the message's name and payload holds its fields. The other properties say which way the message travelled and what kind of message it is.

The game's definitions write field names with underscores, like sender_name. Scripts read them in camelCase, like senderName, and can use either spelling when they send a message. The Dofus protocol reference lists every message, its fields and what they mean.

Requests, events and responses

Most names follow Ankama's own convention: what the Dofus client sends ends in Request, and what the server sends ends in Event. The kind of a message tells you the same thing more precisely:

The detail that matters most: the game answers most requests with an event, not a response. When your character says something, the answer is the same ChatChannelMessageEvent that everyone on the channel receives, your own line included. So a script that sends a request usually waits for an event, and starts waiting before it sends. Send messages shows how.

Directions

A message is inbound when it travels from the game server towards the client, and outbound when it travels from the client towards the server. Handlers registered with on() only receive inbound messages. Handlers registered with onTraffic() receive both.

Where your script sits

Full socket mode

The bot is the Dofus client. Asterobot signs in, chooses the game server and opens the game connection. From there it's up to the script, starting with identifying the bot.

• Your script ↔ Asterobot
• Asterobot ↔ Game server (game connection)

MITM mode

MITM stands for man-in-the-middle. You play Dofus as usual, and the bot relays your game session between your Dofus client and the game server. Your script sits in the middle with it:

• Your Dofus client ↔ Asterobot and your script
• Asterobot and your script ↔ Game server

A script there sees what your client sends and what the server answers. It can send messages to the server as if your client had sent them, send messages to your client as if the server had, and change or drop messages on their way through.

Two things are different for a script on a MITM bot. The session is already identified when the script starts, because your client did it. And you're playing the same character: nothing stops you and the script from acting at the same time, so a script that moves your character competes with you. session.shared is true on such a session, so a script can check.

Full socket mode and MITM mode describe both modes from the player's side, and Sessions describes them from the script's side.

Readable names

On the wire, Dofus 3 doesn't send names like ChatChannelMessageEvent. Its messages carry short scrambled names, and those change between game versions. Asterobot translates them, so scripts work with readable names. In a traffic object, type holds the readable name and wireType the scrambled one.

Not every message has a readable name yet. When Asterobot can't name a message, its type is empty. The bot's Network tool marks such a message Schema when its fields can still be read, and Raw when only its bytes can. A script can only send messages that have a readable name.

Every property of a traffic object is described in Traffic, and After a game update explains what changes for scripts when Ankama patches the game. Next, see Your toolbox.