aego/docs/export.md

Export

aego export builds a game that runs on a machine without Go, without the engine sources and without the project.

aego export [dir] --target host|linux|windows|darwin[/amd64|/arm64]|web --development|--release --out dir
aego export --check --release        pre-export checks only
aego export --json                   report as JSON

In the editor: File → Export… opens the Export panel (target, profile, Check, Export, Reveal in File Manager). Progress is in Task Center, the report stays in the panel. Project Health lists what would block a release export.

What is built

Part	Content
binary	cmd/aego-runtime (or the generated main of a native project) built with -tags aego_runtime: no editor, pipeline, compiler, workspace or docs. SDL3 is linked statically.
data/manifest.aetext	engine version, profile, target, the game block (name, module, version, start scene, window, defaults, project sections) and the asset index
data/artifacts/	imported artifacts named by content hash, <sha>.<kind>; no .aes, .aescene, .meta, project.aego
export.aetext	Export Manifest: versions, target, profile, modules, binary and its size, libraries with licenses, start scene, data sizes by kind, content hash, build time
licenses/	SDL3 license

The runtime reads only the manifest: vfs/exportfs opens a file only when the manifest lists it with the same size.

Target	Layout
linux	game, data/, game.desktop, icon.png
windows	game.exe with icon, version info and a PerMonitorV2 manifest; release has no console
darwin	Game.app/Contents/{Info.plist, MacOS/game, Resources/data, Resources/icon.icns}, ad-hoc signed when codesign exists

Profiles

• development: logs to stderr, debug draw on, unstripped binary.
• release: -trimpath -s -w; debug { enabled=false }; the log goes to <profile>/logs/game.log; tracing only with --trace; missing asset references block the export.

Project fields

project version=1 {
  gameVersion="1.2.3"
  icon="branding/icon.png"
}

The icon must be a PNG of at least 16×16; 1024×1024 square is recommended.

Checks (D288)

Code	Meaning	Severity
EXP001	no start scene, or it is not an imported scene	error
EXP002	scripts do not compile	error
EXP003	an asset failed to import	error
EXP004	an asset references a missing asset	error in release, warning in development
EXP005	the icon is missing or not a PNG	error
EXP006	duplicate .meta ids	error
EXP007	a scene does not load	error
EXP008	a scene uses a component no module registers	warning

Asset validators (DATxxx and module validators) run as well. A blocked export exits with code 2.

Running the game

game [--data dir] [--profile name] [--windowed|--fullscreen] [--scene id|path]
     [--log file] [--trace file] [--replay file] [--headless --frames n] [--seed n]

Settings, saves, logs and crash bundles live in UserConfigDir/aego/<module>/profiles/<name>/, never next to the game.

Toolchains

The export needs Go and the SDL build for the target in .cache/native/<os>_<arch> of the engine tree.

From → to	Setup
host	make bootstrap
linux → windows	CC=x86_64-w64-mingw32-gcc GOOS=windows make bootstrap, then aego export --target windows --cc x86_64-w64-mingw32-gcc, or zig cc -target x86_64-windows-gnu
linux → darwin	osxcross: CC=o64-clang GOOS=darwin make bootstrap, --cc o64-clang
any → web	nothing beyond Go: the build is GOOS=js GOARCH=wasm without cgo

CC_<OS>_<ARCH> (for example CC_WINDOWS_AMD64) replaces --cc.

Not in v1

No .aepak, no pruning of unreferenced assets (every imported asset except presets is exported), no stripping of embedded engine resources, no installers or notarization.

Web (D295)

aego export --target web builds the same runtime for js/wasm and writes a folder that any static server can host:

File	Content
index.html	a full-window canvas, the loader with progress and errors, a fullscreen button
loader.js	fetches data/files.json, then game.wasm, the manifest and every artifact (six at a time), and starts the game
wasm_exec.js	the Go WebAssembly support script of the toolchain that built the game, its license in licenses/Go.txt
game.wasm	cmd/aego-runtime with -tags aego_runtime; release adds -trimpath -s -w
data/	manifest.aetext, artifacts/ and files.json with every file and its size
export.aetext	as for desktop targets, plus binaryGzip

Every file that compresses by more than 10% gets a .gz copy next to it, and a .br copy when brotli is in PATH; serve them with gzip_static/brotli_static or the equivalent, and serve .wasm as application/wasm. Artifacts are named by content hash and can be cached forever; index.html, game.wasm, the manifest and files.json carry the export hash in their query strings.

The game reads its data from memory: the loader hands the bytes to the runtime, which mounts them with vfs/memfs after checking every file against the manifest. Settings and saves go to localStorage through platform.UserFiles() (a few MB per site, writes past the quota fail with an error); there are no log files and no crash bundles, the log goes to the browser console. Fullscreen and pointer lock need a click or key press first. URL parameters ?scene=, ?seed=, ?profile= and ?debug=1 replace the command-line flags.

Checks: EXP010 warns about an asset kind the web runtime cannot load (none yet), EXP011 warns that a native module must build without cgo. The target budget is 8 MB gzip for game.wasm; make site exports the platformer to site/demo/ and fails above it.

Editor app on macOS

make editor-app builds .cache/Aego Editor.app with the native menu bar: File, Edit, Scene, Play, Assets, Window and Help move from the window into the system bar. Create stays in the Scene View "+" and the Hierarchy menu. Shortcuts are shown in the menu and still go to the editor, so text fields keep their own keys.