Skip to content

updated instructions on exporting for web #56

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

Closed
wants to merge 1 commit into from
Closed

updated instructions on exporting for web #56

Show file tree
Hide file tree
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
11 changes: 9 additions & 2 deletions src/toolchain/export-web.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ 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",
"-Cllvm-args=-enable-emscripten-cxx-exceptions=0",
"-Zlink-native-libraries=no"
]
```
Expand Down Expand Up @@ -112,6 +113,7 @@ cargo +nightly build -Zbuild-std --target wasm32-unknown-emscripten

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.
In Godot 4.3 or above, make sure to turn on the `Thread Support` checkbox.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do support builds without threads, but besides the Thread Support toggle in the editor, there are two steps:

  1. Remove the -pthread flag (the line with "-C", "link-args=-pthread") from .cargo/config.toml (it is necessary for thread support = on, and must be absent for thread support = off)
  2. Enable the experimental-wasm-nothreads gdext feature flag.

Conversely, for Wasm binaries with thread support, you must have -pthread and compile without the nothreads feature.

This means that Wasm binaries with and without thread support must be compiled separately. Then, you can add paths to both, allowing you to pick between the two by simply using the editor toggle, by modifying your .gdextension file like so (per godotengine/godot-cpp#1451 ):

[libraries]
# ... other targets above ...
web.debug.threads.wasm32 = "res://bin/libgdexample.web.template_debug.wasm32.wasm"
web.release.threads.wasm32 = "res://bin/libgdexample.web.template_release.wasm32.wasm"
web.debug.wasm32 = "res://bin/libgdexample.web.template_debug.wasm32.nothreads.wasm"
web.release.wasm32 = "res://bin/libgdexample.web.template_release.wasm32.nothreads.wasm"

(Those paths may be changed to be more Rust-friendly, e.g. use target/debug/whatever. But note that, by default, Rust will produce the binaries at the exact same path regardless of the nothreads feature. We don't know yet how to solve that, so renaming will have to be manual.)

Then, once you compile both and place them in those paths within your project, toggling Thread Support on and off in the editor should work.

We should then mention both build modes in the manual, noting that builds without threads have better browser compatibility and don't require Cross-Origin Isolation support, while threaded builds have more limited compatibility and do require Cross-Origin Isolation support but may be more suitable if you depend on threading for your tasks.


![Example of export screen](images/web-export.png)

Expand Down Expand Up @@ -143,6 +145,12 @@ and open it in a supported browser such as Google Chrome or Microsoft Edge.

[godot-export-templates]: https://docs.godotengine.org/en/stable/tutorials/export/exporting_projects.html#export-menu

## Troubleshooting

1. Make sure both `Extensions Support` and `Thread Support` (in Godot 4.3+) are turned on.
2. Make sure the webserver you're running supports Cross-Origin Isolation (I used `sfz --coi`).
3. Make sure your rust library and godot project are named differently, as sometimes `.wasm` files are overwritten.
4. Make sure you're using the `emcc` version in the guide.
Comment on lines +148 to +153
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For 1 (regarding Thread Support), see other comment.

For 2, it's worth mentioning that the Godot editor itself may be used to serve the web game for testing (there are images of this below), but you can also use its serve.py script directly if you want: https://github.com/godotengine/godot/blob/e3213aaef5e0e72b8272e65d989d3d8222be17ca/platform/web/serve.py

In addition, the main reason why support for non-threaded builds was added was precisely to work in environments without Cross-Origin Isolation IIRC, so that may be worth mentioning too.

Otherwise, good advice.


## Debugging

Expand All @@ -155,9 +163,8 @@ for Chrome. It adds support for breakpoints and a memory viewer into the F12 men

---

[^1]: 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`.
[^1]: 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`. Anecdotally, `emcc-3.1.47` has also worked with `Godot 4.3`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The info regarding the emcc version upper bound of 3.1.39 only applies to Godot 4.2 and below, and is thus now outdated. We should recommend 3.1.62 or later for Godot 4.3+. (Note that this is mentioned earlier in this document, so earlier mentions should also be updated.)


[^2]: `emcc` is the name of Emscripten's compiler.

[^3]: 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](https://github.com/rust-lang/rust/issues/77839).

Binary file modified src/toolchain/images/web-export.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading