The JavaScript you need

Scripts are plain JavaScript. These docs don't teach the language, but four ideas come up on almost every page, so each one gets a short explanation here and a link to a proper tutorial.

Why JavaScript

There's nothing to install and nothing to build. You write a package's code in Asteroboard's editor, which completes Asterobot's functions and the names of game messages as you type, and Asterobot runs the files as they are. Files must end in .js or .mjs, so TypeScript isn't an option.

If JavaScript is new to you, javascript.info and the MDN JavaScript Guide are both good places to learn it.

Modules

Every file of a package is a module. A module brings in what it needs with import and makes things available with export. Asterobot starts a script by calling the function that index.js exports as its default export:

import { botInfo } from "asterobot:bot";

export default async function behavior() {
  botInfo("The script started");
}

Imports have to be import statements. Calling import() as a function is refused when the script runs, and require() doesn't exist. MDN explains JavaScript modules in detail.

Promises, async and await

Anything that involves the game takes time, so most of Asterobot's functions return a promise: sending a message, waiting for one, sleeping, most game data lookups. Inside an async function, await pauses your function until the promise settles. The rest of the bot doesn't pause with it: message handlers keep running while you wait.

Code that runs without an await does hold everything up, and Asterobot ends a script whose code runs for more than 250 ms in one go. A promise that rejects without a catch ends the script too, so wrap the awaits that can fail in try/catch. Async and timing has the details.

The default export has to be an async function, or a function that returns a promise.

MDN has good pages on using promises and async functions.

BigInt

Some message fields hold 64-bit integers, such as account ids, character ids or kamas. A regular JavaScript number can't store all of those exactly, so scripts receive them as BigInt values, written with an n at the end:

const id = traffic.payload.senderCharacterId; // for example 123456789012n

if (id === 123456789012n) {
  // A BigInt compares with another BigInt, not with a number.
}

You can't mix a BigInt and a number in one calculation: 1n + 1 throws a TypeError. Convert with Number(value) when you know the value is small enough, or keep working in BigInt. When you send a message, a 64-bit field accepts a BigInt, a string of digits, or a whole number no bigger than Number.MAX_SAFE_INTEGER.

Settings are the exception: a setting declared as int is a regular number. MDN's page on BigInt covers the rest.

Uint8Array

Raw bytes come as Uint8Array values: message fields that hold bytes, and traffic.rawAny, the undecoded bytes of any message. A first script rarely needs them.

What's different from a browser or Node.js

Scripts run inside Asterobot's JavaScript engine. The syntax is modern: classes with private fields, optional chaining (?.), ??=, spread, generators, top-level await and BigInt all work. What surrounds the language is much smaller than in a browser or in Node.js:

JavaScript support has the complete list.