Importing WebAssembly

Wasmbox includes an import pipeline for WASM assets which validates, initialises, transforms, optimises, precompiles and compresses the WASM. Any *.wasm (binary WebAssembly) or *.wat (text WebAssembly) files will automatically be processed and imported through this pipeline into a WasmAsset.

1. General

Settings which apply to the rest of the entire pipeline.

Inspector Options

• Non Deterministic
  • Enable extra optimizations which will produce faster code but may produce different results on different platforms.

2. Initialisation

If Preinitialization is ticked the WASM will be processed through Wizer. Wizer instantiates your WebAssembly module, executes its initialization function, and then snapshots the initialized state out into a new WebAssembly module. This allows one-off initialization to be done now, instead of when the module is loaded at runtime.

caution

Wizer does not support all WASM features and not all modules can be pre-initialized by Wizer. If Wizer fails to run for a file a warning will be printed to the console and it will be disabled for this file.

Inspector Options

• Initialize Export Name
  • Set the name which Wizer will call to initialize the WASM module.
  • Refer to Wizer docs for example usage.
  • Refer to Wizer docs for caveats.
• Exposed Wasi Directories
  • A set of directory paths which will be fully readable and writeable during initialization.
  • These directories are only accessible during wizer initialization.

3. Transformation

If Transformation is ticked the WASM will be rewritten to introduce new capabilities.

Inspector Options

• Asyncify: Rewrite all functions to make them async, allowing execution to be suspended and then resumed later.

4. Optimisation

If Optimization is ticked the WASM will be processed through Binaryen. Binaryen is an optimizer which applies a larger number of optimisation passes to produce to better (faster/smaller) WASM.

caution

Binaryen does not support all WASM features and not all modules can be optimized by Binaryen. If Binaryen fails to run for a file a warning will be printed to the console and it will be disabled for this file.

Inspector Options

• Binaryen Optimization Level
  • Set the optimization level:.
    • None: Do not optimise (equivalent to disabling optimisation).
    • O1/O2/O3/O4: Optimize for speed. Higher levels spend significantly longer optimising.
    • Size: Optimize mostly for speed.
    • Extreme Size: Optimize for absolutely minimum code size.
• Binaryen Fast Math: Optimize floating point maths without properly handling corner cases of NaNs and rounding.
• Binaryen Asyncify: Convert WASM into async WASM, allowing execution to be suspended and resumed.

5. Compilation

If Compilation is ticked the WASM will be pre-compiled into native machine code for all active platforms. This increases the asset size (often by a factor of 10x or more) but can reduce loading times at runtime. If compiled code cannot be loaded for some reason (e.g. incompatible architecture, pre-compilation is not enabled) the runtime loading will fall back to using the "Universal" version.

Inspector Options

• Fuel Usage: Compile with support for Fuel Usage.
• Epoch Interruption: Compile with support for Epoch Interruption.
• SIMD: Enable SIMD instructions (faster, but non-deterministic).
• Cranelift Compiler Settings: Enable specific feature flags in the cranelift compiler. The CPU used at runtime must support these features for the precompiled WASM to be loaded, if they are not supported the Universal fallback will be used instead (equivalent to not precompiling).

6. Compression

Compress the final WASM to reduce size, this can reduce loading time if storage is slow.

Inspector Options

• Compression Level
  • Set the amount of work the compressor will do. This corresponds to this option in the .NET compressor.
    • Optimal: Optimally balance compression speed and output size.
    • Fastest: Compress as quickly as possible, even if the resulting file is not as small as possible.
    • No Compression: No compression should be performed on the file.
• Compression Algorithm:
  • Brotli: Powerful compression algorithm which usually provides the best compression but is slower to compress and decompress than deflate.
  • Deflate: Simple & fast compression algorithm. Usually does not compress as much as Brotli but is often faster to compress and decompress.

7. Code Generation

If Generate C# Wrapper Code is ticked a script will be generated which wraps up the WASM module in a C# accessor. This handles many of the "low level" details of interacting with a WASM module. See this documentation for details on generated wrapper code.

caution

Do not edit the auto generated code! It may be re-generated at any time, which will overwrite your changes.

Inspector Options

• Naming
  • Namespace: C# namespace for the generated wrapper code.
  • Type Name: Name of the generated wrapper type.
  • Visibility: Visibility access modifier (public/internal) to apply to the generated wrapper type.
  • Addressable Loading: Generate a CreateAsync method which loads the WASM asset using the Unity Addressable Asset System.
• Error Handling
  • Trap Handling: Choose if a WASM Trap throws a C# exception (slow, generates garbage) or returns a Result (fast, usually no garbage).
  • Stack Frames: Choose if the Result object records the stacktrace of the WASM Trap. This can help with debugging but requires allocating space to store the stacktrace.
• Exports
  • Wrap Exported Functions: Generate a wrapper for every callable function exported from the WASM module.
  • Wrap Exported Globals: Generate a wrapper for every global exported from the WASM module.
  • Wrap Exported Memory: Generate a wrapper for every memory exported from the WASM module.
  • Wrap Exported Tables: Generate a wrapper for every table exported from the WASM module.