Open Asterune
Command-line exports

Command-line exports

Automate exports, configure profiles, and verify artifacts from a terminal.

The Studio command line exports saved projects and verifies build artifacts. Use Exporting games for the graphical export workflow.

Prerequisites

Save the project before exporting from the command line. A command-line export reads the project from disk. Put asterune-studio on PATH, or invoke the export command through cargo run -p asterune-studio -- from the source checkout.

Each export target needs a compatible runtime template. Run these commands to inspect template availability and project readiness:

Shell
asterune-studio templates
Shell
asterune-studio doctor ../my-game

If doctor reports a missing template, provide the template directory through ASTERUNE_PLAYER_TEMPLATES or place player-templates/ beside Studio's executable. A template includes a binary and its descriptor; copying a player binary alone does not establish template compatibility.

For a source build, install Node.js and run this command from the Asterune repository root to build and stage a release template for the current machine:

Shell
node engine/scripts/build-player.mjs

Set ASTERUNE_PLAYER_TEMPLATES to the absolute path of the resulting engine/player-templates/ directory. Run doctor again and confirm that it lists the requested target as usable before exporting. The script builds the host target; other targets need their own templates.

Export a desktop game

  1. Choose a target with a usable template:

    TargetSystem
    windows-x86_64Windows on x86-64
    linux-x86_64Linux on x86-64
    macos-aarch64macOS on Apple silicon
    macos-x86_64macOS on Intel

  2. Export the saved project. This example requires a Linux template:

    Shell
    asterune-studio export ../my-game ../builds --name MyGame --target linux-x86_64

  3. Inspect ../builds/MyGame-linux-x86_64/ and the adjacent MyGame-linux-x86_64.build.json report. If export fails, read the reported preflight or build error. Repair the named template, asset, or project setting and run the export again.

  4. Verify the exported files against the report:

    Shell
    asterune-studio verify ../builds/MyGame-linux-x86_64.build.json

    Verification checks the product against the report's recorded digests. A mismatch means the output differs from the recorded build; export again before distributing it.

  5. Launch MyGame inside the exported directory. Confirm that the game opens and its assets load. Distribute the complete directory or its generated archive so the executable retains its content and launch manifest.

Windows exports use an .exe. macOS exports place the application in a .app bundle inside the target directory.

Export a dedicated server

The Studio Export dialog reports dedicated-server builds as unavailable. Use the command line with a compatible server template. After building or locating the template, export a saved project with the built-in Linux server profile:

Shell
asterune-studio export ../my-game ../server-builds --name MyGame --profile dedicated-server-linux

The dedicated-server-windows profile selects a Windows server template. Inspect the export's build report and run asterune-studio verify on that report. Multiplayer servers describes launching the result and connecting a client.

Export options

OptionDefaultBehavior
--target <list>Usable template targets, unless a profile selects targetsAccepts comma-separated target keys. Unknown keys fail. macos is ambiguous; choose an architecture.
--profile <id>Ad-hoc release clientSelects an export profile. Command-line overrides take precedence over its settings. An unknown ID fails.
--place <key>The game's start placeSelects the place opened for a game export. An unknown key fails.
--name <title>Project nameSets the export name.
--cooking all|usedall for ad-hoc exportsIncludes all assets or selects assets identified as used. Unknown modes fail.
--package <list>No archives for ad-hoc exportsAccepts zip and tar.zst, separated by commas. Unknown formats fail.
--player-profile release|debugreleaseSelects the template build profile. Debug players retain assertions and development source overrides.
--allow-partialDisabledAllows the command to accept builds for only some requested targets. Without it, a requested target that cannot be built fails the command.

Without a named target or profile, export attempts every target with a usable template. Inspect each build result when exporting for multiple targets; failure does not imply that other target output was removed.

Save export profiles

List the project's profiles or write a starter asterune.export.json at its root. The write command replaces an existing file. Copy any existing asterune.export.json before running it to preserve custom settings:

Shell
asterune-studio export ../my-game --list-profiles
Shell
asterune-studio export ../my-game --write-profile

The starter file contains built-in profiles and signing examples. Signing runs are used only when a profile names one. Profiles can select targets, runtime profile, output directory, archive formats, asset cooking, and signing settings. Relative output paths are resolved against the project root.

Related documentation