ConstructCraft

cc_script API

← API reference · Generated from the source by cargo run -p api_doc; edit the doc comments, not this page.

ConstructCraft’s sandboxed Lua 5.4. sandbox is the restricted state every Lua run uses: no files, no loading of code, an instruction budget and a memory limit. convert turns JSON values into Lua values and back, bounded in depth and size. object runs the scripts of scripted component pieces. The crate depends only on cc_core, so geometry can run scripts without the engine; cc_plugins builds scripts and plugins over engine commands on top of it.

Modules

Module Items Summary
cc_script 0 ConstructCraft’s sandboxed Lua 5.4.
cc_script::convert 5 JSON values to Lua and back, for command arguments and results.
cc_script::object 11 Scripted component pieces: running the Lua of a cc_core::ComponentShape::Script piece.
cc_script::patterns 1 Lua’s pattern matching (string.find, match, gmatch and gsub) with every step counted against the run’s budget.
cc_script::sandbox 6 The sandboxed Lua state scripts and plugins run in.

cc_script

crates/cc_script/src/lib.rs

Re-exports

cc_script::convert

crates/cc_script/src/convert.rs

JSON values to Lua and back, for command arguments and results. Objects become tables with string keys, arrays become sequences marked with the array metatable (so an empty array stays an array), null becomes ccad.null. Back from Lua, a sequence 1..n (or a table marked as an array) is an array, any other table an object with string keys; whole floats become integers (Lua’s / always gives a float, and ids and counts are integers). Nesting and size are bounded: tables can be cyclic or huge.

Items: MAX_DEPTH · MAX_VALUES · MAX_BYTES · to_lua · from_lua

const MAX_DEPTH

pub const MAX_DEPTH: usize

Deepest nesting of tables or JSON values converted.

const MAX_VALUES

pub const MAX_VALUES: usize

Most values converted at once.

const MAX_BYTES

pub const MAX_BYTES: usize

Most bytes of text (strings and keys) converted from Lua at once: a table can hold one large string many times.

fn to_lua

pub fn to_lua(lua: &Lua, value: &Value) -> mlua::Result<LuaValue>

A JSON value as a Lua value.

fn from_lua

pub fn from_lua(lua: &Lua, value: &LuaValue) -> Result<Value, String>

A Lua value as JSON; Err says what cannot be converted.

cc_script::object

crates/cc_script/src/object.rs

Scripted component pieces: running the Lua of a cc_core::ComponentShape::Script piece. A script declares its parameters and hotspots at its top level and defines geometry(p), which returns the pieces:

param.length  { "depth", label = "Depth", default = 0.6 }
param.choice  { "finish", { {"plain", "Plain"}, {"blue", "Blue"} }, default = "plain" }
param.boolean { "doors", default = true, instance = true }
hotspot       { "size", 0.9, 0.6, 0, label = "Size", shape = "diamond", color = "#ffccddee" }
function geometry(p)
  if not p.doors then return {} end
  return { box { 0, 0, 0, p.size.x, p.depth, 0.9, material = "Wood" } }
end
```rust
Scripts are pure: they see the parameter values and nothing else (no
engine commands, files or model), so the same values always give the
same pieces and results can be cached. [`declare`] reads the
declarations, [`evaluate`] runs `geometry`, and [`ScriptCache`] is the
[`ScriptEval`] geometry uses: results by source and values, and the last
pieces that worked for each owner.

**Items:** [`LIMITS`](#cc_script-object-limits) · [`MAX_PIECES`](#cc_script-object-max_pieces) · [`MAX_POINTS`](#cc_script-object-max_points) · [`MAX_PARAMS`](#cc_script-object-max_params) · [`ScriptError`](#cc_script-object-scripterror) · [`Declarations`](#cc_script-object-declarations) · [`declare`](#cc_script-object-declare) · [`evaluate`](#cc_script-object-evaluate) · [`ScriptCache`](#cc_script-object-scriptcache) · [`shared`](#cc_script-object-shared) · [`sync`](#cc_script-object-sync)

<a id="cc_script-object-limits"></a>

### const `LIMITS`

```rust
pub const LIMITS: Limits

What one evaluation may use: less than a plugin command, since scripts come with project files.

const MAX_PIECES

pub const MAX_PIECES: usize

Most pieces a script returns.

const MAX_POINTS

pub const MAX_POINTS: usize

Most points (outline points and mesh vertices) of all its pieces.

const MAX_PARAMS

pub const MAX_PARAMS: usize

Most parameters a script declares.

struct ScriptError

pub struct ScriptError

Why a script failed, with the line when Lua gave one.

Traits: Debug, Clone, PartialEq, Eq, std::fmt::Display

Fields

struct Declarations

pub struct Declarations

What a script declares.

Traits: Debug, Clone, PartialEq, Default

Fields

fn declare

pub fn declare(source: &str) -> Result<Declarations, ScriptError>

Read what source declares (its top level runs; geometry does not).

fn evaluate

pub fn evaluate(source: &str, input: &ScriptInput) -> Result<Vec<ComponentItem>, ScriptError>

Run geometry(p) with the values of input and return its pieces.

struct ScriptCache

pub struct ScriptCache

The ScriptEval geometry uses: runs a script only for source and values it has not seen, and keeps the last pieces that worked for each owner to show while a script fails.

Traits: Default, ScriptEval

Some fields are private.

Methods

fn shared

pub fn shared() -> &'static ScriptCache

The cache shared by everything in the process that resolves components. Scripts are pure, so sharing it only saves runs; the last pieces that worked are kept per owner.

fn sync

pub fn sync(params: &mut Vec<ComponentParam>, hotspots: &mut Vec<Hotspot>, decl: &Declarations) -> Result<(), String>

Merge what a script declares into a definition’s parameters and hotspots: new ones are added, those still declared keep their values when the kind (and, for choices, the value) still fits, and those the script no longer declares are removed. Parameters made by hand stay. Fails when a declaration has the name of a parameter made by hand.

cc_script::patterns

crates/cc_script/src/patterns.rs

Lua’s pattern matching (string.find, match, gmatch and gsub) with every step counted against the run’s budget. Lua’s own matcher runs inside one VM instruction, where the instruction hook cannot stop it, and backtracking patterns take exponential time (("a"):rep(40):find(("a*"):rep(20) .. "b")). These functions follow the reference implementation’s matcher step for step (same results, same errors), but charge their steps to the sandbox’s Meter, which stops the run when its instructions or its time are spent.

Items: install

fn install

pub fn install(lua: &Lua, string: &mlua::Table, meter: &Meter) -> R<()>

Put the metered find, match, gmatch and gsub in the string table (which strings’ methods come from).

cc_script::sandbox

crates/cc_script/src/sandbox.rs

The sandboxed Lua state scripts and plugins run in. Only the table, string, math, utf8 and coroutine libraries are loaded, and the base library without the functions that reach files or load code (dofile, loadfile, load, require) or the collector: a script touches the project only through engine commands, and files only through the commands that read and write them, when it may. Each run has an instruction budget and a time limit (a hook checks them in every coroutine) and the state a memory limit; pcall, xpcall and coroutine.resume pass their errors on, so a script cannot catch them and keep going. Library functions whose work grows with their strings run inside one instruction, so they are charged to the budget by their size, string.rep refuses results past MAX_STRING, and the pattern functions count their steps (crate::patterns).

Items: Limits · BUDGET_SPENT · TIME_SPENT · MAX_STRING · Meter · Sandbox

struct Limits

pub struct Limits

How much a script may use.

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

Fields

const BUDGET_SPENT

pub const BUDGET_SPENT: &str

The message of the error raised when the instruction budget is spent.

const TIME_SPENT

pub const TIME_SPENT: &str

The message of the error raised when the time limit is reached.

const MAX_STRING

pub const MAX_STRING: usize

Largest string string.rep and string.gsub make, in bytes.

struct Meter

pub struct Meter

A run’s budget: instructions spent against the limit, and the time.

Traits: Debug, Clone

Some fields are private.

Methods

struct Sandbox

pub struct Sandbox

A sandboxed Lua state with its budget and captured output.

Fields

Some fields are private.

Methods