godot-wasm

WebAssembly binding for Godot, with rich feature set.

Introduction

Hello there! Thanks for checking out this library 🙏. I published this as my future portfolio on my coding adventure. This is my hobby project, developed over 6 months (+1 year porting to Godot 4). It has gone through a lot of changes.

For the Godot 3 version, check out branch gdnative.

Stability

Generally speaking, this library is stable enough to be used in production. As of writing, there is no new features to be planned. Though it could change in the future.

We may cause breaking changes if/when: - Wasmtime update breaks our feature. - Godot-rust update breaks our bindings. - Feature is deprecated (there's no guarantee on removal timeline).

Stuff that is not covered in stability: - Feature flags beyond default feature. - Justfile. - Internal properties/methods. - Properties/methods marked as unsafe.

Update Schedule

Update schedule is generally in sync with wasmtime release. Interim updates might happen to fix bugs or add features.

Documentation

Documentation is in doc folder. Also available as doc comments.

Features

• Easily run any WASM module.
• Supports WAT compilation.
• Imports any (custom) Godot methods into WASM.
• Easy access to linear memory, per-element basis or bulk array operation.
• Catch and throw runtime error/traps with signal.
• Epoch-based limiter to stop bad-behaving module.
• Memory limiter to prevent exhaustion.
• Experimental API for direct Godot object manipulation. Available in 3 flavors:
• Legacy compat API using indices. Easier to implement.
• Newer extern API using externrefs, with interop with legacy API. Some programming language might not support it at all.
• Component-based API. Requires component model.
• WASI common API with in-memory filesystem.
• Native resource support to ease import/export.
• Optional support for component model and WASI 0.2
• Partial support for WASM GC. Support is dependent on wasmtime.

Features not supported:

• Binding host functions into WASM component. Support is coming later.
• Composing WASM components. Use tool like wac for the moment.
• WASI network API.
• WASI preview 0 API. Not many user of this API, so support is not likely.
• Passing WASM GC values in to/out of host.

Building

To build the addon: 1. Clone this repository 2. Install just and nushell. 3. Run just profile=release deploy-addon 4. Copy addon in out/addons/godot_wasm to your project

Extra build arguments can be added with environment variable BUILD_EXTRA_ARGS, separated by spaces.

Cross-Compilation

Cross-compilation is not always possible. You might be able to do it with WSL (Windows) or cross (Linux), but result may vary. It's recommended to not use just, instead directly run cargo build with the correct arguments.

Platform Support

Officially, it should work for Windows and Linux on x86 (32 and 64-bit) architecture. Other platforms aren't tested and might not work.

Platforms that are listed in .gdextension file is as follow: * Windows: x86_32, x86_64, ARM64. * Linux: x86_32, x86_64, ARM64, RV64. * MacOS: x86_64, ARM64.

Web platform is and will not be supported. Even if it is, it's API will likely be different, and many features (like limiter) will not work.

Using the Library

After adding it to your Godot project, there are many classes added by the library: * WasmModule : Contains the compiled WebAssembly module. * WasmInstance : Contains the instantiated module. * WasiContext : Context for WASI, including stdout and filesystem. * WasiCommand : Optional class to run WASI 0.2 runnable component.

Due to limitation of godot-rust, you must call initialize after creating new object. Here is a snippet of example code:

const WAT = """
(module
  (func $add (export "add") (param i64 i64) (result i64)
    local.get 0
    local.get 1
    i64.add
  )
)
"""

func _ready():
  # initialize() returns itself if succeed and null otherwise
  # WARNING! DO NOT USE UNINITIALIZED/FAILED MODULE OBJECTS
  var module = WasmModule.new().initialize(
    WAT, # Module data (accepts PackedByteArray, String, FileAccess, or WasmModule)
    {} # Imports to other module
  )

  # Create instance from module
  var instance = WasmInstance.new().initialize(
    module, # Module object
    {}, # Host imports
    {} # Configuration
  )
  # Convenience method
  # var instance = module.instantiate({})

  # Call to WASM
  print(instance.call_wasm("add", [1, 2]))

  # There are many more methods of WasmInstance, including:
  # - Trapping (signal_error/signal_error_cancel)
  # - Epoch (reset_epoch)
  # - Memory (too many to list here)
  # See it's source code (src/wasm_instance.rs) for list.

With the addon, there are many more helper scripts too: * WasmHelper : Autoload that contains many helper functions to load WebAssembly code. * WasmLoader/WasmSaver : Registers WASM files as native resource.

Potential Uses

There are many uses of running WebAssembly code in Godot. If you are looking for inspiration or just confused about the purpose of this package, here are some prompts:

Language-independent* programming game

Many programming language now supports compiling to WebAssembly. And with many programming type game out there, it would be awesome to transfer your skill at your favourite programming language into the game. Bonus, if somehow your program has bugs, it won't corrupt or crash the game.

*Right now, very few programming language can emit standalone WASM. Although WASI expands the number of language supported, it may require some custom host API shim layer.

Competitive robot/AI game

Isn't that obvious enough? Tied to previous one, a really great use is some sort of competitive multiplayer AI vs AI game. With sandboxing of WebAssembly, no code can do any harm to participant/judge.

Custom userscript

Instead of making your own scripting language to integrate into your game, why not consider sandboxing it within WebAssembly?

Modding framework

WebAssembly can replace DLL/SO as a way to mod your game. Using it as easy as exposing your API as imports. Plus, sandboxing makes any mod automatically be safe from doing malicious things.

Server-sent Mod

With mods there will always problem with multiplayer. Imagine having to install random code just to join your favorite server. And don't forget to juggle mods for different servers. Well no more, the server could just send you the mods and assets necessary to join. It's automatic, painless, and of course, safe. Think of browsers, where you load untrusted website code safely.