Rust Plugins
A simulator plugin is a Rust library that registers operator functions and exports them through the SimVM plugin interface. The scenario compiler records the Rust function name and signature; the runtime resolves that name to an operator from the loaded plugin. A plugin can contain multiple operators, and a run can load multiple plugin libraries.
This guide covers the plugin author's view of the interface and the user's workflow for building and running it. For workspace creation and the rest of the CLI, see the Simulator CLI guide.
Plugin crate requirements
Start with sim plugin new to create a plugin crate for native and WebAssembly
targets:
sim plugin new my-plugin
cd my-plugin
sim plugin build --target native
sim plugin build --target wasm
The destination must be new or empty. The directory name becomes the Cargo
package name; use letters, numbers, -, or _, starting with a letter, and
avoid Rust keywords. The scaffold includes Cargo.toml, src/lib.rs,
.cargo/config.toml, rust-toolchain.toml, .gitignore, and a README. Its
sample double operator is registered for both targets. The toolchain file
pins the native Rust compiler version used by the sim executable and includes
the wasm32-unknown-unknown target.
The generated manifest pins simvm_abi_syntax to the version of the sim
installation that created it, uses the compatible simvm_abi major version,
and declares Python support as an optional py feature. This avoids manually
matching simulator crate versions and ABI boilerplate. Add dependencies your
operators need, and keep them compatible with every target you plan to build.
For a hand-written plugin crate, configure Cargo to produce a dynamic library
(cdylib) and add the plugin entry point for the target. Choose
simvm_abi_syntax and related dependencies compatible with the sim release
you use. Add dependencies your operators need and keep them compatible with
each target you plan to build. See
Define and export operators for the operator
interface.
Native plugins must use the exact Rust compiler version used to build the
sim executable, because the native plugin boundary passes Rust types across a
shared-library boundary. The scaffold pins that compiler. sim plugin build
uses the current compiler if it matches, or selects the matching installed
rustup toolchain; if neither is available, install the required toolchain or
enter the matching development shell and retry. The loader checks compiler
metadata before calling plugin code, so older native plugins without this
metadata must be rebuilt with sim plugin build.
When Python support is enabled, the host process owns the Python runtime. The
loader checks that a plugin resolves Python symbols from the host rather than
loading a second libpython; rebuild older Python-enabled plugins with the
current sim plugin build if this check fails.
Define and export operators
Define each operator as a public Rust function and add #[operator] above it.
At the crate root, add simvm_abi_syntax::export_plugin!() once to make the
operators available to native runs.
// src/lib.rs
pub mod operators;
simvm_abi_syntax::export_plugin!();
// src/operators.rs
use simvm_abi_syntax::operator;
#[operator]
pub fn advance(angle: f64, rate: f64, dt: f64) -> miette::Result<(f64, f64)> {
let next_angle = angle + rate * dt;
Ok((next_angle, rate))
}
For this example, the registered name is
my_plugin::operators::advance (the crate/lib name, module path, and function
name). Bind the model's Rust operator to exactly that function path. Renaming
the crate target, module, or function changes the ID and requires updating the
model binding; changing an implementation while keeping its registered
signature and path does not change the ID.
Use #[operator] for functions being authored as plugin operators.
Function and type conventions
- Define operators as public functions, not methods, and use simple parameter names.
- Pass copy/value types such as
f64,i32,bool, and tuples of value types by value. Pass heap-owning types such asString,Vec<T>, maps, sets, matrices, and tuples containing them by shared reference (&T). - Return owned values, not references. Use a supported value or a supported
Result<T, E>/SimResult<T>return. Fallible operator errors are propagated to the simulation runtime. - Use supported SimVM value types, including primitives, tuples, options, vectors, ordered maps/sets, and matrices.
sv!(...): adapt a user type to its ABI representation
Use sv!(Type) when the operator should work with a user-defined struct or
enum. Derive StateVariable for the custom type. For a named struct, its fields
define the corresponding value shape (a three-field Velocity, for example,
maps to a tuple of three values).
use simvm_abi_syntax::{StateVariable, operator, sv};
#[derive(StateVariable)]
pub struct Velocity {
x: f64,
y: f64,
z: f64,
}
#[operator]
pub fn speed_up(value: sv!(Velocity), scale: f64) -> sv!(Velocity) {
Velocity {
x: value.x * scale,
y: value.y * scale,
z: value.z * scale,
}
}
Use sv!(Type) in an operator's argument or return type when you want to use
the custom type in the implementation. Use a regular type when working directly
with the corresponding value shape.
query!(...): consume or produce relation-shaped values
Use query!(T) when a parameter or result represents the shape of a SedaroQL
query (a selected relation or nested subqueries), rather than one stored field
whose value happens to be T.
use simvm_abi_syntax::{operator, query};
// The following operator is used with a consumed block-type query such as:
// Spacecraft.mass
#[operator]
pub fn sum_masses(masses: query!(Vec<f64>)) -> f64 {
masses.iter().sum()
}
// The following operator is used with a produced relation query such as:
// battery.(current_charge, max_charge)
#[operator]
pub fn make_pair(value: f64) -> query!((f64, f64)) {
(value, value * 2.0)
}
The first signature describes a query over a collection of f64 fields. A
plain &Vec instead describes one field holding a vector. Nested tuples,
vectors, options, and sv!(...) values can be composed within a query shape.
For example, query!((i32, Vec<i32>)) describes a relation with two
sub-queries. Use query! on an output when it is written to query-shaped
produced destinations; ordinary single-field and tuple outputs do not need
the marker. Keep the operator signature consistent with the model's consumed
and produced query shapes.
Build a native plugin
From the plugin crate directory, build the default release profile:
sim plugin build
sim plugin build defaults to ./Cargo.toml, profile release, target
native, and the current directory as --output-dir. It builds the library,
copies the resulting dynamic library to the output directory, and validates
that it exports a plugin provider. Manage and commit the plugin's Cargo.lock
with Cargo when you need reproducible dependency resolution.
sim plugin build \
--manifest-path path/to/my_plugin/Cargo.toml \
--target native \
--profile dev \
--output-dir out/plugins
--profile dev is useful for iterative builds; release is the default.
--manifest-path selects another plugin crate, and --output-dir chooses where
the copied binary is written. --no-python disables the optional py feature
for a native build; use that feature only when the plugin needs Python support.
--no-validate skips the native provider load check. Build a native plugin for
the host OS and architecture where it will
run. Linux and macOS builds produce .so and .dylib files respectively;
Windows Cargo builds may produce .dll, but the current sim run loader accepts
only .so and .dylib for native plugins.
Native plugins are built with cargo rustc using the exact Rust compiler
version that built sim. The CLI selects that version from rustup if the
current toolchain does not match. The native loader checks this compiler
metadata before invoking plugin code, and rejects older plugins without the
metadata; rebuild them with the current sim plugin build command. It also
checks that Python-enabled plugins resolve Python symbols from the host runtime.
sim run only loads prebuilt plugins; it never rebuilds them. Reuse a binary
while its implementation, dependencies, compiler, and operator interface stay
the same.
Run a model with the plugin
For a Python model, provide the module to --model, set SCF_PATH to the
Sedaro repo or SCF framework checkout, and give --plugin the native library:
SCF_PATH=/path/to/sedaro-or-scf sim run \
--model models.workflows.example \
--plugin /path/to/out/plugins/libmy_plugin.so
The native target is the default. The CLI uses the configured Sedaro/SCF
checkout to export the model to a local build input, compiles the scenario,
and runs it with the plugin. --plugin is repeatable for multiple plugin
libraries. A model using a Rust operator without a matching loaded plugin fails
operator lookup; the diagnostic asks you to load the operator's plugin with
--plugin.
An existing JSON build input can be run without invoking Sedaro/SCF:
sim run --buildinput scenario.json --plugin ./out/plugins/libmy_plugin.so
See the CLI guide for Python module imports, Sedaro/SCF environment, duration, output, and target-specific options.
When must a plugin be rebuilt?
The plugin is a compiled library containing its Rust operator code and linked
Rust dependencies. sim run does not compare source or dependency versions
against the binary and does not rebuild it. Rebuild after any change that can
affect the compiled code or the plugin/runtime contract:
| Change | Rebuild? | Reason |
|---|---|---|
| Operator implementation or a dependency's implementation changes | Yes | The old binary contains the previously compiled code. |
Cargo.toml, Cargo.lock, Rust toolchain, compiler flags, enabled features, or build target changes | Yes | These can change linked code, types, or the produced binary. |
| Function/module/crate target is renamed, or argument/return ABI types or query shape changes | Yes | The registered operator ID and/or binding contract changes. Update the model binding to the new path as needed. |
Rust compiler differs from the compiler used for sim | Yes | Native loading checks compiler metadata and rejects mismatches before calling Rust plugin code. |
| Simulator/SimVM dependencies or plugin interface change | Rebuild against the matching sim release | Native loading enforces the compiler version, but does not fingerprint every Cargo dependency version. |
| Only the scenario data, initial conditions, model duration, or a model query that still calls the same operator with the same ABI shape changes | No | These inputs are compiled at run time; the plugin is unchanged. |
| A Python-only model implementation changes and it does not alter the Rust operator or plugin dependency | No | The change is in the exported model, not the compiled plugin. |
When upgrading the CLI or simulator dependencies, rebuild the plugin with the matching toolchain and dependency versions, especially when the operator ABI or plugin interface has changed. Matching the Rust compiler is mandatory for native loading; matching crate versions remains the plugin author's responsibility.
To keep iteration efficient, use --profile dev while changing plugin code,
let Cargo reuse its target directory, and reserve release builds for
performance checks or delivery. Reuse the output library when changing only
model data or duration. In CI, cache Cargo's build directory by at least the
Rust toolchain, target, profile/features, and Cargo.lock, and publish the
resulting plugin artifact alongside that provenance. For a fresh or changed
dependency graph, update and review the lockfile deliberately, then rebuild.
WASM plugin and browser runner
For WASM builds, use simvm_abi_syntax::export_browser_plugin! at the crate
root:
// Compile this entry point for wasm32-unknown-unknown.
simvm_abi_syntax::export_browser_plugin!(
simvm_abi_syntax::plugin::registry_plugin
);
Use export_browser_plugin! for browser builds instead of
export_plugin!().
Build and run a WASM plugin
The scaffold's rust-toolchain.toml includes the wasm32-unknown-unknown
target. For a hand-written crate, install it with rustup target add before
building the plugin:
sim plugin build \
--manifest-path rust/my_plugin/Cargo.toml \
--target wasm \
--output-dir out/plugins
For this target, the CLI invokes Cargo with --lib --no-default-features --target wasm32-unknown-unknown and the selected profile. Ensure every
dependency and feature enabled for WASM supports wasm32-unknown-unknown; do
not enable Python/PyO3 or native-only system libraries for this build.
sim plugin build copies the Cargo .wasm artifact, but WASM provider
validation is not implemented by the build command. The browser runner checks
for the required plugin exports when it packages the plugin.
Then run a browser-target scenario.
SCF_PATH=/path/to/sedaro-or-scf sim run --target wasm \
--model models.workflows.example \
--plugin ./out/plugins/my_plugin.wasm
sim run --target wasm also builds the browser runtime with wasm-pack.
By default it starts an HTTP server on 127.0.0.1:8000, opens a browser, and
starts the simulation. Use --port 0 for an available port, --no-open to
serve without launching a browser, or --no-serve to emit a static browser app
without starting the server. --output defaults to generated/; the compiler,
interpreter, and browser application artifacts are written there.
The runner can also prepare a WASM plugin that was built with wasm-pack: pass
the generated _bg.wasm with its adjacent .js loader and any snippets/
directory intact. For a raw Cargo .wasm, the runner generates browser JS glue
itself. It checks for the browser plugin exports while packaging; it does not
compile the plugin's Rust sources during the run.
WASM scenario restrictions
The current browser runner has these enforced scenario limits:
- There must be exactly one engine across the entire scenario.
- External co-simulation transports are not supported.
- Python state managers and Python query operators are unavailable. The Sedaro/SCF Python model can still be executed locally to export a build input, but any Python operators in that input prevent the browser run. Replace those operations with Rust plugin operators for WASM.
- Every plugin passed to the run must be a
.wasmbrowser plugin. Native and WASM plugin binaries cannot be mixed, and the runtime must be selected explicitly with--target wasm.
These scenario checks are independent of plugin compilation. A Rust dependency
that calls a host-only API, requires a native library, or otherwise does not
compile for wasm32-unknown-unknown also prevents creation of the plugin; use
WASM-compatible dependencies and code paths. WASM operator names and ABI types
must still match the model's Rust function references, just as for native
plugins.