Traffic

Every message a script receives comes as a traffic object: in on() and onTraffic() handlers, from wait() and request(), and in interceptors.

What a traffic object looks like

A chat line on the general channel reaches a handler like this:

{
  sequence: 1842n,
  direction: "inbound",
  kind: "event",
  uid: -1,
  type: "ChatChannelMessageEvent",
  wireType: "abc", // an example: the real name is scrambled and changes between game versions
  typeUrl: "type.ankama.com/abc",
  unknown: false,
  payload: {
    channel: "GLOBAL",
    senderName: "Airelle",
    senderCharacterId: 123456789012n,
    content: "Anyone up for a dungeon?",
    // ...and the other fields of the message
  },
  rawAny: new Uint8Array([/* the bytes of the fields */]),
}

Properties

The editor marks every property as read-only. Changing one in a handler only changes what the next handlers see: One object for every handler explains why.

Direction and kind

"unknown" exists in the typings, but Asterobot never delivers a message it couldn't classify, so scripts don't receive it. When a message is so damaged that Asterobot can't even tell its kind, a Full socket bot's game connection closes, and the script stops with an error that starts with Game session closed:. A MITM bot passes such a message on without delivering it to scripts.

On a Full socket bot, the game server isn't expected to send requests. If one arrives, it's still decoded, and its decodeError is unexpected inbound game envelope.

Messages Asterobot can't decode

When Asterobot can't decode a message, its traffic object has no payload, unknown is true, type is empty, and decodeError says why:

With an empty type, a handler registered with a message name never receives these messages. To catch them, use the "*" selector, a function selector, or onTraffic(), and test traffic.unknown. Listening describes selectors.

What stays usable is wireType and rawAny. wireType tells two unknown messages apart, but only within one game version, and a message without a readable name can't be sent.

The bot's Network tool sometimes shows fields for such a message, with the Schema badge, because it also decodes messages under their scrambled names. Scripts don't get that: for a script the message stays unknown, with only its bytes. Finding messages explains the badges.

Raw bytes

rawAny holds the bytes of the message's fields before decoding, whether decoding worked or not. It's a copy, so changing it changes nothing. It doesn't include the part around the fields that states the message's kind and name, so it isn't something you could send back as it is. Asterobot has no function that decodes these bytes for you.

For an unknown message, the bytes are all there is. This script writes the start of each unknown message to the bot's console:

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

export default async function behavior(launch) {
  onTraffic((traffic) => {
    if (!traffic.unknown) return;

    // Sixteen bytes keep each console line readable.
    const start = Array.from(traffic.rawAny.slice(0, 16), (byte) => byte.toString(16).padStart(2, "0"));
    botDebug(`${traffic.direction} ${traffic.wireType}, ${traffic.rawAny.length} bytes: ${start.join(" ")}`);
  });

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

Sequence numbers

sequence counts the messages of one game connection, both directions together, starting at 1n. A new game connection starts again from 1n.

The numbers a script sees aren't always consecutive or in order:

• A message an interceptor drops keeps its number and never reaches handlers, which leaves a gap.
• On a MITM bot, Asterobot skips messages for scripts when it can't keep up with the traffic, which also leaves gaps. Sessions explains when that happens.
• A message a script sends from inside an interceptor goes out before the message being decided, and reaches handlers first, while carrying a higher number.

Handlers receive messages in the order they went through the bot. Use sequence as a label, not to sort messages.

On a MITM bot, the traffic object request() resolves with has sequence set to 0n. Handlers receive the same response with its real number.

One object for every handler

When several handlers and waits receive the same message, they all get the same object. A handler that changes traffic.payload changes what the handlers after it see, and nothing on the wire. To change a message on its way through the bot, use an interceptor, which receives its own copy: see Intercepting.

Next, Finding messages shows how to find the name and fields of the message you need. The asterobot:protocol reference lists every function that receives traffic.