Arora Engine

Welcome to the core of the project!

WASM Executor

The Arora engine runs WASM modules — advertised with a custom module description format (or schema) — through pluggable Executor implementations. Two are shipped today:

• wasm::WebAssemblyExecutor hosts modules via wasmtime on native targets. Gated behind the default wasmtime-host feature.
• browser::BrowserExecutor hosts modules via the browser's native WebAssembly runtime when arora itself is compiled to wasm32-unknown-unknown. The JS-facing wrapper lives in arora-web.

Both expose the same ABI to guests (arora_buffer_alloc/free, arora_function_<uuid> exports, arora_dispatch / arora_dispatch_indirect imports), so a module compiled once runs in either host.

Native Executor

A native::NativeExecutor is available and is capable of loading native dynamic libraries, and call the functions declared in the module description. Beware of figuring out the right dynamic library extension for the host platform. Gated behind the default native-host feature; disabled on wasm32-* targets.

Calling Module Functions

Once modules are loaded — either via Engine::load_module directly, or via the load::load_module_from_parts convenience that takes a parsed Header plus the executable bytes and also returns the module's function IDs — their functions can be called using engine's implementation of the CallBridge trait. arora_call takes a Call description holding generic Values as an input, and returns a CallResult holding the return value and the mutated parameters. The engine also advertises a function called arora_dispatch in the module's runtime context, so that they can call one another. It is recommended to use the bindings generated by arora-module-cli, rather than calling these functions directly.

The host of the engine (the process loading this library) can also register native functions using arora_register_callable. An u64 identifier is attributed to each registered function, so that they can be called later using arora_call_indirect from the host side, or from any module via arora_dispatch_indirect.

Behavior Trees typically use this mechanism to wrap the various node functions into uniform tick functions.

Call Mechanism

When a call is performed, its description is serialized into a raw buffer, using the Arora Buffers library, copied into the module's memory (allocated using arora_buffer_alloc that must be exported by the modules), before the function is called with a pointer to the memory segment. The module is in charge of deserializing it and serializing the result into a new buffer, that the engine will free using arora_buffer_free.