Rigby2D

https://github.com/jaisurya-dev-art/rigby2d
Admin
Rigby2D is an open-source 2D skeletal animation editor for games, films and interactive experiences,...
Tokens:53,846
Snippets:389
Trust Score:6.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Build a release

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/README.md

Builds the application and produces installers (MSI and NSIS setup .exe) in src-tauri/target/release/bundle/.

```bash
npm run build
```

--------------------------------

### Clone, install, and run Rigby2D from source

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/README.md

Run these commands in order to clone the repository, install dependencies, and start the development server. Requires Node.js 20 or newer and Tauri system prerequisites.

```bash
git clone https://github.com/jaisurya-dev-art/rigby2d.git
cd rigby2d
npm install
npm run dev
```

--------------------------------

### Install dependencies and run dev/test commands

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/CONTRIBUTING.md

Run these commands after cloning the repository to install dependencies, launch the desktop app with hot reload, and execute unit tests. Requires Node.js 20+ and Tauri prerequisites.

```bash
npm install
npm run dev      # desktop window with hot reload
npm test         # unit tests
```

--------------------------------

### Verify SHA-256 checksum of downloaded installer

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/README.md

Use this PowerShell command to compare the SHA-256 checksum of a downloaded installer against the checksum listed on the Releases page. Replace the filename with the actual installer you downloaded.

```powershell
Get-FileHash .\Rigby2D_0.2.5_x64_en-US.msi -Algorithm SHA256
```

--------------------------------

### run_script JSON example

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Example of the run_script tool call. It runs a Python script against a project, then saves it. The script uses the rigby module to rotate selected bones. print() output is returned in output; exceptions prevent saving and return the traceback. dry_run: true runs without saving.

```json
{
  "path": "hero.rigby",
  "selection": ["arm_l", "arm_r"],
  "script": "import rigby
for b in rigby.selected_bones():
    b.rotation += 10
print('done')"
}
```

--------------------------------

### sample_pose

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Evaluates the setup pose or an animation at a time with the runtime, returning world transforms of every bone, visible attachments, draw order, events so far, and bounds. Does not modify any files.

```APIDOC
## sample_pose

### Description
Evaluates the setup pose or an animation at a time with the runtime, returning world transforms of every bone, visible attachments, draw order, events so far, and bounds. Does not modify any files.

### Method
Tool call

### Endpoint
sample_pose

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Optional - Name of the animation to sample. If omitted, samples the setup pose.
- **time** (number) - Optional - Time in seconds to sample the animation. Defaults to 0.

### Response
#### Success Response
- **bones** (array) - World transforms of every bone.
- **attachments** (array) - Visible attachments.
- **drawOrder** (array) - Draw order.
- **events** (array) - Events that have occurred so far.
- **bounds** (object) - Bounds of the pose.

#### Response Example
{
  "bones": [
    {
      "name": "head",
      "worldX": 10,
      "worldY": 20,
      "worldRotation": 45,
      "worldScaleX": 1,
      "worldScaleY": 1
    }
  ],
  "attachments": ["body.png"],
  "drawOrder": ["body"],
  "events": [],
  "bounds": {
    "x": 0,
    "y": 0,
    "width": 100,
    "height": 100
  }
}
```

--------------------------------

### apply_pose

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Applies a pose at a specified amount (0 to 1) to the setup pose or as keys in an animation at a specific time.

```APIDOC
## apply_pose

### Description
Applies a pose at an amount (0 to 1): to the setup pose, or as keys in an animation at a time.

### Method
MCP Tool

### Endpoint
`apply_pose`

### Parameters
- **pose_name** (string) - Required - The name of the pose to apply.
- **amount** (number) - Required - The blend amount (0 to 1).
- **animation** (string) - Optional - The animation to apply the pose to.
- **time** (number) - Optional - The time (in seconds) or frame at which to apply the pose.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### Build Rigby2D Godot runtime from source

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Builds the Rigby2D Godot runtime library from source on any platform with Rust installed. Run from the runtimes/rust directory; outputs rigby_godot.dll on Windows, librigby_godot.so on Linux, or librigby_godot.dylib on macOS.

```bash
cd runtimes/rust
cargo build --release -p rigby-godot
```

--------------------------------

### add_audio_track

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Stores a sound file (WAV, MP3, OGG, M4A, AAC, FLAC) in the work file as an audio track of an animation, with start time and volume.

```APIDOC
## add_audio_track

### Description
Stores a sound file (WAV, MP3, OGG, M4A, AAC, FLAC) in the work file as an audio track of an animation, with start time and volume.

### Method
MCP Tool

### Endpoint
`add_audio_track`

### Parameters
- **animation** (string) - Required - The animation to add the track to.
- **file** (string) - Required - The path to the sound file.
- **start_time** (number) - Optional - The start time in seconds.
- **volume** (number) - Optional - The volume (0 to 1).

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### set_audio_track

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Changes a track's start time or volume.

```APIDOC
## set_audio_track

### Description
Changes a track's start time or volume.

### Method
MCP Tool

### Endpoint
`set_audio_track`

### Parameters
- **animation** (string) - Required - The animation containing the track.
- **track_index** (number) - Required - The index of the track to modify.
- **start_time** (number) - Optional - The new start time in seconds.
- **volume** (number) - Optional - The new volume (0 to 1).

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### add_bone

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Adds a bone under an existing bone, with its setup pose relative to the parent. Modifies the project file.

```APIDOC
## add_bone

### Description
Adds a bone under an existing bone, with its setup pose relative to the parent. Modifies the project file.

### Method
Tool call

### Endpoint
add_bone

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **parent** (string) - Required - Name of the parent bone.
- **name** (string) - Required - Name of the new bone.
- **x** (number) - Optional - X position relative to parent.
- **y** (number) - Optional - Y position relative to parent.
- **rotation** (number) - Optional - Rotation relative to parent.
- **scaleX** (number) - Optional - Scale X relative to parent.
- **scaleY** (number) - Optional - Scale Y relative to parent.
- **shearX** (number) - Optional - Shear X relative to parent.
- **shearY** (number) - Optional - Shear Y relative to parent.
- **length** (number) - Optional - Length of the bone.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### batch_edit JSON example for building an animation

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Use batch_edit to apply multiple editing operations in one atomic call. The operations list contains { op, ...arguments } without the path, run in order; if any operation fails, nothing is saved. This example adds a 'nod' animation and sets two rotate keys on the 'head' bone with different curves.

```json
{
  "path": "hero.rigby",
  "operations": [
    { "op": "add_animation", "name": "nod" },
    { "op": "set_bone_key", "animation": "nod", "bone": "head", "channel": "rotate", "time": 0, "value": 0, "curve": [0.25, 0.1, 0.25, 1] },
    { "op": "set_bone_key", "animation": "nod", "bone": "head", "channel": "rotate", "time": 0.5, "value": -15, "curve": "easeInOut" }
  ]
}
```

--------------------------------

### rigby.mode() / rigby.set_mode('setup' | 'animate')

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/scripting.md

Gets or sets the editor mode. The mode can be 'setup' or 'animate'.

```APIDOC
## rigby.mode() / rigby.set_mode('setup' | 'animate')

### Description
Gets or sets the editor mode. The mode can be 'setup' or 'animate'.

### Method
Function

### Endpoint
rigby.mode() / rigby.set_mode('setup' | 'animate')

### Parameters
#### Function Arguments
- **mode** (string) - Required - The mode to set: 'setup' or 'animate'.

### Returns
- **string**: The current mode when calling `rigby.mode()`.
```

--------------------------------

### advance(seconds)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Moves playback forward and redraws.

```APIDOC
## advance(seconds)

### Description
Moves playback forward and redraws.

### Method
advance

### Parameters
- **seconds** (float) - Required - Time to advance in seconds.
```

--------------------------------

### set_bone_setup

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Changes a bone's setup pose (x, y, rotation, scale, shear, length); only the given fields are updated. Modifies the project file.

```APIDOC
## set_bone_setup

### Description
Changes a bone's setup pose (x, y, rotation, scale, shear, length); only the given fields are updated. Modifies the project file.

### Method
Tool call

### Endpoint
set_bone_setup

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **bone** (string) - Required - Name of the bone.
- **x** (number) - Optional - X position.
- **y** (number) - Optional - Y position.
- **rotation** (number) - Optional - Rotation.
- **scaleX** (number) - Optional - Scale X.
- **scaleY** (number) - Optional - Scale Y.
- **shearX** (number) - Optional - Shear X.
- **shearY** (number) - Optional - Shear Y.
- **length** (number) - Optional - Length.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### add_face_control

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Adds a face control that blends from the setup pose (or a pose) to a target pose.

```APIDOC
## add_face_control

### Description
Adds a face control that blends from the setup pose (or a pose) to a pose.

### Method
MCP Tool

### Endpoint
`add_face_control`

### Parameters
- **name** (string) - Required - The name of the face control.
- **from_pose** (string) - Optional - The source pose (defaults to setup pose).
- **to_pose** (string) - Required - The target pose.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### slot.attachment

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/scripting.md

Gets or sets the attachment shown in the setup pose. Setting to None shows nothing.

```APIDOC
## slot.attachment

### Description
Gets or sets the attachment shown in the setup pose. Setting to None shows nothing.

### Method
Property

### Endpoint
slot.attachment

### Parameters
#### Property Setter
- **value** (string or None) - Required - The attachment name to show, or None to show nothing.

### Returns
- **string or None**: The current attachment name.
```

--------------------------------

### save_pose

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Saves a pose to the pose library, capturing bone transforms and slot attachments from the setup pose or an animation at a specific time.

```APIDOC
## save_pose

### Description
Saves a pose to the pose library: bone transforms and the attachments their slots show, from the setup pose or an animation at a time.

### Method
MCP Tool

### Endpoint
`save_pose`

### Parameters
- **pose_name** (string) - Required - The name of the pose to save.
- **animation** (string) - Optional - The animation from which to capture the pose.
- **time** (number) - Optional - The time (in seconds) or frame at which to capture the pose.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### set_slot

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Sets a slot's setup attachment (or hides it) and color.

```APIDOC
## set_slot

### Description
Sets a slot's setup attachment (or hides it) and color.

### Method
MCP Tool

### Endpoint
`set_slot`

### Parameters
- **slot** (string) - Required - The name of the slot.
- **attachment** (string) - Optional - The attachment name to set, or empty to hide.
- **color** (string) - Optional - The color to set (hex or named).

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### set_face_control

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Sets a face control's value in the setup pose or as keys at a specific time.

```APIDOC
## set_face_control

### Description
Sets a face control's value: in the setup pose, or as keys at a time.

### Method
MCP Tool

### Endpoint
`set_face_control`

### Parameters
- **name** (string) - Required - The name of the face control.
- **value** (number) - Required - The value to set (0 to 1).
- **animation** (string) - Optional - The animation to set the key in.
- **time** (number) - Optional - The time (in seconds) or frame at which to set the key.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### set_event_key

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Fires an event at a time, creating the event definition if needed. Replaces the same event at the same time. Modifies the project file.

```APIDOC
## set_event_key

### Description
Fires an event at a time, creating the event definition if needed. Replaces the same event at the same time. Modifies the project file.

### Method
Tool call

### Endpoint
set_event_key

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Required - Name of the animation.
- **time** (number) - Required - Time in seconds.
- **name** (string) - Required - Name of the event.
- **intValue** (integer) - Optional - Integer value of the event.
- **floatValue** (number) - Optional - Float value of the event.
- **stringValue** (string) - Optional - String value of the event.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### add_animation

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Adds an empty animation to the project. Modifies the project file.

```APIDOC
## add_animation

### Description
Adds an empty animation to the project. Modifies the project file.

### Method
Tool call

### Endpoint
add_animation

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **name** (string) - Required - Name of the new animation.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### describe_animation

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Describes the key times of every bone, slot, deform, IK and draw-order timeline of one animation, its events, and attachment swaps. Does not modify any files.

```APIDOC
## describe_animation

### Description
Describes the key times of every bone, slot, deform, IK and draw-order timeline of one animation, its events, and attachment swaps. Does not modify any files.

### Method
Tool call

### Endpoint
describe_animation

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Required - Name of the animation to describe.

### Response
#### Success Response
- **bones** (object) - Key times for each bone timeline.
- **slots** (object) - Key times for each slot timeline.
- **deforms** (object) - Key times for deform timelines.
- **ik** (object) - Key times for IK timelines.
- **drawOrder** (array) - Key times for draw-order timeline.
- **events** (array) - Events in the animation.
- **attachments** (array) - Attachment swaps.

#### Response Example
{
  "bones": {
    "head": {
      "rotate": [0, 0.5],
      "translate": [],
      "scale": [],
      "shear": []
    }
  },
  "slots": {},
  "deforms": {},
  "ik": {},
  "drawOrder": [],
  "events": [],
  "attachments": []
}
```

--------------------------------

### set_workspace

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Switches the project between the 'game' and 'film' workspaces, determining which tools the editor shows.

```APIDOC
## set_workspace

### Description
Switches the project between the `game` and `film` workspaces (which tools the editor shows).

### Method
MCP Tool

### Endpoint
`set_workspace`

### Parameters
- **workspace** (string) - Required - The workspace to switch to: `game` or `film`.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### bone.set(**fields)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/scripting.md

Sets several setup pose fields at once on a Bone object.

```APIDOC
## bone.set(**fields)

### Description
Sets several setup pose fields at once on a Bone object.

### Method
Function

### Endpoint
bone.set(**fields)

### Parameters
#### Function Arguments
- **fields** (keyword arguments) - Required - Fields to set, e.g., `bone.set(x=10, rotation=45)`.
```

--------------------------------

### get_skin_names(), get_bone_names(), get_event_names()

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Returns other skeleton data.

```APIDOC
## get_skin_names()

### Description
Returns a list of all skin names.

### Method
get_skin_names

### Returns
- **Array** - List of skin names.

## get_bone_names()

### Description
Returns a list of all bone names.

### Method
get_bone_names

### Returns
- **Array** - List of bone names.

## get_event_names()

### Description
Returns a list of all event names.

### Method
get_event_names

### Returns
- **Array** - List of event names.
```

--------------------------------

### get_load_error(), get_draw_batch_count()

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Diagnostics methods.

```APIDOC
## get_load_error()

### Description
Returns the load error, if any.

### Method
get_load_error

### Returns
- **String** - Error message or empty.

## get_draw_batch_count()

### Description
Returns the number of draw batches.

### Method
get_draw_batch_count

### Returns
- **int** - Draw batch count.
```

--------------------------------

### inspect_project

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Inspects a project file and returns format and version, counts of bones, slots, skins, constraints, events and images, the animations with durations, and read warnings. Does not modify any files.

```APIDOC
## inspect_project

### Description
Inspects a project file and returns format and version, counts of bones, slots, skins, constraints, events and images, the animations with durations, and read warnings. Does not modify any files.

### Method
Tool call

### Endpoint
inspect_project

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.

### Response
#### Success Response
- **format** (string) - Format of the project file.
- **version** (string) - Version of the project file.
- **boneCount** (integer) - Number of bones.
- **slotCount** (integer) - Number of slots.
- **skinCount** (integer) - Number of skins.
- **constraintCount** (integer) - Number of constraints.
- **eventCount** (integer) - Number of events.
- **imageCount** (integer) - Number of images.
- **animations** (array) - List of animations with durations.
- **warnings** (array) - Read warnings.

#### Response Example
{
  "format": "rigby",
  "version": "4.3",
  "boneCount": 10,
  "slotCount": 5,
  "skinCount": 1,
  "constraintCount": 0,
  "eventCount": 2,
  "imageCount": 8,
  "animations": [
    {
      "name": "idle",
      "duration": 2.0
    }
  ],
  "warnings": []
}
```

--------------------------------

### describe_rig

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Describes the rig of a project, including bone hierarchy with setup-pose transforms, slots in draw order with their attachments, and extra skins. Does not modify any files.

```APIDOC
## describe_rig

### Description
Describes the rig of a project, including bone hierarchy with setup-pose transforms, slots in draw order with their attachments, and extra skins. Does not modify any files.

### Method
Tool call

### Endpoint
describe_rig

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.

### Response
#### Success Response
- **bones** (array) - Bone hierarchy with setup-pose transforms.
- **slots** (array) - Slots in draw order with their attachments.
- **skins** (array) - Extra skins.

#### Response Example
{
  "bones": [
    {
      "name": "root",
      "parent": null,
      "x": 0,
      "y": 0,
      "rotation": 0,
      "scaleX": 1,
      "scaleY": 1,
      "shearX": 0,
      "shearY": 0,
      "length": 10
    }
  ],
  "slots": [
    {
      "name": "body",
      "bone": "root",
      "attachments": ["body.png"]
    }
  ],
  "skins": []
}
```

--------------------------------

### detect_parts

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Previews AutoRig on a PSD or unrigged .rigby file, showing each layer's body part, side, and detection source. Read-only.

```APIDOC
## detect_parts

### Description
Previews AutoRig on a PSD (`psd_file`) or an unrigged `.rigby` (`path`): each layer's body part, its side, and whether that came from the name or the position. Read-only.

### Method
MCP Tool

### Endpoint
`detect_parts`

### Parameters
- **psd_file** (string) - Optional - The path to a PSD file.
- **path** (string) - Optional - The path to an unrigged `.rigby` file.

### Response
Returns structured content and JSON text with the detection results.
```

--------------------------------

### Signals

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Signals emitted by the RigbySkeleton2D node.

```APIDOC
## animation_event(track, event_name, int_value, float_value, string_value, audio_path)

### Description
Emitted when an event key is passed.

### Parameters
- **track** (int) - Track index.
- **event_name** (String) - Event name.
- **int_value** (int) - Integer value.
- **float_value** (float) - Float value.
- **string_value** (String) - String value.
- **audio_path** (String) - Audio path.

## animation_started(track, animation_name)

### Description
Emitted when an animation starts on a track.

### Parameters
- **track** (int) - Track index.
- **animation_name** (String) - Animation name.

## animation_completed(track, animation_name)

### Description
Emitted when an animation reaches its end (every loop when looping).

### Parameters
- **track** (int) - Track index.
- **animation_name** (String) - Animation name.

## animation_ended(track, animation_name)

### Description
Emitted when an animation stops affecting the pose.

### Parameters
- **track** (int) - Track index.
- **animation_name** (String) - Animation name.
```

--------------------------------

### lip_sync

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Keys a face control on every frame from the loudness of an audio track (WAV through MCP).

```APIDOC
## lip_sync

### Description
Keys a face control on every frame from the loudness of an audio track (WAV through MCP).

### Method
MCP Tool

### Endpoint
`lip_sync`

### Parameters
- **animation** (string) - Required - The animation containing the audio track.
- **track_index** (number) - Required - The index of the audio track to use.
- **face_control** (string) - Required - The name of the face control to key.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### rename_bone

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Renames a bone; poses follow.

```APIDOC
## rename_bone

### Description
Renames a bone; poses follow.

### Method
MCP Tool

### Endpoint
`rename_bone`

### Parameters
- **old_name** (string) - Required - The current name of the bone.
- **new_name** (string) - Required - The new name for the bone.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### delete_face_control

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Deletes a face control.

```APIDOC
## delete_face_control

### Description
Deletes a face control.

### Method
MCP Tool

### Endpoint
`delete_face_control`

### Parameters
- **name** (string) - Required - The name of the face control to delete.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### run_script

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Runs a Python script against a project with the same rigby module as the editor's script editor, then saves the project. Supports dry-run and selection.

```APIDOC
## run_script

### Description
Runs a Python script against a project with the same `rigby` module as the editor's script editor (see the [scripting guide](scripting.md)), then saves the project. It covers what the other tools do not, in one call.

### Method
MCP Tool

### Endpoint
`run_script`

### Parameters
- **path** (string) - Required - The path to the `.rigby` file.
- **script** (string) - Required - The Python script to run.
- **selection** (array) - Optional - A list of bone names to select.
- **dry_run** (boolean) - Optional - If true, runs without saving.
- **animation** (string) - Optional - The animation to set as open.
- **time** (number) - Optional - The current time (in seconds or frame).

### Response
Returns structured content and JSON text. `print()` output comes back in `output`. If the script raises an exception, nothing is saved, and the error comes back with the script's traceback.
```

--------------------------------

### play(name, loop, mix)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Plays an animation on track 0 with a crossfade. Returns false if the animation is not found.

```APIDOC
## play(name, loop, mix)

### Description
Plays an animation on track 0 with a crossfade. Returns false if the animation is not found.

### Method
play

### Parameters
- **name** (String) - Required - Animation name.
- **loop** (bool) - Required - Whether to loop.
- **mix** (float) - Required - Crossfade duration.

### Returns
- **bool** - True if the animation was found and started, false otherwise.
```

--------------------------------

### convert_project

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Writes skeleton JSON (3.8, 4.2 or 4.3) or binary .skel (4.3) from a .rigby, .json or .skel file. Modifies files by writing the converted output.

```APIDOC
## convert_project

### Description
Writes skeleton JSON (3.8, 4.2 or 4.3) or binary .skel (4.3) from a .rigby, .json or .skel file. Modifies files by writing the converted output.

### Method
Tool call

### Endpoint
convert_project

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the input project file.
- **output** (string) - Required - Path to the output file.
- **format** (string) - Required - Output format: "json" or "skel".
- **version** (string) - Optional - Skeleton JSON version: "3.8", "4.2", or "4.3". Defaults to "4.3".
- **overwrite** (boolean) - Optional - Whether to overwrite an existing output file. Defaults to false.

### Response
#### Success Response
- **success** (boolean) - Whether the conversion succeeded.
- **output** (string) - Path to the written output file.

#### Response Example
{
  "success": true,
  "output": "hero.skel"
}
```

--------------------------------

### reset_physics()

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Restarts physics simulation from the current pose.

```APIDOC
## reset_physics()

### Description
Restarts physics simulation from the current pose.

### Method
reset_physics
```

--------------------------------

### set_output

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Configures film output settings including frame rate, size, background, and framing mode.

```APIDOC
## set_output

### Description
Configures film output settings: frame rate, size, background, and framing mode.

### Method
MCP Tool

### Endpoint
`set_output`

### Parameters
- **frame_rate** (number) - Optional - The frame rate for the output.
- **size** (object) - Optional - The output size (width and height).
- **background** (string) - Optional - Background color: `transparent` or a hex color like `#rrggbb`.
- **framing** (string) - Optional - Framing mode: `auto`, `fixed` (with center and scale), or `camera` (follows a bone named `camera`).

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### batch_edit

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Applies many edits in one call. The project is loaded once and saved once, atomically: if any operation fails, nothing is saved and the error names the operation. Modifies the project file.

```APIDOC
## batch_edit

### Description
Applies many edits in one call. The project is loaded once and saved once, atomically: if any operation fails, nothing is saved and the error names the operation. Modifies the project file.

### Method
Tool call

### Endpoint
batch_edit

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **operations** (array) - Required - List of operations, each with an "op" field and the arguments for that tool (without "path").
- **output** (string) - Optional - Path to save a copy instead of changing the input.
- **overwrite** (boolean) - Optional - Whether to overwrite an existing output file. Defaults to false.

### Response
#### Success Response
- **success** (boolean) - Whether the batch operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### get_animation_names(), get_animation_duration(name)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Returns animation data.

```APIDOC
## get_animation_names()

### Description
Returns a list of all animation names.

### Method
get_animation_names

### Returns
- **Array** - List of animation names.

## get_animation_duration(name)

### Description
Returns the duration of the specified animation.

### Method
get_animation_duration

### Parameters
- **name** (String) - Required - Animation name.

### Returns
- **float** - Duration in seconds.
```

--------------------------------

### map_bones

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Previews how bones of a source character match a target, by name, similar name, body part, or custom mapping. Read-only.

```APIDOC
## map_bones

### Description
Previews how bones of a `source` character match a target (`path`): by name, similar name, body part, or your `mapping`. Read-only.

### Method
MCP Tool

### Endpoint
`map_bones`

### Parameters
- **source** (string) - Required - The source character (e.g., a `.rigby` file).
- **path** (string) - Required - The target character path.
- **mapping** (object) - Optional - Custom bone mapping.

### Response
Returns structured content and JSON text with the mapping preview.
```

--------------------------------

### Example traceback from a script error

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/scripting.md

Shows the trimmed traceback logged when a script raises an exception. The project is left exactly as it was, and the status bar shows the error.

```text
Traceback (most recent call last):
  File "broken.py", line 6, in <module>
    find_leg()
  File "broken.py", line 4, in find_leg
    return rigby.bone("leg")
rigby.RigbyError: No bone 'leg'
```

--------------------------------

### rename_animation

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Renames an animation; its audio tracks follow.

```APIDOC
## rename_animation

### Description
Renames an animation; its audio tracks follow.

### Method
MCP Tool

### Endpoint
`rename_animation`

### Parameters
- **old_name** (string) - Required - The current name of the animation.
- **new_name** (string) - Required - The new name for the animation.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### validate_project

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Validates the project structure, checks for missing images, animations without keys, whether skeleton JSON 4.3 round-trips the data, and whether binary .skel export is possible. Does not modify any files.

```APIDOC
## validate_project

### Description
Validates the project structure, checks for missing images, animations without keys, whether skeleton JSON 4.3 round-trips the data, and whether binary .skel export is possible. Does not modify any files.

### Method
Tool call

### Endpoint
validate_project

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.

### Response
#### Success Response
- **valid** (boolean) - Whether the project is valid.
- **errors** (array) - List of validation errors.
- **warnings** (array) - List of validation warnings.
- **roundTrip** (boolean) - Whether skeleton JSON 4.3 round-trips the data.
- **binaryExport** (boolean) - Whether binary .skel export is possible.

#### Response Example
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "roundTrip": true,
  "binaryExport": true
}
```

--------------------------------

### queue(track, name, loop, mix, delay)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Plays an animation after the current animation. If delay is negative, it plays when the current animation ends.

```APIDOC
## queue(track, name, loop, mix, delay)

### Description
Plays an animation after the current animation. If delay is negative, it plays when the current animation ends.

### Method
queue

### Parameters
- **track** (int) - Required - Track index.
- **name** (String) - Required - Animation name.
- **loop** (bool) - Required - Whether to loop.
- **mix** (float) - Required - Crossfade duration.
- **delay** (float) - Required - Delay in seconds; negative means when current animation ends.
```

--------------------------------

### set_animation_on(track, name, loop, mix)

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Plays an animation on any track; higher tracks layer over lower ones.

```APIDOC
## set_animation_on(track, name, loop, mix)

### Description
Plays an animation on any track; higher tracks layer over lower ones.

### Method
set_animation_on

### Parameters
- **track** (int) - Required - Track index.
- **name** (String) - Required - Animation name.
- **loop** (bool) - Required - Whether to loop.
- **mix** (float) - Required - Crossfade duration.
```

--------------------------------

### delete_bone_key

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Deletes a bone key at a time. Modifies the project file.

```APIDOC
## delete_bone_key

### Description
Deletes a bone key at a time. Modifies the project file.

### Method
Tool call

### Endpoint
delete_bone_key

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Required - Name of the animation.
- **bone** (string) - Required - Name of the bone.
- **channel** (string) - Required - Channel: "rotate", "translate", "scale", or "shear".
- **time** (number) - Required - Time in seconds.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### set_attachment_key

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Shows an attachment of a slot from a time on (image swap), or hides it. Modifies the project file.

```APIDOC
## set_attachment_key

### Description
Shows an attachment of a slot from a time on (image swap), or hides it. Modifies the project file.

### Method
Tool call

### Endpoint
set_attachment_key

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Required - Name of the animation.
- **slot** (string) - Required - Name of the slot.
- **time** (number) - Required - Time in seconds.
- **attachment** (string) - Optional - Name of the attachment to show. If omitted, hides the attachment.

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### bone.key(channel, value, time=None, animation=None, curve='linear')

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/scripting.md

Sets a keyframe on a bone channel. The value is relative to the setup pose.

```APIDOC
## bone.key(channel, value, time=None, animation=None, curve='linear')

### Description
Sets a keyframe on a bone channel. The value is relative to the setup pose.

### Method
Function

### Endpoint
bone.key(channel, value, time=None, animation=None, curve='linear')

### Parameters
#### Function Arguments
- **channel** (string) - Required - The channel name: 'rotate', 'translate', 'scale', or 'shear'.
- **value** (number or tuple) - Required - The key value. For 'rotate' it's degrees; for 'translate', 'scale', 'shear' it's a tuple (x, y).
- **time** (number) - Optional - The time in seconds. Defaults to current time.
- **animation** (string) - Optional - The animation name. Defaults to the animation open in the editor.
- **curve** (string) - Optional - The interpolation curve: 'linear', 'stepped', 'ease_in', 'ease_out', 'ease_in_out'. Defaults to 'linear'.
```

--------------------------------

### retarget_animation

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Copies one or more animations from a source to a target, scaling movement to the target's size and preserving curves, slot, event, and IK keys.

```APIDOC
## retarget_animation

### Description
Copies one animation (`animation`) or several (`animations`) from `source` to the target. Movement is scaled to the target's size (or `scale`); `mode` is `relative` or `world`. Curves are kept, and slot, event and IK keys follow by name.

### Method
MCP Tool

### Endpoint
`retarget_animation`

### Parameters
- **source** (string) - Required - The source character.
- **target** (string) - Required - The target character path.
- **animation** (string) - Optional - The name of a single animation to copy.
- **animations** (array) - Optional - A list of animation names to copy.
- **scale** (number) - Optional - A custom scale factor for movement.
- **mode** (string) - Optional - The retargeting mode: `relative` or `world`.

### Response
Returns structured content and JSON text with the result of the operation.
```

--------------------------------

### Create a feature branch from develop

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/CONTRIBUTING.md

Clone your fork, switch to the develop branch, and create a new branch for your change. Open pull requests against develop, not main.

```bash
git clone https://github.com/<you>/rigby2d.git
cd rigby2d
git checkout develop
git checkout -b feat/my-change
```

--------------------------------

### set_bone_key

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Sets a rotate, translate, scale or shear key at a time, with a curve to the next key. Replaces a key at the same time. Modifies the project file.

```APIDOC
## set_bone_key

### Description
Sets a rotate, translate, scale or shear key at a time, with a curve to the next key. Replaces a key at the same time. Modifies the project file.

### Method
Tool call

### Endpoint
set_bone_key

### Parameters
#### Path Parameters
- **path** (string) - Required - Path to the project file.
- **animation** (string) - Required - Name of the animation.
- **bone** (string) - Required - Name of the bone.
- **channel** (string) - Required - Channel: "rotate", "translate", "scale", or "shear".
- **time** (number) - Required - Time in seconds.
- **value** (number) - Required - Value of the key.
- **curve** (string or array) - Optional - Curve type: "linear", "stepped", "easeIn", "easeOut", "easeInOut", or a custom cubic bezier [cx1, cy1, cx2, cy2].

### Response
#### Success Response
- **success** (boolean) - Whether the operation succeeded.

#### Response Example
{
  "success": true
}
```

--------------------------------

### RigbySkeleton2D animation control in GDScript

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/runtimes/godot/addons/rigby2d/README.md

Shows how to connect to the animation_event signal, play animations on tracks, queue animations, and follow a bone transform. Requires a RigbySkeleton2D node with skeleton and atlas files set.

```gdscript
@onready var hero: RigbySkeleton2D = $Hero

func _ready() -> void:
	hero.animation_event.connect(_on_event)
	hero.play("walk", true, 0.2)                 # track 0, 0.2 s crossfade
	hero.set_animation_on(1, "shoot", false, 0.1) # track 1 layers on top
	hero.queue(0, "idle", true, 0.3, -1.0)        # after walk ends

func _on_event(track: int, event_name: String, int_value: int, float_value: float, string_value: String, audio: String) -> void:
	if event_name == "footstep":
		$Step.play()

func _process(_delta: float) -> void:
	$Gun.transform = hero.get_bone_transform("gun-tip") # follow a bone
```

--------------------------------

### Configure Rigby2D MCP server in mcpServers JSON

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/docs/mcp.md

Configures the Rigby2D MCP server for clients that use an `mcpServers` configuration file, such as Claude Desktop without the extension. The server runs over stdio using Node.js. On Windows, use full paths with doubled backslashes in JSON, e.g., `C:\\Users\\you\\rigby2d\\src\\mcp\\server.js`.

```json
{
  "mcpServers": {
    "rigby2d": {
      "command": "node",
      "args": ["/path/to/rigby2d/src/mcp/server.js", "--root", "/path/to/your/projects"]
    }
  }
}
```

--------------------------------

### Run tests

Source: https://github.com/jaisurya-dev-art/rigby2d/blob/develop/README.md

Runs the test suite for the project.

```bash
npm test
```
Tokens:
Raw