# postscriptum — Quickstart
`postscriptum` is a **multi-interpreted-language scripting engine for Rust**.
It lets you embed scripts in your application, keep interpreter state between
evaluations, and expose your own Rust functions callable from the scripts —
on **native** and **WASM** targets, with no Bevy dependency.
This guide walks through the core concepts and shows the patterns used by the
`pyopyo` demo app. For short, runnable programs see the [`examples/`](examples/)
directory (`basic_rhai`, `basic_python`, `thread_safe`).
---
## 1. The concept
Everything revolves around a few pieces:
- **`ScriptEngine`** — the core trait: `fn eval(&mut self, &str) -> Result<String>`.
Each backend implements it and is **stateful**: variables set by one script
persist across later evaluations of the same engine.
- **`EngineType`** — selects the backend: `Rhai | Python`.
- **`FunctionBundle`** — registers Rust functions so scripts can call them
(`add_rhai_fn0..4`, `add_python_fn0..4`).
- **`ThreadSafeEngine`** — a `Clone` wrapper around
`Arc<Mutex<Box<dyn ScriptEngine>>>` that makes engines shareable across
threads (the Python engine is not `Send` by itself).
| **Rhai** | rhai (pure Rust) | rhai (pure Rust) |
| **Python** | pyo3 | Pyodide (JS interop) |
---
## 2. Add the dependency
```bash
cargo add postscriptum
# or, from a workspace/path:
# postscriptum = { path = "postscriptum" }
```
---
## 3. Create an engine and evaluate a script
```rust
use postscriptum::{EngineType, get_engine};
let mut engine = get_engine(EngineType::Rhai);
let result = engine.eval("40 + 2")?;
assert_eq!(result, "42");
```
Python works the same way with `EngineType::Python`.
---
## 4. Expose Rust functions to scripts
Build a `FunctionBundle` for the language you want, add functions by arity, and
create an engine with the bundle registered:
```rust
use postscriptum::{EngineType, FunctionBundle, get_engine_with_bundle};
let mut bundle = FunctionBundle::new(EngineType::Rhai);
bundle.add_rhai_fn0::<fn() -> i64, i64>("get_answer", || 42);
let mut engine = get_engine_with_bundle(EngineType::Rhai, &bundle);
assert_eq!(engine.eval("double(get_answer())")?, "84");
```
For Python, use the matching `add_python_fn0..4` methods and `EngineType::Python`.
### Available arity adders
| 0 | `add_rhai_fn0` | `add_python_fn0` |
| 1 | `add_rhai_fn1` | `add_python_fn1` |
| 2 | `add_rhai_fn2` | `add_python_fn2` |
| 3 | `add_rhai_fn3` | `add_python_fn3` |
| 4 | `add_rhai_fn4` | `add_python_fn4` |
### The functions the `pyopyo` demo registers
The demo app's `StandardFunctionBundle` registers the same set on both engines
and documents them in its UI. Use them as a template for your own:
| `get_pi()` | `() -> f64` | `std::f64::consts::PI` |
| `get_answer()` | `() -> i64` | Always `42` 🙂 |
| `square(x)` | `(i64) -> i64` | `x * x` |
| `double(x)` | `(i64) -> i64` | `x * 2` |
| `plusone(x)` | `(i64) -> i64` | `x + 1` |
| `multiply(a, b)` | `(i64, i64) -> i64` | `a * b` |
| `power(base, exp)`| `(f64, f64) -> f64` | `base.powf(exp)` |
Registering them looks like this (native, Python side):
```rust
let mut bundle = FunctionBundle::new_python();
bundle.add_python_fn0::<fn() -> f64, f64>("get_pi", || std::f64::consts::PI);
"power",
|base: f64, exp: f64| base.powf(exp),
);
```
---
## 5. Scripts keep state between runs
An engine remembers its variables across evaluations. This is how the app runs
a counter: seed the value, then increment it per call:
```rust
let mut engine = get_engine(EngineType::Python);
assert_eq!(engine.eval("counter = 1\ncounter")?, "1");
assert_eq!(engine.eval("counter += 1\ncounter")?, "2");
assert_eq!(engine.eval("counter += 1\ncounter")?, "3");
```
> Note: Rhai needs a `let` for the first binding (`let counter = 1; counter`).
---
## 6. Share an engine across threads (`ThreadSafeEngine`)
To use an engine from multiple threads (e.g. inside Bevy's parallel systems),
wrap it in a `ThreadSafeEngine` and `clone()` the handle:
```rust
use postscriptum::{EngineType, ThreadSafeEngine, get_engine};
let engine = ThreadSafeEngine::new(get_engine(EngineType::Rhai));
engine.eval("let x = 0")?;
let handle = engine.clone();
});
```
The `pyopyo` app goes one step further with an `EngineContextRegistry` that maps
script **names** to `ThreadSafeEngine`s, preserving per-script state:
```rust
// app-side pattern (pseudo-code)
registry.create_or_update_with_bundle("my_script", EngineType::Python, source, &python_bundle)?;
let result = registry.eval("my_script", "counter += 1\ncounter")?;
```
---
## 7. Native vs WASM
- **Rhai** runs everywhere (pure Rust).
- **Python** runs natively through `pyo3` (needs a Python interpreter available
at link/runtime) and in the browser through **Pyodide** — the WASM path is
compiled in automatically for `wasm32-unknown-unknown` targets.
Feature flags (see `Cargo.toml`): `rhai` (default), `python` (default),
`wasm-python`, `native-python`.
---
## 8. Examples
Run any example with the matching features enabled:
```bash
cargo run --example basic_rhai # needs `rhai`
cargo run --example basic_python # needs `python`
cargo run --example thread_safe # needs `rhai`
```