Build your first hosted system

This tutorial creates a system named Starfall and packages it as a deterministic .aethersystem.zip that Aether can install.

#Before you begin

Install Bun 1.3 or newer, then install the Aether CLI:

bun add --global @aether/cli
aether --version

#1. Scaffold the project

Choose a directory for your system projects, then run:

mkdir starfall-system
cd starfall-system
aether create system starfall --title "Starfall"
cd systems/starfall
bun install

The project contains:

• aether.system.json, which defines the system and lists its files;
• package.json, with the Aether CLI version used by the project;
• README.md, with the commands for working on the system.

The scaffold defines one starfall.character document type, a responsive health sheet, and a roll button. It also includes placeholder listing and rights text. Replace both before publication.

#2. Validate before writing output

From systems/starfall, run:

aether system validate .

Validation prints the system id and version, compatibility range, file size, document types, sheets, companion applications, automation, starter data, dependencies, services, migrations, and rights declaration. It writes nothing.

Errors identify the manifest field or file that needs attention when possible. Do not continue while the validator reports a missing file, unknown field, invalid view reference, dependency conflict, unsupported content type, or exceeded limit.

#3. Add system data

Edit aether.system.json and keep each concern explicit:

1. Add a schema and default value for every document type owned by the system.
2. Bind sheet fields only to paths that exist in that schema.
3. Put authored choices in authored fields and calculated totals in derived fields.
4. Add owner-only or GM-only visibility rules to fields that need them.
5. Add starter records only when a GM can choose whether to include them.
6. Declare every required package and service before using it.

For a companion application, automation entry, or scripted migration, add the source file to the project. Then add a files entry with its artifact path, source path, content type, and role. Source paths must stay inside the project. Artifact paths must stay inside the built package.

Read Hosted system packages before adding executable entries. They run in sandboxes and cannot access Node, Bun, the DOM, the database, the filesystem, or arbitrary network addresses.

#4. Build and inspect

From systems/starfall, run:

aether system build .
aether system inspect dist/system.aethersystem.zip

Build writes dist/system/ and dist/system.aethersystem.zip. Inspect reopens the archive, verifies every file digest, and prints the package's SHA-256 identity.

Run build twice without changing the project. The identity must be the same both times. Published versions cannot change, so update the version in aether.system.json whenever the package contents change.

#5. Exercise the complete flow

Use a local or test Aether installation for acceptance:

1. Publish the artifact through Creator Studio or the supported local/test CLI.
2. Open the Marketplace listing and review the exact hash and package graph.
3. Create a disposable world with the system and optional starter content.
4. Open each sheet at desktop and narrow dock widths.
5. Exercise every companion application, roll, resource edit, effect, automation topic, and hidden field as both GM and player.
6. Restart the world and verify that it loads the same version and hash.
7. If the next version declares migrations, test every supported source version and one deliberate failure before publishing it.

The build command proves that the package is valid. It does not prove the installation, permissions, sandbox, migration, or recovery flows. See Publish a system for both publication paths.