asterobot:movement

move(), changeMap(), useElement(), travel() and the map finders, which walk the bot's character on its map, take it to the next map by a side, use the doors, zaaps, resources and exits of the map, take it to any map however far and find the maps to go to, on Full socket and MITM bots alike, with every option, error and limit.

asterobot:movement moves the bot's character the way the Dofus client does when the player clicks:

• move() walks the character to a cell of the map it stands on;
• changeMap() takes it to the next map by one side of the map;
• useElement() uses an interactive element of the map: a door, a zaap, a resource, a workshop, or an exit (the sun drawn on some cells);
• travel() takes it to another map, however far, map after map; route() tells which way it would take, trip() where a trip stands, and stopTravel() stops one;
• the map finders pick the map to go to: findMaps(), mapAt(), mapInfo(), nearest(), nearestWith(), mapsWithin() and reachable();
• answerMapLoads() tells the bot that the script asks for each new map's contents itself.

The same calls work on a Full socket bot and on a MITM bot (man-in-the-middle: the bot relays the game session of a Dofus client that someone plays). They are the same movements as the bot's Map tab in Asteroboard, which calls them through the API.

import { move, changeMap, useElement, travel, route } from "asterobot:movement";

@asterobot:base exports all of them too.

Each function starts once the messages the script sent before it have left, so await send(...) followed by changeMap() sends that message before the character moves.

move()

move(cell, options?) returns Promise<number>.

It resolves with the cell the character stands on, once the server has acknowledged the end of the walk.

try {
  const cell = await move(301);
  botInfo("Standing on cell", cell);
} catch (error) {
  botWarn("Couldn't walk:", String(error));
}

How it walks

1. It reads where the character and the other actors stand, as currentMap() does, and plans the route to cell the way findPath() does, around every other actor. When cell can't be reached, the route ends on the reachable cell closest to it. When there's nowhere to walk, move() resolves right away with the character's cell and sends nothing.
2. It sends MapMovementRequest and waits for the server's MapMovementEvent granting the walk. A MapMovementRefusedEvent refuses it instead, and move() rejects at once.
3. On a Full socket bot, it waits as long as the Dofus client takes to walk the cells the server granted, then sends MapMovementConfirmRequest. On a MITM bot the Dofus client walks the character on screen and confirms the walk itself. If it hasn't one second past that time, as when it dropped a walk granted before it showed the character on a new map, Asterobot confirms it.
4. It resolves when the server answers with MapMovementConfirmResponse, or moves the character to another map, as walking onto an exit does.

When the server grants a shorter walk than the one asked for, move() times the walk the server granted and resolves with the cell where it ends. On a Full socket bot the confirmation leaves as early as a Dofus client could send it. The path explains how that time is found, and why it can be wrong for a mounted character.

changeMap()

changeMap(side, options?) returns Promise<{ mapId: bigint, cellId: number }>.

It resolves with the map the character stands on and its cell there, once that map's contents have arrived, so a move() can follow at once.

const { mapId, cellId } = await changeMap("top");
botInfo("Now on map", mapId, "cell", cellId);

How it changes map

1. It finds the exits of that side: the cells of that edge of the map whose map data lets the character leave that way (mapChangeData). From those, it takes the one the character walks to soonest, or options.cell. Not every cell of an edge is an exit, and a map split by a river or a wall can have exits the character can't reach.
2. It walks there as move() does. The change goes on only if the walk ends on that exit cell.
3. It sends MapChangeRequest with the map the map data names beyond that side.
4. It waits for MapCurrentEvent, or MapCurrentInstanceEvent for an instanced map, the server putting the character on the next map, then for that map's MapComplementaryInformationEvent, which places the character. The server sends it once ContextReadyRequest and MapInformationRequest have asked for it: see Full socket and MITM bots.

Which map the character arrives on is the server's choice, and the promise resolves with that one. MapChangeRequest carries the map the map data names beyond that side, as the Dofus client sends it, but on some maps the server sends the character somewhere else depending on the exit cell. That's what the next section is about.

Choose the exit

On most maps, every exit of a side leads to the same map, and changeMap(side) is all you need. On a few maps, one side leads to different maps depending on where the character leaves it: the top of the right side to one map, the bottom of the right side to another. To go to a given one, leave from one of its cells with options.cell.

The exits of a side are the cells of that edge whose map data lets the character leave that way: the cell's mapChangeData holds one bit per direction. A script reads them from the map's cells in the game data, with the same rule the Dofus client applies when the player clicks towards a side:

import { record } from "asterobot:gamedata";

// The cells a character may leave a map from, towards one side.
function exits(mapId, side) {
  const cells = record("maps", Number(mapId))?.cells_data ?? [];

  return cells.flatMap((cell, id) => (isExit(id, cell.mapChangeData ?? 0, side) ? [id] : []));
}

// The bits are the 8 directions (1 right, 2 bottom right, 4 bottom, 8 bottom
// left, 16 left, 32 top left, 64 top, 128 top right). A corner cell also
// leaves by the diagonal that points off the map on that side.
function isExit(id, bits, side) {
  switch (side) {
    case "top":
      return id < 28 && ((bits & 64) !== 0 || (id < 14 && (bits & (32 | 128)) !== 0));
    case "bottom":
      return id >= 532 && ((bits & 4) !== 0 || (id >= 546 && (bits & (2 | 8)) !== 0));
    case "right":
      return id % 14 === 13 && ((bits & 1) !== 0 || ((id + 1) % 28 === 0 && (bits & (2 | 128)) !== 0));
    case "left":
      return id % 14 === 0 && ((bits & 16) !== 0 || (id % 28 === 0 && (bits & (8 | 32)) !== 0));
    default:
      return false;
  }
}

Which exit leads where is in the game's travel graph, the one the Dofus client plans trips with, in the tables world_vertices (one row per walkable part of a map) and world_transitions (one row per way out of it). Walking off a side is type 1 or 2, and direction is the side: 0 right, 2 bottom, 4 left, 6 top. When a side leads to several maps, each of its rows has a criterion that lists the cells it's taken from, such as #(PC=447|PC=475|PC=503|PC=531), where PC is the cell the character stands on.

import { botInfo, currentMap } from "asterobot:bot";
import { query } from "asterobot:gamedata";

const result = await query(
  `SELECT t.direction, t.criterion, destination.map_id
     FROM world_transitions t
     JOIN world_vertices origin ON origin.uid = t.from_uid
     JOIN world_vertices destination ON destination.uid = t.to_uid
    WHERE origin.map_id = ? AND t.type IN (1, 2)`,
  [Number(currentMap().mapId)],
);

// undefined when the bot's game version has no game data.
for (const [direction, criterion, destination] of result?.rows ?? []) {
  botInfo("Side", direction, "leads to", destination, criterion || "from every exit");
}

On map 112460037 of game version 3.7.11.11, the right side has two rows: one to map 112461062 with #(PC=27|PC=55|PC=83|PC=97|PC=546|PC=41), one to map 112461060 with #(PC=447|PC=475|PC=503|PC=531|PC=517|PC=489|PC=461|PC=433). exits(112460037, "right") gives 27, 41, 55, 69, 83, 223, 237, 251, 265, 279, 475, 489, 503, 517 and 531. So to reach 112461060, leave from an exit that's also in its list, such as 475:

const { mapId } = await changeMap("right", { cell: 475 });

The tables and the rule can change with a game update. In Asteroboard, the same choice is a right-click on an exit cell of the bot's Map tab.

useElement()

useElement(element, options?) returns Promise<{ mapId: bigint, cellId: number, skillId: number, duration: number, canMove: boolean }>.

It resolves once the server has accepted the use, with:

const map = currentMap();
const door = map.elements.find((element) => element.skills.some((skill) => skill.id === 184));
if (door) {
  await useElement(door.id, { skill: 184 });
}

What follows the use is yours to wait for: the new map of a door that leads indoors (MapCurrentEvent), the destinations of a zaap, the end of a harvest.

How it uses an element

1. It finds the element's cell in the map data and picks the action: options.skill, or the element's only action. Directional signs, which are read and not used, are never picked.
2. It reads the distance the element is used from in the game data's skills table, as the Dofus client does: the smallest range among the element's actions, or 1 as soon as one of them has use_range_in_client off. When the character is further away, it walks to the cell the Dofus client would walk to, next to the element on the character's side for a distance of 1.
3. It sends InteractiveUseRequest with the element id and the action's instance uid, and resolves when the server's InteractiveUsedEvent names the character and that element.

Exits are walked onto, not used. An element whose only action is Point Out an Exit (skill 339) is an exit to another map, drawn as a sun on its cell. The Dofus client doesn't send InteractiveUseRequest for it: it walks onto the cell, and the server moves the character. useElement() does the same, and resolves on the next map as changeMap() does.

While a timed use lasts (duration above 0), the character can't use another element: useElement() rejects until the server ends that use, with InteractiveUseEndedEvent for that element or a StatedMapUpdateEvent, or for one second at most past its duration.

travel()

travel(mapId, options?) returns Promise<{ mapId: bigint, cellId: number }>.

It resolves once the character stands on the map, and on options.cell when it names one, with where the character stands.

const bonta = 212600323;
await travel(bonta, {
  onLeg: (leg, index, total) => botInfo(`${index + 1}/${total}: ${leg.kind} to map ${leg.toMapId}`),
});

How it travels

The game ships a travel graph of the world, which the Dofus client uses for its mount's autopilot: every map, and every way from one map to another. travel() routes over it, with the fewest map changes, and takes the route leg by leg, each leg one of these:

The trip follows its route as long as each leg leaves the character where the route said, and routes again otherwise:

• a leg that leaves the character somewhere else is a detour, not a failure;
• a leg the server refuses, or the map doesn't allow (no exit to walk to, an element missing or offering another action), is left out of the routes that follow, and the bot's Console says so;
• a fight that starts on the way is waited out: once the character stands on a map again, won or lost, the trip routes from there;
• at the 8th refused leg, or the 8th leg that ends off the route, the trip gives up.

On a map the graph doesn't have, such as a house or a dimension, the trip first leaves it: by an exit drawn as a sun, a side of the map, then a door whose action is Leave, until it stands on a map of the graph.

Conditions

Some legs carry a condition: a quest, an item, a level, a breed. Asterobot checks the ones it knows the answer to, from what the game told the bot about its character:

A leg whose condition can't be checked yet, because the game never said or because only the server knows, is unsure: the trip takes it only when no other way leads there (see options.risky), and the server decides. Items gained and quests started or finished during the session are only known once the game lists them again.

Estimates

Each leg carries durationMs: the walk across its map, from where the character lands to the leg's exit, cell or element, at the speed the Dofus client walks, plus 1.5 seconds for the map change and half a second for an element. Where the character lands after stairs or a door can't be told, so such a walk counts 3 seconds. A trip of 70 maps comes out at about 5 minutes.

route()

route(mapId, options?) returns Promise<Array<Leg>>: the legs travel() would take now, from where the character stands, without moving. It takes the same options as travel(), but timeout and onLeg, and resolves with no legs when the character already stands on the map. Each leg is:

const legs = await route(212600323);
const minutes = legs.reduce((total, leg) => total + leg.durationMs, 0) / 60000;
botInfo(`Bonta is ${legs.length} maps away, about ${Math.round(minutes)} minutes`);

trip() and stopTravel()

trip() returns the bot's trip under way, or its last one, whoever started it (this script, another one, or Asteroboard), and undefined before any:

stopTravel() stops the trip under way at the end of its leg under way, so the character never stops halfway through a map change, and returns whether a trip was under way. The travel() it stops rejects with move: the trip was stopped.

Find a map

travel() takes a map id. These functions find one; each returns a promise.

// To the nearest zaap.
const zaap = await nearestWith({ zaap: true });
if (zaap) await travel(zaap.mapId);

// Every map within 3 legs where wheat grows.
const wheat = new Set((await findMaps({ resource: 289 })).map(String));
const around = (await mapsWithin(currentMap().id, 3)).filter((id) => wheat.has(String(id)));

Full socket and MITM bots

So a map change completes in every case, with or without a script, with or without base, and the two requests are sent once, on every PC: by the script that answers map loads, by Asterobot otherwise.

On a MITM bot, changeMap(), useElement() and each leg of travel() that changes map resolve 0.4 to 1.2 seconds after the new map's MapComplementaryInformationEvent, the time the Dofus client takes to show the character on it. The Dofus client drops a walk granted before, so the next walk waits.

answerMapLoads()

answerMapLoads() returns nothing. Call it once, when the script starts answering MapCurrentEvent and MapCurrentInstanceEvent with ContextReadyRequest and MapInformationRequest: from then on, and until the script stops, the map changes these functions make leave those two requests to the script, however long it takes to send them. If the script stops before sending them, Asterobot sends them itself.

A script that answers map loads without calling it races Asterobot, and on a slow PC both send the two requests. Base calls it for you. On a MITM bot it changes nothing: the Dofus client loads every map.

This only covers the map changes these functions make. A Full socket bot with no script at all is not in the game world: identifying, choosing the character, entering the world and answering the server's polls are a script's, base's when it plays.

One at a time

A bot does one walk, map change, use or trip at a time, whoever asks for it. While one is under way, another move(), changeMap(), useElement() or travel() rejects at once and sends nothing, and so does an action started from the bot's Map tab in Asteroboard. A trip counts as one from its first leg to its last: stop it first with stopTravel() or Asteroboard's Stop. Await each call before starting the next. route(), trip() and the map finders move nothing and can be called at any time.

They also refuse to start while the character is still walking a walk they didn't ask for, such as one the player started on a MITM bot. That walk counts until the server acknowledges its end, or for one second at most past the time the Dofus client takes to walk it.

What the character does belongs to the bot, not to your script. If the script stops in the middle, the promise rejects with the reason the script stopped, and the walk, map change or use still goes on to its end, so the server doesn't keep the character walking. A trip stops at the end of the leg under way.

Doing something else in the meantime

These functions don't hold up the rest of your script. Other code keeps running while the character walks, and on a Full socket bot the confirmation still leaves on time. To send a chat message while walking, start both together:

const [cell] = await Promise.all([
  move(301),
  send("ChatChannelMessageRequest", { channel: "GLOBAL", content: "Hello" }),
]);

Don't keep a promise in a variable to await later. If it rejects before your code reaches the await, nothing catches it and the script stops with unhandled Promise rejection:. Await it, put it in a Promise.all, or give it a .catch().

Doing it yourself

A script can make these movements by hand with asterobot:protocol, to do them its own way. Asterobot then takes no part in them: it confirms none of their walks, asks for no map, and doesn't count them in the one-at-a-time rule, so don't mix them with these functions' movements on the same bot. The script sends what the Dofus client would, with findPath() for the routes and currentMap() for the actors and elements:

The Dofus protocol reference describes every field of these messages.

Errors

A mistake in the arguments rejects the promise with a TypeError, and nothing is sent:

A movement that is refused or fails rejects with an error whose message is one of these texts. travel() rejects with them too, for a leg that fails other than by a refusal its route goes round, and "all three" includes it:

They also reject with the texts of findPath() when the game data can't be read, such as failed to load map <mapId> for pathfinding: datacenter: no such record: maps/<mapId>. asterobot:pathfinding lists them.

String(error) gives TypeError: or GoError: followed by the text.

Limits

• They move the character outside fights, like asterobot:pathfinding.
• changeMap() goes to the next map only. travel() goes as far as the travel graph leads, without zaaps, zaapis, the haven bag or potions for now. NPC transports, such as statues and boats, are never used: the game doesn't say where they lead.
• A trip can't yet go round maps whose monsters attack: the game data doesn't say which do.
• useElement() leaves out the house instance a house door can take, as the Dofus client does on a plain click.

Walk along a path shows the messages move() exchanges, for a script that walks by hand. Harvest and move on is a complete script that harvests a route of maps, with recipes for doors, suns, zaaps and exits.