-
Notifications
You must be signed in to change notification settings - Fork 12
FAQs
Godot Wasm embeds a WebAssembly (Wasm) runtime in your Godot project. It allows you to interact with Wasm modules from GDScript. This is a powerful paradigm that allows developers to enhance their Godot projects with fast, secure, single-binary-multi-platform extensions.
WebAssembly (Wasm) is a binary format that runs in a sandboxed virtual machine. It provides a portable target for many programming languages. That means that you can compile a Wasm module once from a language of your choice e.g. Rust, Go, C++ and run it on any platform!
Additionally, WebAssembly's sandboxed model means that you can run untrusted binaries without fear that they can corrupt your machine or access files which they shouldn't!
WASI (WebAssembly System Interface) provides a POSIX-like interface definition that allows WebAssembly modules to interact with the machine on which they're being run (the host). Without WASI, WebAssembly modules have no way to access simple host features available outside of the Wasm VM like printing to to STDOUT, file access, cryptographicly-secure random number generation, system clock time, etc.
Godot Wasm implements a basic subset of these interfaces to extend the abilities of Wasm modules running in Godot. However, to promote security, not all interfaces are provided by Godot Wasm by default. If you need to support a new WASI behaviour, you're free to do so via the imports you provide to a Wasm module when instantiating via Godot Wasm's Wasm.instantiate() method. The default behaviours for default WASI functions may also be overridden by explicitly providing the relevant import.
There are many reasons why you'd want the ability to run Wasm in Godot and interact with it via GDScript!
- Use (almost) any language! You can create a WebAssembly module from any compatible language e.g. Rust, Go, AssemblyScript. This provides the ability to use existing libraries for these languages.
- Safe & sandboxed. Securely run untrusted mods and extensions. Because WebAssembly is sandboxed, you can run Wasm modules from untrusted sources without risking your users' safety. This opens the door for zero-trust mods and plugins for your Godot project.
- Compile once, run everywhere. Wasm is a portable binary format meaning there's no need to compile binaries for Windows x86, Windows x64, macOS ARM, macOS x86, Linux, etc. separately.
- Raw speed! WebAssembly runs incredibly fast. This is particularly apparent when compared to Godot's high-level GDScript. Compute-heavy operations may be ideal tasks to hand off to Wasm. See Benchmarks for a comparison.
There are many ways in which to build a Wasm module and many programming languages from which to compile. See Awesome Wasm Langs for an idea of the breadth of Wasm support.
Mozilla provides a great guide on getting started building Wasm modules. For some concrete examples of building a module from a variety of languages, see here.
Godot Wasm can be exported to Windows, macOS, and Linux.
Once Godot Wasm has been installed, you can export your Godot project as you typically might. For macOS exports, you'll have to disable library validation in Project → Export → Options. Finally, if you're including Wasm binaries in your project, you'll need to mark these for inclusion in your export by adding *.wasm in Project → Export → Resources.
If you're building Godot Wasm as a Godot module, ensure you're using the export template that you compiled yourself following the official guides.
Godot Wasm uses Wasmer as the underlying WebAssembly runtime. Godot Wasm interfaces with Wasmer via the Wasm C API meaning that swapping out the runtime for another that supports this API e.g. Wasmtime is theoretically possible, although untested.
Currently, Wasmer, the runtime used by Godot Wasm, is not able to be exported to run in the web. There are issues tracking support for HTML5/web exports. See #15 and #18.