cc_plugins API← API reference · Generated from the source by cargo run -p api_doc; edit the doc comments, not this page.
Lua scripts and plugins for ConstructCraft.
Lua 5.4 runs sandboxed (sandbox, from cc_script): no files, no loading of code, an
instruction budget and a memory limit. Lua code reaches the project only
through the engine’s commands (ccad.run, see api), the same ones the
GUI, the command line and the MCP server use.
run_script runs a script once (ccad lua file.lua).plugin loads plugins (a folder with plugin.toml and main.lua)
whose commands join the session’s catalog through PluginHost, an
engine cc_engine::Extension: each plugin command is one undo step
and leaves nothing behind when it fails.| Module | Items | Summary |
|---|---|---|
cc_plugins |
0 | Lua scripts and plugins for ConstructCraft. |
cc_plugins::api |
5 | The ccad table scripts and plugins see. |
cc_plugins::plugin |
7 | Plugins: a folder with a plugin.toml manifest and Lua code that adds commands to the session. |
cc_plugins::script |
4 | Lua scripts: a file of Lua code run once over a session (ccad lua). |
cc_plugins::store |
13 | Installing plugins: the community index (index.json of constructcraft-plugins), the version to offer, and checked installs from a downloaded archive. |
cc_pluginscrates/cc_plugins/src/lib.rs
Re-exports
pub use cc_script::{convert, sandbox}pub use api::{API_VERSION, Access}pub use plugin::{Manifest, Permissions, Plugin, PluginError, PluginHost}pub use sandbox::Limitspub use script::{ScriptOptions, ScriptOutput, run_script}cc_plugins::apicrates/cc_plugins/src/api.rs
The ccad table scripts and plugins see.
ccad.run(name, args): run an engine command; returns its result, or
raises an error.ccad.try(name, args): the same, returning result or nil, err
(err.code, err.message) instead of raising.ccad.commands(): the commands (name, kind, group, description);
ccad.describe(name) one of them with its parameters’ schema.ccad.null (JSON null), ccad.array(t) (marks t, even empty, as a
list), ccad.json.encode(v) / ccad.json.decode(s), ccad.version,
ccad.api (the plugin API version).
The functions that reach the session exist only while a script or a
plugin command runs: the Lua wrappers stay (a plugin may keep them in
locals when it loads) and call the session’s functions through a private
table filled for the run.Items: API_VERSION · Access · Api · code_name · engine_error
API_VERSIONpub const API_VERSION: u32
The plugin API version this build provides (api in plugin.toml).
Accesspub struct Access
What the commands a run calls may do.
Traits: Debug, Clone, Copy, PartialEq, Eq
Fields
edits: bool
Commands that change the model.
files: bool
Commands that read or write files.
history: bool
Commands that replace the document or move in its history (open, new, undo, redo), which a plugin command, one undo step, cannot.
language: bool
The language (a session-wide setting).
Methods
pub const ALL: Access
Everything: a script the user runs.
Apipub struct Api
The ccad table and the private table of the run’s functions.
Fields
ccad: TableSome fields are private.
Methods
pub fn install(lua: &Lua) -> mlua::Result<Api>
Make the ccad global in lua.
pub fn with_session<R>(&self, lua: &Lua, session: &mut Session, access: Access, f: impl FnOnce(&Lua) -> mlua::Result<R>) -> mlua::Result<R>
Run f with the session’s functions available to the Lua code.
code_namepub fn code_name(code: ErrorCode) -> String
An error code as its JSON name.
engine_errorpub fn engine_error(e: &mlua::Error) -> EngineError
A Lua error as an engine error: a command’s error raised through
ccad.run keeps its code; anything else is a script error.
cc_plugins::plugincrates/cc_plugins/src/plugin.rs
Plugins: a folder with a plugin.toml manifest and Lua code that adds
commands to the session.
id = "room_tools" # lowercase letters, digits and _, no "__"
name = "Room tools"
version = "0.1.0"
api = 1 # the plugin API it was written for
description = "…"
authors = ["…"]
license = "MIT"
homepage = "https://…"
main = "main.lua" # the default
permissions = ["files"] # optional: run commands that read or write files
```rust
`main.lua` registers commands with `ccad.command { name, title,
description, kind, params, run }` while it loads; `require("a.b")` loads
`a/b.lua` from the plugin's folder. A command `walls` of the plugin
`room_tools` is `room_tools__walls` in the catalog. Each plugin has its
own sandboxed Lua state.
**Items:** [`MANIFEST`](#cc_plugins-plugin-manifest) · [`Manifest`](#cc_plugins-plugin-manifest) · [`Permissions`](#cc_plugins-plugin-permissions) · [`PluginError`](#cc_plugins-plugin-pluginerror) · [`valid_id`](#cc_plugins-plugin-valid_id) · [`Plugin`](#cc_plugins-plugin-plugin) · [`PluginHost`](#cc_plugins-plugin-pluginhost)
<a id="cc_plugins-plugin-manifest"></a>
### const `MANIFEST`
```rust
pub const MANIFEST: &str
The manifest’s file name.
Manifestpub struct Manifest
A plugin’s plugin.toml.
Traits: Debug, Clone, PartialEq, Deserialize, Serialize
Fields
id: Stringname: Stringversion: Stringapi: u32description: Stringauthors: Vec<String>license: Stringhomepage: Stringmain: Stringpermissions: Vec<String>Methods
pub fn parse(text: &str) -> Result<Manifest, String>
Read and check a manifest.
pub fn requested(&self) -> Permissions
The permissions it asks for.
Permissionspub struct Permissions
What a plugin may do beyond querying and editing the model.
Traits: Debug, Clone, Copy, Default, PartialEq, Eq, Serialize
Fields
files: bool
Run commands that read or write files (import, export, save).
Methods
pub const NONE: PermissionsPluginErrorpub struct PluginError
A plugin that could not be loaded, or a plugin command refused.
Traits: Debug, Clone, PartialEq, Eq, std::fmt::Display, std::error::Error
Fields
dir: PathBuf
The plugin’s folder.
message: String
valid_idpub fn valid_id(s: &str) -> bool
Whether s is a valid plugin id (see Manifest).
Pluginpub struct Plugin
A loaded plugin.
Traits: std::fmt::Debug
Fields
manifest: Manifestdir: PathBufSome fields are private.
Methods
pub fn load(dir: &Path, limits: Limits) -> Result<Plugin, PluginError>
Load the plugin in dir: read its manifest, run its main file and
keep the commands it registers. It is granted no permission yet.
pub fn grant(&mut self, permissions: Permissions)
Grant permissions (only those the manifest asks for are kept).
pub fn granted(&self) -> Permissionspub fn commands(&self) -> impl Iterator<Item = &CommandInfo>
Its commands’ catalog entries (full names).
PluginHostpub struct PluginHost
The loaded plugins, as the session’s Extension.
Traits: Debug, Default, Extension
Some fields are private.
Methods
pub fn new() -> PluginHostpub fn add(&mut self, plugin: Plugin) -> Result<(), PluginError>
Add a loaded plugin; refused if one with its id is already there.
pub fn load_folder(&mut self, folder: &Path, limits: Limits, grant: impl Fn(&Manifest) -> Option<Permissions>) -> Vec<PluginError>
Load the plugins of folder: the folder itself when it holds a
manifest, else each of its subfolders that does (in name order),
skipping hidden ones (an install’s .<id>.installing and .<id>.old)
and refusing one whose name is not its plugin’s id (installs are named
so; permissions are granted by id). grant decides the permissions of
each, or None to leave it out (turned off). Returns the plugins that
could not be loaded.
pub fn plugins(&self) -> &[Plugin]pub fn summary(&self) -> Value
A summary of the plugins for listings (ccad plugins).
cc_plugins::scriptcrates/cc_plugins/src/script.rs
Lua scripts: a file of Lua code run once over a session (ccad lua).
The script gets its arguments as ccad.args (and as ...), and what it
returns is its result.
Items: MAX_SCRIPT · ScriptOptions · ScriptOutput · run_script
MAX_SCRIPTpub const MAX_SCRIPT: usize
Largest script accepted, in bytes.
ScriptOptionspub struct ScriptOptions
How a script runs.
Traits: Debug, Clone, Copy, PartialEq, Eq, Default
Fields
limits: Limitsaccess: AccessScriptOutputpub struct ScriptOutput
What a script did: its result (or error) and the lines it printed.
Traits: Debug, Clone, PartialEq
Fields
result: Result<Value, EngineError>output: Vec<String>run_scriptpub fn run_script(session: &mut Session, source: &str, name: &str, args: Value, options: ScriptOptions) -> ScriptOutput
Run the Lua source (named name in errors) over session with args.
Each command it runs is its own undo step.
cc_plugins::storecrates/cc_plugins/src/store.rs
Installing plugins: the community index (index.json of
constructcraft-plugins),
the version to offer, and checked installs from a downloaded archive.
Nothing here reaches the network: callers download the index and the
archives (the app does it in a background thread) and pass the bytes.
Archives are hostile input: the checksum must match the index, the zip is
read in memory with bounded sizes, entries with unsafe paths or links are
refused, and the plugin must load (in the sandbox) before it replaces an
installed one.
Items: INDEX_URL · INDEX_FORMAT · MAX_INDEX · MAX_ARCHIVE · Index · IndexPlugin · IndexVersion · parse_version · Installed · installed · install · install_archive · uninstall
INDEX_URLpub const INDEX_URL: &str
Where the app reads the index.
INDEX_FORMATpub const INDEX_FORMAT: u32
The index format this build reads.
MAX_INDEXpub const MAX_INDEX: usize
Largest index, archive, unpacked plugin and number of files accepted.
MAX_ARCHIVEpub const MAX_ARCHIVE: usize
Indexpub struct Index
The plugin index.
Traits: Debug, Clone, PartialEq, Deserialize
Fields
format: u32plugins: Vec<IndexPlugin>Methods
pub fn parse(json: &[u8]) -> Result<Index, String>
Read an index; plugins with bad ids or no usable version are left out.
IndexPluginpub struct IndexPlugin
A plugin in the index.
Traits: Debug, Clone, PartialEq, Deserialize
Fields
id: Stringname: Stringdescription: Stringauthors: Vec<String>license: Stringhomepage: Option<String>repository: Option<String>tags: Vec<String>versions: Vec<IndexVersion>Methods
pub fn newest(&self) -> Option<&IndexVersion>
The newest version, whether this build can run it or not.
pub fn best(&self, app: (u64, u64, u64)) -> Option<&IndexVersion>
The newest version this build can run: plugin API at most
API_VERSION, min_app at most app, an https archive.
IndexVersionpub struct IndexVersion
One downloadable version of a plugin.
Traits: Debug, Clone, PartialEq, Deserialize
Fields
version: Stringapi: u32url: Stringsha256: Stringpermissions: Vec<String>path: Option<String>
The folder of plugin.toml inside the archive.
min_app: Option<String>
The oldest ConstructCraft version it works with.
notes: Option<String>parse_versionpub fn parse_version(text: &str) -> Option<(u64, u64, u64)>
A version major.minor.patch, ignoring any pre-release or build suffix.
Installedpub struct Installed
A plugin found in a plugins folder (loaded or not).
Traits: Debug, Clone, PartialEq
Fields
dir: PathBufmanifest: Result<Manifest, String>
Its manifest, or why it cannot be read.
installedpub fn installed(folder: &Path) -> Vec<Installed>
The plugins of folder: each subfolder with a manifest, in name order.
installpub fn install(archive: &[u8], plugin: &IndexPlugin, version: &IndexVersion, folder: &Path) -> Result<PathBuf, String>
Install version of plugin from its downloaded archive into
folder (as folder/<id>, replacing an installed one). Returns the
plugin’s folder.
install_archivepub fn install_archive(archive: &[u8], folder: &Path) -> Result<PathBuf, String>
Install a plugin archive that is not in the index (a local .zip):
the same checks, except the checksum and the index’s own fields.
uninstallpub fn uninstall(folder: &Path, id: &str) -> Result<(), String>
Remove the installed plugin id from folder (only a folder whose
manifest has that id).