asterobot:pathfinding

asterobot:pathfinding computes moves on a map the way the Dofus client does. findPath() gives the route the client would walk from one cell to another, the key cells to send for it and how long the walk lasts. The other functions work with cell positions: where a cell sits on the map's grid, and the distance and the direction between two cells.

It only computes. To walk, call move() from asterobot:movement, or send the walk yourself as Walk along a path shows.

import { findPath, cellToPoint, pointToCell, distance, direction } from "asterobot:pathfinding";

These are the module's only exports. There's no pathfinding object to import.

None of them returns a promise. Like the functions of asterobot:gamedata, they throw when the top level of a module calls them while Asterobot reads the package's declarations: see Declarations.

Everything here is about moving outside fights. Moves in a fight follow other rules, and this module doesn't cover them.

Cells and directions

A map has 560 cells, numbered 0 to 559. Every function takes cell ids as regular whole numbers: a BigInt or a string is refused.

A direction is a number from 0 to 7:

findPath()

findPath(mapId, from, to, options?) returns a Path, or undefined.

It reads the map from the game data of the bot's game version and returns the route the Dofus client would take. When to can't be reached, the route ends on the reachable cell closest to it instead, and end tells you which. findPath() returns undefined only when the Dofus client itself would find no route at all, which doesn't happen on the game's maps.

Occupied cells

The Dofus client's router makes a cell with an actor on it more expensive to walk onto, so its routes tend to go around actors. To get the route the client would walk, pass in occupied the cell of every actor the server shows on the map except the bot's own character: other players, monster groups, NPCs, merchants, tax collectors, prisms and the like. Items on the ground, marks and glyphs don't count. currentMap() lists the actors:

import { currentMap } from "asterobot:bot";
import { findPath } from "asterobot:pathfinding";

const map = currentMap();

if (map?.cellId !== undefined) {
  const others = map.actors.filter((actor) => actor.id !== map.characterId);
  const path = findPath(map.mapId, map.cellId, 301, {
    occupied: others.map((actor) => actor.cellId),
  });
}

The path

A character walks a route of 3 cells or fewer, the start included, and runs a longer one. With cautious: true it always walks.

duration is the earliest moment a Dofus client can confirm the walk. A real client only ends a step when it draws its next frame, so it confirms a little later: in walks recorded from the Dofus client, the confirmation left 10 to 48 ms after duration. The times are those of a character on foot. A mounted character runs at a speed Asterobot doesn't cover yet, so its duration can be wrong.

Errors

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

cellToPoint()

cellToPoint(cell) returns { x, y }, the cell's position on the map's grid.

cellToPoint(300); // { x: 17, y: -4 }

The grid is the map turned 45 degrees, so both numbers change along a row of the screen. One cell to the east adds 1 to x and 1 to y. One cell to the south adds 1 to x and takes 1 from y.

pointToCell()

pointToCell(x, y) returns the cell at that grid position, or undefined when the position is off the map.

pointToCell(18, -3); // 301
pointToCell(0, 1); // undefined

It throws a TypeError with pathfinding.pointToCell x and y must be integers when x or y isn't a whole number in the 32-bit range, or is a BigInt or a string.

distance()

distance(a, b) returns the grid distance between two cells, as the Dofus client measures it: how far apart their x are, plus how far apart their y are.

distance(300, 301); // 2

So the next cell to the south-east, south-west, north-east or north-west is 1 away, and the next cell to the east, west, north or south is 2 away.

direction()

direction(from, to) returns the direction from one cell to another, or undefined when the two cells aren't on one line.

direction(300, 301); // 0, east
direction(300, 316); // undefined

Two cells on one line give that line's direction, whatever their distance. The same cell twice gives 1, as it does in the Dofus client.

Walk along a path

A walk takes two exchanges with the game server:

1. The script sends MapMovementRequest with the path's keyCells, the cautious flag and the map's id. The server grants the walk with MapMovementEvent, whose cells list every cell of the walk. The server sends that message for every actor that walks on the map, so compare its characterId with the character's. It can also grant a shorter walk than the one asked for.
2. Once the walk is over, the character confirms it with MapMovementConfirmRequest, which has no field, and the server answers with MapMovementConfirmResponse. Until then, the server considers the character still walking.

Who sends the confirmation depends on the bot:

import { currentMap, session } from "asterobot:bot";
import { findPath } from "asterobot:pathfinding";
import { send, wait } from "asterobot:protocol";
import { sleep } from "asterobot:timers";

async function walkTo(cell) {
  const map = currentMap();
  if (map?.cellId === undefined) return;

  const others = map.actors.filter((actor) => actor.id !== map.characterId);
  const path = findPath(map.mapId, map.cellId, cell, {
    occupied: others.map((actor) => actor.cellId),
  });
  if (!path || path.keyCells.length === 0) return;

  await Promise.all([
    wait(
      (traffic) =>
        traffic.type === "MapMovementEvent" && traffic.payload?.characterId === map.characterId,
      { timeout: 5000 },
    ),
    send("MapMovementRequest", { keyCells: path.keyCells, cautious: false, mapId: map.mapId }),
  ]);

  if (session.shared) {
    // The Dofus client confirms the walk once it has walked it.
    await wait("MapMovementConfirmResponse", { timeout: path.duration + 5000 });
    return;
  }

  await sleep(path.duration);
  await Promise.all([
    wait("MapMovementConfirmResponse", { timeout: 5000 }),
    send("MapMovementConfirmRequest", {}),
  ]);
}

wait() comes first in each Promise.all, so it's already listening when the message goes out, as Send messages explains.

This sample times the confirmation with the route it asked for. When the server grants a shorter walk, time the walk it granted instead, for example with findPath() from the first of its cells to the last. Start one walk at a time: a walk started before the previous one ends would start from a cell the character hasn't reached yet.

To stop a walk before its end, the Dofus client sends MapMovementCancelRequest with the cell the character stopped on, and the server doesn't answer it. stepEnds tells you which step the character has reached at a given moment.

move() does all of this in one call, shorter walks and both kinds of bots included.

asterobot:bot describes currentMap(), and the Dofus protocol reference lists the fields of the movement messages.