rhai/doc/src/rust/packages/index.md

Packages

{{#include ../../links.md}}

Standard built-in Rhai features are provided in various packages that can be loaded via a call to Engine::load_package.

Packages reside under rhai::packages::* and the trait rhai::packages::Package must be loaded in order for packages to be used.

Packages typically contain Rust functions that are callable within a Rhai script. All functions registered in a package is loaded under the global namespace (i.e. they're available without module qualifiers).

Once a package is created (e.g. via Package::new), it can be shared (via Package::get) among multiple instances of [Engine], even across threads (under [sync]). Therefore, a package only has to be created once.

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)

let mut engine = Engine::new_raw(); // create a 'raw' Engine
let package = CorePackage::new();   // create a package - can be shared among multiple `Engine` instances

engine.load_package(package.get()); // load the package manually. 'get' returns a reference to the shared package

Difference Between a Package and a Module

Packages are internally implemented as [modules], so they share a lot of behavior and characteristics.

The main difference is that a package loads under the global namespace, while a module loads under its own namespace alias specified in an [import] statement (see also [modules]).

A package is static (i.e. pre-loaded into an [Engine]), while a module is dynamic (i.e. loaded with the import statement).

Sub-modules in a package are flattened, meaning that functions from them must be pulled up to the root level. In other words, there can be no sub-modules in a package, and everything should reside in one, flat namespace.

Only functions matter for a package. Constant variables registered in a package are ignored.

Load a Module as a Package

Stand-alone [modules] can be loaded directly into an [Engine] as a package via the same Engine::load_package API.

let mut module = Module::new();
        :
    // add functions into module
        :

engine.load_package(module);

[Modules], however, are not shared, so use a [custom package] if it must be shared among multiple instances of [Engine].