Skip to content

CPU Logic ​

Some nodes aren't pixel work: generating a shape, scattering or moving points, counting, deciding. For those, a plugin can include a WebAssembly module with one function per node. Caddis calls the function with the node's points, shapes and values and gets new ones back.

json
{
  "sdk": 1, "id": "com.example.pointtools", "name": "Point Tools", "version": "1.0.0",
  "wasm": "logic.wasm",
  "nodes": [{
    "id": "jitter", "label": "Point Jitter", "time": "animated",
    "inputs":  [{ "id": "points", "type": "points" }],
    "outputs": [{ "id": "out", "type": "points" }],
    "params":  [{ "id": "amount", "type": "float", "default": 10, "unit": "px" }],
    "logic": "jitter"
  }]
}

In Rust ​

Add the caddis-plugin crate (in the Plugin Kit at rust/caddis-plugin) and build a cdylib for wasm32-unknown-unknown:

toml
[lib]
crate-type = ["cdylib"]

[dependencies]
caddis-plugin = { path = "…/rust/caddis-plugin" }
rust
use caddis_plugin::*;

fn jitter(req: &Request) -> Result<Response, String> {
    let mut pts = req.points("points").cloned().unwrap_or_default();
    let amount = req.param_f64("amount", 10.0);
    for (i, p) in pts.positions.iter_mut().enumerate() {
        let a = hash01(pts.ids[i], 1) * std::f64::consts::TAU;
        p[0] += a.cos() * amount;
        p[1] += a.sin() * amount;
    }
    Ok(Response::new().output("out", Value::Points(pts)))
}

caddis_plugin::entry!(jitter => jitter);
sh
rustup target add wasm32-unknown-unknown
cargo build --release --target wasm32-unknown-unknown
cp target/wasm32-unknown-unknown/release/point_tools.wasm my-plugin/logic.wasm

examples/point-tools in the Plugin Kit is a complete example: a point jitter, a star-shape generator, a node whose logic drives a GPU pass, and a stateful particle system.

Other languages that compile to WebAssembly (C, C++, Zig, AssemblyScript) work too. They need to speak the request/response format documented in rust/caddis-plugin/src/wire.rs, and export caddis_alloc(len) -> ptr plus your node functions as (ptr, len) -> (ptr << 32 | len).

What a call receives ​

  • req.context: frame, time, fps, comp_width, comp_height, layer_frame, seed.
  • req.inputs: every connected non-image input (points, shapes, numbers, vectors, colors, strings).
  • req.params: every setting, resolved at this frame. Keyframes and wires are applied, enums arrive as their option text, and angles as degrees.

Geometry is in composition pixels with the origin at the comp center, +y down. Points carry stable ids and named attribute columns (scale, rotation, color, opacity, velocity…). Key per-point randomness on the id (hash01(id, seed)), never on the row index: rows move whenever a point upstream appears or disappears, but ids don't.

What it returns ​

  • Outputs by port id. Each must match the declared type. Caddis checks positions are finite, ids unique, attribute columns full length, and that shape segments point at real points.
  • params.<id> overrides (Response::uniform): values your node's GPU passes see instead of the param. Use them for anything a shader can't compute itself.
  • log messages, shown once each in the status console.
  • An error string, which leaves the node outputting nothing and tells the user why.

Buttons ​

A button setting with an "action" calls that export when it's pressed. The call gets the node's settings at the playhead, like any logic call, and returns the settings to change with Response::set:

json
{ "id": "newSeed", "type": "button", "label": "New Seed", "action": "new_seed" }
rust
fn new_seed(req: &Request) -> Result<Response, String> {
    let seed = req.param_f64("seed", 1.0) as u64;
    Ok(Response::new().set("seed", Value::Scalar(((seed * 2654435761 + 97) % 100_000) as f64)))
}

Everything an action changes is one undo step, keyframed at the playhead for settings that are animated. An action can only change settings, not inputs or outputs, and only exports a button names can be called this way. The sandbox has no clock or random numbers, so derive "random" values from the settings, as above. To reset settings, use "resets" instead; it needs no code.

State ​

A stateful node with logic gets last frame's @state value as an input and returns the next one as an output. That can be any value, usually Points for a particle system. Caddis replays and snapshots it like GPU state, so it scrubs correctly. See Time and State.

The sandbox ​

Each call runs in a fresh instance: no memory survives between calls (state goes through @state), and there are no imports — no files, network, clock or random numbers. A call that runs too long is stopped (the budget is about two billion WebAssembly instructions, a second or two of work), and so is one that allocates more than 2 GB of memory. WebAssembly SIMD (simd128) is available; threads are not. The same inputs therefore always give the same outputs, and a broken plugin can't take Caddis down.