Skip to content

Development

Jump to bottom
Ashton Meuser edited this page Feb 6, 2026 · 19 revisions

Build Godot Wasm

These instructions describe the process of building the Godot Wasm GDExtension/GDNative addon. For building the Godot engine with Godot Wasm as a module, see Installation.

This is intended to aid in developing the Godot Wasm project; not simply using it in a Godot project.

These instructions are tailored to UNIX machines.

  1. Clone repo and submodules via git clone --recurse-submodules https://github.com/ashtonmeuser/godot-wasm.git.
  2. Ensure the correct Godot submodule commit is checked out. Refer to relevant branch of the godot-cpp project e.g. 3.x to verify submodule hash. At the time of this writing, the hash for the godot-cpp submodule was 1049927a596402cd2e8215cd6624868929f5f18d.
  3. Install SConstruct via pip install SCons. SConstruct is what Godot uses to build Godot and generate C++ bindings. For convenience, we'll use the same tool to build the Godot Wasm addon.
  4. Compile the Godot C++ bindings. From within the godot-cpp directory, run scons target=template_release platform=PLATFORM replacing PLATFORM with your relevant platform type e.g. macos, linux, windows, etc. For Godot 3, this should be scons target=release generate_bindings=yes platform=PLATFORM. Note that some platform names differ in Godot 3.
  5. Compile the Godot Wasm addon. From the repository root directory, run scons target=template_release platform=PLATFORM once again replacing PLATFORM with your platform. This will create the addons/godot-wasm/bin/PLATFORM directory where PLATFORM is your platform. You should see a dynamic library (.dylib, .so, .dll, etc.) created within this directory. Note that this step will automatically download the Wasm runtime if a relevant directory is not found on disk. For Wasm runtime configuration, see Runtime Options.
  6. Compress the addons directory via zip -FSr addons.zip addons. This allows the addon to be conveniently distributed and imported into Godot. This ZIP file can be imported directly into Godot (see Installation).

Note When building for Godot 3.x, use target=release instead of target=template_release in the instructions above. Additionally, use platform=osx instead of platform=macos when building for macOS.

If frequently iterating on the addon using a Godot project, it may help to create a symlink from the Godot project to the compiled addon via ln -s RELATIVE_PATH_TO_ADDONS addons from the root directory of your Godot project.

IDE Setup

Depending on your IDE and C++ linter, you may need to add include files. These should include the following:

  • godot-cpp/gdextension/
  • godot-cpp/include/
  • wasmer/include/
  • wasmtime/include/
  • godot-cpp/gen/include/
  • godot-cpp/gen/include/godot_cpp/
  • extensions

Alternatively, you may need to generate a compilation database e.g. for clangd. This can be done by running scons db from the root of the Godot Wasm project.

Targeting GDExtension and Godot Module

Godot Wasm was built to be used as either a GDExtension addon or a Godot module (see comparison). As such, several quirks and compromises were introduced to the codebase. Generally, these are:

  • Inclusion of build files for both targets, SConstruct and SCsub.
  • Use of a definitions file, defs.h, to align the APIs of both targets.
  • Namespace usage (via NS define) where it may not be strictly required.
  • Custom error definitions in Godot 3.x branch e.g., ERR_INVALID_DATA. Not necessary for Godot 4.x as errors are now aligned.
  • Some ugliness in classes where API differs greatly between GDExtension and Godot modules e.g., WasmMemory.

For more context, please see PR#17.

An alternative to this approach may have been to use a dedicated tool e.g., GDExtension to Module. The author is open to suggestions and/or PRs on this front.

Runtime Options

Note

Godot Wasm must be built from source to change the Wasm runtime. If using a prepackaged release of Godot Wasm e.g. from the Godot Asset Library, you're restricted to using the default runtime.

Godot Wasm can be configured to use either the Wasmer or Wasmtime WebAssembly runtimes. By default, Wasmtime is used. When building as either a Godot addon or module, Godot Wasm can accept the following options to configure the runtime.

Argument Description
wasm_runtime Either "wasmer" or "wasmtime". Defaults to "wasmtime". Determines the WebAssembly runtime used.
download_runtime Boolean option accepting either "yes" or "no" (default). Forces (re)downloading of the runtime library. By default, the library is only downloaded when the wasmer or wasmtime directory is not found.
runtime_version The version of the selected WebAssembly runtime used. Must be valid semver.

For example, the following command will build Godot with Godot Wasm as a module using version 12.0.1 of the Wasmtime runtime and forcing a (re)download of the Wasmtime library scons platform=macos arch=x86_64 target=editor wasm_runtime=wasmtime runtime_version=v12.0.1 download_runtime=yes.

Clone this wiki locally