forma-engine/docs/BUILDS.md

Web and application builds

Forma packages a project as a standalone web build, Linux x64 AppImage, Windows x64 portable EXE or Android APK. The output contains the project's scenes, behaviours, models and runtime. The player does not need the editor or MCP service.

Application builds wrap the web runtime. Desktop uses Electron and Chromium; Android uses a Java WebView shell. Project JavaScript is not compiled ahead of time into native machine code. Android requires Android 8+ and a compatible, updated system WebView.

From the editor

1. Start the local engine and open Сборка игры.
2. Choose a target, name, stable application ID and version.
3. Set desktop window/fullscreen options or Android orientation.
4. Start the build and inspect its log. The job uses an immutable snapshot of the selected project revision.
5. Download a successful artifact. The build panel shows its size, SHA-256 and source revision.

The queue allows one active build and up to three waiting jobs. Jobs can be cancelled. Build results and logs remain in the project folder; an interrupted build is marked failed when the server restarts.

Without the local service, the editor can download a build kit containing the current web project, platform templates, configuration and lockfile. A build kit is source material for a local build, not an already compiled executable.

Web

Choose the web target and extract its ZIP. Serve the extracted directory over HTTP:

python3 -m http.server 8080

Open http://localhost:8080/. Static HTTPS hosting also works. Opening index.html through file:// is not supported. For testing on a phone, serve only the exported project to your local network; the editor's MCP service remains bound to loopback.

Desktop toolchain

Requires Node.js 22.13+. Install the optional tools separately from the editor:

npm run setup:desktop
npm run build:doctor

The first build downloads the required Electron runtime and packaging tools. Linux AppImage requires a Linux host. The current Windows configuration can be packaged from Linux; Windows output is unsigned.

ELECTRON_BUILDER_COMPRESSION_LEVEL can override the default compression level of 3. Toolchains live outside project source and are not required for web export.

Android toolchain on Linux

Install a full JDK 17, including javac, plus curl and unzip. Set JAVA_HOME, then run:

npm run setup:android
npm run build:doctor

The setup script downloads Gradle 8.13, Android SDK platform 36 and Build Tools 35.0.0. Android SDK license acceptance and dependency downloads are part of local setup. The Gradle archive is checked against its published SHA-256.

An existing SDK can be selected with ANDROID_HOME or ANDROID_SDK_ROOT. FORMA_GRADLE selects an existing Gradle executable by absolute path. The automated Android toolchain setup currently targets Linux.

Debug APKs use the local Android debug signing key. Release APKs require your signing configuration in the server process environment:

Variable	Value
FORMA_KEYSTORE	Absolute keystore path
FORMA_KEY_ALIAS	Signing-key alias
FORMA_KEYSTORE_PASSWORD	Keystore password
FORMA_KEY_PASSWORD	Key password

Keep the key outside the repository and retain a backup for application updates. Signing passwords are not entered through the editor or MCP. The builder verifies generated APK signatures. A release build without a configured key fails instead of substituting a debug package. AAB output is not implemented.

Command line

After npm run build, pass a saved project folder, JSON or .forma file:

npm run game:build -- --project ./projects/MyProject --target linux --app-id games.studio.myproject --version 1.0.0 --mode release
npm run game:build -- --project ./projects/MyProject --target windows --app-id games.studio.myproject --mode release
npm run game:build -- --project ./projects/MyProject --target android --app-id games.studio.myproject --mode debug --version-code 1

Additional CLI options include --name and --fullscreen. A downloaded build kit provides a JSON configuration for window dimensions and orientation. The standalone builder accepts:

node native/build.mjs --config ./my-build.json --game ./my-web-project --out ./my-output

The output directory must be new or empty. Existing application packages are not overwritten.

MCP build tools

Tool	Purpose
build_targets	Inspect toolchain and signing readiness
build_start	Queue a build from the current project revision
build_status	Read status, logs, artifacts and hashes
build_list	List recent jobs
build_cancel	Cancel a waiting or active job

Read the project and available targets before starting a build. Poll its status until it finishes. Successful packaging confirms that an artifact was produced; launch and performance checks on the target device are separate.

Runtime boundaries

Desktop keeps Node integration unavailable to project scripts, with sandboxing and context isolation enabled. Packaged resources are served through the local forma protocol; external navigation and permissions are blocked. AppImage needs a working Chromium sandbox, and the wrapper rejects --no-sandbox.

Android uses WebViewAssetLoader for packaged resources, with no Internet permission, general file access or JavaScript-to-Java bridge. Both wrappers are intended for offline projects. Network features, storefront integration and platform services require additional implementation.

The automated test suite covers build configuration, resource access, kit generation and job handling. Native package creation requires the separate platform toolchains. Hardware performance and application launch behaviour must be checked on the intended devices.