asterobot:character

character(), items(), itemCount() and jobLevel(), which tell a script its character's level, kamas, energy, life, pods, whether it's in a fight, its items and its jobs, with when each one is known and every error.

asterobot:character tells your script what the game has said about its character: level, kamas, energy, life, how full its bags are, whether it's in a fight, its items and its job levels. Use it to decide what to do next, such as going to the bank when the bags are nearly full or resting when life is low.

import { character, items, itemCount, jobLevel } from "asterobot:character";

These are the module's only exports. There's no character object grouping them.

None of the functions returns a promise, and none of them changes anything in the game.

Where the values come from

Asterobot follows the character itself, for the whole game session, from the messages the server sends: the character's selection, its characteristics, its inventory and the weight of its bags, its job list, and when it enters or leaves a fight. So a script started or reloaded in the middle of a session reads the character as it is, not only what it saw since it started.

A value the game hasn't sent yet is missing, never guessed. character() leaves the property out, and items(), itemCount() and jobLevel() return undefined. A missing value is never 0 or null, so a script can always tell "zero" from "not known yet".

Every call asks again and returns a new value. Nothing updates by itself: read it again when you need it.

character()

character() returns an object with the properties below. Each one is a number, except inFight, and each one is absent until the game has sent it.

import { botInfo, botWarn } from "asterobot:bot";
import { character } from "asterobot:character";

const { weight, maxWeight, life, maxLife } = character();

if (weight !== undefined && maxWeight) {
  botInfo(`Bags: ${Math.round((100 * weight) / maxWeight)}%`);
}

if (life !== undefined && maxLife && life < maxLife / 2) {
  botWarn("Below half life");
}

For a character carrying 98 pods out of 1075 with full life, the console shows Bags: 9%.

The object is the script's own: changing it changes nothing, neither in Asterobot nor in the next call's answer.

Life

life and maxLife come from the character's characteristics, which the server sends as the character enters the world and later on. Asterobot works them out the way the Dofus client's character sheet does: the health points of the character's level and its vitality make the full amount, erosion takes the maximum down, and the life lost takes life down.

Between two of these messages, life follows the regeneration the way the Dofus client counts it. LifePointsRegenBeginEvent starts it, at one life point every regenRate tenths of a second, and a new rate, as the character sits down or stands up, goes on from there. UpdateLifePointsEvent stops it. life never goes past maxLife. The damage the character takes during a fight isn't followed: life is the last value until the next characteristics.

Pods

weight and maxWeight come from InventoryWeightEvent, which the server sends with both numbers whenever what the character carries changes. They're up to date as long as the session lasts. weight can be above maxWeight: the character is then overloaded.

Fights

inFight becomes true when the server switches the character into a fight, and false again when it switches it back to the world. Both switches come with ContextCreationEvent. It's false from the moment the character is selected, so a character that has entered the world and hasn't fought yet reads false, not "not known".

travel() waits for the end of a fight by watching the same switch.

items()

items() returns every stack of items the character has, worn or in its bags, sorted by uid, or undefined until the inventory is known. Each call returns a new array.

The list follows what the server says: stacks gained, used up or thrown away, moved in or out of a slot, and their quantities.

import { items } from "asterobot:character";
import { send } from "asterobot:protocol";

// 468 is Incarnam Bread.
const bread = items()?.find((stack) => stack.itemId === 468 && stack.position === 63);

if (bread) await send("ObjectUseRequest", { objectUid: bread.uid });

itemCount()

itemCount(itemId) returns how many of an item the character has, worn or in its bags, or undefined until the inventory is known.

import { botInfo } from "asterobot:bot";
import { itemCount } from "asterobot:character";

// 303 is Ash Wood.
const ash = itemCount(303);

if (ash !== undefined) botInfo(`Ash Wood: ${ash}`);

An item the character has none of gives 0. It follows the updates the server sends, so a stack gained, used up or that grows or shrinks is counted at once.

jobLevel()

jobLevel(jobId) returns the level of one of the character's jobs, 0 for a job it doesn't have, or undefined until the job list is known.

import { botInfo } from "asterobot:bot";
import { jobLevel } from "asterobot:character";

const lumberjack = jobLevel(2);

if (lumberjack === 0) botInfo("This character isn't a lumberjack.");

When the values are known

The server sends most of these values as the character enters the world, before it's placed on its first map:

In a recorded world entry, every value was known before the character was placed on its first map.

Before the selection, character() is empty, except for a brief moment: the server sends the character's characteristics right before selecting it, and the selection then forgets them. In that recording, they gave the character 0 life and 0 energy, and the ones sent a moment later gave it full life and 10000 energy. So don't decide anything from character() until level is there.

Values last as long as the game connection. They survive the script being stopped and played again, and they're forgotten when the bot connects again, until the server sends them for the new session.

While Asterobot reads declarations

When Asterobot reads a package's settings, steps and conditions, it runs the top level of its modules without a bot (see Declarations). There's no character then: character() returns an empty object, and items(), itemCount() and jobLevel() return undefined, whatever you pass them. None of them throws, so importing asterobot:character at the top of a file is always safe.

Errors

String(error) gives TypeError: followed by the text. character() never throws.

The Dofus protocol reference describes the messages these values come from, if you'd rather follow one yourself.