Skip to main content

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 as String, 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:

ChangeRebuild?Reason
Operator implementation or a dependency's implementation changesYesThe old binary contains the previously compiled code.
Cargo.toml, Cargo.lock, Rust toolchain, compiler flags, enabled features, or build target changesYesThese can change linked code, types, or the produced binary.
Function/module/crate target is renamed, or argument/return ABI types or query shape changesYesThe 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 simYesNative loading checks compiler metadata and rejects mismatches before calling Rust plugin code.
Simulator/SimVM dependencies or plugin interface changeRebuild against the matching sim releaseNative 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 changesNoThese 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 dependencyNoThe 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 .wasm browser 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.