Export to Web
Web builds are a fair bit more difficult to get started with compared to native builds. This will be a complete guide on how to get things compiled. However, setting up a web server to host and share your game is considered out of scope of this guide, and is best explained elsewhere.
Installation
Install a nightly build of rustc
, the wasm32-unknown-emscripten
target for rustc
, and rust-src
.
The reason why nightly rustc
is required is the unstable flag to build std
(-Zbuild-std
).
Assuming that Rust was installed with rustup
, this is quite simple.
rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
rustup target add wasm32-unknown-emscripten --toolchain nightly
Next, install Emscripten. The simplest way to achieve this is to install emsdk
from the git repo.
We recommended version 3.1.39 for now.1
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 3.1.39
./emsdk activate 3.1.39
source ./emsdk.sh (or ./emsdk.bat on windows)
It would also be highly recommended to follow the instructions in the terminal to add emcc
2 to your PATH
.
If not, it is necessary to manually source
the emsdk.sh
file in every new terminal prior to compilation.
This is platform-specific.
Project Configuration
Enable the experimental-wasm
feature on gdext in the Cargo.toml
file.
It is also recommended to enable the lazy-function-tables
feature to avoid long compile times with release builds
(this might be a bug and not necessary in the future). Edit the line to something like the following:
[dependencies.godot]
git = "https://github.com/godot-rust/gdext"
branch = "master"
features = ["experimental-wasm", "lazy-function-tables"]
If you do not already have a .cargo/config.toml
file, do the following:
- Create a
.cargo
directory at the same level as yourCargo.toml
. - Inside that directory, create a
config.toml
file.
This file needs to contain the following:
[target.wasm32-unknown-emscripten]
rustflags = [
"-C", "link-args=-sSIDE_MODULE=2",
"-C", "link-args=-pthread", # was -sUSE_PTHREADS=1 in earlier emscripten versions
"-C", "target-feature=+atomics,+bulk-memory,+mutable-globals",
"-Zlink-native-libraries=no",
"-Cllvm-args=-enable-emscripten-cxx-exceptions=0",
]
Edit the project's .gdextension
file to include support for web exports.
This file will probably be at godot/{YourCrate}.gdextension
.
The format will be similar to the following:
[libraries]
...
web.debug.wasm32 = "res://../rust/target/wasm32-unknown-emscripten/debug/{YourCrate}.wasm"
web.release.wasm32 = "res://../rust/target/wasm32-unknown-emscripten/release/{YourCrate}.wasm"
Compile the Project
Verify emcc
is in the PATH
. This can be as simple as doing the following:
emcc --version
Compile the code. It is necessary to both use the nightly compiler and specify to build std3, along with specifying the Emscripten target.
cargo +nightly build -Zbuild-std --target wasm32-unknown-emscripten
Godot editor setup
Add a web export in the Godot Editor. In the top menu bar, go to Project > Export...
and configure it there.
Make sure to turn on the Extensions Support
checkbox.
If instead, the bottom on the export popup contains this error in red:
No export template found at expected path:
Then click on Manage Export Templates
next to the error message, and then on the next screen select Download and Install
.
See Godot tutorial for further information.
Running the webserver
Back at the main editor screen, there is an option to run the web debug build (not a release build) locally
without needing to run an export or set up a web server.
At the top right, choose Remote Debug > Run in Browser
and it will automatically open up a web browser.
- Godot 4.1.3+ or 4.2+ is necessary.
- Only Chromium-based browsers (Chrome or Edge) appear to be supported by GDExtension at the moment; Firefox and Safari don't work yet. Info about browser support can be found here.
If your default browser is not Chromium-based, you will need to copy the URL (which is usually http://localhost:8060/tmp_js_export.html
)
and open it in a supported browser such as Google Chrome or Microsoft Edge.
Debugging
Currently, the only option for WASM debugging is this extension for Chrome. It adds support for breakpoints and a memory viewer into the F12 menu.
Note: Due to a bug with emscripten
, the maximum version of emcc
2 that can one compile Godot
with is 3.1.39
. gdext itself should be able to support the latest version of emcc
, however, it may be a safer bet to stick to version 3.1.39
.
emcc
is the name of Emscripten's compiler.
The primary reason for this is it is necessary to compile with -sSHARED_MEMORY
enabled. The shipped std
does not, so building std
is a requirement. Related info on about WASM support can be found here.