Fights

How scripts and Asterobot's fight module share a bot's fights: starting a fight from a script, knowing when it starts and ends, driving the module and taking its decisions, what the module sends and holds back, and what a script must send when the module is off.

Asterobot has a fight module that plays a bot's fights by itself, when the person running the bot switches it on: it places the character, says it's ready, plays every turn and answers everything the Dofus client answers during a fight. How it decides is set by fight profiles. The guide describes it for players: The fight module and Fight profiles.

The module plays fights, it never starts one. Starting fights, and deciding what happens between them, is your script's job.

Who does what

The person running the bot chooses whether the module plays, on the bot's Fight tab. Your script can override that choice while it runs, and the profile and speed too, with asterobot:fight. Write your package so it works either way, or switch the module as it needs it.

Start a fight

A Dofus client attacks a monster group by walking onto the group's cell, then sending AttackMonsterRequest with the group's actor id. The server then removes the group from the map and switches the character into a fight.

To know which actors of the map are monster groups, read the map's contents when they arrive: a monster group's actorInformation.rolePlayActor holds a monsterGroupActor. The ids and cells of the actors standing on the map now are in currentMap().

import { currentMap, botWarn } from "asterobot:bot";
import { on, send, wait } from "asterobot:protocol";
import { move } from "asterobot:movement";

// The actor ids of the monster groups the server placed on the map, read
// each time a map's contents arrive, after every fight included.
const groups = new Set();

on("MapComplementaryInformationEvent", (traffic) => {
  groups.clear();
  for (const actor of traffic.payload?.actors ?? []) {
    if (actor.actorInformation?.rolePlayActor?.monsterGroupActor) groups.add(actor.actorId);
  }
});

// Walks onto a monster group and attacks it. Resolves with true once the
// fight has started, false when the group was gone or the attack got no answer.
async function attack() {
  const group = currentMap()?.actors.find((actor) => groups.has(actor.id));
  if (!group) return false;

  await move(group.cellId);
  await send("AttackMonsterRequest", { monsterGroupId: group.id });

  try {
    await wait(
      (traffic) => traffic.type === "ContextCreationEvent" && traffic.payload?.context === "FIGHT",
      { timeout: 5000 },
    );
    return true;
  } catch {
    // The group walked away while the character walked to it: the server
    // doesn't answer an attack from a cell the group left.
    botWarn("The attack got no answer");
    return false;
  }
}

Call attack() once the character stands on a map, for example after @asterobot:base has taken a Full socket bot into the game.

Groups walk around. When one moves while the character walks to it, the server ignores the attack, and the Dofus client walks again and attacks from the group's new cell. Do the same: try again after a failed attack, from a fresh currentMap().

Groups that arrive later come with GameRolePlayShowActorsEvent, in the same actors shape, and ContextRemoveElementEvent removes the ones that leave. A script that waits on a map for groups to come back reads those too.

Know when a fight starts and ends

To wait for a fight to end, give the wait a long timeout: fights can last many minutes.

await wait(
  (traffic) => traffic.type === "ContextCreationEvent" && traffic.payload?.context === "ROLE_PLAY",
  { timeout: 30 * 60_000 },
);

Your script keeps running during the fight, and its handlers keep receiving every message the server sends, fight messages included. travel() waits out a fight that starts on the way, and @asterobot:base leaves the fight's map to the fight module.

While the module plays

• Don't send fight actions. Moves, spells and the end of the turn sent by a script would reach the server alongside the module's, and the turn would go wrong. The module doesn't hold back what a script sends. To decide an action, answer it from a decision hook: the module sends it, checked by the rules engine.
• Your interceptors don't see the clicks it holds. On a relayed session, the module is asked first about every message the Dofus client sends. The clicks it holds back, the moves, spells and turn ends of the person playing, and placement or ready when the profile decides them, go neither to the server nor to your interceptors. Every other message reaches them as usual.
• Its console lines are the bot's. The module writes what it does in the bot's console, such as The fight module casts a spell, between your script's lines.

When the module is off

With the module off, Asterobot sends nothing during a fight, but what Hurry the server adds when it's on. On a relayed session, the person's Dofus client plays it. On a Full socket bot, nothing answers the server unless your script does, and the fight doesn't move: the server waits for each fighter's answer before the next turn.

A script that plays fights itself sends what the Dofus client sends:

1. The fight's map. After MapCurrentEvent names it, FightPingsRequest (empty) then ContextReadyRequest with mapId, the fight map's id. Unlike a world map, no MapInformationRequest.
2. Placement, optionally: FightPlacementPositionRequest with cellId, a cell of the character's team from FightPlacementPossiblePositionsEvent, and entityId, the character's id.
3. Ready: FightReadyRequest with isReady: true. Without it, the fight starts when the placement countdown runs out.
4. Its turns: when FightTurnEvent names the character, or a summon FightControlEvent gave it to play (its masterId the character, its slaveId the summon, with the summon's spells), MapMovementRequest to walk, GameActionFightCastRequest with spellId and cell to cast (spell 0 for the weapon or bare hands, a fighter aimed at through its cell), and FightTurnFinishRequest to end the turn.
5. Acknowledgements: GameActionAcknowledgementRequest with actionId, the action id of each outermost sequence the character or a summon it controls authored, as SequenceEndEvent gives it, and valid: true. The server doesn't wait for them, but the Dofus client sends them.
6. Ready for the next turn: FightTurnReadyRequest with isReady: true for every FightIsTurnReadyEvent. The server waits for this one.

The Dofus protocol reference describes each message and its fields. It's a lot of work to do well, which is what the module is for.

Faster fights

Three switches on the bot's Fight tab work in every fight, whether the module plays it, the person, or your script. Scripts can't change them. What they change for a script:

• Hurry the server: Asterobot also sends GameActionAcknowledgementRequest for each outermost sequence nobody else acknowledges, a monster's or an ally's, and FightTurnReadyRequest { isReady: true } every 100 ms from the FightTurnEndEvent of the character's turn until the next FightTurnEvent, 20 at most. Neither is one of the answers listed above, so a script that plays fights keeps sending its own.
• Fewer animations, on a relayed session: a GameActionFightEvent with targetedAbility reaches the Dofus client with silentCast: true, and one with staging or executeScript doesn't reach it at all.
• Skip walking in fights, on a relayed session: a MapMovementEvent during a fight reaches the Dofus client with its last cell alone. On every session, the module then answers without waiting for a fight walk to play.

Your script's interceptors see casts and walks as the server sent them, and never see a staging or executeScript that Fewer animations drops. Its handlers receive all of them as the Dofus client does: silent, shortened, or not at all.

Ship fight profiles

A package can ship fight profiles alongside its script: they show on the Fight Profiles page of everyone who installs it, and any bot can play them. See Ship fight profiles, and the Fight profile format for every field.

Drive the module

asterobot:fight is the module for scripts that work with the fight module:

• Switch it, play another profile or change its speed while the script runs, with enable(), disable(), setProfile() and setSpeed(). The bot's Fight tab says what the script overrides.
• Read the fight under way with state(): every fighter's life, AP, MP, cell, states and monster, the round and whose turn it is.
• Follow every fight with onFight(): its start, each turn's start and end, the module's actions with their reasons, and its end.
• Take its decisions with onDecision(): where to place, holding the ready, and each action of a turn, from one of the AI's turns to a whole turn of your own. The rules engine checks every action.

The choice of challenges comes later, with the challenges themselves.

That's the end of the protocol chapter. The next one, Game data, covers reading items, monsters, maps and texts from a script.