pantin

This page is docs/plugins.md of the repository, as it is on main.

Plugins

A plugin adds commands to pantin: renaming every bone by a rule of your team, putting a root under a character, laying out a rig as your studio does. It is one file, name.rhai, a script of Rhai, a small language close to Rust and JavaScript. A plugin reaches nothing but what pantin gives it: no file, no network; a command that runs too long (five million operations) is stopped, and what it changed is dropped.

Where they are

  • In the folder plugins of a project: the plugins of that project, which go with it.
  • In the folder plugins of the settings of pantin (on Linux ~/.config/pantin/plugins): yours, for every project.

The command palette (Ctrl+K) reads them each time it opens and offers each command under Plugins, as « command · plugin ». A command is one change: one undo takes all it did back. What it says is shown at the bottom right; a command that cannot be done changes nothing and says why.

On the command line, pantin plugin <project> <plugin.rhai> says the commands of a plugin, and pantin plugin <project> <plugin.rhai> <command> runs one and saves the project.

Writing one

Each function of the script that takes nothing, and is not private, is a command: add_root is offered as « add root ».

// Puts every bone that has no parent under a new bone `root`, at the origin.
fn add_root() {
    let roots = [];
    for name in bones() {
        if bone(name).parent == "" {
            roots.push(name);
        }
    }
    add_bone("root", "", #{ length: 0 });
    for name in roots {
        set_bone(name, #{ parent: "root" });
    }
    say(`${roots.len()} bones put under root`);
}

The whole plugin is docs/plugins/tidy_names.rhai in the repository.

What a script is given

Function What it does
bones() The names of the bones, parents before their children.
bone(name) A map: name, parent (empty for a root), x, y, rotation, length, scale_x, scale_y, shear_x, shear_y.
set_bone(name, map) The setup pose of a bone, from the keys the map has (those of bone, name and parent included).
rename_bone(name, new_name) Renames a bone.
add_bone(name, parent, map) A bone under parent (empty for a root), placed by what the map says; 50 long unless it says length.
slots(), animations() Their names.
say(text), print(text) A line for the user, shown when the command is done.

A change a function cannot make (a name taken, a bone that is not there) stops the command with what went wrong, and nothing is changed. More functions come with the next plugins: importers and exporters, tools and panels, checks.