Finding messages

Before writing a handler, you need the name of the message and the names of its fields. Three tools give you those, and each one is best at a different question:

Readable names and wire names

Every traffic object carries two names. type is the readable name, such as ChatChannelMessageEvent, and wireType is the scrambled name the message has on the wire. Scripts should rely on type only:

• Wire names change with game versions. A script that compares wireType breaks at the next patch.
• on(), wait() and intercept() compare a name with type, and send() and request() take a readable name. None of them accept a wire name.
• Readable names come from Asterobot, which keeps them when the wire names change. An Asterobot update can still rename a message when it finds a better name for it: After a game update explains what to watch.

Only part of the protocol has readable names so far. A message without one reaches scripts with an empty type, as described in Traffic.

Field names

The game's definitions and the protocol reference write field names with underscores, like sender_name. Scripts read them in camelCase, like senderName: each underscore is removed and the letter after it is capitalized. When sending, a script can use either spelling, but not both for the same field in one payload.

Some fields and enum values still have short scrambled names, such as fzbl. Asterobot doesn't know what they mean yet, and their names can change, so don't build a script on them.

The Dofus protocol reference

The Dofus protocol reference on asterobot.net describes the game's messages: what each one is for, its fields, and what they mean. Start there when you know what you want to do but not which message does it, and come back to it whenever a field's meaning isn't obvious from its name.

Completion in the editor

The package editor knows every message the Asterobot it's connected to has a readable name for. Hover IntelliSense in the editor's top bar to see how many.

With those names, the editor:

• completes the fields of the payload you pass to send() and request(), and marks a field the message doesn't have, or a value of the wrong type, as an error;
• knows the fields of traffic.payload in on(), wait() and intercept() handlers that name a message, so reading them completes too;
• refuses two members of the same oneof in one payload. Payloads explains oneofs.

The editor doesn't check the message name itself. A misspelled name in send() only fails when the script runs, with semantic protobuf message is not mapped: followed by the name. In on() or wait(), a misspelled name is accepted and never matches anything, but the editor then knows no field of traffic.payload, and reading one is marked as an error.

Errors add up on the editor's error badge. They don't stop you from saving or running the package. When the typings can't be loaded, hovering IntelliSense says Couldn't load the typings - editing works, completion doesn't.

The typings describe the Asterobot the editor is connected to. After updating Asterobot, open the editor again to get the names of the new version.

The Network tool

On a bot's page, Tools > Network shows the messages going through the bot. Network traffic describes the whole tool. Here's what matters when you're looking for a message.

Choose what to watch

Settings lists every message this Asterobot has a readable name for, which are the names a script can use in on() or send(). Traffic shows nothing until you tick some of them and click Apply.

• The filter box narrows the list, and the select button next to it ticks every message the filter shows.
• Also mirror unrecovered messages adds the messages that have no readable name, the ones scripts receive with an empty type.

What you select only changes what Asteroboard shows. A script receives every message, selected or not.

Read a message

In Traffic, each row shows the message's name, In or Out, its sequence number after #, and its uid when it has one. Click a row to see its fields. They have the names a script reads, in camelCase. The one difference is 64-bit numbers: they show in quotes here, while a script receives them as BigInt values.

Some rows are marked:

The search box above the list filters rows. Type a word, or name a field, as in name:Ping direction:inbound. A - in front of a term excludes the rows that match it.

Messages your script sends show up too, as long as they're selected: what it sends to the server as Out, and what it sends with { to: "client" } as In.

Try a message by hand

Send a game message sends one message from a form, the same way send() does. It's the quickest way to try a message before writing code for it. Send messages by hand describes the form, and Send messages walks through an example.

Find the message for an action

A MITM bot (man-in-the-middle: the bot relays the game session of the Dofus client you play) is the best place to look, because you do the action yourself and watch what goes through:

1. On the bot's page, open Tools > Network > Settings.
2. Type a word related to the action in the filter, such as Inventory or Chat, tick the messages that look related, and click Apply.
3. Open Traffic, then do the action in Dofus.
4. Read the new rows from the top. Out is what your client sent, and In is what the server sent. Click a row to see its fields.
5. Look the names up in the Dofus protocol reference to learn what the fields mean.
6. Write your handler with the names you found, as in React to messages.

If Settings then shows a badge such as "12 message(s) dropped - the stream couldn't keep up", select fewer messages and do the action again. Those drops only affect what Asteroboard shows, never what scripts receive.

Next, Listening covers every way to receive the messages you found, and Payloads how their fields become JavaScript values.