Engine release: plan¶
Goal: a game developer downloads one .zip per platform, runs the engine without installing anything, develops a
game with it, and ships the runtime/ folder with the game. The same workflow also publishes a rolling nightly.
Based on the code of 2026-11-07 (the generic executable is aylo-runtime, the signing tool aylo-sign).
1. Decisions of this plan¶
| # | Decision | Why |
|---|---|---|
| D1 | One zip per platform and architecture, aylo-engine-<version>-<os>-<arch>.zip, holding the runtime, the tools and (when it exists) the editor. No separate editor zip. |
One download for a game developer; the runtime/ folder is the only part a game ships. |
| D2 | No dependency beyond the OS and the GPU driver. Third-party libraries are static or bundled; a script fails the build when a binary resolves a library outside runtime/ (allowlist: the OS and the Vulkan driver). |
"Runs without any dependency" is checked, not hoped for. |
| D3 | No headers or SDK in the zip. A game is Luau; a native plugin needs the compiler of the engine (checkLibrary()), so a separate -sdk zip would come later, if asked. |
The Luau API is the product. |
| D4 | SemVer, one version for the engine. 0.x until the script API settles; after that a breaking change to what a script sees is a major version. The version is in xmake.lua, --version and manifest.json. |
A game developer must know what an upgrade can break. |
| D5 | The package is made by one xmake task, run the same locally and in CI. The build and the zip have the same layout: lib/ holds the libraries that are not plugins, plugins/ the plugins, all real files, no link (a second copy of a library would be loaded twice, and a tool that flattens links would make one). |
One recipe, testable on a developer's machine. |
| D6 | A v* tag publishes a draft GitHub Release; a human reviews and publishes it. Notes come from the Conventional Commits. |
Releases are a human decision (AGENTS.md). |
| D7 | Nightly: a rolling nightly prerelease, replaced after every push to main whose CI is green (docs-only pushes skipped, a burst of pushes builds the last one). Version <next>-nightly.<sha>. |
Game developers can test main; the stable "latest" release stays stable. |
| D8 | Signing: free options only. SHA256SUMS and a GitHub artifact attestation on every zip; ad-hoc codesign on macOS; SignPath Foundation for Windows when accepted. Notarization and paid certificates are out of scope. |
No certificate budget; the repository is public. |
2. Layout of the zip¶
aylo-engine-<version>-<os>-<arch>/
├── runtime/ what a game ships
│ ├── aylo-runtime(.exe)
│ ├── lib/ the libraries that are not plugins (on Windows, next to the executable)
│ ├── plugins/ the plugin libraries, real files; the engine scans it
│ │ └── backends/
│ └── licenses/
├── editor/ later, never shipped
├── tools/aylo-sign(.exe)
├── templates/game/ a starter game folder
├── manual/ offline copy of the manual
├── README.md LICENSE VERSION
└── manifest.json version, library ABI version, compiler, commit, sha256 of every file
A game ships runtime/ and its own game/ folder.
3. Tasks¶
| Id | Task | Blocked by | Priority | Size |
|---|---|---|---|---|
| REL-01 | Check script: a build resolves nothing outside its folder | none | P1 | S |
| REL-02 | Self-contained dependencies on the three platforms | REL-01 | P1 | L |
| REL-03 | Engine version: --version and manifest.json data |
none | P1 | S |
| REL-04 | Packaging task: the zip layout | REL-02, REL-03 | P1 | M |
| REL-05 | Smoke test of the zip in a clean directory | REL-04 | P1 | M |
| REL-06 | release.yml: tag, matrix, attestation, draft release |
REL-05 | P1 | M |
| REL-07 | Nightly prerelease on main |
REL-06 | P2 | S |
| REL-08 | Sign the binaries: ad-hoc macOS, SignPath on Windows | REL-06 | P3 | M |
| REL-09 | Docs: shipping a game, releasing the engine | REL-04 | P2 | S |
| REL-10 | Runtime layout: lib/ and plugins/, real files |
REL-04 | P2 | M |
| REL-11 | Transform and input loaded as plugins | REL-10 | P2 | M |
| REL-12 | Static modules that no plugin links | REL-11 | P2 | M |
REL-01 -> REL-02 --\
+-> REL-04 -> REL-05 -> REL-06 -> REL-07
REL-03 ------------/ \ \-> REL-08
\-> REL-09
REL-04 -> REL-10 -> REL-11 -> REL-12
REL-01: check script¶
A script (.github/scripts/check-self-contained.sh, and a .ps1 for Windows) that takes a folder and lists every
binary in it whose dynamic dependencies resolve outside it: ldd / readelf -d on Linux, otool -L on macOS,
dumpbin /dependents on Windows. An allowlist per platform holds the OS libraries (libc, libm, libvulkan where
loaded from the driver, kernel32, libSystem...). It exits non-zero with the offenders. First run on the current build:
the list of what REL-02 has to fix.
REL-02: self-contained dependencies¶
Make every third-party package static or bundled so the check passes. Linux: build on an old glibc baseline (an Ubuntu
22.04 container), static or bundled libstdc++ and libgcc, libsodium and the other packages static, Vulkan loaded
so a missing loader gives a clear message. Windows: /MD with the VC++ runtime DLLs next to the executable. macOS:
MoltenVK and the Vulkan loader bundled. Rpaths stay relative to the executable. Raise kLibraryAbiVersion if a library
entry changes.
REL-03: engine version¶
One version in xmake.lua (set_version), read by aylo-runtime --version (version, commit, compiler, library ABI
version) and written to manifest.json by REL-04. A nightly stamps <version>-nightly.<sha>. Tested.
REL-04: packaging task¶
An xmake task (xmake package-release) builds in release mode and produces the layout of section 2 in build/package/
and the zip next to it: the build's layout copied as it is (REL-10), symbols stripped (debug symbols in a -symbols zip),
manifest.json with a sha256 per file, third-party licenses in runtime/licenses/, templates/game/ from a small
example game, the offline manual (uvx zensical build). Runs the check of REL-01 on runtime/.
REL-05: smoke test¶
A script that unzips into an empty directory (a bare container on Linux, no toolchain) and runs the checks of a real
user: aylo-runtime --version; aylo-runtime --server --game templates/game starts, accepts a client connection and
stops cleanly; the check of REL-01 on the unzipped folder; aylo-sign keygen works.
REL-06: release.yml¶
Triggered by a v* tag. Matrix Linux, macOS (arm64), Windows: build in release mode, run the tests, package (REL-04),
smoke test (REL-05), SHA256SUMS, actions/attest-build-provenance on every zip, then a draft GitHub Release with
notes generated from the Conventional Commits and the zips attached. Permissions: contents: write,
id-token: write, attestations: write for this workflow only.
REL-07: nightly¶
On every push to main (paths-ignore: docs/, manual/, *.md), after the CI is green: build, package, smoke test,
attest, and replace the assets of the nightly prerelease (the tag moves to the commit). A concurrency group with
cancel-in-progress builds only the last of a burst. Release notes say it is untested and not for shipping.
REL-08: signing¶
macOS: an explicit ad-hoc codesign -s - on every binary and library, in the packaging. Windows: apply to the SignPath
Foundation for the repository, then sign the .exe and .dll in release.yml once accepted. Documented limits:
Gatekeeper quarantine on macOS, SmartScreen on Windows.
REL-09: docs¶
manual/: a page "Shipping your game" (what to copy, how to rename, signing your own build, the macOS quarantine
command, SmartScreen), written with the write-manual skill. docs/release/: how a release and a nightly are made and
how to cut a version. The README of the zip.
REL-10: runtime layout¶
The build tree and the zip share one layout: the executable, lib/ for the shared libraries that are not plugins,
plugins/ for the plugin libraries and plugins/backends/ for the backends, all real files, no link. A second copy of a
library would be loaded twice, and a tool that flattens links would make one. rpaths: the executable lib, a plugin
$ORIGIN:$ORIGIN/../lib (plugins link each other), a backend $ORIGIN/../../lib. Windows has no rpath: the DLLs the
executable links sit next to it.
REL-11: transform and input as plugins¶
The engine stops linking plugin-transform and plugin-input and loads them from their libraries like the others
(the transform plugin, which every game has, by name; a clear error if it is missing). NetworkInput stays in the
engine and reads the input through the rtype.input.read engine call: moving it to the input plugin would make a plugin
depend on replication.
REL-12: static modules¶
luau, network, replication, scripting and engine are static libraries linked into the executable: no plugin
or backend links them. ecs and the contracts stay shared (registries and RTTI shared with plugins). A build rule
refuses a shared library that links a static module, so their state can never be duplicated.