Scripting

Questions people ask while writing packages. The developer docs cover each topic in full.

Which language are scripts written in?

JavaScript. Every file of a package is an ES module, and scripts can use the syntax of JavaScript up to ES2022, apart from three constructs: async generators, for await and import() called as a function. See JavaScript support.

Can I write scripts in TypeScript?

No. A package's files must end in .js or .mjs. You still get types: the editor checks your JavaScript the way TypeScript checks it, and JSDoc comments such as /** @type {BehaviorParameters} */ give your own code completion and checks. See JavaScript support.

Can I use npm packages?

No. There's no npm and no require(), and an import such as "lodash" is read as a dependency your package didn't declare, so the script doesn't load. To reuse code, import your own files with paths starting with ./, or turn the code into a package of your own and declare it as a dependency. See Modules and imports and Dependencies.

Is there setTimeout or setInterval?

No. sleep() from asterobot:timers is the only timer: await sleep(1500) pauses your function for 1.5 seconds without holding up the bot. For something that repeats, write a loop with await sleep() inside and start it from the entry function without awaiting it. For anything the game announces, a message handler is better than a loop. See Async and timing.

Can a script use the internet?

No. There's no fetch(), no WebSocket and no connection of any kind besides the bot's game connection. See What scripts can do.

Can a script read or write files?

No. A script only reaches the modules of its own package and of the packages it depends on. It has nowhere to keep data for its next run either: each start begins from scratch, and values is read-only. What a script needs again has to come from the game, or from a setting someone fills in. See Play, stop and reload.

Can two bots share data?

No. Each bot runs its own copy of the script, and two copies share no variables. A script can't see or control another bot either. See What scripts can do.

Where do I find message names and fields?

In three places:

• The Dofus protocol reference describes every message and what its fields mean.
• The package editor completes message names and payload fields as you type, and marks a field a message doesn't have.
• A bot's Tools > Network shows the messages the game really exchanges, with their values. On a MITM bot, do the action in Dofus and watch what goes through.

Scripts read field names in camelCase, such as senderName for sender_name. See Finding messages.

Are there functions to walk, fight or harvest?

No. A script plays the way the Dofus client does: it sends the game's messages and reacts to what the server answers. Game data helps with the rest, such as finding which maps hold a given resource. See What scripts can do.

Why doesn't my script get a Full socket bot into the game?

Because a Full socket script has to identify the bot itself. Its first message on a new connection must be IdentificationRequest, sent when launch.reason is "initial", and choosing a character and entering the game are up to scripts too. Identify and run shows the lines every sample in these docs uses.

Which bot should I test my scripts on?

A MITM bot on your own Dofus client. You make things happen in the game yourself and watch the script react, and no Ankama account has to be stored. Keep in mind that everything the script sends goes out as your character. See Identify and run.

How do I restart a script after changing its code?

Click Run in the editor, or Stop then Play on the bot's page. There's no Reload button. Saving alone doesn't change a script that's already running: the next start loads what you saved. See Play, stop and reload.

How do I debug a script?

Start with the bot's console:

1. Check the editor's error badge before running.
2. Write to the bot's Console with botInfo() and the other functions of asterobot:bot, and keep only Script in Sources.
3. When the script stops on an error, The behavior stopped with an error appears at the top of the bot's page, with the full text and a Copy button.
4. When a handler never seems to run, look at what really arrives in the Network tool.

Logging and debugging goes through the whole routine.

Why does my log show map[] instead of the error?

Because Asterobot turns logged values into text itself, and an Error object comes out as map[]. Log String(error) or error.message instead. Other objects come out as map[...] too: JSON.stringify() reads better, once BigInt values are converted, since it throws on them. See Logging and debugging.

Why did my script stop with JavaScript execution deadline exceeded?

Some of your code ran for more than 250 ms without awaiting anything. Split long work with await sleep(0) now and then, and replace thousands of record() or text() calls in a row with one find() or query(). See Async and timing.

Why are game texts and item names in French?

Because every script started from Asteroboard uses the language fr, whatever language the bot is set to. text() and search() answer in that language. To read another one, query the _names table, which has a language column. See Game data overview.

Can a script change its own settings?

No. values is read-only: assigning to one of its properties throws a TypeError, and the setting keeps its value. Settings change when someone applies them on the bot's Settings tab. See Read settings.

Will my script break when Dofus updates?

It can. As long as Asterobot knows the game version, it keeps readable message names when the scrambled names on the wire change. But a patch can add, remove or change messages, an Asterobot update can rename a message, and game data tables and columns follow the game version. Read fields with ?., give every wait() a timeout, and check your script after each update. See After a game update.

Are there example scripts?

Yes. The tutorials are small complete scripts to copy and adapt, and the samples throughout the developer docs work on Full socket and MITM bots alike.