ConstructCraft

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.

Modules

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_plugins

crates/cc_plugins/src/lib.rs

Re-exports

cc_plugins::api

crates/cc_plugins/src/api.rs

The ccad table scripts and plugins see.

Items: API_VERSION · Access · Api · code_name · engine_error

const API_VERSION

pub const API_VERSION: u32

The plugin API version this build provides (api in plugin.toml).

struct Access

pub struct Access

What the commands a run calls may do.

Traits: Debug, Clone, Copy, PartialEq, Eq

Fields

Methods

struct Api

pub struct Api

The ccad table and the private table of the run’s functions.

Fields

Some fields are private.

Methods

fn code_name

pub fn code_name(code: ErrorCode) -> String

An error code as its JSON name.

fn engine_error

pub 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::plugin

crates/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.

struct Manifest

pub struct Manifest

A plugin’s plugin.toml.

Traits: Debug, Clone, PartialEq, Deserialize, Serialize

Fields

Methods

struct Permissions

pub struct Permissions

What a plugin may do beyond querying and editing the model.

Traits: Debug, Clone, Copy, Default, PartialEq, Eq, Serialize

Fields

Methods

struct PluginError

pub 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

fn valid_id

pub fn valid_id(s: &str) -> bool

Whether s is a valid plugin id (see Manifest).

struct Plugin

pub struct Plugin

A loaded plugin.

Traits: std::fmt::Debug

Fields

Some fields are private.

Methods

struct PluginHost

pub struct PluginHost

The loaded plugins, as the session’s Extension.

Traits: Debug, Default, Extension

Some fields are private.

Methods

cc_plugins::script

crates/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

const MAX_SCRIPT

pub const MAX_SCRIPT: usize

Largest script accepted, in bytes.

struct ScriptOptions

pub struct ScriptOptions

How a script runs.

Traits: Debug, Clone, Copy, PartialEq, Eq, Default

Fields

struct ScriptOutput

pub struct ScriptOutput

What a script did: its result (or error) and the lines it printed.

Traits: Debug, Clone, PartialEq

Fields

fn run_script

pub 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::store

crates/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

const INDEX_URL

pub const INDEX_URL: &str

Where the app reads the index.

const INDEX_FORMAT

pub const INDEX_FORMAT: u32

The index format this build reads.

const MAX_INDEX

pub const MAX_INDEX: usize

Largest index, archive, unpacked plugin and number of files accepted.

const MAX_ARCHIVE

pub const MAX_ARCHIVE: usize

struct Index

pub struct Index

The plugin index.

Traits: Debug, Clone, PartialEq, Deserialize

Fields

Methods

struct IndexPlugin

pub struct IndexPlugin

A plugin in the index.

Traits: Debug, Clone, PartialEq, Deserialize

Fields

Methods

struct IndexVersion

pub struct IndexVersion

One downloadable version of a plugin.

Traits: Debug, Clone, PartialEq, Deserialize

Fields

fn parse_version

pub fn parse_version(text: &str) -> Option<(u64, u64, u64)>

A version major.minor.patch, ignoring any pre-release or build suffix.

struct Installed

pub struct Installed

A plugin found in a plugins folder (loaded or not).

Traits: Debug, Clone, PartialEq

Fields

fn installed

pub fn installed(folder: &Path) -> Vec<Installed>

The plugins of folder: each subfolder with a manifest, in name order.

fn install

pub 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.

fn install_archive

pub 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.

fn uninstall

pub fn uninstall(folder: &Path, id: &str) -> Result<(), String>

Remove the installed plugin id from folder (only a folder whose manifest has that id).