The Rhai Book

Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way to add scripting to any application.

Versions

This Book is for version 1.20.0 of Rhai.

Introduction to Rhai

Trivia

Origin of the Rhai logo

Original prototype

One of Rhai’s maintainers, @schungx, was thinking about a logo when he accidentally came across a copy of Catcher in the Rye in a restaurant, and drew the first prototype version of the logo.

Then @semirix refined it to the current version.

Features of Rhai

What Rhai Isn’t

Rhai’s purpose is to provide a dynamic layer over Rust code, in the same spirit of zero cost abstractions.

It doesn’t attempt to be a new language. For example:

• No classes. Well, Rust doesn’t either. On the other hand…

• No traits… so it is also not Rust. Do your Rusty stuff in Rust.

• No structures/records/tuples – define your types in Rust instead; Rhai can seamlessly work with any Rust type that implements Clone.

• No first-class functions – Code your functions in Rust instead, and register them with Rhai.

• No garbage collection – this should be expected, so…

• No first-class closures – do your closure magic in Rust instead: turn a Rhai scripted function into a Rust closure.

• No formal language grammar – Rhai uses a hand-coded lexer, a hand-coded top-down recursive-descent parser for statements, and a hand-coded Pratt parser for expressions.

• No bytecodes/JIT – Rhai uses a heavily-optimized AST-walking interpreter which is fast enough for most real-life scenarios.

Benchmarking Rhai

The purpose of Rhai is not to be blazing fast, but to make it as easy and versatile as possible to integrate with native Rust applications.

What you lose from running an AST walker, you gain back from increased flexibility.

The following benchmarks were run on a 2.6GHz Linux VM comparing performance-optimized and full builds of Rhai with Python 3 and V8 (Node.js).

In general, Rhai is roughly 2x slower than Python 3, which is a bytecodes interpreter, for typical real-life workloads.

Supported Targets and Builds

Rhai supports all CPU and O/S targets supported by Rust, including:

• WebAssembly (WASM)

• no-std

Minimum Rust Version

The minimum version of Rust required to compile Rhai is 1.66.0.

Dependencies

Rhai takes care to pull in as few dependencies as possible in order to avoid bloat when using the library.

Main Dependencies

no-std Dependencies

Feature Dependencies

WASM Dependencies

Licensing

Rhai is licensed under either of the following, at your choice:

• Apache License, Version 2.0, or

• MIT license.

Related Resources

Getting Started

This section shows how to install the Rhai crate into a Rust application.

Online Playground

Rhai provides an online playground to try out its language and engine features without having to install anything.

The playground provides a syntax-highlighting script editor with example snippets.

Scripts can be evaluated directly from the editor.

Install the Rhai Crate

In order to use Rhai in a project, the Rhai crate must first be made a dependency.

[dependencies]
rhai = "1.20.0"    # assuming 1.20.0 is the latest version

[dependencies]
rhai = "*"

[dependencies]
rhai = { git = "https://github.com/rhaiscript/rhai" }

Optional Features

By default, Rhai includes all the standard functionalities in a small, tight package.

Features that Enable Special Functionalities

Features that Disable Certain Language Features

Features that Disable Certain Engine Features

Features that Configure the Engine

Features for no-std Builds

The following features are provided exclusively for no-std targets. Do not use them when not compiling for no-std.

Specify default-features = false when compiling for no-std, which will remove the default std feature.

Features for WebAssembly (WASM) Builds

The following features are provided exclusively for WASM targets. Do not use them for non-WASM targets.

Features for Building Bin Tools

The feature bin-features include all the features necessary for building the bin tools.

By default, it includes: decimal, metadata, serde, debugging and rustyline.

Example

The Cargo.toml configuration below:

[dependencies]
rhai = { version = "1.20.0", features = [ "sync", "unchecked", "only_i32", "no_float", "no_module", "no_function" ] }

turns on these six features:

The resulting scripting engine supports only the i32 integer numeral type (and no others like u32, i16 or i64), no floating-point, is Send + Sync (so it can be safely used across threads), and does not support defining functions nor loading external modules.

This configuration is perfect for an expression parser in a 32-bit embedded system without floating-point hardware.

Packaged Utilities

A number of Rhai-driven tools can be found in the src/bin directory:

Install Tools

To install all these tools (with full features), use the following command:

cargo install --path . --bins  --features bin-features

or specifically:

cargo install --path . --bin sample_app_to_run  --features bin-features

Run a Tool from Cargo

Tools can also be run with the following cargo command:

cargo run --features bin-features --bin sample_app_to_run

Tools List

rhai-repl init1.rhai init2.rhai init3.rhai

rhai-run script1.rhai script2.rhai script3.rhai

rhai-dbg my_script.rhai

Using the Engine

Rhai’s interpreter resides in the Engine type under the master rhai namespace.

This section shows how to set up, configure and use this scripting engine.

Your First Script in Rhai

Run a Script

To get going with Rhai is as simple as creating an instance of the scripting engine rhai::Engine via Engine::new, then calling Engine::run.

use rhai::{Engine, EvalAltResult};

pub fn main() -> Result<(), Box<EvalAltResult>>
//                          ^^^^^^^^^^^^^^^^^^
//                          Rhai API error type
{
    // Create an 'Engine'
    let engine = Engine::new();

    // Your first Rhai Script
    let script = "print(40 + 2);";

    // Run the script - prints "42"
    engine.run(script)?;

    // Done!
    Ok(())
}

Get a Return Value

To return a value from the script, use Engine::eval instead.

use rhai::{Engine, EvalAltResult};

pub fn main() -> Result<(), Box<EvalAltResult>>
{
    let engine = Engine::new();

    let result = engine.eval::<i64>("40 + 2")?;
    //                      ^^^^^^^ required: cast the result to a type

    println!("Answer: {result}");             // prints 42

    Ok(())
}

Use Script Files

Or evaluate a script file directly with Engine::run_file or Engine::eval_file.

Loading and running script files is not available for no_std or WASM builds.

let result = engine.eval_file::<i64>("hello_world.rhai".into())?;
//                                   ^^^^^^^^^^^^^^^^^^^^^^^^^
//                                   a 'PathBuf' is needed

// Running a script file also works in a similar manner
engine.run_file("hello_world.rhai".into())?;

#!/home/to/me/bin/rhai-run

// This is a Rhai script

let answer = 42;
print(`The answer is: ${answer}`);

Specify the Return Type

The type parameter for Engine::eval is used to specify the type of the return value, which must match the actual type or an error is returned. Rhai is very strict here.

There are two ways to specify the return type: turbofish notation, or type inference.

Turbofish

let result = engine.eval::<i64>("40 + 2")?;     // return type is i64

result.is::<i64>() == true;

let result = engine.eval::<Dynamic>("boo()")?;  // use 'Dynamic' if you're not sure what type it'll be!

let result = engine.eval::<String>("40 + 2")?;  // returns an error because the actual return type is i64, not String

Type inference

let result: i64 = engine.eval("40 + 2")?;       // return type is inferred to be i64

result.is::<i64>() == true;

let result: Dynamic = engine.eval("boo()")?;    // use 'Dynamic' if you're not sure what type it'll be!

let result: String = engine.eval("40 + 2")?;    // returns an error because the actual return type is i64, not String

Compile a Script (to AST)

To repeatedly evaluate a script, compile it first with Engine::compile into an AST (Abstract Syntax Tree) form.

Engine::eval_ast_XXX and Engine::run_ast_XXX evaluate a pre-compiled AST.

// Compile to an AST and store it for later evaluations
let ast = engine.compile("40 + 2")?;

for _ in 0..42 {
    let result: i64 = engine.eval_ast(&ast)?;

    println!("Answer #{i}: {result}");      // prints 42
}

let ast = engine.compile_file("hello_world.rhai".into())?;

Practical Use – Header Template Scripts

Sometimes it is desirable to include a standardized header template in a script that contains pre-defined functions, constants and imported modules.

// START OF THE HEADER TEMPLATE
// The following should run before every script...

import "hello" as h;
import "world" as w;

// Standard constants

const GLOBAL_CONSTANT = 42;
const SCALE_FACTOR = 1.2;

// Standard functions

fn foo(x, y) { ... }

fn bar() { ... }

fn baz() { ... }

// END OF THE HEADER TEMPLATE

// Everything below changes from run to run

foo(bar() + GLOBAL_CONSTANT, baz() * SCALE_FACTOR)

Option 1 – The easy way

Prepend the script header template onto independent scripts and run them as a whole.

Pros: Easy!

Cons: If the header template is long, work is duplicated every time to parse it.

let header_template = "..... // scripts... .....";

for index in 0..10000 {
    let user_script = db.get_script(index);

    // Just merge the two scripts...
    let combined_script = format!("{header_template}\n{user_script}\n");

    // Run away!
    let result = engine.eval::<i64>(combined_script)?;
    
    println!("{result}");
}

Option 2 – The hard way

Option 1 requires the script header template to be recompiled every time. This can be expensive if the header is very long.

This option compiles both the script header template and independent scripts as separate AST’s which are then joined together to form a combined AST.

Pros: No need to recompile the header template!

Cons: More work…

let header_template = "..... // scripts... .....";

let mut template_ast = engine.compile(header_template)?;

// If you don't want to run the template, only keep the functions
// defined inside (e.g. closures), clear out the statements.
template_ast.clear_statements();

for index in 0..10000 {
    let user_script = db.get_script(index);

    let user_ast = engine.compile(user_script)?;

    // Merge the two AST's
    let combined_ast = template_ast + user_ast;

    // Run away!
    let result = engine.eval_ast::<i64>(combined_ast)?;
    
    println!("{result}");

Option 3 – The not-so-hard way

Option 1 does repeated work, option 2 requires manipulating AST’s…

This option makes the scripted functions (not imported modules nor constants however) available globally by first making it a module (via Module::eval_ast_as_new) and then loading it into the Engine via Engine::register_global_module.

Pros: No need to recompile the header template!

Cons: No imported modules nor constants; if the header template is changed, a new Engine must be created.

let header_template = "..... // scripts... .....";

let template_ast = engine.compile(header_template)?;

let template_module = Module::eval_ast_as_new(Scope::new(), &template_ast, &engine)?;

engine.register_global_module(template_module.into());

for index in 0..10000 {
    let user_script = db.get_script(index);

    // Run away!
    let result = engine.eval::<i64>(user_script)?;
    
    println!("{result}");
}

Raw Engine

Engine::new creates a scripting Engine with common functionalities (e.g. printing to stdout via print or debug).

In many controlled embedded environments, however, these may not be needed and unnecessarily occupy application code storage space.

Use Engine::new_raw to create a raw Engine, in which only a minimal set of built-in basic arithmetic and logical operators are supported.

To add more functionalities to a raw Engine, load packages into it.

Since packages can be shared, this is an extremely efficient way to create multiple instances of the same Engine with the same set of functions.

use rhai::module_resolvers::FileModuleResolver;
use rhai::packages::StandardPackage;

// Create a raw scripting Engine
let mut engine = Engine::new_raw();

// Use the file-based module resolver
engine.set_module_resolver(FileModuleResolver::new());

// Enable the strings interner
engine.set_max_strings_interned(1024);

// Default print/debug implementations
engine.on_print(|text| println!("{text}"));

engine.on_debug(|text, source, pos| match (source, pos) {
    (Some(source), Position::NONE) => println!("{source} | {text}"),
    (Some(source), pos) => println!("{source} @ {pos:?} | {text}"),
    (None, Position::NONE) => println!("{text}"),
    (None, pos) => println!("{pos:?} | {text}"),
});

// Register the Standard Package
let package = StandardPackage::new();

// Load the package into the [`Engine`]
package.register_into_engine(&mut engine);

Built-in Operators

The following operators are built-in, meaning that they are always available, even when using a raw Engine.

All built-in operators are binary, and are supported for both operands of the same type.

Scope – Maintaining State

By default, Rhai treats each Engine invocation as a fresh one, persisting only the functions that have been registered but no global state.

This gives each evaluation a clean starting slate.

In order to continue using the same global state from one invocation to the next, such a state (a Scope) must be manually created and passed in.

All Scope variables and constants have values that are Dynamic, meaning they can store values of any type.

Under sync, however, only types that are Send + Sync are supported, and the entire Scope itself will also be Send + Sync. This is extremely useful in multi-threaded applications.

Scope API

Serializing/Deserializing

With the serde feature, Scope is serializable and deserializable via serde.

Custom types stored in the Scope, however, are serialized as full type-name strings. Data in custom types are not serialized.

Example

In the following example, a Scope is created with a few initialized variables, then it is threaded through multiple evaluations.

use rhai::{Engine, Scope, EvalAltResult};

let engine = Engine::new();

// First create the state
let mut scope = Scope::new();

// Then push (i.e. add) some initialized variables into the state.
// Remember the system number types in Rhai are i64 (i32 if 'only_i32')
// and f64 (f32 if 'f32_float').
// Better stick to them or it gets hard working with the script.
scope.push("y", 42_i64)
     .push("z", 999_i64)
     .push_constant("MY_NUMBER", 123_i64)       // constants can also be added
     .set_value("s", "hello, world!");          // 'set_value' adds a new variable when one doesn't exist

// First invocation
engine.run_with_scope(&mut scope, 
"
    let x = 4 + 5 - y + z + MY_NUMBER + s.len;
    y = 1;
")?;

// Second invocation using the same state.
// Notice that the new variable 'x', defined previously, is still here.
let result = engine.eval_with_scope::<i64>(&mut scope, "x + y")?;

println!("result: {result}");                   // prints 1103

// Variable y is changed in the script - read it with 'get_value'
assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 1);

// We can modify scope variables directly with 'set_value'
scope.set_value("y", 42_i64);
assert_eq!(scope.get_value::<i64>("y").expect("variable y should exist"), 42);

Engine API Using Scope

Engine API methods that accept a Scope parameter all end in _with_scope, making that Scope (and everything inside it) available to the script:

let mut scope = Scope::new();

engine.run_with_scope(&mut scope, "let x = 42;")?;

// Variable 'x' stays inside the custom scope!
engine.run_with_scope(&mut scope, "print(x);")?;    //  prints 42

let mut scope = Scope::new();

// Don't do this - this creates 1 million variables named 'x'
//                 inside 'scope'!!!
for _ in 0..1_000_000 {
    engine.run_with_scope(&mut scope, "let x = 42;")?;
}

// The 'scope' contains a LOT of variables...
assert_eq!(scope.len(), 1_000_000);

// Variable 'x' stays inside the custom scope!
engine.run_with_scope(&mut scope, "print(x);")?;    //  prints 42

// Run a million times
for _ in 0..1_000_000 {
    // Save the current size of the 'scope'
    let orig_scope_size = scope.len();

    engine.run_with_scope(&mut scope, "let x = 42;")?;

    // Rewind the 'scope' to the original size
    scope.rewind(orig_scope_size);
}

// The 'scope' is empty
assert_eq!(scope.len(), 0);

// Variable 'x' is no longer inside 'scope'!
engine.run_with_scope(&mut scope, "print(x);")?;    //  error: variable 'x' not found

Evaluate Expressions Only

Very often, a use case does not require a full-blown scripting language, but only needs to evaluate expressions.

In these cases, use the Engine::compile_expression and Engine::eval_expression methods or their _with_scope variants.

let result: i64 = engine.eval_expression("2 + (10 + 10) * 2")?;

let result: Dynamic = engine.eval_expression("get_value(42)")?;

// Usually this is done together with a custom scope with variables...

let mut scope = Scope::new();

scope.push("x", 42_i64);
scope.push_constant("SCALE", 10_i64);

let result: i64 = engine.eval_expression_with_scope(&mut scope,
                        "(x + 1) * SCALE"
                  )?;

// The following are all syntax errors because the script
// is not a strict expression.

engine.eval_expression::<()>("x = 42")?;

let ast = engine.compile_expression("let x = 42")?;

let result = engine.eval_expression_with_scope::<i64>(&mut scope,
                    "{ let y = calc(x); x + y }"
             )?;

let fp: FnPtr = engine.eval_expression("|x| x + 1")?;

// The following are allowed.

let result = engine.eval_expression_with_scope::<i64>(&mut scope,
                    "if x { 42 } else { 123 }"
             )?;

let result = engine.eval_expression_with_scope::<i64>(&mut scope, "
                    switch x {
                        0 => x * 42,
                        1..=9 => foo(123) + bar(1),
                        10 => 0,
                    }
             ")?;

Engine Configuration Options

A number of other configuration options are available from the Engine to fine-tune behavior and safeguards.

Compile-Time Language Features

Beware that these options activate during compile-time only. If an AST is compiled on an Engine but then evaluated on a different Engine with different configuration, disallowed features contained inside the AST will still run as normal.

Runtime Behavior

Safety Limits

Examples

Rhai comes with a number of examples showing how to integrate the scripting Engine within a Rust application, as well as a number of sample scripts that showcase different Rhai language features.

Rust Examples

Standard Examples

A number of examples can be found under examples.

Scriptable Event Handler With State Examples

Because of its popularity, the pattern Scriptable Event Handler With State has sample implementations for different styles.

Running Examples

Examples can be run with the following command:

cargo run --example {example_name}

no-std Examples

To illustrate no-std builds, a number of example applications are available under the no_std directory:

Building the no-std examples

cd no_std/no_std_test

cargo +nightly build --release

./target/release/no_std_test

Example Scripts

Language Feature Scripts

There are also a number of examples scripts that showcase Rhai’s features, all in the scripts directory:

Benchmark Scripts

The following scripts are for benchmarking the speed of Rhai:

Run Example Scripts

The rhai-run utility can be used to run Rhai scripts:

cargo run --bin rhai-run scripts/any_script.rhai

Special Builds

It is possible to mix-and-match various features of the Rhai crate to make specialized builds with specific characteristics and behaviors.

Performance Build

Some features are for performance. In order to squeeze out the maximum performance from Rhai, the following features should be considered:

When the above feature flags are used, performance may increase by around 15-20%.

Unchecked Build

By default, Rhai provides a Don’t Panic guarantee and prevents malicious scripts from bringing down the host. Any panic can be considered a bug.

For maximum performance, however, these safety checks can be turned off via the unchecked feature.

Fast Operators Mode

Make sure that Fast Operators Mode, which is enabled by default, is on. It ignores any user overloading of built-in operators.

For operator-heavy scripts, this may provide a substantial speed-up.

Use Only One Integer Type

If only a single integer type is needed in scripts – most of the time this is the case – it is best to avoid registering lots of functions related to other integer types that will never be used. As a result, Engine creation will be faster because fewer functions need to be loaded.

The only_i32 and only_i64 features disable all integer types except i32 or i64 respectively.

Use Only 32-Bit Numbers

If only 32-bit integers are needed – again, most of the time this is the case – turn on only_i32. Under this feature, only i32 is supported as a built-in integer type and no others.

On 64-bit targets this may not gain much, but on certain 32-bit targets this improves performance due to 64-bit arithmetic requiring more CPU cycles to complete.

Minimize Size of Dynamic

Turning on f32_float (or no_float) and only_i32 on 32-bit targets makes the critical Dynamic data type only 8 bytes long for 32-bit targets.

Normally Dynamic needs to be up 12-16 bytes long in order to hold an i64 or f64.

A smaller Dynamic helps performance due to better cache efficiency.

Use ImmutableString

Internally, Rhai uses immutable strings instead of the Rust String type. This is mainly to avoid excessive cloning when passing function arguments.

Rhai’s internal string type is ImmutableString (basically Rc<SmartString> or Arc<SmartString> depending on the sync feature). It is cheap to clone, but expensive to modify (a new copy of the string must be made in order to change it).

Therefore, functions taking String parameters should use ImmutableString or &str (maps to ImmutableString) for the best performance with Rhai.

Disable Capturing in Closures

Support for closures that capture shared variables adds material overhead to script evaluation.

This is because every data access must be checked whether it is a shared value and, if so, take a read lock before reading it.

As the vast majority of variables are not shared, needless to say this is a non-trivial performance overhead.

Use no_closure to disable support for closures to optimize the hot path because it no longer needs to take locks for shared data.

Disable Position

For embedded scripts that are not expected to cause errors, the no_position feature can be used to disable position tracking during parsing.

No line number/character position information is kept for error reporting purposes.

This may result in a slightly fast build due to elimination of code related to position tracking.

Avoid Cloning

Use &mut functions

Rhai values are typically cloned when passed around, especially into function calls. Large data structures may incur material cloning overhead.

Some functions accept the first parameter as a mutable reference (i.e. &mut), for example methods for custom types, and may avoid potentially-costly cloning.

Compound assignment

For example, the += (append) compound assignment takes a mutable reference to the variable while the corresponding + (add) assignment usually doesn’t. The difference in performance can be huge:

let x = create_some_very_big_and_expensive_type();

x = x + 1;
//  ^ 'x' is cloned here

// The above is equivalent to:
let temp_value = x.clone() + 1;
x = temp_value;

x += 1;             // <- 'x' is NOT cloned

Use take

Another example: use the take function to extract a value out of a variable (replacing it with ()) without cloning.

let x = create_some_very_big_and_expensive_type();

let y = x;          // <- 'x' is cloned here

let y = x.take();   // <- 'x' is NOT cloned

x = x + 1;          // <- this statement...

x += 1;             // ... is rewritten as this

x[y] = x[y] + 1;    // <- but this is not, so this is MUCH slower...

x[y] += 1;          // ... than this

some_func(x, 1);    // <- this statement...

x.some_func(1);     // ... is rewritten as this

some_func(x[y], 1); // <- but this is not, so 'x[y]` is cloned

Short Variable Names for 32-Bit Systems

On 32-bit systems, variable and constant names longer than 11 ASCII characters incur additional allocation overhead.

This is particularly true for local variables inside a hot loop, where they are created and destroyed in rapid succession.

Therefore, avoid long variable and constant names that are over this limit.

On 64-bit systems, this limit is raised to 23 ASCII characters, which is almost always adequate.

Minimal Build

Configuration

In order to compile a minimal build – i.e. a build optimized for size – perhaps for no-std embedded targets or for compiling to WASM, it is essential that the correct linker flags are used in Cargo.toml:

[profile.release]
lto = "fat"         # turn on Link-Time Optimizations
codegen-units = 1   # trade compile time with maximum optimization
opt-level = "z"     # optimize for size

Use i32 Only

For embedded systems that must optimize for code size, the architecture is commonly 32-bit. Use only_i32 to prune away large sections of code implementing functions for other numeric types (including i64).

If, for some reason, 64-bit long integers must be supported, use only_i64 instead of only_i32.

Opt-Out of Features

Opt out of as many features as possible, if they are not needed, to reduce code size because, remember, by default all code is compiled into the final binary since what a script requires cannot be predicted. If a language feature will never be needed, omitting it is a prudent strategy to optimize the build for size.

Removing the script optimizer (no_optimize) yields a sizable code saving, at the expense of a less efficient script.

Omitting arrays (no_index) yields the most code-size savings, followed by floating-point support (no_float), safety checks (unchecked) and finally object maps and custom types (no_object).

Where the usage scenario does not call for loading externally-defined modules, use no_module to save some bytes. Disable script-defined functions (no_function) and possibly closures (no_closure) when the features are not needed. Both of these have some code size savings but not much.

For embedded scripts that are not expected to cause errors, the no_position feature can be used to disable position tracking during parsing. No line number/character position information is kept for error reporting purposes. This may result in a slightly smaller build due to elimination of code related to position tracking.

Use a Raw Engine

Engine::new_raw creates a raw engine. A raw engine supports, out of the box, only a very restricted set of basic arithmetic and logical operators.

Selectively include other necessary functionalities by picking specific packages to minimize the footprint.

Packages are shared (even across threads via the sync feature), so they only have to be created once.

In addition, a Engine::new_raw disables the strings interner, which might actually increase memory usage if many strings are created in scripts. Therefore, selectively turn on the strings interner via Engine::set_max_strings_interned.

no-std Build

The feature no_std automatically converts the scripting engine into a no-std build.

Usually, a no-std build goes hand-in-hand with minimal builds because typical embedded hardware (the primary target for no-std) has limited storage.

Implementation

Rhai allocates, so the first thing that must be included in any no-std project is an allocator crate, such as wee_alloc.

Then there is the need to set up proper error/panic handlers. The following example uses panic = "abort" and wee_alloc as the allocator.

// Set up for no-std.
#![no_std]

// The following no-std features are usually needed.
#![feature(alloc_error_handler, start, core_intrinsics, lang_items, link_cfg)]

// Set up the global allocator.
extern crate alloc;
extern crate wee_alloc;

#[global_allocator]
static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;

// Rust needs a CRT runtime on Windows when compiled with MSVC.
#[cfg(all(windows, target_env = "msvc"))]
#[link(name = "msvcrt")]
#[link(name = "libcmt")]
extern "C" {}

// Set up panic and error handlers
#[alloc_error_handler]
fn err_handler(_: core::alloc::Layout) -> ! {
    core::intrinsics::abort();
}

#[panic_handler]
#[lang = "panic_impl"]
extern "C" fn rust_begin_panic(_: &core::panic::PanicInfo) -> ! {
    core::intrinsics::abort();
}

#[lang = "eh_personality"]
extern "C" fn eh_personality() {}

#[no_mangle]
extern "C" fn rust_eh_register_frames() {}

#[no_mangle]
extern "C" fn rust_eh_unregister_frames() {}

#[no_mangle]
extern "C" fn _Unwind_Resume() {}

#[start]
fn main(_argc: isize, _argv: *const *const u8) -> isize {
    // ... main program ...
}

WebAssembly (WASM) Build

It is possible to use Rhai when compiling to WebAssembly (WASM).

This yields a scripting engine (and language) that can be run in a standard web browser, among other places.

JavaScript Interop

Specify either of the wasm-bindgen or stdweb features when building for WASM that requires interop with JavaScript. This selects the appropriate JavaScript interop layer to use.

It is still possible to compile for WASM without either wasm-bindgen or stdweb, but then the interop code must then be explicitly provided.

Target Environments

[dependencies]
rhai = { version = "1.20.0", default-features = false, features = [ "std" ] }

Size

Also look into minimal builds to reduce generated WASM size.

A typical, full-featured Rhai scripting engine compiles to a single WASM32 file that is less than 400KB (non-gzipped).

When excluding features that are marginal in WASM environment, the gzipped payload can be shrunk further.

Standard packages can also be excluded to yield additional size savings.

Speed

In benchmark tests, a WASM build runs scripts roughly 30% slower than a native optimized release build.

Common Features

Some Rhai functionalities are not necessary in a WASM environment, so the following features are typically used for a WASM build:

The following features are typically not used because they don’t make sense in a WASM build:

Extend Rhai with Rust

Most features and functionalities required by a Rhai script should actually be coded in Rust, which leverages the superior native run-time speed.

This section discusses how to extend Rhai with functionalities written in Rust.

Traits

A number of traits, under the rhai:: module namespace, provide additional functionalities.

Register a Rust Function for Use in Rhai Scripts

Rhai’s scripting engine is very lightweight. It gets most of its abilities from functions.

To call these functions, they need to be registered via Engine::register_fn.

use rhai::{Dynamic, Engine, ImmutableString};

// Normal function that returns a standard type
// Remember to use 'ImmutableString' and not 'String'
fn add_len(x: i64, s: ImmutableString) -> i64 {
    x + s.len()
}
// Alternatively, '&str' maps directly to 'ImmutableString'
fn add_len_count(x: i64, s: &str, c: i64) -> i64 {
    x + s.len() * c
}
// Function that returns a 'Dynamic' value
fn get_any_value() -> Dynamic {
    42_i64.into()                       // standard types can use '.into()'
}

let mut engine = Engine::new();

// Notice that all three functions are overloaded into the same name with
// different number of parameters and/or parameter types.
engine.register_fn("add", add_len)
      .register_fn("add", add_len_count)
      .register_fn("add", get_any_value)
      .register_fn("inc", |x: i64| {    // closure is also OK!
          x + 1
      })
      .register_fn("log", |label: &str, x: i64| {
          println!("{label} = {x}");
      });

let result = engine.eval::<i64>(r#"add(40, "xx")"#)?;

println!("Answer: {result}");           // prints 42

let result = engine.eval::<i64>(r#"add(40, "x", 2)"#)?;

println!("Answer: {result}");           // prints 42

let result = engine.eval::<i64>("add()")?;

println!("Answer: {result}");           // prints 42

let result = engine.eval::<i64>("inc(41)")?;

println!("Answer: {result}");           // prints 42

engine.run(r#"log("value", 42)"#)?;     // prints "value = 42"

┌──────┐
│ Rust │
└──────┘

engine.register_fn("foo", |x: i64, y: i64| x * 2 + y * 3);
//                            ^^^     ^^^
// Usually parameter types need to be specified

engine.register_fn("bar", |x: i64| -> Result<_, Box<EvalAltResult>> { x * 2 });
//                                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
// For fallible closures, the return ERROR type may need to be specified

┌─────────────┐
│ Rhai script │
└─────────────┘

foo(42, 100);       // <- 42 * 2 + 100 * 3

┌──────┐
│ Rust │
└──────┘

/// A type that encapsulates some behavior.
#[derive(Clone)]
struct TestStruct { ... }

impl TestSTruct {
    /// Some action defined on that type.
    pub fn do_foo(&self, x: i64, y: bool) {
        // ... do something drastic with x and y
    }
}

/// Wrapped in shared mutability: Rc<RefCell<TestStruct>>.
let shared_obj = Rc::new(RefCell::new(TestStruct::new()));

/// Clone the shared reference and move it into the closure.
let embedded_obj = shared.clone();

engine.register_fn("foo", move |x: i64, y: bool| {
//                        ^^^^ 'embedded_obj' is captured into the closure

    embedded_obj.borrow().do_foo(x, y);
});

┌─────────────┐
│ Rhai script │
└─────────────┘

foo(42, true);      // <- equivalent to: shared_obj.borrow().do_foo(42, true);

// The following fails to compile because the compiler does not know
// the return _error_ type of the closure.
// It knows the return type, which is 'Result<i64, E>', but 'E' is not known.
engine.register_fn("foo", |x: i64| Ok(x));

// Don't do this...
engine.register_fn::<_, 1, false, i64, Box<EvalAltResult>>("foo", |x: i64| Ok(x));

// Do this...
engine.register_fn("foo", |x: i64| -> Result<i64, Box<EvalAltResult>> { Ok(x) });

Function Overloading

Functions registered with the Engine can be overloaded as long as the signature is unique, i.e. different functions can have the same name as long as their parameters are of different numbers (i.e. arity) or different types.

New definitions overwrite previous definitions of the same name, same arity and same parameter types.

// The following definition of 'foo' is equivalent to the pseudo-code:
//   fn foo(x = 42_i64, y = "hello", z = true) -> i64 { ... }

fn foo3(x: i64, y: &str, z: bool) -> i64 { ... }
fn foo2(x: i64, y: &str) -> i64 { foo3(x, y, true) }
fn foo1(x: i64) -> i64 { foo2(x, "hello") }
fn foo0() -> i64 { foo1(42) }

engine.register_fn("foo", foo0)     // no parameters
      .register_fn("foo", foo1)     // 1 parameter
      .register_fn("foo", foo2)     // 2 parameters
      .register_fn("foo", foo3);    // 3 parameters

Register a Generic Rust Function

Rust generic functions can be used in Rhai, but separate instances for each concrete type must be registered separately.

This essentially overloads the function with different parameter types as Rhai does not natively support generics but Rhai does support function overloading.

The example below shows how to register multiple functions (or, in this case, multiple overloaded versions of the same function) under the same name.

use std::fmt::Display;

use rhai::Engine;

fn show_it<T: Display>(x: &mut T) {
    println!("put up a good show: {x}!");
}

let mut engine = Engine::new();

engine.register_fn("print", show_it::<i64>)
      .register_fn("print", show_it::<bool>)
      .register_fn("print", show_it::<ImmutableString>);

String Parameters in Rust Functions

&str Maps to ImmutableString

Rust functions accepting parameters of String should use &str instead because it maps directly to ImmutableString which is the type that Rhai uses to represent strings internally.

The parameter type String involves always converting an ImmutableString into a String which mandates cloning it.

Using ImmutableString or &str is much more efficient.

fn get_len1(s: String) -> i64 {             // BAD!!! Very inefficient!!!
    s.len() as i64
}
fn get_len2(s: &str) -> i64 {               // this is better
    s.len() as i64
}
fn get_len3(s: ImmutableString) -> i64 {    // the above is equivalent to this
    s.len() as i64
}

engine.register_fn("len1", get_len1)
      .register_fn("len2", get_len2)
      .register_fn("len3", get_len3);

let len = engine.eval::<i64>("len1(x)")?;   // 'x' cloned, very inefficient!!!
let len = engine.eval::<i64>("len2(x)")?;   // 'x' is shared
let len = engine.eval::<i64>("len3(x)")?;   // 'x' is shared

fn bad(s: &mut String) { ... }              // '&mut String' will not match string values

fn good(s: &mut ImmutableString) { ... }

engine.register_fn("bad", bad)
      .register_fn("good", good);

engine.eval(r#"bad("hello")"#)?;            // <- error: function 'bad (string)' not found

engine.eval(r#"good("hello")"#)?;           // <- this one works

Dynamic Parameters in Rust Functions

It is possible for Rust functions to contain parameters of type Dynamic.

A Dynamic value can hold any clonable type.

// 'item: Dynamic' matches all data types
fn push(array: &mut Array, item: Dynamic) {
    array.push(item);
}

Precedence

Any parameter in a registered Rust function with a specific type has higher precedence over Dynamic, so it is important to understand which version of a function will be used.

Parameter matching starts from the left to the right. Candidate functions will be matched in order of parameter types.

Therefore, always leave Dynamic parameters (up to 16, see below) as far to the right as possible.

use rhai::{Engine, Dynamic};

// Different versions of the same function 'foo'
// will be matched in the following order.

fn foo1(x: i64, y: &str, z: bool) { }

fn foo2(x: i64, y: &str, z: Dynamic) { }

fn foo3(x: i64, y: Dynamic, z: bool) { }

fn foo4(x: i64, y: Dynamic, z: Dynamic) { }

fn foo5(x: Dynamic, y: &str, z: bool) { }

fn foo6(x: Dynamic, y: &str, z: Dynamic) { }

fn foo7(x: Dynamic, y: Dynamic, z: bool) { }

fn foo8(x: Dynamic, y: Dynamic, z: Dynamic) { }

let mut engine = Engine::new();

// Register all functions under the same name (order does not matter)

engine.register_fn("foo", foo5)
      .register_fn("foo", foo7)
      .register_fn("foo", foo2)
      .register_fn("foo", foo8)
      .register_fn("foo", foo1)
      .register_fn("foo", foo3)
      .register_fn("foo", foo6)
      .register_fn("foo", foo4);

// The 'd' parameter counts 17th from the right!
fn weird(a: i64, d: Dynamic, x1: i64, x2: i64, x3: i64, x4: i64,
                             x5: i64, x6: i64, x7: i64, x8: i64,
                             x9: i64, x10: i64, x11: i64, x12: i64,
                             x13: i64, x14: i64, x15: i64, x16: i64) {

    // ... do something unspeakably evil with all those parameters ...
}

TL;DR

foo(42, "hello", true);

Dynamic Return Value

Rhai supports registering functions that return Dynamic.

A Dynamic value can hold any clonable type.

use rhai::{Engine, Dynamic};

// The 'Dynamic' return type allows this function to
// return values of any supported type!
fn get_info(bag: &mut PropertyBag, key: &str) -> Dynamic {
    if let Some(prop_type) = bag.get_type(key) {
        match prop_type {
            // Use '.into()' for standard types
            "string" => bag.get::<&str>(key).into(),
            "int" => bag.get::<i64>(key).into(),
            "bool" => bag.get::<bool>(key).into(),
                            :
                            :
            // Use 'Dynamic::from' for custom types
            "bag" => Dynamic::from(bag.get::<PropertyBag>(key))
        }
    } else {
        // Return () upon error
        Dynamic::UNIT
    }
}

let mut engine = Engine::new();

engine.register_fn("get_info", get_info);

use rhai::Dynamic;

let obj = TestStruct::new();

let x = Dynamic::from(obj);

// '.into()' works for standard types

let x = 42_i64.into();

let y = "hello!".into();

use rhai::{Engine, Dynamic};

// Function that may fail - return () upon failure
fn safe_divide(x: i64, y: i64) -> Dynamic {
    if y == 0 {
        // Return () to indicate an error if y is zero
        Dynamic::UNIT
    } else {
        // Use '.into()' to convert standard types to 'Dynamic'
        (x / y).into()
    }
}

let mut engine = Engine::new();

engine.register_fn("divide", safe_divide);

// The following prints 'error!'
engine.run(r#"
    let result = divide(40, 0);
    
    if result == () {
        print("error!");
    } else {
        print(result);
    }
"#)?;

Register a Fallible Rust Function

If a function is fallible (i.e. it returns a Result<_, _>), it can also be registered with via Engine::register_fn.

The function must return Result<T, Box<EvalAltResult>> where T is any clonable type.

In other words, the error type must be Box<EvalAltResult>. It is Boxed in order to reduce the size of the Result type since the error path is rarely hit.

use rhai::{Engine, EvalAltResult};

// Function that may fail - the error type must be 'Box<EvalAltResult>'
fn safe_divide(x: i64, y: i64) -> Result<i64, Box<EvalAltResult>> {
    if y == 0 {
        // Return an error if y is zero
        Err("Division by zero!".into())         // shortcut to create Box<EvalAltResult::ErrorRuntime>
    } else {
        Ok(x / y)
    }
}

let mut engine = Engine::new();

engine.register_fn("divide", safe_divide);

if let Err(error) = engine.eval::<i64>("divide(40, 0)") {
    println!("Error: {error:?}");               // prints ErrorRuntime("Division by zero detected!", (1, 1)")
}

NativeCallContext

If the first parameter of a function is of type rhai::NativeCallContext, then it is treated specially by the Engine.

NativeCallContext is a type that encapsulates the current call context of a Rust function call and exposes the following.

Example Implementations

use rhai::{Array, NativeCallContext, EvalAltResult, Position};

// This function builds an array of arbitrary size, but is protected against attacks
// by first checking with the allowed limit set into the 'Engine'.
pub fn new_array(context: NativeCallContext, size: i64) -> Result<Array, Box<EvalAltResult>>
{
    let array = Array::new();

    if size <= 0 {
        return array;
    }

    let size = size as usize;
    let max_size = context.engine().max_array_size();

    // Make sure the function does not generate a data structure larger than
    // the allowed limit for the Engine!
    if max_size > 0 && size > max_size {
        return Err(EvalAltResult::ErrorDataTooLarge(
            "Size to grow".to_string(),
            max_size, size,
            context.position(),
        ).into());
    }

    for x in 0..size {
        array.push(x.into());
    }

    OK(array)
}

use rhai::{Engine, NativeCallContext};

let mut engine = Engine::new();

// A function expecting a callback in form of a function pointer.
engine.register_fn("super_call", |context: NativeCallContext, value: i64| {
    // Call a function within the current evaluation!
    // 'call_native_fn' ensures that only registered native Rust functions
    // are called, so a scripted function named 'double' cannot hijack
    // the process.
    // To also include scripted functions, use 'call_fn' instead.
    context.call_native_fn::<i64>("double", (value,))
    //                                      ^^^^^^^^ arguments passed in tuple
});

use rhai::{Dynamic, FnPtr, NativeCallContext, EvalAltResult};

pub fn greet(context: NativeCallContext, callback: FnPtr) -> Result<String, Box<EvalAltResult>>
{
    // Call the callback closure with the current evaluation context!
    let name = callback.call_within_context(&context, ())?;
    Ok(format!("hello, {}!", name))
}

Advanced Usage – Restore NativeCallContext

The NativeCallContext type encapsulates the entire context of a script up to the particular point of the native Rust function call.

The data inside a NativeCallContext can be stored (as a type NativeCallContextStore) for later use, when a new NativeCallContext can be constructed based on these stored data.

A reconstructed NativeCallContext acts almost the same as the original instance, so it is possible to suspend the evaluation of a script, and to continue at a later time with a new NativeCallContext.

Doing so requires the internals feature to access internal API’s.

Step 1: Store NativeCallContext data

// Store context for later use
let context_data = context.store_data();

// ... store 'context_data' somewhere ...
secret_database.push(context_data);

Step 2: Restore NativeCallContext

// ... do something else ...

// Restore the context
let context_data = secret_database.get();

let new_context = context_data.create_context(&engine);

Override a Built-in Function

Any similarly-named function defined in a script overrides any built-in or registered native Rust function of the same name and number of parameters.

// Override the built-in function 'to_float' when called as a method
fn to_float() {
    print(`Ha! Gotcha! ${this}`);
    42.0
}

let x = 123.to_float();

print(x);       // what happens?

Call Rhai Functions from Rust

Rhai also allows working backwards from the other direction – i.e. calling a Rhai-scripted function from Rust via Engine::call_fn.

┌─────────────┐
│ Rhai script │
└─────────────┘

import "process" as proc;           // this is evaluated every time

fn hello(x, y) {
    // hopefully 'my_var' is in scope when this is called
    x.len + y + my_var
}

fn hello(x) {
    // hopefully 'my_string' is in scope when this is called
    x * my_string.len()
}

fn hello() {
    // hopefully 'MY_CONST' is in scope when this is called
    if MY_CONST {
        proc::process_data(42);     // can access imported module
    }
}


┌──────┐
│ Rust │
└──────┘

// Compile the script to AST
let ast = engine.compile(script)?;

// Create a custom 'Scope'
let mut scope = Scope::new();

// A custom 'Scope' can also contain any variables/constants available to
// the functions
scope.push("my_var", 42_i64);
scope.push("my_string", "hello, world!");
scope.push_constant("MY_CONST", true);

// Evaluate a function defined in the script, passing arguments into the
// script as a tuple.
//
// Beware, arguments must be of the correct types because Rhai does not
// have built-in type conversions. If arguments of the wrong types are passed,
// the Engine will not find the function.
//
// Variables/constants pushed into the custom 'Scope'
// (i.e. 'my_var', 'my_string', 'MY_CONST') are visible to the function.

let result = engine.call_fn::<i64>(&mut scope, &ast, "hello", ( "abc", 123_i64 ) )?;
//                            ^^^                             ^^^^^^^^^^^^^^^^^^
//              return type must be specified                 put arguments in a tuple

let result = engine.call_fn::<i64>(&mut scope, &ast, "hello", ( 123_i64, ) )?;
//                                                            ^^^^^^^^^^^^ tuple of one

let result = engine.call_fn::<i64>(&mut scope, &ast, "hello", () )?;
//                                                            ^^ unit = tuple of zero

( arg , )

FuncArgs Trait

Engine::call_fn takes a parameter of any type that implements the FuncArgs trait, which is used to parse a data type into individual argument values for the function call.

Custom types (e.g. structures) can also implement FuncArgs so they can be used for calling Engine::call_fn.

use std::iter::once;
use rhai::FuncArgs;

// A struct containing function arguments
struct Options {
    pub foo: bool,
    pub bar: String,
    pub baz: i64
}

impl FuncArgs for Options {
    fn parse<C: Extend<Dynamic>>(self, container: &mut C) {
        container.extend(once(self.foo.into()));
        container.extend(once(self.bar.into()));
        container.extend(once(self.baz.into()));
    }
}

let options = Options { foo: true, bar: "world", baz: 42 };

// The type 'Options' can now be used as argument to 'call_fn'
// to call a function with three parameters: fn hello(foo, bar, baz)
let result = engine.call_fn::<i64>(&mut scope, &ast, "hello", options)?;

Engine::call_fn_with_options

For more control, use Engine::call_fn_with_options, which takes a type CallFnOptions:

use rhai::{Engine, CallFnOptions};

let options = CallFnOptions::new()
                .eval_ast(false)            // do not evaluate the AST
                .rewind_scope(false)        // do not rewind the scope (i.e. keep new variables)
                .bind_this_ptr(&mut state); // 'this' pointer

let result = engine.call_fn_with_options::<i64>(
                options,                    // options
                &mut scope,                 // scope to use
                &ast,                       // AST containing the functions
                "hello",                    // function entry-point
                ( "abc", 123_i64 )          // arguments
             )?;

CallFnOptions allows control of the following:

Skip evaluation of the AST

By default, the AST is evaluated before calling the target function.

This is necessary to make sure that necessary modules imported via import statements are available.

Setting eval_ast to false skips this evaluation.

Keep new variables/constants

By default, the Engine rewinds the custom Scope after each call to the initial size, so any new variable/constant defined are cleared and will not spill into the custom Scope.

This prevents the Scope from being continuously polluted by new variables and is usually the intuitively expected behavior.

Setting rewind_scope to false retains new variables/constants within the custom Scope.

This allows the function to easily pass values back to the caller by leaving them inside the custom Scope.

┌─────────────┐
│ Rhai script │
└─────────────┘

fn initialize() {
    let x = 42;                     // 'x' is retained
    let y = x * 2;                  // 'y' is retained

    // Use a new statements block to define temp variables
    {
        let temp = x + y;           // 'temp' is NOT retained

        foo = temp * temp;          // 'foo' is visible in the scope
    }
}

let foo = 123;                      // 'foo' is retained

// Use a new statements block to define temp variables
{
    let bar = foo / 2;              // 'bar' is NOT retained

    foo = bar * bar;
}


┌──────┐
│ Rust │
└──────┘

let options = CallFnOptions::new().rewind_scope(false);

engine.call_fn_with_options(options, &mut scope, &ast, "initialize", ())?;

// At this point, 'scope' contains these variables: 'foo', 'x', 'y'

Bind the this pointer

CallFnOptions can also bind a value to the this pointer of a script-defined function.

It is possible, then, to call a function that uses this.

let ast = engine.compile("fn action(x) { this += x; }")?;

let mut value: Dynamic = 1_i64.into();

let options = CallFnOptions::new()
                .eval_ast(false)
                .rewind_scope(false)
                .bind_this_ptr(&mut value);

engine.call_fn_with_options(options, &mut scope, &ast, "action", ( 41_i64, ))?;

assert_eq!(value.as_int()?, 42);

Create a Rust Closure from a Rhai Function

It is possible to further encapsulate a script in Rust such that it becomes a normal Rust closure.

Creating them is accomplished via the Func trait which contains create_from_script (as well as its companion method create_from_ast).

use rhai::{Engine, Func};       // use 'Func' for 'create_from_script'

let engine = Engine::new();     // create a new 'Engine' just for this

let script = "fn calc(x, y) { x + y.len < 42 }";

// Func takes two type parameters:
//   1) a tuple made up of the types of the script function's parameters
//   2) the return type of the script function
//
// 'func' will have type Box<dyn Fn(i64, &str) -> Result<bool, Box<EvalAltResult>>> and is callable!
let func = Func::<(i64, &str), bool>::create_from_script(
//                ^^^^^^^^^^^ function parameter types in tuple

                engine,         // the 'Engine' is consumed into the closure
                script,         // the script, notice number of parameters must match
                "calc"          // the entry-point function name
)?;

func(123, "hello")? == false;   // call the closure

schedule_callback(func);        // pass it as a callback to another function

// Although there is nothing you can't do by manually writing out the closure yourself...
let engine = Engine::new();
let ast = engine.compile(script)?;
schedule_callback(Box::new(move |x: i64, y: String| {
    engine.call_fn::<bool>(&mut Scope::new(), &ast, "calc", (x, y))
}));

Operator Overloading

In Rhai, a lot of functionalities are actually implemented as functions, including basic operations such as arithmetic calculations.

For example, in the expression “a + b”, the + operator actually calls a function named “+”!

let x = a + b;

let x = +(a, b);        // <- the above is equivalent to this function call

Similarly, comparison operators including ==, != etc. are all implemented as functions, with the stark exception of &&, || and ??.

Overload Operator via Rust Function

Operator functions cannot be defined in script because operators are usually not valid function names.

However, operator functions can be registered via Engine::register_fn.

When a custom operator function is registered with the same name as an operator, it overrides the built-in version. However, make sure the Fast Operators Mode is disabled; otherwise this will not work.

use rhai::{Engine, EvalAltResult};

let mut engine = Engine::new();

fn strange_add(a: i64, b: i64) -> i64 {
    (a + b) * 42
}

engine.register_fn("+", strange_add);               // overload '+' operator for two integers!

engine.set_fast_operators(false);                   // <- IMPORTANT! must turn off Fast Operators Mode

let result: i64 = engine.eval("1 + 0");             // the overloading version is used

result == 42;

let result: f64 = engine.eval("1.0 + 0.0");         // '+' operator for two floats not overloaded

result == 1.0;

fn mixed_add(a: i64, b: bool) -> f64 { a + if b { 42 } else { 99 } }

engine.register_fn("+", mixed_add);                 // register '+' operator for an integer and a bool

let result: i64 = engine.eval("1 + true");          // <- normally an error...

result == 43;                                       //    ... but not now

Working with Any Rust Type

Rhai works seamlessly with any Rust type, as long as it implements Clone as this allows the Engine to pass by value.

A type that is not one of the standard types is termed a “custom type”.

Custom types can have the following:

• a custom (friendly) display name

• methods

• property getters and setters

• indexers

Free Typing

Rhai works seamlessly with any Rust type.

A custom type is stored in Rhai as a Rust trait object (specifically, a dyn rhai::Variant), with no restrictions other than being Clone (plus Send + Sync under the sync feature).

The type literally does not have any prerequisite other than being Clone.

It does not need to implement any other trait or use any custom #[derive].

This allows Rhai to be integrated into an existing Rust code base with as little plumbing as possible, usually silently and seamlessly.

External types that are not defined within the same crate (and thus cannot implement special Rhai traits or use special #[derive]) can also be used easily with Rhai.

Support for custom types can be turned off via the no_object feature.

Register API

For Rhai scripts to interact with the custom type, and API must be registered for it with the Engine.

The API can consist of functions, methods, property getters/setters, indexers, iterators etc.

There are three ways to register an API for a custom type.

1. Auto-Generate API

If you have complete control of the type, then this is the easiest way.

The #[derive(CustomType)] macro can be used to automatically generate an API for a custom type via the CustomType trait.

2. Custom Type Builder

For types in the same crate that you do not control, each function, method, property getter/setter, indexer and iterator can be registered manually, as a single package, via the CustomType trait using the Custom Type Builder.

3. Manual Registration

For external types that cannot implement the CustomType trait due to Rust’s orphan rule, each function, method, property getter/setter, indexer and iterator must be registered manually with the Engine.

Auto-Generate API for Custom Type

To register a type and its API for use with an Engine, the simplest method is via the CustomType trait.

A custom derive macro is provided to auto-implement CustomType on any struct type, which exposes all the type’s fields to an Engine all at once.

It is as simple as adding #[derive(CustomType)] to the type definition.

use rhai::{CustomType, TypeBuilder};    // <- necessary imports

#[derive(Clone, CustomType)]            // <- auto-implement 'CustomType'
pub struct Vec3 {                       //    for normal structs
    pub x: i64,
    pub y: i64,
    pub z: i64,
}

#[derive(Clone, CustomType)]            // <- auto-implement 'CustomType'
pub struct ABC(i64, bool, String);      //    for tuple structs

let mut engine = Engine::new();

// Register the custom types!
engine.build_type::<Vec3>()
      .build_type::<ABC>();

Custom Attribute Options

The rhai_type attribute, with options, can be added to the fields of the type to customize the auto-generated API.

Function signatures

The signature of the function for get is:

Fn(&T) -> V

The signature of the function for get_mut is:

Fn(&mut T) -> V

The signature of the function for set is:

Fn(&mut T, V)

The signature of the function for extra is:

Fn(&mut TypeBuilder<T>)

Example

use rhai::{CustomType, TypeBuilder};    // <- necessary imports

#[derive(Debug, Clone)]
#[derive(CustomType)]                   // <- auto-implement 'CustomType'
pub struct ABC(
    #[rhai_type(skip)]                  // <- 'field0' not included
    i64,

    #[rhai_type(readonly)]              // <- only auto getter, no setter for 'field1'
    i64,
    
    #[rhai_type(name = "flag")]         // <- override property name for 'field2'
    bool,
    
    String                              // <- auto getter/setter for 'field3'
);

#[derive(Default, Clone)]
#[derive(CustomType)]                   // <- auto-implement 'CustomType'
#[rhai_type(name = "MyFoo", extra = Self::build_extra)] // <- call this type 'MyFoo' and use 'build_extra' to add additional API's
pub struct Foo {
    #[rhai_type(skip)]                  // <- field not included
    dummy: i64,

    #[rhai_type(readonly)]              // <- only auto getter, no setter for 'bar'
    bar: i64,

    #[rhai_type(name = "flag")]         // <- override property name
    baz: bool,                          // <- auto getter/setter for 'baz'

    #[rhai_type(get = Self::qux)]       // <- call custom getter (with '&self') for 'qux'
    qux: char,                          // <- auto setter for 'qux'

    #[rhai_type(set = Self::set_hello)] // <- call custom setter for 'hello'
    hello: String                       // <- auto getter for 'hello'
}

impl Foo {
    /// Regular field getter function with `&self`
    pub fn qux(&self) -> char {
        self.qux
    }

    /// Special setter implementation for `hello`
    pub fn set_hello(&mut self, value: String) {
        self.hello = if self.baz {
            let mut s = self.hello.clone();
            s.push_str(&value);
            for _ in 0..self.bar { s.push('!'); }
            s
        } else {
            value
        };
    }

    /// Additional API's
    fn build_extra(builder: &mut TypeBuilder<Self>) {
        // Register constructor function
        builder.with_fn("new_foo", || Self::default());
    }
}

#[derive(Debug, Clone, Eq, PartialEq, CustomType)]
#[rhai_fn(extra = vec3_build_extra)]
pub struct Vec3 {
    #[rhai_type(get = Self::x, set = Self::set_x)]
    x: i64,
    #[rhai_type(get = Self::y, set = Self::set_y)]
    y: i64,
    #[rhai_type(get = Self::z, set = Self::set_z)]
    z: i64,
}

impl Vec3 {
    fn new(x: i64, y: i64, z: i64) -> Self { Self { x, y, z } }
    fn x(&self) -> i64 { self.x }
    fn set_x(&mut self, x: i64) { self.x = x }
    fn y(&self) -> i64 { self.y }
    fn set_y(&mut self, y: i64) { self.y = y }
    fn z(&self) -> i64 { self.z }
    fn set_z(&mut self, z: i64) { self.z = z }
}

fn vec3_build_extra(builder: &mut TypeBuilder<Self>) {
    // Register constructor function
    builder.with_fn("Vec3", Self::new);
}

impl CustomType for ABC {
    fn build(mut builder: TypeBuilder<Self>)
    {
        builder.with_name("ABC");
        builder.with_get("field1", |obj: &mut Self| obj.1.clone());
        builder.with_get_set("flag",
            |obj: &mut Self| obj.2.clone(),
            |obj: &mut Self, val| obj.2 = val
        );
        builder.with_get_set("field3",
            |obj: &mut Self| obj.3.clone(),
            |obj: &mut Self, val| obj.3 = val
        );
    }
}

impl CustomType for Foo {
    fn build(mut builder: TypeBuilder<Self>)
    {
        builder.with_name("MyFoo");
        builder.with_get("bar", |obj: &mut Self| obj.bar.clone());
        builder.with_get_set("flag",
            |obj: &mut Self| obj.baz.clone(),
            |obj: &mut Self, val| obj.baz = val
        );
        builder.with_get_set("qux",
            |obj: &Self| Self::qux(&*obj)),
            |obj: &mut Self, val| obj.qux = val
        )
        builder.with_get_set("hello",
            |obj: &mut Self| obj.hello.clone(),
            Self::set_hello
        );
        Self::build_extra(&mut builder);
    }
}

impl CustomType for Vec3 {
    fn build(mut builder: TypeBuilder<Self>)
    {
        builder.with_name("Vec3");
        builder.with_get_set("x", |obj: &mut Self| Self::x(&*obj), Self::set_x);
        builder.with_get_set("y", |obj: &mut Self| Self::y(&*obj), Self::set_y);
        builder.with_get_set("z", |obj: &mut Self| Self::z(&*obj), Self::set_z);
        vec3_build_extra(&mut builder);
    }
}

Register a Custom Type via the Type Builder

It is usually convenient to package a custom type’s API (i.e. methods, properties, indexers and type iterators) together such that they can be more easily managed.

This can be achieved by manually implementing the CustomType trait, which contains only a single method:

fn build(builder: TypeBuilder<T>)

The TypeBuilder parameter provides a range of convenient methods to register methods, property getters/setters, indexers and type iterators of a custom type:

Example

// Custom type
#[derive(Debug, Clone, Eq, PartialEq)]
struct Vec3 {
    x: i64,
    y: i64,
    z: i64,
}

// Custom type API
impl Vec3 {
    fn new(x: i64, y: i64, z: i64) -> Self {
        Self { x, y, z }
    }
    fn get_x(&mut self) -> i64 {
        self.x
    }
    fn set_x(&mut self, x: i64) {
        self.x = x
    }
    fn get_y(&mut self) -> i64 {
        self.y
    }
    fn set_y(&mut self, y: i64) {
        self.y = y
    }
    fn get_z(&mut self) -> i64 {
        self.z
    }
    fn set_z(&mut self, z: i64) {
        self.z = z
    }
}

// The custom type can even be iterated!
impl IntoIterator for Vec3 {
    type Item = i64;
    type IntoIter = std::vec::IntoIter<Self::Item>;

    fn into_iter(self) -> Self::IntoIter {
        vec![self.x, self.y, self.z].into_iter()
    }
}

// Use 'CustomType' to register the entire API
impl CustomType for Vec3 {
    fn build(mut builder: TypeBuilder<Self>) {
        builder
            .with_name("Vec3")
            .with_fn("vec3", Self::new)
            .is_iterable()
            .with_get_set("x", Self::get_x, Self::set_x)
            .with_get_set("y", Self::get_y, Self::set_y)
            .with_get_set("z", Self::get_z, Self::set_z)
            // Indexer get/set functions that do not panic on invalid indices
            .with_indexer_get_set(
                |vec: &mut Self, idx: i64) -> Result<i64, Box<EvalAltResult>> {
                    match idx {
                        0 => Ok(vec.x),
                        1 => Ok(vec.y),
                        2 => Ok(vec.z),
                        _ => Err(EvalAltResult::ErrorIndexNotFound(idx.Into(), Position::NONE).into()),
                    }
                },
                |vec: &mut Self, idx: i64, value: i64) -> Result<(), Box<EvalAltResult>> {
                    match idx {
                        0 => vec.x = value,
                        1 => vec.y = value,
                        2 => vec.z = value,
                        _ => Err(EvalAltResult::ErrorIndexNotFound(idx.Into(), Position::NONE).into()),
                    }
                    Ok(())
                }
            );
    }
}

let mut engine = Engine::new();

// Register the custom type in one go!
engine.build_type::<Vec3>();

Manually Register Custom Type

The custom type needs to be registered into an Engine via:

use rhai::{Engine, EvalAltResult};

#[derive(Debug, Clone)]
struct TestStruct {
    field: i64
}

impl TestStruct {
    fn new() -> Self {
        Self { field: 1 }
    }
}

let mut engine = Engine::new();

// Register custom type with friendly name
engine.register_type_with_name::<TestStruct>("TestStruct")
      .register_fn("new_ts", TestStruct::new);

// Cast result back to custom type.
let result = engine.eval::<TestStruct>(
"
    new_ts()        // calls 'TestStruct::new'
")?;

println!("result: {}", result.field);   // prints 1

type_of() a Custom Type

type_of() works fine with custom types and returns the name of the type.

If Engine::register_type_with_name is used to register the custom type with a special “pretty-print” friendly name, type_of() will return that name instead.

engine.register_type::<TestStruct1>()
      .register_fn("new_ts1", TestStruct1::new)
      .register_type_with_name::<TestStruct2>("TestStruct")
      .register_fn("new_ts2", TestStruct2::new);

let ts1_type = engine.eval::<String>("let x = new_ts1(); x.type_of()")?;
let ts2_type = engine.eval::<String>("let x = new_ts2(); x.type_of()")?;

println!("{ts1_type}");                 // prints 'path::to::TestStruct'
println!("{ts2_type}");                 // prints 'TestStruct'

== Operator

Many standard functions (e.g. filtering, searching and sorting) expect a custom type to be comparable, meaning that the == operator must be registered for the custom type.

For example, in order to use the in operator with a custom type for an array, the == operator is used to check whether two values are the same.

// Assume 'TestStruct' implements `PartialEq`
engine.register_fn("==",
    |item1: &mut TestStruct, item2: TestStruct| item1 == &item2
);

// Then this works in Rhai:
let item = new_ts();        // construct a new 'TestStruct'
item in array;              // 'in' operator uses '=='

Methods

Methods of custom types are registered via Engine::register_fn.

use rhai::{Engine, EvalAltResult};

#[derive(Debug, Clone)]
struct TestStruct {
    field: i64
}

impl TestStruct {
    fn new() -> Self {
        Self { field: 1 }
    }

    fn update(&mut self, x: i64) {      // methods take &mut as first parameter
        self.field += x;
    }
}

let mut engine = Engine::new();

// Most Engine API's can be chained up.
engine.register_type_with_name::<TestStruct>("TestStruct")
      .register_fn("new_ts", TestStruct::new)
      .register_fn("update", TestStruct::update);

// Cast result back to custom type.
let result = engine.eval::<TestStruct>(
"
    let x = new_ts();                   // calls 'TestStruct::new'
    x.update(41);                       // calls 'TestStruct::update'
    x                                   // 'x' holds a 'TestStruct'
")?;

println!("result: {}", result.field);   // prints 42

First Parameter Must be &mut

Methods of custom types take a &mut first parameter to that type, so that invoking methods can always update it.

All other parameters in Rhai are passed by value (i.e. clones).

Call Method as Function

Method-Call Style vs. Function-Call Style

Method-call syntax

object . function ( parameter, … , parameter)

// Below is a syntax error under 'no_object'.
engine.run("let x = [42]; x.clear();")?;
                        // ^ cannot call method-style

Function-call syntax

function ( object, parameter, … , parameter)

Equivalence

Internally, methods on a custom type is the same as a function taking a &mut first argument of the object’s type.

Therefore, methods and functions can be called interchangeably.

impl TestStruct {
    fn foo(&mut self) -> i64 {
        self.field
    }
}

engine.register_fn("foo", TestStruct::foo);

let result = engine.eval::<i64>(
"
    let x = new_ts();
    foo(x);                         // normal call to 'foo'
    x.foo()                         // 'foo' can also be called like a method on 'x'
")?;

println!("result: {result}");       // prints 1

First &mut Parameter

The opposite direction also works — methods in a Rust custom type registered with the Engine can be called just like a regular function. In fact, like Rust, object methods are registered as regular functions in Rhai that take a first &mut parameter.

Unlike functions defined in script (for which all arguments are passed by value), native Rust functions may mutate the first &mut argument.

Sometimes, however, there are more subtle differences. Methods called in normal function-call style may end up not muting the object afterall — see the example below.

Custom types, properties, indexers and methods are disabled under the no_object feature.

let a = new_ts();   // constructor function
a.field = 500;      // property setter
a.update();         // method call, 'a' can be modified

update(a);          // <- this de-sugars to 'a.update()'
                    //    'a' can be modified and is not a copy

let array = [ a ];

update(array[0]);   // <- 'array[0]' is an expression returning a calculated value,
                    //    a transient (i.e. a copy), so this statement has no effect
                    //    except waste time cloning 'a'

array[0].update();  // <- call in method-call style will update 'a'

Number of Parameters in Methods

Native Rust methods registered with an Engine take one additional parameter more than an equivalent method coded in script, where the object is accessed via the this pointer instead.

The following table illustrates the differences:

&mut is Efficient, Except for &mut ImmutableString

Using a &mut first parameter is highly encouraged when using types that are expensive to clone, even when the intention is not to mutate that argument, because it avoids cloning that argument value.

Even when a function is never intended to be a method – for example an operator, it is still sometimes beneficial to make it method-like (i.e. with a first &mut parameter) if the first parameter is not modified.

For types that are expensive to clone (remember, all function calls are passed cloned copies of argument values), this may result in a significant performance boost.

For primary types that are cheap to clone (e.g. those that implement Copy), including ImmutableString, this is not necessary.

// This is a type that is very expensive to clone.
#[derive(Debug, Clone)]
struct VeryComplexType { ... }

// Calculate some value by adding 'VeryComplexType' with an integer number.
fn do_add(obj: &VeryComplexType, offset: i64) -> i64 {
    ...
}

engine.register_type::<VeryComplexType>()
      .register_fn("+", add_pure /* or  add_method*/);

// Very expensive to call, as the 'VeryComplexType' is cloned before each call.
fn add_pure(obj: VeryComplexType, offset: i64) -> i64 {
    do_add(obj, offset)
}

// Efficient to call, as only a reference to the 'VeryComplexType' is passed.
fn add_method(obj: &mut VeryComplexType, offset: i64) -> i64 {
    do_add(obj, offset)
}

Data Race Considerations

Because methods always take a mutable reference as the first argument, even it the value is never changed, care must be taken when using shared values with methods.

Usually data races are not possible in Rhai because, for each function call, there is ever only one value that is mutable – the first argument of a method. All other arguments are cloned.

It is possible, however, to create a data race with a shared value, when the same value is captured in a closure and then used again as the object of calling that closure!

let x = 20;

x.is_shared() == false;             // 'x' is not shared, so no data race is possible

let f = |a| this += x + a;          // 'x' is captured in this closure

x.is_shared() == true;              // now 'x' is shared

x.call(f, 2);                       // <- error: data race detected on 'x'

Custom Type Property Getters and Setters

A custom type can also expose properties by registering get and/or set functions.

Properties can be accessed in a Rust-like syntax:

object . property

object . property = value ;

The Elvis operator can be used to short-circuit processing if the object itself is ():

// returns () if object is ()
object ?. property

// no action if object is ()
object ?. property = value ;

Property getter and setter functions are called behind the scene. They each take a &mut reference to the first parameter.

Getters and setters are disabled under the no_object feature.

Examples

#[derive(Debug, Clone)]
struct TestStruct {
    field: String
}

impl TestStruct {
    // Remember &mut must be used even for getters.
    fn get_field(&mut self) -> String {
        // Property getters are assumed to be PURE, meaning they are
        // not supposed to mutate any data.
        self.field.clone()
    }

    fn set_field(&mut self, new_val: String) {
        self.field = new_val;
    }

    fn new() -> Self {
        Self { field: "hello, world!".to_string() }
    }
}

let mut engine = Engine::new();

engine.register_type::<TestStruct>()
      .register_get_set("xyz", TestStruct::get_field, TestStruct::set_field)
      .register_fn("new_ts", TestStruct::new);

let result = engine.eval::<String>(
r#"
    let a = new_ts();
    a.xyz = "42";
    a.xyz
"#)?;

println!("Answer: {result}");                   // prints 42

Fallback to Indexer

If the getter/setter of a particular property is not defined, but an indexer is defined on the custom type with string index, then the corresponding indexer will be called with the name of the property as the index value.

In other words, indexers act as a fallback to property getters/setters.

a.foo           // if property getter for 'foo' doesn't exist...

a["foo"]        // an indexer (if any) is tried

Chaining Updates

It is possible to chain property accesses and/or indexing (via indexers) together to modify a particular property value at the end of the chain.

Rhai detects such modifications and updates the changed values all the way back up the chain.

In the end, the syntax works as expected by intuition, automatically and without special attention.

// Assume a deeply-nested object...
let root = get_new_container_object();

root.prop1.sub["hello"].list[0].value = 42;

// The above is equivalent to:

// First getting all the intermediate values...
let prop1_value = root.prop1;                   // via property getter
let sub_value = prop1_value.sub;                // via property getter
let sub_value_item = sub_value["hello"];        // via index getter
let list_value = sub_value_item.list;           // via property getter
let list_item = list_value[0];                  // via index getter

list_item.value = 42;       // modify property value deep down the chain

// Propagate the changes back up the chain...
list_value[0] = list_item;                      // via index setter
sub_value_item.list = list_value;               // via property setter
sub_value["hello"] = sub_value_item;            // via index setter
prop1_value.sub = sub_value;                    // via property setter
root.prop1 = prop1_value;                       // via property setter

// The below prints 42...
print(root.prop1.sub["hello"].list[0].value);

Custom Type Indexers

A custom type can also expose an indexer by registering an indexer function.

A custom type with an indexer function defined can use the bracket notation to get/set a property value at a particular index:

object [ index ]

object [ index ] = value ;

The Elvis notation is similar except that it returns () if the object itself is ().

// returns () if object is ()
object ?[ index ]

// no action if object is ()
object ?[ index ] = value ;

Like property getters/setters, indexers take a &mut reference to the first parameter.

They also take an additional parameter of any type that serves as the index within brackets.

Indexers are disabled when the no_index and no_object features are used together.

Cannot Override Arrays, BLOB’s, Object Maps, Strings and Integers

For efficiency reasons, indexers cannot be used to overload (i.e. override) built-in indexing operations for arrays, object maps, strings and integers (acting as bit-field operation).

The following types have built-in indexer implementations that are fast and efficient.

Examples

#[derive(Debug, Clone)]
struct TestStruct {
    fields: Vec<i64>
}

impl TestStruct {
    // Remember &mut must be used even for getters
    fn get_field(&mut self, index: String) -> i64 {
        self.fields[index.len()]
    }
    fn set_field(&mut self, index: String, value: i64) {
        self.fields[index.len()] = value
    }

    fn new() -> Self {
        Self { fields: vec![1, 2, 3, 4, 5] }
    }
}

let mut engine = Engine::new();

engine.register_type::<TestStruct>()
      .register_fn("new_ts", TestStruct::new)
      // Short-hand: .register_indexer_get_set(TestStruct::get_field, TestStruct::set_field);
      .register_indexer_get(TestStruct::get_field)
      .register_indexer_set(TestStruct::set_field);

let result = engine.eval::<i64>(
r#"
    let a = new_ts();
    a["xyz"] = 42;                  // these indexers use strings
    a["xyz"]                        // as the index type
"#)?;

println!("Answer: {result}");       // prints 42

Convention for Negative Index

If the indexer takes a signed integer as an index (e.g. the standard INT type), care should be taken to handle negative values passed as the index.

It is a standard API convention for Rhai to assume that an index position counts backwards from the end if it is negative.

-1 as an index usually refers to the last item, -2 the second to last item, and so on.

Therefore, negative index values go from -1 (last item) to -length (first item).

A typical implementation for negative index values is:

// The following assumes:
//   'index' is 'INT', 'items: usize' is the number of elements
let actual_index = if index < 0 {
    index.checked_abs().map_or(0, |n| items - (n as usize).min(items))
} else {
    index as usize
};

The end of a data type can be interpreted creatively. For example, in an integer used as a bit-field, the start is the least-significant-bit (LSB) while the end is the most-significant-bit (MSB).

Convention for Range Index

It is very common for ranges to be used as indexer parameters via the types std::ops::Range<INT> (exclusive) and std::ops::RangeInclusive<INT> (inclusive).

One complication is that two versions of the same indexer must be defined to support exclusive and inclusive ranges respectively.

use std::ops::{Range, RangeInclusive};

let mut engine = Engine::new();

engine
    /// Version of indexer that accepts an exclusive range
    .register_indexer_get_set(
        |obj: &mut TestStruct, range: Range<i64>| -> bool { ... },
        |obj: &mut TestStruct, range: Range<i64>, value: bool| { ... },
    )
    /// Version of indexer that accepts an inclusive range
    .register_indexer_get_set(
        |obj: &mut TestStruct, range: RangeInclusive<i64>| -> bool { ... },
        |obj: &mut TestStruct, range: RangeInclusive<i64>, value: bool| { ... },
    );

engine.run(
"
    let obj = new_ts();

    let x = obj[0..12];             // use exclusive range

    obj[0..=11] = !x;               // use inclusive range
")?;

Indexer as Property Access Fallback

An indexer taking a string index is a special case – it acts as a fallback to property getters/setters.

During a property access, if the appropriate property getter/setter is not defined, an indexer is called and passed the string name of the property.

This is also extremely useful as a short-hand for indexers, when the string keys conform to property name syntax.

// Assume 'obj' has an indexer defined with string parameters...

// Let's create a new key...
obj.hello_world = 42;

// The above is equivalent to this:
obj["hello_world"] = 42;

// You can write this...
let x = obj["hello_world"];

// but it is easier with this...
let x = obj.hello_world;

// Assume 'v' is a 'Float4'
let r = v.w;        // -> v.w
let r = v.xx;       // -> Float2::new(v.x, v.x)
let r = v.yxz;      // -> Float3::new(v.y, v.x, v.z)
let r = v.xxzw;     // -> Float4::new(v.x, v.x, v.z, v.w)
let r = v.yyzzxx;   // error: property 'yyzzxx' not found

Caveat – Reverse is NOT True

The reverse, however, is not true – when an indexer fails or doesn’t exist, the corresponding property getter/setter, if any, is not called.

type MyType = HashMap<String, i64>;

let mut engine = Engine::new();

// Define custom type, property getter and string indexers
engine.register_type::<MyType>()
      .register_fn("new_ts", || {
          let mut obj = MyType::new();
          obj.insert("foo".to_string(), 1);
          obj.insert("bar".to_string(), 42);
          obj.insert("baz".to_string(), 123);
          obj
      })
      // Property 'hello'
      .register_get("hello", |obj: &mut MyType| obj.len() as i64)
      // Index getter/setter
      .register_indexer_get(|obj: &mut MyType, prop: &str| -> Result<i64, Box<EvalAltResult>>
          obj.get(index).cloned().ok_or_else(|| "not found".into())
      ).register_indexer_set(|obj: &mut MyType, prop: &str, value: i64|
          obj.insert(prop.to_string(), value)
      );

engine.run("let ts = new_ts(); print(ts.foo);");
//                                   ^^^^^^
//                 Calls ts["foo"] - getter for 'foo' does not exist

engine.run("let ts = new_ts(); print(ts.bar);");
//                                   ^^^^^^
//                 Calls ts["bar"] - getter for 'bar' does not exist

engine.run("let ts = new_ts(); ts.baz = 999;");
//                             ^^^^^^^^^^^^
//                 Calls ts["baz"] = 999 - setter for 'baz' does not exist

engine.run(r#"let ts = new_ts(); print(ts["hello"]);"#);
//                                     ^^^^^^^^^^^
//                 Error: Property getter for 'hello' not a fallback for indexer

Custom Collection Types

A collection type holds a… well… collection of items. It can be homogeneous (all items are the same type) or heterogeneous (items are of different types, use Dynamic to hold).

Because their only purpose for existence is to hold a number of items, collection types commonly register the following methods.

Example

type MyBag = HashSet<MyItem>;

engine
    .register_type_with_name::<MyBag>("MyBag")
    .register_iterator::<MyBag>()
    .register_fn("new_bag", || MyBag::new())
    .register_fn("len", |col: &mut MyBag| col.len() as i64)
    .register_get("len", |col: &mut MyBag| col.len() as i64)
    .register_fn("clear", |col: &mut MyBag| col.clear())
    .register_fn("contains", |col: &mut MyBag, item: i64| col.contains(&item))
    .register_fn("add", |col: &mut MyBag, item: MyItem| col.insert(item))
    .register_fn("+=", |col: &mut MyBag, item: MyItem| col.insert(item))
    .register_fn("remove", |col: &mut MyBag, item: MyItem| col.remove(&item))
    .register_fn("-=", |col: &mut MyBag, item: MyItem| col.remove(&item))
    .register_fn("+", |mut col1: MyBag, col2: MyBag| {
        col1.extend(col2.into_iter());
        col1
    });

What About Indexers?

Many users are tempted to register indexers for custom collections. This essentially makes the original Rust type something similar to Vec<MyType>.

Rhai’s standard Array type is Vec<Dynamic> which already holds an ordered, iterable and indexable collection of dynamic items. Since Rhai has built-in support, manipulating arrays is fast.

In most circumstances, it is better to use Array instead of a custom type.

// Say you have a custom typed array...
let my_custom_array: Vec<MyType> = do_lots_of_calc(42);

// Convert it into a 'Dynamic' that holds an array
let value: Dynamic = my_custom_array.into();

// Use is anywhere in Rhai...
scope.push("my_custom_array", value);

engine
    // Raw function that returns a custom type
    .register_fn("do_lots_of_calc_raw", do_lots_of_calc)
    // Wrap function that return a custom typed array
    .register_fn("do_lots_of_calc", |seed: i64| -> Dynamic {
        let result = do_lots_of_calc(seed);     // Vec<MyType>
        result.into()                           // Array in Dynamic
    });

TL;DR

Disable Custom Types

The no_object feature disables support for custom types including:

• method-style function calls (e.g. obj.method()),

• object maps and the Map type,

• the register_get, register_set and register_get_set API’s for Engine

Printing for Custom Types

Provide These Functions

To use custom types for print and debug, or convert a custom type into a string, it is necessary that the following functions, at minimum, be registered (assuming the custom type is T: Display + Debug).

Also Consider These

The following functions are implemented using to_string or to_debug by default, but can be overloaded with custom versions.

Modules

Rhai allows organizing functionalities (functions, both Rust-based and scripted, and variables) into independent modules.

A module has the type rhai::Module and holds a collection of functions, variables, type iterators and sub-modules.

It may contain entirely Rust functions, or it may encapsulate a Rhai script together with all the functions and variables defined by that script.

Other scripts then load this module and use the functions and variables exported.

Alternatively, modules can be registered directly into an Engine and made available to scripts, either globally or under individual static module namespaces.

Modules can be disabled via the no_module feature.

Usage Patterns

Create a Module in Rust

The Easy Way – Plugin

By far the simplest way to create a module is via a plugin module which converts a normal Rust module into a Rhai module via procedural macros.

The Hard Way – Module API

Manually creating a module is possible via the Module public API, which is volatile and may change from time to time.

Create a Module from an AST

Module::eval_ast_as_new

A module can be created from a single script (or pre-compiled AST) containing global variables, functions and sub-modules via Module::eval_ast_as_new.

When given an AST, it is first evaluated (usually to import modules and set up global constants used by functions), then the following items are exposed as members of the new module:

• global variables and constants – all variables and constants exported via the export statement (those not exported remain hidden),

• functions not specifically marked private,

• imported modules that remain in the Scope at the end of a script run become sub-modules.

Examples

Don’t forget the export statement, otherwise there will be no variables exposed by the module other than non-private functions (unless that’s intentional).

use rhai::{Engine, Module};

let engine = Engine::new();

// Compile a script into an 'AST'
let ast = engine.compile(
r#"
    // Functions become module functions
    fn calc(x) {
        x + add_len(x, 1)       // functions within the same module
                                // can always cross-call each other!
    }
    fn add_len(x, y) {
        x + y.len
    }

    // Imported modules become sub-modules
    import "another module" as extra;

    // Variables defined at global level can become module variables
    const x = 123;
    let foo = 41;
    let hello;

    // Variable values become constant module variable values
    foo = calc(foo);
    hello = `hello, ${foo} worlds!`;

    // Finally, export the variables and modules
    export x as abc;            // aliased variable name
    export foo;
    export hello;
"#)?;

// Convert the 'AST' into a module, using the 'Engine' to evaluate it first
// A copy of the entire 'AST' is encapsulated into each function,
// allowing functions in the module script to cross-call each other.
let module = Module::eval_ast_as_new(Scope::new(), &ast, &engine)?;

// 'module' now contains:
//   - sub-module: 'extra'
//   - functions: 'calc', 'add_len'
//   - constants: 'abc' (renamed from 'x'), 'foo', 'hello'

Make a Module Available to Scripts

Use Case 1 – Make It Globally Available

Engine::register_global_module registers a shared module into the global namespace.

This is by far the easiest way to expose a module’s functionalities to Rhai.

use rhai::{Engine, Module, FuncRegistration};

let mut module = Module::new();             // new module

// Add new function.
FuncRegistration::new("inc")
    .with_params_info(&["x: i64", "i64"])
    .set_into_module(&mut module, |x: i64| x + 1);

// Use 'Module::set_var' to add variables.
module.set_var("MYSTIC_NUMBER", 41_i64);

// Register the module into the global namespace of the Engine.
let mut engine = Engine::new();
engine.register_global_module(module.into());

// No need to import module...
engine.eval::<i64>("inc(MYSTIC_NUMBER)")? == 42;

Equivalent to Engine::register_XXX

Registering a module via Engine::register_global_module is essentially the same as calling Engine::register_fn (or any of the Engine::register_XXX API) individually on each top-level function within that module.

// The above is essentially the same as:
let mut engine = Engine::new();

engine.register_fn("inc", |x: i64| x + 1);

engine.eval::<i64>("inc(41)")? == 42;       // no need to import module

Use Case 2 – Make It a Static Namespace

Engine::register_static_module registers a module and under a specific module namespace.

use rhai::{Engine, Module, FuncRegistration};

let mut module = Module::new();             // new module

// Add new function.
FuncRegistration::new("inc")
    .with_params_info(&["x: i64", "i64"])
    .set_into_module(&mut module, |x: i64| x + 1);

// Use 'Module::set_var' to add variables.
module.set_var("MYSTIC_NUMBER", 41_i64);

// Register the module into the Engine as the static module namespace path
// 'services::calc'
let mut engine = Engine::new();
engine.register_static_module("services::calc", module.into());

// Refer to the 'services::calc' module...
engine.eval::<i64>("services::calc::inc(services::calc::MYSTIC_NUMBER)")? == 42;

Expose functions to the global namespace

The Module API can optionally expose functions to the global namespace by setting the namespace parameter to FnNamespace::Global.

This way, getters/setters and indexers for custom types can work as expected.

use rhai::{Engine, Module, FuncRegistration, FnNamespace};

let mut module = Module::new();             // new module

// Add new function.
FuncRegistration::new("inc")
    .with_params_info(&["x: i64", "i64"])
    .with_namespace(FnNamespace::Global)    // <- global namespace
    .set_into_module(&mut module, |x: i64| x + 1);

// Use 'Module::set_var' to add variables.
module.set_var("MYSTIC_NUMBER", 41_i64);

// Register the module into the Engine as a static module namespace 'calc'
let mut engine = Engine::new();
engine.register_static_module("calc", module.into());

// 'inc' works when qualified by the namespace
engine.eval::<i64>("calc::inc(calc::MYSTIC_NUMBER)")? == 42;

// 'inc' also works without a namespace qualifier
// because it is exposed to the global namespace
engine.eval::<i64>("let x = calc::MYSTIC_NUMBER; x.inc()")? == 42;
engine.eval::<i64>("let x = calc::MYSTIC_NUMBER; inc(x)")? == 42;

Use Case 3 – Make It Dynamically Loadable

In order to dynamically load a custom module, there must be a module resolver which serves the module when loaded via import statements.

The easiest way is to use, for example, the StaticModuleResolver to hold such a custom module.

use rhai::{Engine, Scope, Module, FuncRegistration};
use rhai::module_resolvers::StaticModuleResolver;

let mut module = Module::new();             // new module

module.set_var("answer", 41_i64);           // variable 'answer' under module

FuncRegistration::new("inc")
    .with_params_info(&["x: i64"])
    .set_into_module(&mut module, |x: i64| x + 1);

// Create the module resolver
let mut resolver = StaticModuleResolver::new();

// Add the module into the module resolver under the name 'question'
// They module can then be accessed via: 'import "question" as q;'
resolver.insert("question", module);

// Set the module resolver into the 'Engine'
let mut engine = Engine::new();
engine.set_module_resolver(resolver);

// Use namespace-qualified variables
engine.eval::<i64>(
r#"
    import "question" as q;
    q::answer + 1
"#)? == 42;

// Call namespace-qualified functions
engine.eval::<i64>(
r#"
    import "question" as q;
    q::inc(q::answer)
"#)? == 42;

Module Resolvers

When encountering an import statement, Rhai attempts to resolve the module based on the path string.

Module Resolvers are service types that implement the ModuleResolver trait.

Set into Engine

An Engine’s module resolver is set via a call to Engine::set_module_resolver:

use rhai::module_resolvers::{DummyModuleResolver, StaticModuleResolver};

// Create a module resolver
let resolver = StaticModuleResolver::new();

// Register functions into 'resolver'...

// Use the module resolver
engine.set_module_resolver(resolver);

// Effectively disable 'import' statements by setting module resolver to
// the 'DummyModuleResolver' which acts as... well... a dummy.
engine.set_module_resolver(DummyModuleResolver::new());

Built-in Module Resolvers

There are a number of standard module resolvers built into Rhai, the default being the FileModuleResolver which simply loads a script file based on the path (with .rhai extension attached) and execute it to form a module.

Built-in module resolvers are grouped under the rhai::module_resolvers module.

DummyModuleResolver

This module resolver acts as a dummy and fails all module resolution calls.

FileModuleResolver

The default module resolution service, not available for no_std or WASM builds. Loads a script file (based off the current directory or a specified one) with .rhai extension.

Function Namespace

All functions in the global namespace, plus all those defined in the same module, are merged into a unified namespace.

All modules imported at global level via import statements become sub-modules, which are also available to functions defined within the same script file.

Base Directory

Relative paths are resolved relative to a root directory, which is usually the base directory.

The base directory can be set via FileModuleResolver::new_with_path or FileModuleResolver::set_base_path.

Custom Scope

The set_scope method adds an optional Scope which will be used to optimize module scripts.

Caching

By default, modules are also cached so a script file is only evaluated once, even when repeatedly imported.

Unix Shebangs

On Unix-like systems, the shebang (#!) is used at the very beginning of a script file to mark a script with an interpreter (for Rhai this would be rhai-run).

If a script file starts with #!, the entire first line is skipped. Because of this, Rhai scripts with shebangs at the beginning need no special processing.

#!/home/to/me/bin/rhai-run

// This is a Rhai script

let answer = 42;
print(`The answer is: ${answer}`);

Example

┌────────────────┐
│ my_module.rhai │
└────────────────┘

// This function overrides any in the main script.
private fn inner_message() { "hello! from module!" }

fn greet() {
    print(inner_message());     // call function in module script
}

fn greet_main() {
    print(main_message());      // call function not in module script
}


┌───────────┐
│ main.rhai │
└───────────┘

// This function is overridden by the module script.
fn inner_message() { "hi! from main!" }

// This function is found by the module script.
fn main_message() { "main here!" }

import "my_module" as m;

m::greet();                     // prints "hello! from module!"

m::greet_main();                // prints "main here!"

Simulate Virtual Functions

When calling a namespace-qualified function defined within a module, other functions defined within the same module override any similar-named functions (with the same number of parameters) defined in the global namespace.

This is to ensure that a module acts as a self-contained unit and functions defined in the calling script do not override module code.

In some situations, however, it is actually beneficial to do it in reverse: have module functions call functions defined in the calling script (i.e. in the global namespace) if they exist, and only call those defined in the module if none are found.

One such situation is the need to provide a default implementation to a simulated virtual function:

┌────────────────┐
│ my_module.rhai │
└────────────────┘

// Do not do this (it will override the main script):
// fn message() { "hello! from module!" }

// This function acts as the default implementation.
private fn default_message() { "hello! from module!" }

// This function depends on a 'virtual' function 'message'
// which is not defined in the module script.
fn greet() {
    if is_def_fn("message", 0) {    // 'is_def_fn' detects if 'message' is defined.
        print(message());
    } else {
        print(default_message());
    }
}


┌───────────┐
│ main.rhai │
└───────────┘

// The main script defines 'message' which is needed by the module script.
fn message() { "hi! from main!" }

import "my_module" as m;

m::greet();                         // prints "hi! from main!"


┌────────────┐
│ main2.rhai │
└────────────┘

// The main script does not define 'message' which is needed by the module script.

import "my_module" as m;

m::greet();                         // prints "hello! from module!"

StaticModuleResolver

Loads modules that are statically added.

Functions are searched in the global namespace by default.

use rhai::{Module, module_resolvers::StaticModuleResolver};

let module: Module = create_a_module();

let mut resolver = StaticModuleResolver::new();
resolver.insert("my_module", module);

engine.set_module_resolver(resolver);

ModuleResolversCollection

A collection of module resolvers.

Modules are resolved from each resolver in sequential order.

This is useful when multiple types of modules are needed simultaneously.

DylibModuleResolver

[dependencies]
rhai-dylib = { version = "0.1" }

Parallel to how the FileModuleResolver works, DylibModuleResolver loads external native Rust modules from compiled dynamic shared libraries (e.g. .so in Linux and .dll in Windows).

Therefore, FileModuleResolver loads Rhai script files while DylibModuleResolver loads native Rust shared libraries. It is very common to have the two work together.

Example

use rhai::{Engine, Module};
use rhai::module_resolvers::{FileModuleResolver, ModuleResolversCollection};
use rhai_dylib::module_resolvers::DylibModuleResolver;

let mut engine = Engine::new();

// Use a module resolvers collection
let mut resolvers = ModuleResolversCollection::new();

// First search for script files in the file system
resolvers += FileModuleResolver::new();

// Then search for shared-library plugins in the file system
resolvers += DylibModuleResolver::new();

// Set the module resolver into the engine
engine.set_module_resolver(resolvers);


┌─────────────┐
│ Rhai Script │
└─────────────┘

// If there is 'path/to/my_module.rhai', load it.
// Otherwise, check for 'path/to/my_module.so' on Linux
// ('path/to/my_module.dll' on Windows).
import "path/to/my_module" as m;

m::greet();

Implement a Custom Module Resolver

For many applications in which Rhai is embedded, it is necessary to customize the way that modules are resolved. For instance, modules may need to be loaded from script texts stored in a database, not in the file system.

A module resolver must implement the ModuleResolver trait, which contains only one required function: resolve.

When Rhai prepares to load a module, ModuleResolver::resolve is called with the name of the module path (i.e. the path specified in the import statement).

Example of a Custom Module Resolver

use rhai::{ModuleResolver, Module, Engine, EvalAltResult};

// Define a custom module resolver.
struct MyModuleResolver {}

// Implement the 'ModuleResolver' trait.
impl ModuleResolver for MyModuleResolver {
    // Only required function.
    fn resolve(
        &self,
        engine: &Engine,                        // reference to the current 'Engine'
        source_path: Option<&str>,              // path of the parent module
        path: &str,                             // the module path
        pos: Position,                          // position of the 'import' statement
    ) -> Result<Rc<Module>, Box<EvalAltResult>> {
        // Check module path.
        if is_valid_module_path(path) {
            // Load the custom module
            match load_secret_module(path) {
                Ok(my_module) => {
                    my_module.build_index();    // index it
                    Rc::new(my_module)          // make it shared
                },
                // Return 'EvalAltResult::ErrorInModule' upon loading error
                Err(err) => Err(EvalAltResult::ErrorInModule(path.into(), Box::new(err), pos).into())
            }
        } else {
            // Return 'EvalAltResult::ErrorModuleNotFound' if the path is invalid
            Err(EvalAltResult::ErrorModuleNotFound(path.into(), pos).into())
        }
    }
}

let mut engine = Engine::new();

// Set the custom module resolver into the 'Engine'.
engine.set_module_resolver(MyModuleResolver {});

engine.run(
r#"
    import "hello" as foo;  // this 'import' statement will call
                            // 'MyModuleResolver::resolve' with "hello" as 'path'
    foo:bar();
"#)?;

Advanced – ModuleResolver::resolve_ast

There is another function in the ModuleResolver trait, resolve_ast, which is a low-level API intended for advanced usage scenarios.

ModuleResolver::resolve_ast has a default implementation that simply returns None, which indicates that this API is not supported by the module resolver.

Any module resolver that serves modules based on Rhai scripts should implement ModuleResolver::resolve_ast. When called, the compiled AST of the script should be returned.

ModuleResolver::resolve_ast should not return an error if ModuleResolver::resolve will not. On the other hand, the same error should be returned if ModuleResolver::resolve will return one.

Compile to a Self-Contained AST

When a script imports external modules that may not be available later on, it is possible to eagerly pre-resolve these imports and embed them directly into a self-contained AST.

For instance, a system may periodically connect to a central source (e.g. a database) to load scripts and compile them to AST form. Afterwards, in order to conserve bandwidth (or due to other physical limitations), it is disconnected from the central source for self-contained operation.

Compile a script into a self-contained AST via Engine::compile_into_self_contained.

let mut engine = Engine::new();

// Compile script into self-contained AST using the current
// module resolver (default to `FileModuleResolver`) to pre-resolve
// 'import' statements.
let ast = engine.compile_into_self_contained(&mut scope, script)?;

// Make sure we can no longer resolve any module!
engine.set_module_resolver(DummyModuleResolver::new());

// The AST still evaluates fine, even with 'import' statements!
engine.run(&ast)?;

When such an AST is evaluated, import statements within are provided the pre-resolved modules without going through the normal module resolution process.

Only Static Paths

Engine::compile_into_self_contained only pre-resolves import statements in the script that are static, i.e. with a path that is a string literal.

// The following import is pre-resolved.
import "hello" as h;

if some_event() {
    // The following import is pre-resolved.
    import "hello" as h;
}

fn foo() {
    // The following import is pre-resolved.
    import "hello" as h;
}

// The following import is also pre-resolved because the expression
// is usually optimized into a single string during compilation.
import "he" + "llo" as h;

let module_name = "hello";

// The following import is NOT pre-resolved.
import module_name as h;

Plugin Modules

Rhai contains a robust plugin system that greatly simplifies registration of custom functionality.

Instead of using the complicated Engine::register_XXX or Module’s FuncRegistration API to register Rust functions, a plugin simplifies the work of creating and registering new functionality to an Engine.

Plugins are processed via a set of procedural macros under the rhai::plugin module. These allow registering Rust functions directly into an Engine instance, or adding Rust modules as packages.

Import Prelude

When using the plugins system, the entire rhai::plugin module must be imported as a prelude because code generated will need these imports.

use rhai::plugin::*;

#[export_module]

When applied to a Rust module, the #[export_module] attribute generates the necessary code and metadata to allow Rhai access to its public (i.e. marked pub) functions, constants, type aliases, and sub-modules.

This code is exactly what would need to be written by hand to achieve the same goal, and is custom fit to each exported item.

All pub functions become registered functions, constants become module constants, type aliases become custom types, and sub-modules become Rhai sub-modules.

use rhai::plugin::*;        // a "prelude" import for macros

// My custom type
pub struct TestStruct {
    pub value: i64
}

#[export_module]
mod my_module {
    // This type alias will register the friendly name 'ABC' for the
    // custom type 'TestStruct'.
    pub type ABC = TestStruct;

    // This constant will be registered as the constant variable 'MY_NUMBER'.
    // Ignored when registered as a global module.
    pub const MY_NUMBER: i64 = 42;

    // This function will be registered as 'greet'
    // but is only available with the 'greetings' feature.
    #[cfg(feature = "greetings")]
    pub fn greet(name: &str) -> String {
        format!("hello, {}!", name)
    }
    /// This function will be registered as 'get_num'.
    ///
    /// If this is a Rust doc-comment, then it is included in the metadata.
    pub fn get_num() -> i64 {
        mystic_number()
    }
    /// This function will be registered as 'create_abc'.
    pub fn create_abc(value: i64) -> ABC {
        ABC { value }
    }
    /// This function will be registered as the 'value' property of type 'ABC'.
    #[rhai_fn(get = "value")]
    pub fn get_value(ts: &mut ABC) -> i64 {
        ts.value
    }
    // This function will be registered as 'increment'.
    // It will also be exposed to the global namespace since 'global' is set.
    #[rhai_fn(global)]
    pub fn increment(ts: &mut ABC) {
        ts.value += 1;
    }
    // This function is not 'pub', so NOT registered.
    fn mystic_number() -> i64 {
        42
    }
    // This global function defines a custom operator '@'.
    #[rhai_fn(name = "@", global)]
    pub fn square_add(x: i64, y: i64) -> i64 {
        x * x + y * y
    }

    // Sub-modules are ignored when the module is registered globally.
    pub mod my_sub_module {
        // This function is ignored when registered globally.
        // Otherwise it is a valid registered function under a sub-module.
        pub fn get_info() -> String {
            "hello".to_string()
        }
    }

    // Sub-modules are commonly used to put feature gates on a group of
    // functions because feature gates cannot be put on function definitions.
    // This is currently a limitation of the plugin procedural macros.
    #[cfg(feature = "advanced_functions")]
    pub mod advanced {
        // This function is ignored when registered globally.
        // Otherwise it is a valid registered function under a sub-module
        // which only exists when the 'advanced_functions' feature is used.
        pub fn advanced_calc(input: i64) -> i64 {
            input * 2
        }
    }
}

Usage

The plugin module can be registered into an Engine as a normal module.

This is usually done via the exported_module! macro.

The macro combine_with_exported_module! can also be used to combine all the functions and variables into an existing module, flattening the namespace – i.e. all sub-modules are eliminated and their contents promoted to the top level. This is typical for developing custom packages.

Register with Engine::register_global_module

The simplest way to register the plugin module into an Engine is:

1. use the exported_module! macro to turn it into a normal Rhai module,
2. call Engine::register_global_module to register it

fn main() {
    let mut engine = Engine::new();

    // The macro call creates a Rhai module from the plugin module.
    let module = exported_module!(my_module);

    // A module can simply be registered into the global namespace.
    engine.register_global_module(module.into());

    // Define a custom operator '@' with precedence of 160 (i.e. between +|- and *|/).
    engine.register_custom_operator("@", 160).unwrap();
}

The functions contained within the module definition (i.e. greet, get_num, create_abc and increment, the value property getter), and the TestStruct custom type (with friendly name ABC) are automatically registered into the Engine when Engine::register_global_module is called.

let x = greet("world");
x == "hello, world!";

let x = greet(get_num().to_string());
x == "hello, 42!";

let x = get_num();
x == 42;

x @ x == 3528;      // custom operator

let abc = create_abc(x);

type_of(abc) == "ABC";

abc.value == 42;

abc.increment();

abc.value == 43;

Register with Engine::register_static_module

Another simple way to register the plugin module into an Engine is, again:

1. use the exported_module! macro to turn it into a normal Rhai module,
2. call Engine::register_static_module to register it under a particular module namespace

fn main() {
    let mut engine = Engine::new();

    // The macro call creates a Rhai module from the plugin module.
    let module = exported_module!(my_module);

    // A module can simply be registered as a static module namespace.
    engine.register_static_module("service", module.into());

    // Define a custom operator '@' with precedence of 160 (i.e. between +|- and *|/).
    engine.register_custom_operator("@", 160).unwrap();
}

The functions contained within the module definition (i.e. greet, get_num and increment), plus the constant MY_NUMBER, are automatically registered under the module namespace service:

let x = service::greet("world");
x == "hello, world!";

service::MY_NUMBER == 42;

let x = service::greet(service::get_num().to_string());
x == "hello, 42!";

let x = service::get_num();
x == 42;

x @ x == 3528;      // custom operator

let abc = service::create_abc(x);

type_of(abc) == "ABC";

abc.value == 42;

service::increment(abc);

abc.value == 43;

Use #[rhai_fn(global)]

All functions (usually methods) defined in the module and marked with #[rhai_fn(global)], all type iterators and all custom types are automatically exposed to the global namespace, so iteration, getters/setters and indexers for custom types can work as expected.

Therefore, in the example above, the increment method (defined with #[rhai_fn(global)]) works fine when called in method-call style:

let x = 42;
x.increment();
x == 43;

Load Dynamically

Using this directly as a dynamically-loadable Rhai module is almost the same, except that a module resolver must be used to serve the module, and the module is loaded via import statements.

Combine into Custom Package

Finally, the plugin module can also be used to develop a custom package, using combine_with_exported_module! which automatically flattens the module namespace so that all functions in sub-modules are promoted to the top level namespace, all sub-modules are eliminated, and all variables are ignored.

#[export_module]
mod my_module {
    // Always available
    pub fn func0() {}

    // The following functions are only available under 'foo'.
    // Use a sub-module for convenience, since all functions underneath
    // will be flattened into the namespace.
    #[cfg(feature = "foo")]
    pub mod group_foo {
        pub fn func1() {}
        pub fn func2() {}
        pub fn func3() {}
    }

    // The following functions are only available under 'bar'
    #[cfg(feature = "bar")]
    pub mod group_bar {
        pub fn func4() {}
        pub fn func5() {}
        pub fn func6() {}
    }
}

// The above is equivalent to:
#[export_module]
mod my_module_alternate {
    pub fn func0() {}

    #[cfg(feature = "foo")]
    pub fn func1() {}
    #[cfg(feature = "foo")]
    pub fn func2() {}
    #[cfg(feature = "foo")]
    pub fn func3() {}

    #[cfg(feature = "bar")]
    pub fn func4() {}
    #[cfg(feature = "bar")]
    pub fn func5() {}
    #[cfg(feature = "bar")]
    pub fn func6() {}
}

// Registered functions:
//   func0 - always available
//   func1, func2, func3 - available under 'foo'
//   func4, func5, func6 - available under 'bar'
//   func0, func1, func2, func3, func4, func5, func6 - available under 'foo' and 'bar'
combine_with_exported_module!(module, "my_module_ID", my_module);

Functions Overloading and Operators

Operators and overloaded functions can be specified via applying the #[rhai_fn(name = "...")] attribute to individual functions.

The text string given as the name parameter to #[rhai_fn] is used to register the function with the Engine, disregarding the actual name of the function.

With #[rhai_fn(name = "...")], multiple functions may be registered under the same name in Rhai, so long as they have different parameters.

use rhai::plugin::*;        // a "prelude" import for macros

#[export_module]
mod my_module {
    // This is the '+' operator for 'TestStruct'.
    #[rhai_fn(name = "+")]
    pub fn add(obj: &mut TestStruct, value: i64) {
        obj.prop += value;
    }
    // This function is 'calc (i64)'.
    pub fn calc(num: i64) -> i64 {
        ...
    }
    // This function is 'calc (i64, bool)'.
    #[rhai_fn(name = "calc")]
    pub fn calc_with_option(num: i64, option: bool) -> i64 {
        ...
    }
}

Getters, Setters and Indexers

Functions can be marked as getters/setters and indexers for custom types via the #[rhai_fn] attribute, which is applied on a function level.

use rhai::plugin::*;        // a "prelude" import for macros

#[export_module]
mod my_module {
    // This is a normal function 'greet'.
    pub fn greet(name: &str) -> String {
        format!("hello, {}!", name)
    }
    // This is a getter for 'TestStruct::prop'.
    #[rhai_fn(get = "prop", pure)]
    pub fn get_prop(obj: &mut TestStruct) -> i64 {
        obj.prop
    }
    // This is a setter for 'TestStruct::prop'.
    #[rhai_fn(set = "prop")]
    pub fn set_prop(obj: &mut TestStruct, value: i64) {
        obj.prop = value;
    }
    // This is an index getter for 'TestStruct'.
    #[rhai_fn(index_get)]
    pub fn get_index(obj: &mut TestStruct, index: i64) -> bool {
        obj.list[index]
    }
    // This is an index setter for 'TestStruct'.
    #[rhai_fn(index_set)]
    pub fn set_index(obj: &mut TestStruct, index: i64, state: bool) {
        obj.list[index] = state;
    }
}

Multiple Registrations

Parameters to the #[rhai_fn(...)] attribute can be applied multiple times, separated by commas.

use rhai::plugin::*;        // a "prelude" import for macros

#[export_module]
mod my_module {
    // This function can be called in five ways
    #[rhai_fn(name = "get_prop_value", name = "prop", name = "+", set = "prop", index_get)]
    pub fn prop_function(obj: &mut TestStruct, index: i64) -> i64 {
        obj.prop[index]
    }
}

The above function can be called in five ways:

Pure Functions

Apply the #[rhai_fn(pure)] attribute on a method function (i.e. one taking a &mut first parameter) to mark it as pure – i.e. it does not modify the &mut parameter.

This is often done to avoid expensive cloning for methods or property getters that return information about a custom type and does not modify it.

use rhai::plugin::*;        // a "prelude" import for macros

#[export_module]
mod my_module {
    // This function can be passed a constant
    #[rhai_fn(name = "add1", pure)]
    pub fn add_scaled(array: &mut rhai::Array, x: i64) -> i64 {
        array.iter().map(|v| v.as_int().unwrap()).fold(0, |(r, v)| r += v * x)
    }
    // This function CANNOT be passed a constant
    #[rhai_fn(name = "add2")]
    pub fn add_scaled2(array: &mut rhai::Array, x: i64) -> i64 {
        array.iter().map(|v| v.as_int().unwrap()).fold(0, |(r, v)| r += v * x)
    }
    // This getter can be applied to a constant
    #[rhai_fn(get = "first1", pure)]
    pub fn get_first(array: &mut rhai::Array) -> i64 {
        array[0]
    }
    // This getter CANNOT be applied to a constant
    #[rhai_fn(get = "first2")]
    pub fn get_first2(array: &mut rhai::Array) -> i64 {
        array[0]
    }
    // The following is a syntax error because a setter is SUPPOSED to
    // mutate the object.  Therefore the 'pure' attribute cannot be used.
    #[rhai_fn(get = "values", pure)]
    pub fn set_values(array: &mut rhai::Array, value: i64) {
        // ...
    }
    // The following is a volatile function which returns different values
    // for each call.
    #[rhai_fn(volatile)]
    pub fn get_current_time() -> String {
        // ...
    }
}

When applied to a Rhai script:

// Constant
const VECTOR = [1, 2, 3, 4, 5, 6, 7];

let r = VECTOR.add1(2);     // ok!

let r = VECTOR.add2(2);     // runtime error: constant modified

let r = VECTOR.first1;      // ok!

let r = VECTOR.first2;      // runtime error: constant modified

Volatile Functions

A volatile function is one that does not guarantee the same result for the same input(s).

Most functions are non-volatile, meaning that they always generate the same result when called with the same arguments.

Common examples of volatile functions are:

• a function that returns the current date and/or time

• a function that looks up the current value of a variable in the environment

• a function that reads from a file (which depends on the content of the file at the time of read)

• a function that reads from a database or a cache (which depends on the content at the time of read)

When using Full Optimization, functions with constant arguments are called eagerly at compile time. However, volatile functions are never called.

Plugin functions are assumed to be non-volatile by default, unless marked with #[rhai_fn(volatile)].

Fallible Functions

To register fallible functions (i.e. functions that may return errors), apply the #[rhai_fn(return_raw)] attribute on functions that return Result<T, Box<EvalAltResult>> where T is any clonable type.

use rhai::plugin::*;        // a "prelude" import for macros

#[export_module]
mod my_module {
    /// This overloads the '/' operator for i64.
    #[rhai_fn(name = "/", return_raw)]
    pub fn double_and_divide(x: i64, y: i64) -> Result<i64, Box<EvalAltResult>> {
        if y == 0 {
            Err("Division by zero!".into())
        } else {
            Ok((x * 2) / y)
        }
    }
}

#[export_module] Parameters

Parameters can be applied to the #[export_module] attribute to override its default behavior.

Inner Attributes

Inner attributes can be applied to the inner items of a module to tweak the export process.

Parameters should be set on inner attributes to specify the desired behavior.

Packages

The built-in library of Rhai is provided as various packages that can be turned into shared modules, which in turn can be registered into the global namespace of an Engine via Engine::register_global_module.

Packages reside under rhai::packages::* and the trait rhai::packages::Package must be loaded in order for packages to be used.

Share a Package Among Multiple Engine’s

Engine::register_global_module and Engine::register_static_module both require shared modules.

Once a package is created (e.g. via Package::new), it can be registered into multiple instances of Engine, even across threads (under the sync feature).

use rhai::Engine;
use rhai::packages::Package         // load the 'Package' trait to use packages
use rhai::packages::CorePackage;    // the 'core' package contains basic functionalities (e.g. arithmetic)

// Create a package - can be shared among multiple 'Engine' instances
let package = CorePackage::new();

let mut engines_collection: Vec<Engine> = Vec::new();

// Create 100 'raw' Engines
for _ in 0..100 {
    let mut engine = Engine::new_raw();

    // Register the package into the global namespace.
    package.register_into_engine(&mut engine);

    engines_collection.push(engine);
}

Built-In Packages

Engine::new creates an Engine with the StandardPackage loaded.

Engine::new_raw creates an Engine with no package loaded.

CorePackage

If only minimal functionalities are required, register the CorePackage instead.

use rhai::Engine;
use rhai::packages::{Package, CorePackage};

let mut engine = Engine::new_raw();
let package = CorePackage::new();

// Register the package into the 'Engine'.
package.register_into_engine(&mut engine);

Create a Custom Package

The macro def_package! can be used to create a custom package.

A custom package can aggregate many other packages into a single self-contained unit. More functions can be added on top of others.

Custom packages are extremely useful when multiple raw Engine instances must be created such that they all share the same set of functions.

def_package!

def_package! {
    /// Package description doc-comment
    pub name(variable) {
                        :
        // package init code block
                        :
    }

    // Multiple packages can be defined at the same time,
    // possibly with base packages and/or code to setup an Engine.

    /// Package description doc-comment
    pub(crate) name(variable) : base_package_1, base_package_2, ... {
                        :
        // package init code block
                        :
    } |> |engine| {
                        :
        // engine setup code block
                        :
    }

    /// A private package description doc-comment
    name(variable) {
                        :
        // private package init code block
                        :
    }

    :
}

where:

Examples

// Import necessary types and traits.
use rhai::def_package;      // 'def_package!' macro
use rhai::packages::{ArithmeticPackage, BasicArrayPackage, BasicMapPackage, LogicPackage};
use rhai::{FuncRegistration, CustomType, TypeBuilder};

/// This is a custom type.
#[derive(Clone, CustomType)]
struct TestStruct {
    foo: String,
    bar: i64,
    baz: bool
}

def_package! {
    /// My own personal super package
    // Aggregate other base packages (if any) simply by listing them after a colon.
    pub MyPackage(module) : ArithmeticPackage, LogicPackage, BasicArrayPackage, BasicMapPackage
    {
        // Register additional Rust function.
        FuncRegistration::new("get_bar_value")
            .with_params_info(&["s: &mut TestStruct", "i64"])
            .set_into_module(module, |s: &mut TestStruct| s.bar);

        // Register a function for use as a custom operator.
        FuncRegistration::new("@")
            .with_namespace(FnNamespace::Global)    // <- make it available globally.
            .set_into_module(module, |x: i64, y: i64| x * x + y * y);
    } |> |engine| {
        // This optional block performs tasks on an 'Engine' instance,
        // e.g. register custom types and/or custom operators/syntax.

        // Register custom type.
        engine.build_type::<TestStruct>();

        // Define a custom operator '@' with precedence of 160
        // (i.e. between +|- and *|/).
        engine.register_custom_operator("@", 160).unwrap();
    }
}

def_package! {
    // 'BasicArrayPackage' is used only under 'arrays' feature.
    pub MyPackage(module) :
            ArithmeticPackage,
            LogicPackage,
            #[cfg(feature = "arrays")]
            BasicArrayPackage
    {
        ...
    }
}

def_package! {
    pub MyPackage(module) {
            :
            :
    } |> |engine| {
        // Call methods on 'engine'
    }
}

Create a Custom Package from a Plugin Module

By far the easiest way to create a custom package is to call plugin::combine_with_exported_module! from within def_package! which simply merges in all the functions defined within a plugin module.

Due to specific requirements of a package, plugin::combine_with_exported_module! flattens all sub-modules (i.e. all functions and type iterators defined within sub-modules are pulled up to the top level instead) and so there will not be any sub-modules added to the package.

Variables in the plugin module are ignored.

// Import necessary types and traits.
use rhai::def_package;
use rhai::packages::{ArithmeticPackage, BasicArrayPackage, BasicMapPackage, LogicPackage};
use rhai::plugin::*;

// Define plugin module.
#[export_module]
mod my_plugin_module {
    // Custom type.
    pub type ABC = TestStruct;

    // Public constant.
    pub const MY_NUMBER: i64 = 42;

    // Public function.
    pub fn greet(name: &str) -> String {
        format!("hello, {}!", name)
    }

    // Non-public functions are by default not exported.
    fn get_private_num() -> i64 {
        42
    }

    // Public function.
    pub fn get_num() -> i64 {
        get_private_num()
    }

    // Custom operator.
    #[rhai_fn(name = "@")]
    pub fn square_add(x: i64, y: i64) -> i64 {
        x * x + y * y
    }

    // A sub-module.  If using 'combine_with_exported_module!', however,
    // it will be flattened and all functions registered at the top level.
    //
    // Because of this flattening, sub-modules are very convenient for
    // putting feature gates onto large groups of functions.
    #[cfg(feature = "sub-num-feature")]
    pub mod my_sub_module {
        // Only available under 'sub-num-feature'.
        pub fn get_sub_num() -> i64 {
            0
        }
    }
}

def_package! {
    /// My own personal super package
    // Aggregate other base packages (if any) simply by listing them after a colon.
    pub MyPackage(module) : ArithmeticPackage, LogicPackage, BasicArrayPackage, BasicMapPackage
    {
        // Merge all registered functions and constants from the plugin module
        // into the custom package.
        //
        // The sub-module 'my_sub_module' is flattened and its functions
        // registered at the top level.
        //
        // The text string name in the second parameter can be anything
        // and is reserved for future use; it is recommended to be an
        // ID string that uniquely identifies the plugin module.
        //
        // The constant variable, 'MY_NUMBER', is ignored.
        //
        // This call ends up registering three functions at the top level of
        // the package:
        // 1) 'greet'
        // 2) 'get_num'
        // 3) 'get_sub_num' (flattened from 'my_sub_module')
        //
        combine_with_exported_module!(module, "my-mod", my_plugin_module));
    } |> |engine| {
        // This optional block is used to set up an 'Engine' during registration.

        // Define a custom operator '@' with precedence of 160
        // (i.e. between +|- and *|/).
        engine.register_custom_operator("@", 160).unwrap();
    }
}

Create a Custom Package as an Independent Crate

Creating a custom package as an independent crate allows it to be shared by multiple projects.

Implementation

Cargo.toml:

[package]
name = "my-package"     # 'my-package' crate

[dependencies]
rhai = "1.20.0"    # assuming 1.20.0 is the latest version

lib.rs:

use rhai::def_package;
use rhai::plugin::*;

// This is a plugin module
#[export_module]
mod my_module {
    // Constants are ignored when used as a package
    pub const MY_NUMBER: i64 = 42;

    pub fn greet(name: &str) -> String {
        format!("hello, {}!", name)
    }
    pub fn get_num() -> i64 {
        42
    }

    // This is a sub-module, but if using combine_with_exported_module!, it will
    // be flattened and all functions registered at the top level.
    pub mod my_sub_module {
        pub fn get_sub_num() -> i64 {
            0
        }
    }
}

// Define the package 'MyPackage' which is exported for the crate.
def_package! {
    /// My own personal super package in a new crate!
    pub MyPackage(module) {
        combine_with_exported_module!(module, "my-functions", my_module);
    }
}

External Packages

Following are external packages that can be used with Rhai for additional functionalities.

rhai-rand: Random Number Generation, Shuffling and Sampling

rhai-rand is an independent Rhai package that provides:

• random number generation using the rand crate
• array shuffling and sampling

On crates.io: rhai-rand

On GitHub: rhaiscript/rhai-rand

Package name: RandomPackage

Dependency

Cargo.toml:

[dependencies]
rhai = "1.20.0"
rhai-rand = "0.1"       # use rhai-rand crate

Load Package into Engine

use rhai::Engine;
use rhai::packages::Package;    // needed for 'Package' trait
use rhai_rand::RandomPackage;

let mut engine = Engine::new();

// Create new 'RandomPackage' instance
let random = RandomPackage::new();

// Load the package into the `Engine`
random.register_into_engine(&mut engine);

Features

[dependencies]
# Rhai is set for 'no_float', meaning no floating-point support
rhai = { version="1.20.0", features = ["no_float"] }

# Use 'default-features = false' to clear defaults, then only add 'array'
rhai-rand = { version="0.1", default-features = false, features = ["array"] }

rhai-sci: Functions for Scientific Computing

rhai-sci is an independent Rhai package that provides functions useful for scientific computing, inspired by languages like MATLAB, Octave, and R.

On crates.io: rhai-sci

On GitHub: rhaiscript/rhai-sci

Package name: SciPackage

Dependency

Cargo.toml:

[dependencies]
rhai = "1.20.0"
rhai-sci = "0.1"       # use rhai-sci crate

Features

Load Package into Engine

use rhai::Engine;
use rhai::packages::Package;    // needed for 'Package' trait
use rhai_sci::SciPackage;

let mut engine = Engine::new();

// Create new 'SciPackage' instance
let sci = SciPackage::new();

// Load the package into the [`Engine`]
sci.register_into_engine(&mut engine);

rhai-ml: Functions for AI and Machine Learning

rhai-ml is an independent Rhai package that provides functions useful for artificial intelligence and machine learning.