The Rhai Book
User’s Guide
Introduction
❱
Features of Rhai
What Rhai Isn't
Benchmarks
Supported Targets and Builds
Dependencies
Licensing
Related Resources
Getting Started
❱
Online Playground
Install the Rhai Crate
Optional Features
Packaged Utilities
The Scripting Engine
❱
“Hello, Rhai”
Compile to AST
Raw Engine
❱
Built-in Operators
Scope – Maintaining State
Expressions Only
Options
Examples
❱
Rust
Scripts
Special Builds
❱
Performance
Minimal
no-std
WebAssembly (WASM)
Rust Integration
Introduction
Traits
Register a Rust Function
❱
Function Overloading
Generic Functions
String Parameters
Dynamic Parameters
Dynamic Return Value
Fallible Functions
NativeCallContext
❱
Restore NativeCallContext
Override a Built-in Function
Call a Rhai Function from Rust
❱
Create a Rust Closure from a Rhai Function
Operator Overloading
Working with Any Rust Type
❱
Auto-Generate API
Custom Type Builder
Manually Register Custom Type
Methods
❱
Call Method as Function
Property Getters and Setters
Indexers
❱
Fallback to Properties
Collection Types
Disable Custom Types
Printing Custom Types
Modules
❱
Create in Rust
Create from AST
Use a Module
Module Resolvers
❱
Built-in Module Resolvers
❱
DummyModuleResolver
FileModuleResolver
StaticModuleResolver
ModuleResolversCollection
DylibModuleResolver (external)
Custom Module Resolvers
Self-Contained AST
Plugin Modules
Packages
❱
Built-in Packages
Create Custom Packages
Create Packages as Crates
External Packages
❱
Random Number Generation, Shuffling and Sampling
Scientific Computing
AI and Machine Learning
Filesystem Access
Working with Urls
Scripting Language
Comments
❱
Doc-Comments
Values and Types
❱
Dynamic Values
❱
type_of()
Interop with Rust
Value Tag
Serialization/Deserialization with serde
Numbers
❱
Operators
Standard Functions
Value Conversions
Ranges
Bit-Fields
Strings and Characters
❱
String Interpolation
ImmutableString
Standard Functions and Operators
Strings Interner
Arrays
❱
BLOB's (Byte Arrays)
Out-of-Bounds Index
Object Maps
❱
Parse from JSON
Special Support for OOP
Non-Existent Property
Timestamps
Keywords
Statements
❱
Statement Expression
Variables
❱
Variable Shadowing
Strict Variables Mode
Variable Definition Filter
Variable Resolver
Constants
❱
Automatic Global Module
Assignments
Compound Assignments
Logic Operators
In Operator
If Statement
Switch Statement
❱
Switch Expression
While Loop
Do Loop
Loop Statement
For Loop
❱
Standard Iterable Types
Make a Custom Type Iterable
Return Value
Throw Exception on Error
Catch Exceptions
Functions
❱
Method Calls
Overloading
Namespaces
Function Pointers
❱
Currying
Anonymous Functions
Closures
Metadata
❱
Get Scripted Functions Metadata in Rhai
Get Scripted Functions Metadata from AST
Get Native Function Signatures
Export All Functions Metadata to JSON
Generate Definition Files for Language Server
Print and Debug
Modules
❱
Export Variables, Functions and Sub-Modules from Script
Import Modules
Eval Function
Safety and Protection
Introduction
Sand-Boxing
Limiting Run Time
Limiting Memory Usage
Limiting Stack Usage
Built-in Safety Limits
❱
Maximum Length of Strings
Maximum Size of Arrays
Maximum Size of Object Maps
Maximum Number of Operations
Maximum Number of Variables
Maximum Number of Functions
Maximum Number of Modules
Maximum Call Stack Depth
Maximum Expression Depth
Turn Off Safety Checks
Script Optimization
Introduction
Optimization Passes
❱
Dead Code Elimination
Constants Propagation
Compound Assignment Rewrite
Eager Operator Evaluation
Eager Function Evaluation
❱
Side-Effect Considerations
Volatility Considerations
Subtle Semantic Changes
Re-Optimize an AST
Advanced Topics
Manage AST's
Low-Level API to Register Functions
Evaluation Context
Call Function Within Caller's Scope
Use Rhai in Dynamic Libraries
Use Rhai as a DSL
❱
Remap Tokens During Parsing
Disable Keywords and/or Operators
Disable Looping
Custom Operators
❱
Operator Precedence
Extend with Custom Syntax
❱
Custom Syntax Parsers
Debugging Interface
❱
Debugger
❱
State
Call Stack
Break-Points
Debugging Server
Usage Patterns
Object-Oriented Programming (OOP)
Scriptable Event Handler with State
❱
Main Style
JS Style
Map Style
Control Layer Over Rust Backend
Singleton Command Object
Loadable Configuration
Multi-Layered Functions
Hot Reloading
Builder Pattern / Fluent API
Dynamic Constants Provider
Global Constants
Mutable Global State
Working with Rust Enums
Simulate Macros to Simplify Scripts
One Engine Instance Per Call
Multi-Threaded Synchronization
Blocking/Async Function Calls
External References (Unsafe)
Static Hashing
Serialize an AST
Domain-Specific Tools
Multiple Instantiation
Language Reference
Introduction
Comments
Value Types
❱
Dynamic Values
❱
type_of()
Value Tag
Numbers
❱
Operators
Standard Functions
Value Conversions
Ranges
Bit-Fields
Strings and Characters
❱
Standard Functions and Operators
Arrays
BLOB's (Byte Arrays)
Object Maps
Timestamps
Keywords
Statements
Variables
Constants
Assignments
❱
Compound Assignments
Operators
Indexing
Properties
Methods
If Statement
Switch Statement
While Loop
Do Loop
Infinite Loop
For Loop
Return Value
Throw Exception on Error
❱
Catch Exceptions
Functions
❱
Method Calls
Overloading
Function Pointers
Closures
Metadata
Print and Debug
Modules
❱
Export Variables, Functions and Sub-Modules from Script
Import Modules
Eval Function
Appendix
External Tools
❱
Online Playground
Language Server
rhai-doc
Dynamic Loadable Libraries
Generate MarkDown/MDX API Documentation
Keywords
Operators and Symbols
Literals
Light
Rust
Coal
Navy
Ayu
Rhai - Embedded Scripting for Rust
Getting Started
This section shows how to install the Rhai crate into a Rust application.