Crate lumen_plugin 

SDK for Lumen runtime plugins.

A runtime plugin is a Rust cdylib the engine loads when an app starts. It registers native functions the app’s scripts call, ships language source that wraps them, and pushes events at the app from its own threads. Authors implement RuntimePlugin and export it with lumen_plugin!; no unsafe code is involved on the author side.

The plugin and the engine exchange bytes over a C ABI (abi), so a plugin works with the prebuilt engine as long as both were built from the same release tag (enforced by a version handshake at load).

A plugin is not in the engine’s address space

The cdylib links its own copy of every Lumen crate it names. The types re-exported below are data: they encode, cross the boundary, and decode into the engine’s own copy of the same type. Anything that is not data does not cross. A static inside the plugin is a different static from the engine’s, a resource the plugin inserts into a world of its own is not the app’s world, and a handle it holds means nothing on the other side.

Every effect on the app therefore goes one of two ways: a ScriptCommand emitted from a call through Cx::emit, or an event pushed at any time through Host. That is the whole surface, and it is why this crate re-exports data types only and never a whole engine crate.

Re-exports

pub use wire::Call;

pub use wire::CallOut;

pub use wire::FnDecl;

pub use wire::InitCx;

pub use wire::Manifest;

Modules

abi

The C ABI a runtime plugin exports and the engine loads.

codec

The one bincode call site for both sides of the plugin boundary.

wire

What the two sides say to each other, as serde shapes.

Macros

lumen_plugin

Export a RuntimePlugin from a cdylib crate.

Structs

Cx

The call a PluginFn body receives: its arguments, the sink it emits commands into, and the host it can reach.

Error

A failure inside a plugin. The message reaches the user prefixed with the module’s name.

Host

The engine, as a plugin can reach it.

InitEnv

What every module in a set is told about the app.

LoadFailure

One module that did not load, named so a banner can say which and why.

PluginFn

One function a plugin offers to the app’s scripts.

PluginFnBuilder

Builder for a PluginFn. Start it with PluginFn::new.

PluginSet

The loaded modules of one app, in declaration order.

Registrar

What a plugin registers into, handed to RuntimePlugin::register.

ResolvedModule

One module to load: a name, a library file that already exists, and the configuration the app declared for it.

ScriptField

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. One field of a ScriptStruct.

ScriptParam

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. One declared parameter: the name a doc or an editor shows, and its type.

ScriptPrelude

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. Source a plugin ships in a script language, compiled ahead of the app’s own program.

ScriptSig

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. The declared signature of a ScriptFn.

ScriptStruct

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. A struct parameter: a name, and fields in declaration order, each with the value it starts with.

Enums

FailureReason

Why one module did not load.

PluginEvent

Something a plugin or a capability pushes at the engine outside a call.

ScriptCommand

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. One side-effect a script wants to apply to the app this tick.

ScriptNs

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. Where a function lives in the script’s name space.

ScriptTy

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. The shape of one parameter or return value.

ScriptValue

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. Typed sum the script-host trait understands across the boundary.

Constants

SCRIPT_WIRE_VERSION

The script surface a plugin describes its functions in and answers calls with. Data types, from the engine’s own crate, so a value a plugin builds decodes into the one the script layer routes. Encoding version of the script surface.

Traits

HostHooks

What the engine provides to the plugins it loads.

RuntimePlugin

What a runtime plugin does.

Type Aliases

PluginFnBody

The body of a PluginFn: the arguments and the command sink go in, a value or the message the script raises comes out.