Skip to content

Document hosted website exports for all scripting languages #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JamieW105 merged 1 commit into from
Nov 9, 2026
Merged

Document hosted website exports for all scripting languages #87

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 56 additions & 4 deletions docs/PROJECT_BUILDS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,59 @@ The game opens its own window and isolated simulation, forwards keyboard, primar

## Playable website

Select **Website (playable game)** and click **Build Project**. The editor exports the current game automatically: its scene snapshot, registered scripts, assets, HTML/CSS game UI, browser player and compiled WebAssembly runtime. **Do not create a `web/` folder or prepare a separate website.** No game server is required.
Select **Website (playable game)** in **File → Build Project…**. Choose the website mode:

| Mode | Languages | Hosting |
| --- | --- | --- |
| Hosted runtime (default for new build settings) | Lua 5.4, Luau, JavaScript, Python, C, C++, C#, Java, PHP, HTML/CSS | Native runtime on a matching OS/architecture with GPU and required language toolchains |
| Static WebAssembly | Lua 5.4, JavaScript, HTML/CSS | Any static HTTP/HTTPS host |

Existing saved build settings retain static mode until you select hosted mode.

### Hosted runtime: all scripting languages

Choose **Hosted runtime (all scripting languages)** and click **Build Project**.
The generated `website/` folder contains the native runtime, available sibling
runtime libraries and Luau host, a verified game snapshot in `data/`, player files,
launchers, game title and `readme.md`. It requires no browser-runtime resources.
Registered scripts are retained in their original language and use the same
native gameplay adapters as desktop play; no translation is performed.

1. Keep the complete folder together. Run `start-website.cmd` on Windows, or
`sh start-website.sh` on Linux/macOS. Use a host matching the exported binary.
2. Install the external toolchains used by the game on that host: Luau, Python,
C/C++ compiler, .NET SDK, JDK including `javac`, and/or PHP. The included Luau
host is used when present. Lua 5.4 and JavaScript are bundled. Missing
registered-script toolchains produce a startup error in the host terminal.
3. Open `http://127.0.0.1:8080`. Each connection starts an independent native game
session and temporary writable game copy; disconnecting removes that copy.
4. For another port pass `--website-address 127.0.0.1:9090` to the launcher.

For remote players, run on a GPU-capable server with a compatible graphics driver.
Use an HTTPS reverse proxy at the origin root; forward WebSocket upgrades for
`/play` and preserve the public Host and Origin headers. The default listener is
loopback. To bind a server interface pass `--website-address 0.0.0.0:8080`.
Static hosting alone cannot run this mode. No player-side language installation
is needed.

Keyboard, primary mouse, touch, native game UI (including PHP pages), and game
audio use the native simulation. Click/tap or press a key on the canvas to enable
sound. The host streams PNG-compressed 640 × 360 frames at up to 30 fps and
stereo 48 kHz audio. Bandwidth varies with scene complexity; network latency
adds input delay. Up to eight connections are accepted; inactive connections time
out after 30 seconds. Saves are connection-local and not persistent. Browser
microphone forwarding and player-side audio-device selection are unavailable;
native device APIs refer to the host. Run only trusted game packages under a
suitable host account, since native scripts have that account's privileges.

If the page fails, inspect both the browser error and host terminal. Restore
missing/corrupted game data, install reported toolchains, and check GPU drivers,
WebSocket forwarding, matching Host/Origin, proxy timeouts and bandwidth. Reload
after a disconnect to start a fresh session. Stop the launcher to stop hosting.

### Static WebAssembly

Choose **Static WebAssembly (Lua 5.4, JavaScript, HTML/CSS)** and click **Build Project**. The editor exports the current game automatically: its scene snapshot, registered scripts, assets, HTML/CSS game UI, browser player and compiled WebAssembly runtime. **Do not create a `web/` folder or prepare a separate website.** No game server is required.

The output's `website/` directory contains `index.html`, `player.js`, `rustic-browser.js`, `rustic-browser.wasm`, the game file manifest, `data/`, and a `readme.md` with local preview and publishing instructions. Publish the complete directory to any static web host, including a subdirectory. For a local preview:

Expand All @@ -33,7 +85,7 @@ Open `http://localhost:8080`. The game starts automatically with no engine-added

Use a recent browser with WebAssembly exception handling and WebGL 2. The generated player reports missing/corrupted files, unsupported graphics and runtime initialization failures. Game files are verified before scripts execute. Browser file writes use the runtime's in-memory filesystem and disappear on reload. Native microphone capture and native audio-device selection are unavailable; ordinary game audio uses Web Audio.

**Script compatibility:** direct web and Android exports currently support Lua 5.4, JavaScript and HTML/CSS behaviors. Scripts that need external desktop processes (including Luau, Python, C/C++, C#, Java and PHP) cause an explicit build error. Standalone PHP pages also cause an error. They are not silently omitted or converted. Use supported behaviors for these targets.
**Static script compatibility:** static web and Android exports currently support Lua 5.4, JavaScript and HTML/CSS behaviors. Scripts that need external desktop processes (including Luau, Python, C/C++, C#, Java and PHP) cause an explicit build error. Standalone PHP pages also cause an error. They are not silently omitted or converted. Use supported behaviors for these targets, or choose the hosted website mode for all scripting languages.

Installed engine distributions bundle `browser-runtime/` beside the editor. Game authors do not need Emscripten to export when those resources are installed. Source developers must build that runtime once with `python tools/build-browser-runtime.py` from the engine workspace, after activating Emscripten SDK 6.0.13 and installing Rust, Python 3 and libclang. The default output is `target/distribution/browser-runtime/`; keep it beside the editor executable. For a `dev-fast` editor, pass `--profile dev-fast`.

Expand All @@ -53,8 +105,8 @@ An APK can be installed on a compatible device with `adb install <output>/artifa

- **Build is disabled:** check the Required messages. Read-only editors cannot build; close the other writable editor and reopen the project. Windows packaging requires a Windows host and its bundled runtime. Inno Setup is configured automatically only when creating setup; a missing default compiler does not disable the build.
- **Inno Setup configuration failed:** check the displayed error, internet access to GitHub releases, and permission to install in your local Programs folder and update your user PATH, then retry **Build Project**. A failed signature check stops installation. You can also install Inno Setup 6 manually and enter its existing absolute `ISCC.exe` path. Invalid custom paths are reported in **Required**; reset the field to `ISCC.exe` for automatic setup. Inspect compiler failures for invalid version or image resources.
- **Website fails to load:** serve the complete generated `website/` directory over HTTP/HTTPS rather than opening `index.html` directly. Check the displayed error, browser console, and WebGL 2/WebAssembly support.
- **Browser runtime missing:** install an engine distribution with `browser-runtime/` or build the resources from source as described above.
- **Static website fails to load:** serve the complete generated `website/` directory over HTTP/HTTPS rather than opening `index.html` directly. Check the displayed error, browser console, and WebGL 2/WebAssembly support.
- **Browser runtime missing (static website/Android):** install an engine distribution with `browser-runtime/` or build the resources from source as described above.
- **Website has no sound:** click, tap, or press a key in the game to enable browser audio.
- **Resource path rejected:** use a path inside the project without `..` or absolute components. Remove symbolic links from website/Android build inputs. Choose a source folder outside the builds directory; outputs cannot be nested in their input.
- **Gradle fails:** the dialog includes its exit status and output. Check JDK/SDK compatibility, wrapper resources, required platform packages, SDK licenses, network access for Gradle dependencies, and release signing configuration.
Expand Down
Loading