reorganize module

_archive/rhai_engine/rhaibook/rust/packages/index.md

@@ -0,0 +1,60 @@
+Packages
+========
+
+{{#include ../../links.md}}
+
+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.
+
+```admonish question.small "Trivia: Packages _are_ modules!"
+
+Internally, a _package_ is a [module], with some conveniences to make it easier to define and use as
+a standard _library_ for an [`Engine`].
+
+Packages typically contain Rust functions that are callable within a Rhai script.
+All _top-level_ functions in a package are available under the _global namespace_
+(i.e. they're available without namespace qualifiers).
+
+Sub-[modules] and [variables] are ignored in packages.
+```
+
+
+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).
+
+```admonish tip.small "Tip: Sharing package"
+
+A package only has to be created _once_ and essentially shared among multiple [`Engine`] instances.
+
+This is particularly useful when spawning large number of [raw `Engine`'s][raw `Engine`].
+```
+
+```rust
+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);
+}
+```