WebAssembly support

[Bromeon]

This issue serves as a knowledge base for approching WASM builds. Ideally it should have more consolidated pieces of information. Please edit your responses to update anything outdated.

For free-form discussion, check out the Discord thread.

[PgBiel]

Hello, thanks for opening this issue! Hopefully other contributors can see this and feel motivated to help 😄

(EDIT: results in this comment are outdated; see #438 (comment))

I'd like to share here some of the progress we have so far. In particular, I tried to summarize our current progress in a gist, after attempting to compile a Gdext project to WASM from scratch: https://gist.github.com/PgBiel/ffa695a479ef4466cb24755db983950b

The most important section in the link above is the gdext-wasm-min-report.md file, at the top, where I summarize what I found, also based on the most recent discussions from the Discord thread:

1. Setup: Tools and steps needed to try to compile Gdext to WASM (at least, to our best knowledge so far), through the wasm32-unknown-emscripten Rust target. Basically, you'll need a nightly Rust toolchain in order to recompile the Rust standard library (currently needed due to build flags related to threading in WASM), along with custom emscripten flags (more specifically --no-entry -sSIDE_MODULE=2 -sUSE_PTHREADS=1 - the required ones that we know of so far). You'll also need at least -g -sASSERTIONS=2 -sSTACK_OVERFLOW_CHECK=2 -sDEMANGLE_SUPPORT=1 (maybe a few others) to enable debug assertions and symbols on the browser (mapping errors/compiled WASM to source code requires this Chrome extension, though, with those debug flags enabled).

2. Results (and updates): Errors I found which are currently stopping the gdext web export from working (those errors show up when trying to run, on the browser (Firefox/Chromium), the project exported to the web through the Godot editor). The two main ones are load count too large, which seems to be related to some inefficiency somewhere in gdext codegen (as that error disappears when compiling with --release, or with default-features = false (which apparently disables a good chunk of codegen), and thus is not an unavoidable error), and memory access out of bounds (which translates to a Stack Overflow/invalid pointer address error when enabling debug assertions) - this last one has been the larger blocker so far (although different errors have been obtained by experimenting with different sets of emscripten flags).

I've been playing with this last error but haven't found much so far. Curiously, with the right settings (larger stack size etc.), I managed to receive an index out of bounds message on Firefox instead, which apparently occurred in some internal emscripten function cull_zombies; I couldn't decompile the WASM in firefox (/map to source code), but I suspect it was related to this line, which suggests there's something related to threading going on:

https://github.com/emscripten-core/emscripten/blob/ef3e4e3b044de98e1811546e0bc605c65d3412f4/system/lib/pthread/em_task_queue.c#L80

In the Discord thread, there were other theories such as problems with function pointer tables being too large, but also a theory that function pointers in WASM aren't "legit" function pointers due to JavaScript interop in WASM, so using them may require adaptation somehow.

Overall, we need some more investigation on this matter before determining what we can do in gdext to solve this. (It's possible that there are upstream problems as well, from Godot and/or from emscripten, but we just don't know yet if that's the case.) Let's hope other interested contributors - and/or WASM experts 👀 - drop by and give their opinions as well 😉

[Esption]

As of writing, this is what I know needs to be done. There's still some gdext work to be done, it seems like, but if anyone gets involved this should hopefully serve as a recap.
If anyone wants to run things by me I'm happy to help at least get something going. I'm usually easy to reach on discord. But please read this first!

Compile gdextension web template

You'll need to manually compile the template. Godot doesn't ship with a web template that has gdextension support. It's important to note this template will be SPECIFIC to the version of emscripten that it was compiled with. This probably means you'll need to install emsdk along with a few other tools. Follow the official docs for a guide on what to do, and where to place the template zip.

You do not need to recompile the entire editor. ONLY the template. If compiling from git, don't forget to make use of tags prior to compiling anything so it matches the editor version you are using.

Setup Rust config

You need to be able to use unstable features. So, a nightly build is probably the best choice.

rustup toolchain install nightly
rustup default nightly
rustup target add wasm32-unknown-emscripten

At the root directory of your project, you'll need to make a .cargo/config.toml file.

The big thing is needing to compile your extension with SHARED_MEMORY. This requires a few flags and rebuilding std (this is because the std included from rustup was not compiled with it enabled).

[unstable]
build-std = ["std"]

[target.wasm32-unknown-emscripten]
rustflags = [
    "-C", "link-args=-sSIDE_MODULE=2 -sEXPORT_ALL=1",
    "-Zlink-native-libraries=no",
    "-C", "link-args=-pthread",
    "-C", "target-feature=+bulk-memory",
    "-C", "target-feature=+atomics",
    "-C", "target-feature=+mutable-globals",
    "-C", "link-args=-sSHARED_MEMORY=1",
]

You'll then have to either compile with --target wasm32-unknown-emscripten or add

[build]
target = ["wasm32-unknown-emscripten"]

to the .cargo/config.toml file

Don't forget to add a web section to your extension's .gdextension file.
Something like

web.debug = "res://path/to/debug/project.wasm"
web.release = "res://path/to/release/project.wasm"

Setup a web server

You need to have HTTPS and enable some cross-origin headers. Either use certbot or a self-signed cert.
For nginx, enabling the necessary headers is quite simple by just adding

add_header 'Cross-Origin-Opener-Policy' 'same-origin';
add_header 'Cross-Origin-Embedder-Policy' 'require-corp';

inside the location {} section of your site. Look for something similar for other web servers.

Debugging

Use chrome and install this extension. It'll basically allow the devtools (F12) to act like a worse LLDB. Breakpoints, memory inspector, etc.

Random notes

• Making sure the emscripten version that rust uses, and that you compiled the web template with, is possibly necessary. It technically shouldn't be, but emscripten can sometimes break compatibility between releases, so YMMV.
• Having -sEXPORT_ALL=1 is probably not necessary. Only exporting the gdext entry symbol is (probably?) necessary. But I would leave that there until you know it works.
• Emscripten's dead code elimination can be unnecessarily aggressive on a release build. Make sure to try a debug build or lower -o if it seems like the .wasm file is strangely small. Probably related to a bug in gdext, but just a heads-up if you run into it.

[Esption]

Newer info:

• Most recent supported emcc versions for godot are emcc 3.1.39 for latest dev, and emcc 3.1.28 for godot 4.1.2 (and probably earlier). I haven't checked if the patch to push version up to emcc 3.1.39 got into godot 4.1.3
• We probably need a way to manually register things.
• We need to fix the UB as heck reading of a function pointer in compat_4_1.rs the quick fix is just to check and exit out if it's being ran on wasm.

[Esption]

Thanks to @zecozephyr for figuring out how to work around some of the rust+emscripten limitations, we currently have gdext on wasm working with the dodge-the-creeps example.

We're hoping to get more people to test with their projects to jump in and confirm/deny this. This is coming with a big DISCLAIMER that this patch is probably buggy and not production ready. On top of that, we literally found two bugs in emscripten in the process of this, so... yeah. Bugs!

KNOWN CAVEATS

Godot 4.1.3+ or 4.2-dev is necessary.
The only browser supported appears to be Chrome (Firefox and Safari don't work with GDExtension yet, discussion here).

Steps to test wasm patch

1. Ensure you have a nightly build of Rust with the rust-src component, and install the emscripten target. With rustup, that looks something like

rustup toolchain install nightly
rustup component add rust-src --toolchain nightly
rustup target add wasm32-unknown-emscripten --toolchain nightly

3. Install Emscripten. Prefer to use Emscripten 3.1.39, as that's the maximum version Godot itself builds with (even though gdext itself should work with later versions). Using emsdk that would be something like

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)

• Note You probably also want to follow the given prompts to add emcc to your $PATH otherwise you'll need to run the source ./emsdk.sh / ./emsdk.bat for every new shell.

4. Add this to your .cargo/config.toml

[target.wasm32-unknown-emscripten]
rustflags = [
    "-C", "link-args=-sSIDE_MODULE=2",
    "-C", "link-args=-sUSE_PTHREADS=1",
    "-C", "target-feature=+atomics,+bulk-memory,+mutable-globals",
    "-Zlink-native-libraries=no"
]

5. Edit your Cargo.toml to add the "experimental-wasm" feature.

godot = { git = "https://github.com/godot-rust/gdext", branch = "master", features = ["experimental-wasm", "lazy-function-tables"] }

NOTE: May need to enable the "lazy-function-tables" feature for a successful runtime and a SIGNIFICANTLY shorter compile time.
6. Add the web target to your project's .gdextension file. Will be similar to the others in that file, roughly something like this

web.debug.wasm32 = "res://../target/wasm32-unknown-emscripten/debug/EXTENSIONNAME.wasm"
web.release.wasm32 = "res://../target/wasm32-unknown-emscripten/release/EXTENSIONNAME.wasm"

7. Verify that you're using emcc version 3.1.39 with emcc --version and then compile your code. Debug builds seem to take a while longer to load in the browser, but release builds take a very long time to compile, as well as a lot of RAM. Compile with:

cargo +nightly build -Zbuild-std --target wasm32-unknown-emscripten

8. In godot, add a web target and ensure that the "Extensions Support" checkbox is ticked ON. Set it to export wherever you would like
9. From here you have two choices to run your game, as you need to spawn a server to serve the HTML file (just double-clicking probably won't work).

• The first and easiest choice is through the Godot editor itself: from the main scene view godot, press "Remote Debug > Run in Browser"

• NOTE 1: The above will always run a debug build, so make sure to compile with debug (or change the path to the debug build in the NAME.gdextension file) if you'd like to use the "Run in Browser" button.

• NOTE 2: If your default browser isn't Chrome, you'll need to copy the URL and paste it into Chrome (e.g. manually head to localhost:8060 and click the HTML file), as your game will not work on Firefox or Safari (as of the time of writing).

• Alternatively, run the web export process fully and point a web-server at the exported files. If this is what you'd like to do, you're going to need to have a web-server with some specific cross-origin headers to get this part to work. A quick way to do this is through simple-http-server:

  cargo install simple-http-server
  simple-http-server --coop --coep --nocache ./path/to/export/

  And then open up a Chrome/Chromium browser at localhost:8000/EXPORTNAME.html. It may take a while to load, especially if you built with debug instead of release.

• NOTE: Both solutions above are only suitable for testing. If you want to share your game to others properly, then you'll want to setup an actual HTTPS web-server.

Discussion

Either post here or post in the discord thread where most of this has been taking place.

[zecozephyr]

Preliminary support has now been merged into master by #493.

Instructions remain largely unchanged except that one now needs to enable the feature experimental-wasm to explicitly opt-in to wasm builds.

[DeprecatedLuke]

Since I know that there's quite a few people looking to run gdext on wasm, but are afraid to use it due to instability here's a few words:

If you haven't made anything yet within godot and are able to switch engines the bevy game engine is pretty good if you want to use rust and have web-assembly/full multiplatform support. Bevy is in much earlier stages than godot, but so is gdext and it's understandable that each of them have their own challenges. Bevy having no editor could be preferrable as I've seen people ditch the editor for pure-code scene creation in some cases.

As someone who had experience now with both - gdext and bevy are good enough to make work with few days of research and hands-on fixes, as a bonus - bevy has webgpu support.

[Bromeon]

@DeprecatedLuke please don't hijack the issue tracker only to advertise other projects. People are aware that there are many choices in the Rust ecosystem.

Godot itself works absolutely fine with web (there are tons of game jam entries for it, and I have used it myself). The main issue specific to GDExtension is that it's not yet fully supported in non-Chromium based browsers; something that will likely improve.

If you want to discuss the issue further, please bring it up on Discord, here is not the right place.

[Bromeon]

I wonder if godotengine/godot-cpp#1489 has relevance for us (panics might use the same mechanism as exceptions) 🤔

[PgBiel]

Perhaps, but this will depend on Rust and LLVM support for wasm exceptions, which seems to be fairly early days still. However, as seen here rust-lang/rust#118168 , since last year both the language and stdlib got support for building with panic=unwind (it's still opt-in and unstable, so an explicit -Z flag is needed), so maybe it's worth experimenting with it now? Seems like LLVM might still have some problems with it, but I don't know enough about the current situation to tell without testing.