# 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.