Modules and imports

Every file of a package is an ES module. Scripts reach Asterobot's functions, their own files and other packages through import statements, and through nothing else.

The built-in modules

These modules only have named exports. Import each function by its name:

import { on, send } from "asterobot:protocol";
import { record, text } from "asterobot:gamedata";

There's no default export and no object grouping a module's functions: import gamedata from "asterobot:gamedata" and import { gamedata } from "asterobot:gamedata" both fail. If you prefer one name for a module, use a namespace import: import * as protocol from "asterobot:protocol", then protocol.send(...). asterobot:console is the one module that also exports an object, console, so that console.log() reads the way it does elsewhere.

asterobot:parameters is scoped to the package that imports it. In your package, values holds your package's settings. Imported from a dependency, it holds the dependency's own. Settings in dependencies explains how those show on the bot's page.

A built-in name that doesn't exist, such as asterobot:fs, keeps the script from loading. The reason contains built-in module "asterobot:fs" is not registered.

Importing your own files

// index.js
import { formatChat } from "./lib/format.js";

// lib/format.js
export function formatChat(channel, sender, content) {
  return `[${channel}] ${sender}: ${content}`;
}

A relative import follows these rules:

• It starts with ./ or ../, and is resolved from the folder of the importing file.
• It names the file completely, extension included: ./lib/format.js, not ./lib/format.
• It stays inside the package. ../ can't lead to another package's files.
• It never starts with / and never contains a backslash.

A path without ./, such as lib/format.js, isn't a file path: Asterobot reads it as the name of a package your package depends on, and fails with has no locked dependency for "lib/format.js".

When an import breaks a rule, the script doesn't load, and the toast gives no reason. The reason contains one of these texts:

The editor underlines an import of a file that doesn't exist as an error, and the bot's Settings > Package settings shows the full reason, as The entry function explains.

Each module runs once per start, however many files import it, so a variable at the top level of lib/format.js is shared by every file that imports it. Each bot has its own copy: two bots playing the same package never share a variable.

Importing another package

To import another package from your library, first declare it in the dependencies of your asterobot.json, as Dependencies describes. Then import it by the name you declared:

import { formatChat } from "chat-tools";
import { findSpots } from "@alice:mining";

You receive what the dependency's index.js exports, and only that. A path into the dependency, such as "chat-tools/lib/format.js", isn't supported and fails with has no locked dependency for "chat-tools/lib/format.js". A package that wants to share something exports it from its index.js.

A name your package doesn't declare fails the same way. That's also what happens with "lodash", "fs" or any other npm or Node.js module name.

Versioned imports

An import can carry a version after an @:

A range or latest only chooses among the versions of that package that are already part of what the bot runs, brought in by your manifest or by a dependency's. It never installs anything. When none matches, the script doesn't load, and the reason contains no installed version of "chat-tools" satisfies "^1.0.0".

What a script can't import

No browser or Node.js globals

Scripts have the standard JavaScript built-ins, such as Math, JSON, Date, Map, Promise and BigInt, and the functions of the asterobot: modules. The globals of a browser or of Node.js don't exist:

The editor knows this: it marks these names as errors. JavaScript support lists the language features scripts have and the few they don't.

Next, Async and timing.