Zip files and the command line

A package leaves Asterobot and comes back as a .zip file: that's what Export produces, what Import a .zip reads, and what you upload to publish on asterobot.net. The command line installs packages from a folder instead, which lets you write them in the code editor you already know.

What goes in a .zip

The simplest archive, and the one Export produces, has the package's files at its root:

index.js
asterobot.json
lib/format.js

The rules:

• index.js has to be at the root of the archive.
• Only .js and .mjs files are read, in any subfolder, following the paths described in Package layout. Other files, such as a README or images, are left out and not kept.
• asterobot.json is optional, next to index.js. Its sourceId and integrity are removed at import, as The manifest explains.
• An archive can't be larger than 32 MiB, whether it's imported or installed from the marketplace.
• The archive doesn't carry the package's name and version. They come from the import dialog, or from the file on asterobot.net.

Asterobot also accepts an archive whose files all sit in a single folder, such as my-bot/index.js, which is what compressing a folder produces. That only works when the archive lists nothing but the folder's contents. With a file or a second folder next to it, or with an entry for the folder itself, which some archiving tools add, Asterobot doesn't find index.js and the import fails. To avoid surprises, compress the files of the package rather than the folder that holds them.

Export

In Library Manager, open a package's menu, or right-click its row, and choose Export. The package's page has the same menu. Your browser downloads the archive.

• The file is named after the package and its version, with the @ removed and the : turned into -: version 1.2.0 of @alice:chat-tools gives alice-chat-tools-1.2.0.zip, and my-bot 1.0.0 gives my-bot-1.0.0.zip.
• The archive holds every file of the package at its root: its modules, and asterobot.json when it has one.
• The manifest is exported as it is. For a package installed from the marketplace, that includes its sourceId and integrity, which an import removes but library install keeps.
• Every package can be exported, local or not.

Import a .zip

Share your package walks through the dialog, and Manage your library lists its messages. The details that matter to an author:

• Version fills in by itself when the file's name ends with a hyphen and a version starting with a digit, as in my-bot-1.2.0.zip, and only while Version is empty. A version with its own hyphen defeats it: my-bot-1.2.0-rc.1.zip suggests nothing.
• Any valid name works, local or @publisher:name. Only a local name gives a package you can edit.
• An installed package with the same name and version is replaced. The dialog warns you, but, unlike New package, it doesn't disable the button.
• Importing never installs the package's dependencies. Install them first, or the package won't start.
• When the import fails, the toast Couldn't import the package gives no reason. Unzip the archive and install the folder with library install: the command prints the reason for most failures.

The command line

Three commands of the library group manage the library from a terminal. Command line explains how to run Asterobot's commands on each system.

library install

asterobot library install --path ./my-bot --name my-bot --version 1.0.1

What it does:

• It copies every .js and .mjs file of the folder and of all its subfolders, whether index.js imports it or not, and asterobot.json from the root of the folder. Other files are ignored. Keep the folder to your package's own files.
• It replaces the package if that name and version are already installed.
• It refuses a folder that contains a symbolic link anywhere, with module source "<path>" is a symbolic link.
• It keeps the sourceId and integrity of the folder's asterobot.json, when the file has them.
• It doesn't download dependencies.

On success, it logs Package my-bot@1.0.1 installed. On failure, the message contains failed to install package: followed by the reason, such as package my-bot@1.0.1 entry "index.js" is missing from its sources.

library list

asterobot library list

Prints a table with one row per installed version, sorted by name, then by version: the name, the version, the provenance and the publisher, which is empty for a local package.

NAME               VERSION  PROVENANCE  PUBLISHER
@alice:chat-tools  1.2.0    community   alice
my-bot             1.0.0    local
my-bot             1.0.1    local

library remove

asterobot library remove --name my-bot --version 1.0.0

Both flags are required. The command removes that version and logs Package removed. Unlike Library Manager, it doesn't warn about the packages that depend on it or the bots set to it. A version that isn't installed fails with a message containing package my-bot@1.0.0: package is not installed.

Asteroboard shows what these commands changed the next time it loads the library, for example after you reload its page.

Work with your own code editor

Only Asteroboard's editor completes the asterobot: modules and the game's messages. If you'd still rather write the code in the editor you're used to, keep the package in a folder of your own and install it with library install after each change:

1. Create a folder with index.js, your other modules and, if the package needs one, its asterobot.json without sourceId or integrity. To start from a package you already have, export it, unzip it, and remove those two keys from its manifest if they're there.
2. Edit the files.
3. Install the folder, under the same name and version for as long as you work on that version:

asterobot library install --path ./my-bot --name my-bot --version 1.0.1

4. The first time, set a bot to that package and version with Load a new package, reloading Asteroboard's page first if the package isn't listed. Then click Play, and Stop then Play after each new install: every start reads the files installed at that moment.
5. Go back to step 2.

While you work this way, don't save that package from Asteroboard's editor: saving replaces the installed files with what the editor holds, and Run saves first. When the version is done, move on to a new --version for the next changes.

You can also edit the files of a local package directly in the library, inside Asterobot's data folder, and the next start reads them. The same caution about Asteroboard's editor applies. Never change the files of a package installed from the marketplace there: its integrity check then refuses it. Files and folders says where the data folder is.

Next, the Publishing chapter starts with what to check before you publish.