The editor

Every part of the package editor, with its files and plan files, saving and unsaved changes, Run, the Game panel, completion and error checking, and why marketplace packages can't be edited.

The editor is where you write a package's code, in Asteroboard. Create a package gave a first tour of it. Some of its parts aren't obvious: saving replaces the package's files, Run does four things in one click, and a clean error badge doesn't mean the script will run.

Open it

• In Library Manager, open a package's menu, or right-click its row, and choose Edit code.
• On a package's page, click Edit code at the top.
• New package and Copy to a new version open the editor on the package they create.

Edit code is only offered for local packages. When the editor can't load a package's files, for example because the package was removed in the meantime, it shows Couldn't load this package's code instead of the files and the code.

The top bar

Files

The Files column lists the package's files: index.js first, then the others in alphabetical order, each with its folders in its path, such as lib/format.js. A package's fight profiles, the .json files of its fightprofiles folder, are listed too, and open as JSON.

• Click a file to show it. Each file keeps its own cursor, scroll position, selection, folded blocks and undo history while you move between files.
• A dot after a file's name marks unsaved changes in it, and a number next to it counts its errors.
• The plus button at the top of the column opens Add a file. Type a Path, such as lib/helper.js, then click Add a file or press Enter. The dialog refuses a path that is neither a module ending in .js or .mjs nor a profile such as fightprofiles/careful.json or chatprofiles/wheat-ads.json, one that starts with / or contains .. or \, and one already used. It shows A file must be a .js or .mjs module, or a fight profile in fightprofiles/ or a chat profile in chatprofiles/, as a .json file. for the first. The new file is empty, opens right away, and only exists in the package once you save. Package layout gives every path rule, including one the dialog doesn't check.
• Resting the pointer on a file shows a trash icon. It removes the file from the list at once, without asking, and saving then deletes it from the package. index.js has no trash icon.

The other files see a new file as soon as you add it, before you save: an import of it completes and isn't marked as an error. Jumping to a function's definition, or renaming it, works across the files of the package the same way.

Plan files

A plan is a file of the package made in Asteroboard's Studio: places on the world map, the order the bot goes round them, and what it does at each. What makes a file a plan is its first line, wherever the file is:

// asterobot-studio-plan v1

• The Studio writes the whole file. It holds the plan as JSON between /* studio:plan */ and /* studio:end */, and generates everything around it: the imports of the packages and plans it uses, and its exports. The second line says so: a change made by hand is lost the next time the Studio saves the plan.
• It opens in the Studio. A file whose first line is the marker gets a plan icon in Files, and opens in the Studio instead of the code. View as code shows the file itself.
• It needs @asterobot:base. Base's run() plays it, so creating a plan adds base to the package's dependencies.

A script plays a plan by importing its default export and passing it to run(). This is the index.js Start with the Studio creates:

import { run } from "@asterobot:base";
import main from "./plans/main.js";

export { parameters } from "./plans/main.js";

export default async function behavior() {
  void run(main);
}

run() resolves when the plan ends and rejects when it fails, and stop() stops it cleanly. Base's README describes how a plan plays, and the plan format.

A plan can declare settings of its own, which its file exports as parameters. They're the package's settings, on the bot's Settings tab, only once index.js re-exports them, as the line above does. A package has a single parameters export, so the settings of several plans are merged into one.

The Studio's Add it button writes this for every plan, as long as index.js only gathers plans' settings. When index.js has no settings yet, it adds the line above, after the imports. For a second plan, it turns that line into the merge of both:

import { parameters as mainSettings } from "./plans/main.js";
import { parameters as bankSettings } from "./plans/bank.js";

export const parameters = { ...mainSettings, ...bankSettings };

A third plan adds its own import and its own spread to that merge. Each name comes from the plan's file name, so plans/farm-run.js gives farmRunSettings, with a number added when the name is already used in index.js.

When index.js declares settings of its own, the Studio leaves them alone: instead of Add it, it shows the lines to write, and you merge them by hand the same way:

import { parameters as mainSettings } from "./plans/main.js";

export const parameters = { ...mainSettings, maxFights: { type: "int", default: 20 } };

A plan whose settings aren't re-exported uses their defaults, and the bot's Console says so.

Saving

Click Save, or press Ctrl+S (Cmd+S on a Mac).

Saving replaces the package's files with exactly the files the editor holds. A file you removed from the list is deleted, and so is any file that isn't in the list, such as one added to the package from somewhere else while the editor was open. The manifest isn't touched.

What else to know about saving:

• Unsaved also goes away when you undo your changes back to what was last saved.
• Removing a file counts as a change, even when every other file is unchanged.
• Nothing asks you to save when you leave the editor: unsaved changes are lost.
• The editor reads the files when it opens. If the package changes elsewhere in the meantime, in another tab or from the command line, the editor doesn't show it, and saving from the editor overwrites that change. With the same package open in two tabs, the last save wins.
• A script that's already running keeps the code it started with. The next start uses what you saved: see Play, stop and reload.
• Saving doesn't check the declarations of settings and actions. Package settings, on a bot set to the package, does: see Declare settings.

When saving fails, a toast says Couldn't save, without a reason. The usual causes are a file path Asterobot refuses, such as ./lib/helper.js, a package that was removed in the meantime, or a package that isn't local.

Run

Run does in one click what you'd otherwise do in four steps:

1. It saves the package. If saving fails, it stops there, with Couldn't save.
2. It stops the script the picked bot is running, if there's one.
3. It sets the bot's package to this package, at this version.
4. It starts the script.

A toast then says Running on followed by the bot's name, or Couldn't run the package when a step failed. The bot keeps this package afterwards, so Play on its page starts it again. Identify and run shows where the output goes and what to check when the script doesn't start.

The Game panel

Game opens a panel next to the code, with two tabs: Atlas, the map viewer, and Datacenter, the game data browser. Drag the line between the code and the panel to share the width differently. Closing the panel only hides it: when you open it again, each tab is where you left it.

The panel shows one game version:

• The game version Asterobot is tested against, when it's downloaded and its game data extracted. A badge shows the version number, and resting the pointer on it explains that Atlas and Datacenter answer from that version, the one bots meet.
• Otherwise, the most recent game version with extracted game data. The badge then reads Incompatible version, and resting the pointer on it explains the difference: fine for writing a script, since most IDs carry over between neighbouring versions, but not the version Asterobot connects bots with, and map IDs, table columns and game texts can differ.
• When no game version has extracted game data, the panel says No extracted game version. Extract one, as Extract game data shows, then open the panel again.

Names and texts in the panel use the language picked for game data on the game's page. Map viewer and Game data describe both tools.

Completion and error checking

The editor loads its typings from the Asterobot it's connected to: the asterobot: modules, and a type for each game message that version of Asterobot knows. With them, it completes functions, message names and payload fields, and checks your code the way TypeScript checks JavaScript. JavaScript support describes that check, the warnings for the three constructs scripts don't support, and the JSDoc types you can use.

The error badge and the numbers in Files count errors only, in every file, open or not. Warnings aren't counted. Neither errors nor warnings stop you from saving or running.

Two mistakes are worth looking for in the editor before anywhere else: a syntax error, and an import of a file that doesn't exist. When a script can't even load because of one of them, Run only says Couldn't run the package, while the editor shows the line, and Package settings, on the bot's Settings tab, gives the full reason. On the other hand, code with no error in the editor can still fail when it runs: the editor knows the shape of messages, not what the game will send.

Marketplace packages are read-only

A package installed from the marketplace, or any package with a @publisher:name name, can't be edited. Library Manager doesn't offer Edit code or Copy to a new version for it, Asterobot refuses to save its files, so Couldn't save appears if you reach the editor for it anyway, and its Manifest card is read-only. The package stays exactly as it was installed, which the integrity check described in The manifest relies on.

When you need another author's code in your package, depend on their package, as Dependencies explains. When you really need to change it, export it and import the .zip under a local name: the imported package is yours to edit. It has no link to the marketplace any more, so no updates and no Source row, and bots save its settings under its new name. See Zip files and the command line.

Next, Zip files and the command line.