# pixelate-mcp

> PixelAOI's MCP server: lets an AI agent (Claude Code, Codex, Cursor, Claude Desktop) see the PixelAOI canvas, paint it, arrange layers, build animations, apply filters, pixelate images on your machine, wire Blueprint node graphs and build 3D models into s

Latest version **0.7.0** (published 2026-10-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install pixelate-mcp
pnpm add pixelate-mcp
yarn add pixelate-mcp
bun add pixelate-mcp
```

Provides the command `pixelate-mcp`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2026-10-24 |
| First published | 2026-06-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 222.6 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | PixelAOI |
| Maintainers | red444 |
| Keywords | mcp, model-context-protocol, pixel-art, pixelaoi, pixelate, codex, claude |

## Links

- npm: https://www.npmjs.com/package/pixelate-mcp
- Homepage: https://pixelaoi.pro
- npm.io page: https://npm.io/package/pixelate-mcp

## Dependencies (2)

- [zod](https://npm.io/package/zod.md) ^3.25.76
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.32.1

## Recent versions

- 0.7.0 (latest) — 2026-10-24
- 0.6.0 — 2026-10-06
- 0.3.1 — 2026-07-07
- 0.3.0 — 2026-06-04
- 0.2.0 — 2026-06-04
- 0.1.0 — 2026-06-03

## README

# PixelAOI MCP

An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Claude
Code, Codex, Cursor, Claude Desktop) work in the **PixelAOI** pixel-art editor:
see the canvas, paint it, arrange layers, build animations, apply filters and
adjustment layers, pixelate images, and wire Blueprint node graphs.

Everything runs on **your machine**: the server talks to the editor over a
localhost-only link (`127.0.0.1`). No cloud, no accounts, no API keys.

**Requires PixelAOI 0.6.0 or newer (with the agent token handshake) and
`pixelate-mcp` 0.7.0 or newer.** Older `pixelate-mcp` versions don't say hello
with the token, and every call fails with "say hello with the bridge token
first": update with `npx -y pixelate-mcp@latest`.

## 1. Turn on the agent link in PixelAOI

Click **agent off** in PixelAOI's status bar (bottom right). It turns to
**agent ready** while it waits, and **agent live** once your agent connects.
Click it again to turn it off: that cuts the agent off at once and stops
listening. Whatever it asked for that PixelAOI hadn't run yet is dropped, not
run later, the token file is deleted, and its calls fail until you turn the
link back on. (Or start PixelAOI with `PIXELAOI_AGENT_BRIDGE=1`, which turns it
on from the start.) If it says **agent: port busy (retrying)**, something
else holds the port. PixelAOI tries it again every few seconds, so a port held
for a moment frees itself; if another PixelAOI holds it, close that one.

One agent at a time: an agent that connects with the token takes over, and the
one before it is disconnected (its calls fail with "the link to PixelAOI
closed"). A connection without the token can't disturb the agent.

### The token

Anything on your computer can open a connection to `127.0.0.1`, so PixelAOI
doesn't take orders from just any of them. Each time the link turns on, it
writes a fresh random token to `agent-bridge-token` in your user's PixelAOI
data folder. Whatever can read that file can drive the editor, so PixelAOI
writes it for your user only (on macOS and Linux only your user can read it;
on Windows it lives in your own `%LOCALAPPDATA%`):

| | |
|---|---|
| Windows | `%LOCALAPPDATA%\pixelaoi\agent-bridge-token` |
| macOS | `~/Library/Application Support/pixelaoi/agent-bridge-token` |
| Linux | `~/.local/share/pixelaoi/agent-bridge-token` (under `$XDG_DATA_HOME` when that is set) |

On Linux, when the server's `$XDG_DATA_HOME` has no token there, it also looks
in `~/.local/share/pixelaoi`: an agent host packaged as a Flatpak or Snap
starts the server with the sandbox's own `XDG_DATA_HOME`, while PixelAOI wrote
its token in the usual place.

With `PIXELAOI_PROFILE` set, the folder is `pixelaoi/profiles/<name>`, so give
the server the same `PIXELAOI_PROFILE` as the editor. On a port moved with
`PIXELAOI_BRIDGE_PORT` the file is `agent-bridge-token-<port>`, so two
PixelAOIs on two ports each keep their own. The server reads the
file every time it connects and sends the token as its first line,
`{"id":0,"op":"hello","args":{"token":"…"}}`; PixelAOI answers nothing else
until it has seen it. You never copy it by hand. (To give it yourself, set
`PIXELAOI_BRIDGE_TOKEN`.)

## 2. Add the server to your agent

### Claude Code
```
claude mcp add pixelaoi -- npx -y pixelate-mcp
```

### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.pixelaoi]
command = "npx"
args = ["-y", "pixelate-mcp"]
```

### Claude Desktop / Cursor (JSON config)
```json
{
  "mcpServers": {
    "pixelaoi": { "command": "npx", "args": ["-y", "pixelate-mcp"] }
  }
}
```

Restart the agent, make sure PixelAOI says **agent ready**, and ask it to
draw something. The server shows up as **PixelAOI**, with the PixelAOI mark
(in colours for light and dark clients), and tells the agent how to work with
the editor when it connects.

## Tools

Each tool has a title your client can show, and says whether it only reads or
changes the document, so a client can let reads through and ask before
changes.

Each change to the document is one undo step in PixelAOI, with a name, and
`run_command` `undo` takes the last one back: each `set_canvas_image` or
`set_pixels` paint (an image opened as a new document is a new tab instead),
a filter, a layer change, a new frame, an `add_tag`, a `render_model` (a
`sprite_size` other than the sprite's is a `Sprite size` step of its own
before it), a change of the sun or the shade (`model_light`). Edits to a Blueprint graph's
nodes and wires are outside it. The 3D model has Model mode's own undo: each
change to it (`new_model`, `model_character`, `model_shape`, `model_carve`,
`model_part`, `model_pose`, `rig_model`, `model_action`, `model_light`'s lamps,
`model_reference`, `scale_model`, `model_colour`) is one step there, named for what it
did (`Agent: keys on Arm L`: the result's `undo_label`), as is the sprite
camera a `render_model` sets (`Agent: sprite camera`, from its `angle`,
`tilt` or `directions`), and the user takes it back with Ctrl+Z in Model
mode, whether the mode was open (it stays open, and
the change shows at once) or shut. `run_command` `undo` is the document's: it
is refused while Model mode is open and never takes back a model change.

| Tool | Title | |
|---|---|---|
| `get_state` | Editor state | reads |
| `get_canvas_image` | See the canvas | reads |
| `run_command` | Run a command | changes |
| `apply_filter` | Apply a filter | changes |
| `layers` | Arrange layers | changes |
| `adjustment_layer` | Adjustment layers | changes |
| `set_canvas_image` | Paint an image | changes |
| `set_pixels` | Paint pixels | changes |
| `pixelate_image` | Pixelate an image | changes (may fetch a URL) |
| `extrude_animate` | 3D turntable | changes |
| `add_frame` | Add a frame | adds |
| `select_frame` | Show a frame | adds |
| `set_frame_duration` | Frame timing | changes |
| `add_tag` | Tag frames | adds |
| `save_document` | Save the project | changes |
| `close_document` | Close the document | changes |
| `blueprint_node_kinds` | Blueprint node kinds | reads |
| `blueprint_list` | Read the Blueprint | reads |
| `blueprint_select_graph` | Switch Blueprint graph | adds |
| `blueprint_add_node` | Add a node | adds |
| `blueprint_connect` | Connect nodes | adds |
| `blueprint_connect_value` | Drive a parameter | adds |
| `blueprint_set_param` | Set a parameter | changes |
| `blueprint_set_data` | Set node data | changes |
| `blueprint_delete_node` | Delete a node | changes |
| `blueprint_bake` | Bake the Blueprint | changes |
| `get_model` | Read the 3D model | reads |
| `look_model` | Look at the 3D model | reads |
| `check_model` | Check the 3D model | reads |
| `new_model` | Start a 3D model | changes |
| `model_shape` | Build the 3D model | changes |
| `model_carve` | Carve a 3D part | changes |
| `model_character` | Make a 3D character | changes |
| `model_part` | Rig a 3D part | changes |
| `model_pose` | Pose the 3D model | changes |
| `rig_model` | Rig the 3D model | changes |
| `model_action` | Actions of the 3D model | changes |
| `model_light` | Light the 3D model | changes |
| `model_reference` | Reference drawings of the 3D model | changes |
| `scale_model` | Scale the 3D model | changes |
| `model_colour` | Colour the 3D model | changes |
| `render_model` | Render the 3D model | adds |
| `export_model` | Export the 3D model | writes a file |

In more detail:

- **`get_state`**: canvas size, frames, the layer stack (each layer's index and
  uid, each folder's id), the selection, the tool, the palette, the Blueprint
  editor's state, and the command names `run_command` takes.
- **`get_canvas_image`**: the current frame as PixelAOI shows it, as a PNG.
- **`run_command`** `{ action }`: a command by name (`flip_h`, `rotate_90`,
  `trim`, `undo`, `save`, ...). A filter's name (`invert`, `blur`, ...)
  applies it at once with its remembered settings.
- **`apply_filter`** `{ name, params?, output?, frames? }`: a filter on the
  active layer as one undo step: `blur`, `hsl_adjust`, `levels`, `outline`,
  `drop_shadow`, `color_reduce`, ... `params` by the labels PixelAOI shows
  (`{"Radius": 3}`, `{"Hue": 30}`) or in order; `output` `pixels` (default),
  `new_layer` or `adjustment` (an adjustment layer doing it live, with
  `affects` `layer` or `below`); `frames` `this` (default), `selected` or
  `all`. A selection limits it. Curves takes points per channel,
  `{"all": [[input, output], ...], "red": ...}`, and Gradient Map a ramp,
  `{"stops": [[position, r, g, b], ...]}` (0-255, at most 16 points or stops).
- **`adjustment_layer`** `{ action, kind?, params?, affects?, enabled?, item? }`:
  layers with no art of their own that change what is under them, live: `add`,
  `set`, `remove`, `bake`.
- **`layers`** `{ action, items?, … }`: `select`, `move`, `group`, `ungroup`,
  `new_folder`, `set` (`visible`, `locked`, `opacity`, `blend`, `draft`,
  `clipping`, `expanded`, `name`), `delete`, `duplicate`, `merge`. A layer by
  its index, `{layer: i}` or `{uid: "…"}`; a folder by `{folder: id}`; no
  `items` means the selection.
- **`set_canvas_image`** `{ image_path | png_base64, as_new_document?, name? }`:
  paint an image; at the canvas's size it paints the open document, otherwise
  it opens as a new one. At most 4096 pixels a side.
- **`set_pixels`** `{ x, y, w, h, rgba_base64 }`: a raw RGBA block, clipped to
  the canvas (at most 4096 pixels a side). Each paint is its own undo step.
- **`pixelate_image`**: any image (path, base64 or URL) into grid-perfect
  pixel art with PixelAOI's own engine (it finds the native grid and palette),
  then painted in. `colors` is a palette size up to 256 (PixelAOI uses at
  least 2); left out, the palette is found too. A URL must answer within 30 s
  with at most 64 MB; an HTTP error comes back as its status.
- **`extrude_animate`**: a 3D extrusion turntable of the canvas across the
  timeline.
- **`add_frame`**, **`select_frame`** `{ index }`, **`set_frame_duration`**
  `{ index?, duration_ms }`, **`add_tag`** `{ name, from, to? }`: build an
  animation (frames from 0; 10-10000 ms a frame).
- **`save_document`** `{ path }`: save as a `.pxl` project at an absolute path;
  **`close_document`**: close the tab once saved (refused while unsaved).
- **Blueprints**: switch the graph (`Particle`, `Canvas`, `Ai`, `Layer`), list
  the node kinds, add, wire (output to input, or a value node driving a
  parameter), set parameters and node data, delete, and bake the result into
  the document. In an `Ai` graph an AI Result Source can feed an AI Generate or
  an AI Prompt, to chain one generation into the next; a wire that would close
  a loop is refused. A bake with nothing to bake (no output wired, say) is an
  error saying why; an AI bake answers once its generations have started, and
  their images land when they arrive.
- **3D models** (Sprite › 3D Model in PixelAOI; a block is one unit, y is up
  and the front faces +z): **`get_model`** reads the open sprite's model (its
  box in blocks; its parts with their blocks, the box they span, pivot,
  parent and whether they are locked, each one's `mirror` (its own Mirror X,
  Y and Z), its `twin` (by name, or null), its `rest` (its turn and move
  with no key), whether it is a `control`, its `depth` and `order` in the
  parts tree, and the `tree` itself as Model mode's PARTS shows it, each part
  after the part it goes with, and `outline: false` on a part the PART card's
  Outline draws without its outline; its actions, each with its frames,
  `frame_ms`, `loop`, the parts it keys, its `steps` (`free`, or 8, 16 or 32
  a turn) and `whole_pixels` (and, where it has them, its `holds` as
  `[frame, times]` and its `kept_keys`, the keys kept past its end), and the
  one on show; its lamps; and the
  mirror plane, `mirror_at` (`[x, y, z]` in blocks, the box's middle until
  it is moved)), or null.
  **`look_model`** `{ view?,
  action?, frame?, direction?, angle?, tilt?, directions?, zoom?, isolate?, rest? }`
  shows it as a PNG, changing nothing: one action on one frame from one
  direction (`S` … `SSE`, or `all` for every direction of the sheet side by
  side), in the Sprite view (the sprite as a render makes it, at its own size)
  or the Build view (its blocks, the whole box in view), scaled up by whole
  pixels (`zoom` 1-8, lowered where it would pass 2048 a side, never below 1:
  `all` on many directions or a big sprite is a wide picture, one direction
  keeps it small). It looks through the model's own sprite camera (with Model
  mode open, the one its header's SPRITE cluster shows), or the `angle`
  (`bottom` looks up at the underside), `tilt` and `directions` (2-64) asked,
  set nowhere. A `tilt` names its style, as one typed in Model mode's header
  does (0 `side`, 90 `top`, -90 `bottom`, else `three_quarter`), so `side`,
  `top` or `bottom` asked with a tilt not theirs is refused, as `render_model`
  refuses it; the answer's `angle` and `tilt` say the camera it looked from.
  `isolate` (a part's name, or a list of them) shows those parts
  as they are and the rest at 20%, as Model mode's Isolate draws them, to see
  a part inside or behind others; the answer names them in `isolated`. A
  hidden part is refused, as Isolate refuses it. `rest: true` shows the rest
  pose, the model with no key as Model mode's Rig stage and Build's REST
  show it (every action's: `frame` and `action` are refused with it, and the
  answer's `rest` is true, its `frame` and `action` null).
  **`check_model`** `{ dismissed? }` says what will look broken once the
  model is posed and rendered, as Model mode's CHECK finds it, changing
  nothing: a part that only touches what it goes with at a corner, stands
  apart from it, or meets it flush where it bends (posing opens a gap; the
  fix is Overlap the joint); a part one block thick that turns, at a pixel a
  block; a part going with nothing beside a part that moves (it stays
  behind); an action whose different keys land on one step; a one-block
  detail that drops out in some directions on the frames a render makes; a
  part reaching past the frame; and, as notes, two parts named for each
  other's side (`Arm L` and `Arm R`) that aren't twins (`not_twins`) and Rig
  it's guesses. Each row has
  its `kind`, its `text` (the words the list shows), the `part`, `action` and
  `frame` it is about, its `fix` (`do`: `overlap`, `keep_details`, `steps`,
  `go_with` or `pair_by_names`, the button's `label`, and what it is carried
  out with: `action`
  and `steps`, `free` or a count, for `model_action` `set`; `with`, the part
  to go with for `model_part`'s `parent`, or the part overlapped;
  `pair_by_names` is `model_part`'s `pair_by_names: true`, which links every
  such pair; Overlap the
  joint and Keep 1-block details are the user's buttons, and `render_model`'s
  `keep_details` keeps details in one render), `note` and `dismissed`; `count` is
  the warnings to look at. Rows dismissed on the model are left out unless
  `dismissed` is true.
  **`new_model`** `{ width?, height?,
  depth?, starter?, vox_path?, vox_base64?, example? }` gives the sprite a new, empty model (1-512 blocks a
  side), the starter house or one of Model mode's Examples… by name (`Oak`,
  `Fox`..., as it is), in place of the one it has, or brings a
  `.vox` file in as Import does: each object a part placed where its
  scene graph puts it (moved, turned, in its groups), named as its object is
  (else `Vox 1`, `Vox 2`... by its model), hidden when its object or its
  layer is, in a box that holds them all (a file without a scene graph stacks
  its models at their own corners); no size or `starter` goes with it, and a
  file of no blocks is refused. The answer's `note` says when a scene came in
  otherwise than placed: one wider than a model holds (512 a side) comes in
  stacked, every voxel kept; one placing more than 256 objects, its first
  256. A `.vox` or an example replaces the model: Import's join of a file's
  objects beside the model's parts, and Examples…' Add as parts, are the
  user's. **`model_shape`**
  `{ shape?, from, to?, sides?, face?, depth?, plane?, facing?, radius?,
  thickness?, colour?, op?, part?, smooth?, twin_mirror? }` adds,
  erases or paints a box, rounded box, ball, cylinder, cone, ramp, roof or
  ring between two corner blocks, in a named part (a new part's name is at
  most 40 characters). The box can also be given as Model mode's Box and
  Shape drags set it: `from` and its `sides` typed (`[x, y, z]` blocks, a
  negative one the other way), a footprint `from`-`to` on one layer pulled
  out `face` (`+x`, `-x`, `+y` or `up`, `-y` or `down`, `+z`, `-z`) `depth`
  layers or `"auto"` (the footprint's shorter side), or a footprint on a
  work plane, `plane` `{ axis, layer }` (pulled toward the axis's + side
  unless `face` says the other way, a layer thick unless `depth` says
  more). `facing` turns a ramp (`north`, `east`, `south`, `west`: the side
  it rises to), a roof (`x`, `z`: its ridge), a cylinder or a ring (`x`,
  `y`, `z`) or a cone (its tip, `+y`, `-y`, `+x` ...); `radius` rounds a
  rounded box (1-4) and `thickness` sets a ring's tube (0.1-1 of its
  radius). The answer says the box drawn: `from`, `to` and `sides`. On a part with a twin, what is drawn lands mirrored
  on the twin too, in the same step, as Model mode's twin mirror has it (a
  block added where the twin's cell is empty, a paint only on the twin's own
  blocks and only on the faces painted); `twin_mirror: false` keeps it on
  the part alone. The answer's `twin` and `twin_changed` say what changed
  there, `twin_missed` and a `note` what couldn't land (outside the box, or
  the model full) or why nothing did (left alone, or locked). A model with
  twins keeps its x plane where they stand mirrored as the box grows.
- **`model_carve`** `{ views, depth?, outline?, part?, at?, new_model?, smooth?, back?, bottom? }`
  carves a part from drawings, a pixel a block, as Model mode's Carve does:
  `views` is one to six `{ view, image_path | png_base64, flip? }` (`front`,
  `back`, `left`, `right` or `side`, `top`, `bottom`), each drawn as seen from
  its side. A block is solid where every drawing has a pixel, and each face
  takes the colour of the drawing looking at it. It goes in as a new part
  (centred on the floor, or its low corner at `at`), into the part `part` names
  (carved again in the box it was carved in, centred there on its floor, as
  Model mode's Remake carves it, the overlap its joint had made again; one
  with no box kept, or turned or scaled since, where it stands; its pivot,
  keys and parent kept; a new name is at most 40 characters), or as a new
  model of it alone (a part with a twin is carved alone, as the Carve card
  carves it: `model_part`'s `update_from` brings the twin along); the box
  grows to hold it and nothing else moves. With no
  back drawn, `back` says how the back is coloured: `sides` (the default: each
  row takes the colour the side drawings show at their back edge, so hair stays
  hair round the back of a head, whatever shade the top draws it in),
  `mirrored` (the front seen through, its face too; with no front drawn, the
  right side's, else the top's, the left's or the bottom's, the first of those
  drawn) or `plain` (one colour); `bottom` the same for an undrawn bottom
  (`sides`: the lowest row of the drawings beside it; `mirrored`: the top seen
  through, and with no top drawn the front's, else the right side's, the
  back's or the left's, the first of those drawn). The answer's `back` and
  `bottom` say what an undrawn one took (`back_from` and `bottom_from`: the
  drawing a mirrored one took where the one opposite isn't drawn either), and
  the part keeps it for Re-carve.
  A character carves in one call from the open sprite's layer folders
  instead, as Model mode's Carve a character does: `{ folders, place?, on?,
  at?, depth?, outline?, new_model?, back?, bottom? }`, `folders` `true` (every
  folder whose layers are named for the views they show: `front`, `side`,
  `top`...) or the folders' names. Each folder (Head, Body, Arm L...) is a part
  named after it, carved from its own layers; the parts line up as they are
  drawn on the canvas (each part's front where it stands in the character's
  front, each side where it stands in its side) and are rigged among
  themselves as `rig_model` rigs them (what goes with what, pivots at the
  joints, joints overlapping, IK on two-part limbs). The character goes in
  `place` `drawn` (the default: lined up with the parts carved from the
  sprite's layers before; with none, centred on the floor) or `floor` (the
  box grown about its middle where it must, as the card's Floor middle grows
  it); `on` a part (standing on its top, centred, its root going with it;
  one folder's part turning about its bottom's middle); its low corner
  `at`; or as a new model. `part` and `smooth` are one part's, and refused
  with `folders`. The answer lists each `part` (`blocks`, `box`, `goes_with`,
  `pivot`), the `root`, `ik_limbs` and `moved` (how far the model moved over
  to make room). One undo step, `Agent: carve a character`
  (`Agent: new model from a character carve` with `new_model`, or when the
  sprite has no model yet).
- **`model_character`** `{ plan, height?, thickness?, head?, body?, arms?,
  legs?, ears?, tail?, joints?, colours?, into? }` makes a rigged voxel
  character to start from, already walking, as Model mode's New › Character
  does: `plan` is `chibi` (a fox kit, about 2½ heads), `tall` (a hare),
  `four_legs` (a fawn), `round` (an owl), `small` (a hedgehog) or `heavy` (a
  bear), or the animal's name (`fox_kit`, `hare`...). Its parts are named
  Hips (a control: no blocks, the root that carries the whole character),
  Pelvis (the hips' blocks, going with Hips), Body, Head, Ear L/R, Arm L/R
  (the owl's Wing L/R), Leg L/R, Tail (on four legs Front leg L/R and Back
  leg L/R) and Eyes shut (a blink's lids, going with Head: resting hidden,
  shown on Idle's frame before its last); Body and the legs go with Pelvis
  (on four legs the back legs and the tail; the front legs go with Body, and
  on two legs the tail too). Every L/R pair comes linked as twins
  (`get_model`'s `twin`), the mirror plane at the body's middle, so what
  `model_shape` draws or `model_colour` shades on one lands mirrored on the
  other, and a pivot `model_part` gives one moves the other's, unless
  `twin_mirror` is `false` (added as parts, a pair stays twins only where it
  still mirrors across the model's plane). `joints`
  `knees_and_elbows` puts each long enough limb in two parts (Forearm, Shin,
  Front shin, Back shin), and is refused, saying why, where no limb would
  bend: the owl keeps each limb in one part (its wings fold whole and its legs
  step without a knee), the hedgehog each leg. Each goes with the
  part it hangs from and turns about its joint, which overlaps a block so a
  bend never opens a gap; it faces +z, so the S sprite shows its face, and
  comes with Idle (a breath a second and a blink, 4 frames at 4 fps) and
  Walk at 12 fps (Walk on show). The sizes are blocks as the tab shows them:
  `height`
  (16-48) and `thickness` (2-4: a one-block limb breaks into dots as it
  turns) first (the rest then within what they leave, as the tab takes them),
  then `head`, `body` (its width), `arms` (front legs, wings), `legs` (back
  legs) and `ears`, set together as named, in any order, the ones not named
  making room where they must, as the tab's sliders do (an error names the
  first one named that can't be, and its reach with the others named).
  `tail` is `none`, `short` or `long`;
  `colours` `{ fur?, belly?, dark? }` are `#rrggbb`. `into` `new_model` (the
  default) replaces the model; `parts` adds its parts beside the model's
  (taken names get a number; its Walk joins the action on show, a namesake
  its namesake, the rest come as their own: `actions_joined`). The box grows
  to hold them, both ways across a plane the model mirrors across (a
  character's Head and Body mirror x), the model's own parts and lamps moving
  over with it: `moved` says how far, `[dx, dy, dz]` (left out when nothing
  moved), and the answer's `model` gives their new boxes; where only a box
  grown one way would fit (past 512 both ways), it is refused, naming the
  parts that mirror. The sprite keeps its size: `sprite_fit` is the size that
  holds every pose.
- **`model_part`** `{ part?, parts?, action?, split_from?, region?, goes_with?,
  copy?, merge_down?, merge_into?, outline?,
  joint?, copy_keys?, pivot?, parent?, keys?, tracks?, smooth?, visible?,
  locked?, delete?, rest_turn?, rest_move?, rest_from_frame?, reset?, control?,
  frames?, frame_ms?, loop?, mirror_part?, twin?, update_from?, update?,
  pair_by_names?, mirror_plane?, axis?, twin_mirror?, limits?, chain?, shown?,
  rest_shown?, swap_with?, leave_swap?, socket?, held_by?, export_point? }` rigs and animates
  (`locked`
  keeps Model mode's tools, `model_shape` and `model_carve` off a part; `parts`, in place of `part`, names
  several at once, as picking them in PARTS does, and `visible`, `locked`,
  `parent`, `delete`, `reset` or `rest_from_frame` act on every one as one
  undo step whose pill counts them: `Agent · 3 parts locked`; the action's
  motion, `frames`, `frame_ms` and `loop`, goes in a call without `parts`). `copy: true`
  puts a copy just after the part (`Roof copy`, its keys in every action);
  `merge_down: true` merges it into the part after it in the tree, and
  `merge_into` into the part named (its blocks where they stand in the model;
  what went with it goes with that part); `outline` `false` draws it without
  its outline (no line on it or round it: eyes and small gear), `true` with.
  Each of the four is given alone with `part` (any other key refused), one
  step. The rest pose
  is where a part stands with no key: `rest_turn` and `rest_move` (`[x, y,
  z]`, degrees and blocks) set it, as the PART card's REST numbers do, and
  every action's keys of the part are worked out about the new rest, so its
  motion keeps its shape, while everything that goes with it is carried with
  it at rest and on every frame (the answer's `rekeyed` says whether keys
  changed, for `rest_from_frame` and `reset` too; `rest_move` is -1024 to
  1024 blocks on each axis; not with `keys` or `tracks` in the same call;
  keys worked out again keep within each part's joint limits about its new
  rest, the answer's `limited` saying when they held any back). `rest_from_frame` makes a frame's pose (of
  `action`, as it draws it: its turns on its steps, its moves on whole
  pixels) the rest, its keys as they were (its joint limits' ranges moving
  with the rest) and what goes with it staying
  where it stands (a part going with it keeps within its own joint limits,
  `limited` saying so); it is refused, changing nothing, where a frame would
  then draw a step or a pixel off (a turn exactly half a step from two
  drawings, or an action on other steps), the error naming the frame;
  `reset` keys each property it has keys on at its rest on
  a frame (no step when it stands at rest there). `control: true` makes a
  control, a part with no blocks that carries what goes with it and renders
  nothing: by a new part's name it is made, and an empty part's name makes
  it one, its pivot on the floor's middle unless `pivot` says (a template's
  Hips is one; its blocks are the Pelvis
  that goes with it). `get_model` gives each part's `rest` (`{ turn, move }`)
  and whether it is a `control`. `split_from` + `region` (`{
  from, to, shape?: box | ball | cylinder, axis? }`) takes a part's blocks into
  a new part, rigged as Model mode's Split off rigs it (a wheel: a cylinder
  along `x`). It goes with the part it came from (`goes_with`, default true;
  `false`: with what that part goes with), turns about the joint where they
  touched (`pivot` defaults to `joint`; a point is put where its blocks stay)
  and has no turn or move keys (going with its part it takes the part's
  Shown keys, so a piece of a blink still blinks; `copy_keys`, with
  `goes_with` false, takes that part's keys in every action, and its
  pivot). `joint` is how it meets that part: `overlap`
  (the default about the joint) keeps a copy of the touching layer inside it,
  hidden at rest, so a bend never opens a gap; `flush` is a plain cut (the
  default about anything else, a wheel at its centre, and where they don't
  meet face to face); `rounded` trims its end round the joint (with `pivot`
  `joint`, and an end of it facing that part: not a limb lying along it). A
  joint that can't be made is refused; with nothing of that part within 8
  blocks it turns about its centre (`joint` is refused then). Left out, `part`
  is named by where it sits (`Head` above, `Arm L` or `Arm R` at the sides,
  `Leg L` or `Leg R` below, `Tail` behind), and the answer's `part` and
  `split` say what it made (`split`: its `pivot`, the preset that put it there
  as `pivot_at`, the `joint` made, a joint that made nothing being `flush`,
  whether it `met` that part, how many blocks `overlapped` and `trimmed`, and
  its `keys`: `copy` with that part's keys, `shown` with its part's Shown
  keys, or `none`). `pivot` is what it
  turns about (`[x, y, z]`,
  or a preset in the part's own terms, whichever way the view looks: `centre`,
  `top`, `base`, `joint`, `front`, `back`, `its_left` or `its_right`; a
  character faces +z, so its left is +x, the side on the S sprite's right;
  `joint` is where it touches its `parent`: the middle of that, or for a limb
  lying along it the end it hangs from, an arm hanging against a body at its
  shoulder, the top of where they meet; `parent` given before or in the same
  call; on a part with a twin the twin's pivot moves with it, mirrored, as
  in Model mode, unless `twin_mirror: false`, given only with `pivot`, and
  the answer's `twin` and `twin_pivot` say so) and `parent` what it moves
  with; `keys` (`[{ frame,
  rotate?, move?, ease?: in_out | linear | hold | smooth | ease_in | ease_out }]`) pose it on frames of an
  action's motion (the one on show, or `action`), which `frames`, `frame_ms`
  and `loop` set; the blocks, pivots and parents are every action's. A
  part's motion is six tracks (`turn_x` … `move_z`), each keyed on its own:
  `keys` sets them from whole poses, `tracks` (`{ turn_y: [{ frame, value,
  ease? }], … }`) sets only the ones it names. `hold` stays put, then jumps on
  the next key. Turns are degrees about x, then y, then z: +x rolls a wheel
  forward. A loop runs from the last key back to the first, so a wheel keyed 0
  on frame 0 and 315 on frame 7 of 8 turns round and round; a track's one key
  holds on every frame. `delete` takes the part away: the parts that went with
  it go with what it went with (`now_with`; on their own if nothing), each
  where it stands, and its motion is baked into their keys on every whole
  frame of every action (`baked`), so they keep their pose; `children` names
  them. Twins and the mirror plane, each given on its own (with `part`):
  `mirror_part: true` is Model mode's Mirror part, the part's other side
  made across the model's x mirror plane and linked to it as its twin (its
  blocks and pivot mirrored, going
  with the twin of what it goes with, its name's side swapped, `Arm L` to
  `Arm R`, a name with no side taking ` R` and the part ` L`, and every
  action's keys mirrored: Turn X stays, Turn Y, Turn Z and Move X go the other
  way; the answer's `made`, `from`, `renamed` and `plane` say what it did, and
  a part with its other side already is refused: `update_from` updates it);
  `twin` names the part's twin (`null` or `""` unlinks it; links either part
  had to another are let go, and the answer's `unlinked` names those parts);
  `update_from` puts the part back as that part mirrored, from its twin or
  the part its name's other side names only (`update`, given only with it:
  `blocks`, its blocks and pivot, the default, or `blocks_and_keys`, its rest
  and every action's keys too); `pair_by_names: true`, with no part, links
  every pair named for each other's side (`Arm L` and `Arm R`), as CHECK's
  Pair by names does; `mirror_plane` moves the plane square to `axis` (`x`,
  the default, `y` or `z`, given only with it) to `box_middle`, `part_middle` (of `part`) or a
  number of blocks within the box, to the half block, as the plane's tag in
  Model mode does (`Agent: mirror plane at x 9.5`; where it stands already, a
  `note` and no step). With the twin mirror on (the default), a build or a
  paint on one twin in Model mode, and `model_shape`, lands mirrored on the
  other. `get_model` names each part's `twin` and the plane, `mirror_at`
  (`[x, y, z]` in blocks: the box's middle until it is put elsewhere); its
  `mirror` is a part's own Mirror X, Y and Z, which `model_part` doesn't set.
  `limits` sets a part's joint limits, as the PART card's LIMITS does: `free`
  (none), or `{ x?, y?, z?, hinge? }` over those it has, each Turn axis
  `[low, high]` degrees from its rest (low -180 to 0, high 0 to 180: the rest
  lies within it), `locked` (it stays at its rest) or `free`, and `hinge`
  `x` (it bends about X alone: Y and Z locked) or `false` (every lock off).
  Every key writer keeps to them from then on: `model_pose`, Model mode's
  rings (a ring stops at a limit, a locked one refuses), and this tool's
  `keys` and `tracks` (the answer's `limited` and `note` say when they were
  kept within them). `chain` `make` makes an IK chain of the part and the
  part it bends with (a forearm or a shin with what it goes with, else the
  part with the first part going with it: Model mode's Make a chain; one
  step, `Agent: IK on Leg L`), `remove` takes the chain it is in away (its
  keys stay). A chain goes by itself when either part is taken away or goes
  with something else (a delete, a merge, a re-parent or a hold): the
  answer's `ik_removed` and the pill say so (`IK on Leg L
  removed: its shin now goes with Hips`). `get_model` lists the `chains` and
  each limited part's `limits`.
  Shown keys, swaps and held things, each given alone (with `part`):
  `shown` `{ frame, on }` shows or hides the part from that frame (from 0) of
  `action` on, Model mode's Shown row: a stepped track apart from its turns
  and moves, before its first key as the part rests (a blink is an `Eyes
  shut` part shown for one frame, as the character templates' Idle has it);
  on a part of a swap group, `on: true` shows it alone from there, the
  others hidden, as far as the group's next change (the POSE card's chips:
  `Agent · Mouth: Smile from frame 6 to 8`; the answer's `to` is the run's
  last frame), and `on: false` hides it only where none of the group shows
  (a socket's `empty`; a mouth always shows one of its parts).
  `rest_shown` says whether it shows as the model rests and on every frame
  no Shown key covers (the eye, `visible`, stays the editing hide, never
  keyed); a swap group's part rests as its one choice, the others hidden
  (`false` only for a socket's props), each keyed frame showing as it did. `swap_with` groups the part with the part named, shown one at a
  time (a mouth's Open, Shut and Smile; the one joining rests hidden while
  another rests shown, and a group it leaves for the other's, when it was
  that group's part resting shown, rests as its first), `leave_swap: true`
  takes it out (it rests as it did, the answer's `rests_shown` saying
  which; the group, when it was its part resting shown, rests as its
  first; after either, the answer's `rests_shown_now` names a part that
  came to rest shown so, as the pill does). A group that rested with none shown, as a blink's lids do, keeps
  resting so whichever part leaves it (deleted, merged, held or swapped
  away too): a lid never comes to rest shown by itself. `socket` makes a
  socket on the part (Model mode's `+ ▾ › Socket on`): a control named `{part}
  socket` going with it, at `[x, y, z]` (a point of the model as it rests)
  or the middle of a side of its blocks (`top`, `bottom`, `front`, `back`,
  `left`, `right`: its left is +x); `held_by` puts the part in that
  socket's hand: it goes with the socket, its pivot at the socket and its
  grip kept, the hand's pose carrying it on every frame (props on one socket
  are a swap by themselves: `Hand R: Sword · Torch · empty`); `export_point`
  marks a control a point (a socket is made one): `render_model` keeps each
  point as a slice keyed on every frame it renders (its answer's `points`).
  `get_model` says each part's `shown` (`at_rest` and its `keys` as `[frame,
  shown]`), `socket` and `point`, the model's `swaps` and `lamps_with`.
  No two parts share a name, letters' case aside, and a part is found by its
  name either way.
- **`model_pose`** `{ key? | reset? | mirror? | ik? | pose? | save?, part? |
  parts? | all?, frame, action?, reach?, keep_foot?, flip?, plant?, at?,
  amount?, mirrored?, mine?, to? }` poses the model on one frame (from 0) of
  an action (the one on show unless named), one of six a call:
  - `key` `six` keys `part`, the `parts` named or `all` of them on all six
    tracks (Turn X, Y, Z and Move X, Y, Z), `turns` on their three turns
    alone, each at its value there, so the frame stands as it did and a key
    there already stays as it is: Model mode's K, Shift+K and the posing
    bar's Key ◆. A turn an older key (made before a joint limit) has past
    that limit there keys at the limit instead, so the frame changes there,
    and `stopped` says where (`Shin L's Turn Y stops at 0°`). A part with no
    blocks yet that is not a control is left out (`skipped`); a control,
    such as a character's Hips, is keyed like any part. The answer names
    the parts `keyed` and the `tracks`.
  - `reset` `true` puts `part`, `parts` or `all` back at rest there, each
    property they have keys on keyed at its rest value (the posing bar's and
    the POSE card's Reset).
  - `mirror` `twin` puts `part`'s pose there on its twin, mirrored across the
    x plane (Turn X stays; Turn Y, Turn Z and Move X the other way), as the
    POSE card's Mirror to does; `whole` swaps every pair of twins on that
    frame and mirrors the parts with no twin where they are (a head turned
    left turns right). Each property that stands elsewhere is keyed there.
  - `ik` names a part of an IK chain (`get_model`'s `chains`: an arm and its
    forearm, a leg and its shin), its upper or its lower, with one of:
    `reach` `[x, y, z]` puts the chain's end (its lower part's tip: a shin's
    sole under the knee) at that point in the model's blocks, both parts
    turned and keyed on the frame (the lower on its hinge's turn alone, Turn
    X for a knee), the bend kept as posed, within their joint limits; out of
    reach the limb straightens toward it (the answer's `reach`, the distance
    over the limb's length, and `out_of_reach`; a target too near for the
    bend to fold to is `out_of_reach` too, with `off_by`, the blocks the end
    stays off); at a joint limit the upper
    aims for the bend the limits keep, and `stopped` says where (`Shin L
    stops at 90°`); `keep_foot: true` keeps the
    lower part's first child (a foot) turned as it stood (with none, a
    `note` says it did nothing). `flip: true` bends it the other way, the
    frame re-posed with its end where it was (Flip bend); where the other
    way is past a joint limit (or its end would move) nothing is keyed and
    the chain keeps its way: `changed` and `flipped` false, `stopped` saying
    why (`Shin L stops at -10° · it can't bend the other way`). `plant` `[from,
    to]` holds its end where `frame` puts it (or `at`, `[x, y, z]`) on every
    frame of the range, each solved under the body's motion and keyed, so a
    foot stays put while the body walks on (the Plant pin; the answer's
    `keys` counts a part keyed on a frame once, `missed` the frames a joint
    limit or the reach kept its end off, with `stopped`; planted there
    already, nothing changes, and `missed` and `stopped` still say the
    frames held off).
  - `pose` names a pose of the pose library (Model mode's POSES under the
    POSE card) to key on `part`, `parts` or `all` (the default: every part):
    the model's own first (`get_model`'s `poses`; a character template comes
    with Stand, Contact, Pass, Jump, Sit and Wave), else My poses (the
    app-wide library, by part name, so a pose there fits any character with
    parts so named; `mine: true` looks there alone). A pose holds each part's
    six values as the change from its rest, put on this part's rest, every
    turn the way round nearest where it stands and within its joint limits.
    `amount` (0 to 1, default 1) blends it in that far from where the parts
    stand (a drag on a thumbnail); `mirrored: true` puts each side's values
    on the other side, mirrored across x (Alt+click). The answer names the
    parts `keyed` and where the pose came `from` (`model` or `mine`).
  - `save` keeps the pose `part`, `parts` or `all` (the default) hold on the
    frame under that name, made unique: `to` `model` (the default) into the
    model's library, `mine` into My poses (the app's own, kept with its
    settings: no undo step).

  Each is one undo step in Model mode, named for what it did (`Agent: key the
  pose of 9 parts`, `Agent: reset Arm L`, `Agent: reach with IK on Leg L`,
  `Agent: plant IK on Leg L`, `Agent: the pose Wave`, `Agent: blend in the
  pose Jump`, `Agent: save the pose Lean`), none when the frame stands so
  already (`changed: false` and a `note`).
- **`rig_model`** `{ do?, leave_out?, include?, joint?, joints?, rerig? }` is
  Model mode's Rig it: the parts made a rig in one step, from the root out (a
  part named Hips, Pelvis, Body, Torso or Chest, in that order, else the
  biggest part, a guess). Each part goes with the part it touches most (one of
  the kind it hangs off first, a forearm its arm; what it meets at its end
  before what it lies along), turns about the joint where they meet (an arm
  hanging against a body about its shoulder, the top of where they meet), a
  `Part N` is named by where it sits (`Head`, `Arm L`, `Leg R`, `Tail`;
  `Forearm L` down an arm), and each joint is made `overlap` where they meet
  face to face, else `flush`. `do` `preview` (the default) lists the rows and
  changes nothing: each row's `part`, the `name` it gets, `goes_with`, `pivot`
  (null: as it is), `joint`, how they `meets`, `guess`, a `warning` where
  posing would open a gap, a `note`, `changes_motion`, `ticked`, `blocked`
  (it can't go with what its row says while that goes with it, a row upstream
  left out: `apply` leaves it as it is) and `said`.
  `apply` makes the
  ticked rows, but those in `leave_out` (by a part's name, as it is or as its
  row gives it), as one step, and chains each forearm with its arm and each
  shin with its leg for IK (`get_model`'s `chains`), each elbow and knee so
  chained, where its turns were free, left to bend on the turn nearest its
  bend at rest, the other two locked: the joint limit `hinge` `x` for a knee
  or an arm hanging down, Y alone for an arm held straight out to the side;
  an arm held out at a slant (its bend 25° or more off every turn) keeps its
  turns free, and IK bends it about its own bend (the
  preview's `chains_due` counts them, the answer's `chains_made` those it
  made; over a rig, chaining limbs alone, with no row ticked, needs no
  `rerig`). A part with keys of its own that would go with
  a part that moves starts unticked (its motion would change) and keeps its
  pivot: `include` ticks it. `joint` sets every row's joint where Rig it can
  make it (`overlap` and `rounded` need them to meet face to face, the part
  turning about the joint; `rounded` an end of it facing what it goes with),
  the other rows keeping the one offered (`kept_joint` lists them); `joints`
  sets one row's (`{ "Leg L": "rounded" }`), refused, saying why, where it
  can't be made (and on the root's row). Over a model rigged already (a part
  goes with another), `apply` needs `rerig: true`.
- **`model_action`** `{ do?, action?, name?, copy_of?, steps?, whole_pixels?,
  from?, offset?, stride?, bob?, arm_swing?, tail_sway?, frames?, breath?,
  sway?, replace?, sprite?, actions?, leave_out?, frame?, times?, ms?,
  timing?, span?, onto?, parts?, tracks?, ease? }`:
  the model's actions, named motions such as Idle and Walk, sharing its parts
  and each with its own keys, frames, speed and loop, and its own steady
  pixels. `do` is `list` (the default), `add` (no keys, the frames and speed
  of the one on show, or `copy_of` another, keys and steps too; the one on
  show stays), `rename`, `delete` (a model keeps one), `show` (the one Model
  mode shows and edits, and the one the other tools use when told none; not
  an undo step) or `set` (an action's steps and whole pixels; `action`, else
  the one on show). `steps` is `free` or 8, 16 or 32 a turn: only the turn
  away from the rest is stepped, after easing, so each frame is a clean
  drawing; the keys keep their values and the glTF stays exact.
  `whole_pixels` lands the moves on whole pixels at the sprite's pixels per
  block, each part's pivot on the pixel grid. A new action is steady as
  Model mode makes one (16 steps a turn for a sprite up to 64 px, 32 above,
  and whole pixels) unless told otherwise; models from before and models
  built in code are free. `list` says each action's `steps` and
  `whole_pixels`. `other_side` is Make the other side: in `action` (else the
  one on show), each twin on one side (`from`: `left`, the default, or
  `right`) gives its keys to its twin, mirrored across the x plane, `offset`
  frames later round the loop (`half`, the default: a walk's second side in
  one call; `none`; or a number of frames, less than the action's); a part
  with no keys there gives nothing, and the answer's `other_side` lists the
  `parts` it changed. `walk` and `idle` are Model mode's A walk… and An
  idle…, for a rigged character (its legs found by name, else by its IK
  chains and twins; refused without two legs, saying so): `walk` takes
  `stride`, `arm_swing` and `tail_sway` (degrees) and `bob` (blocks), each
  landing on the action's Steps grid as the card's sliders do, and `frames`
  6, 8 or 12; `idle` takes `breath` (blocks) and `sway` (degrees). Each makes
  a new action (`name`, default `Walk` or `Idle`, made unique), steady, and
  shows it; with `replace: true` it replaces the keys of `action` (else the
  one on show), its name and steps kept. The answer's `made` says the action,
  its frames, the parts keyed and the values as they landed. `bring_in` is
  Bring in actions from…: `sprite` names another open sprite (its tab's
  name) whose model's `actions` (default all) come in, each an action of its
  own, its name made unique, with its frames, speed, loop and steps; each of
  its keyed parts goes onto the part here of the same name, else onto the
  twin of where its own twin went (mirrored across x where it stands on the
  other side); `leave_out` names its parts to leave out; moves are scaled by
  the ratio of the legs' lengths, so a short fox kit takes a tall hare's
  walk, and the first action brought in is put on show (the answer's
  `shown`). The answer's `brought` lists the actions, each row and the
  `scale`.
  Timing (Model mode's frame menu, its action menu and the keys' grips;
  MODEL3D_PART6_PLAN.md Phase 37), each in `action` (else the one on show):
  `hold` holds `frame` (from 0) `times` frame lengths (1: one frame again),
  or the nearest whole number of them to `ms`; its rendered sprites last so,
  and the exports with them (Godot's per-frame duration, the JSON's, Unity's
  keys). `timing` is `even` (every frame one frame long) or `attack` (long ·
  short · short · short · long · short spread over its frames, a long beat
  twice as long). `insert_frame` puts a frame in at `frame` (0 to the frames:
  their count adds one at the end) and `delete_frame` takes `frame` out (its
  keys go), every later key of every part's track, Shown's too, a frame
  later or earlier; the other actions are untouched. `stretch` stretches the
  keys from `span`'s first frame to its last (of `parts`, default every part;
  of `tracks`, default the six) `onto` a span that keeps one of its ends,
  about that end, in whole frames (refused where two keys of a track would
  meet). `ease` sets how keys run on (of `parts` and `tracks`, within `span`;
  by default every key): `smooth` (the motion carried through each key,
  never overshooting), `in_out`, `ease_in` (slow out, speeding in),
  `ease_out` (at speed, slowing in), `linear` or `hold`; `model_part`'s keys
  and tracks take the same words. Shortening an action keeps its late keys
  past its end (greyed in Model mode; lengthening it brings them back), and
  `drop_kept` lets them go. The answer's `timing` says what each did, and
  `list` says each action's `holds` (`[frame, times]`) and `kept_keys` where it
  has them. Names are up to 24 characters, no two alike.
- **`model_light`** `{ azimuth?, elevation?, intensity?, colour?, ambient?,
  ambient_colour?, lamps?, lamp?, goes_with? }`: the light a render bakes in. The sun is the
  document's (Lighting mode shows the same one), in the picture's terms:
  azimuth clockwise from the top of the sprite (315 is the upper left),
  elevation out of the picture towards the viewer (below 0: from behind). It
  stays put on screen as the model turns. `lamps` replace the model's lamps
  (`{ at, colour?, strength?, reach?, shadows?, goes_with? }`, at most 16);
  a lamp's `goes_with` names the part whose pose carries it from where it
  rests (a torch's flame with the torch: Model mode's lamp WITH). `lamp` (its
  place, from 0) with `goes_with` (a part, or `null`: on its own) sets one
  lamp's alone, one step (`Agent: lamp goes with`). With nothing given it
  tells the light as it is, each lamp's `goes_with` too.
- **`model_reference`** `{ action?, plane?, image_path?, png_base64?, name?,
  offset?, scale?, opacity? }`: the model's reference drawings, to build over
  (Model mode's Model › View › Reference…), one on each of the `front`, `side` and
  `top` planes. Each lies on the box's far side as its plane's view sees it
  (the front at z 0, the side at x 0 with its right toward −z, the top on the
  floor) and stands at first on the floor across the box's middle, one block
  a pixel, at 30%. It is never rendered: no sprite, export or check reads it,
  and the sprite's size never cuts it. `action` is `list` (the default),
  `add` (the image onto `plane`, in place of the one there: the answer says
  `replaced`), `place` (`offset` `[right, up]` in blocks from where it first
  stands, `scale` in blocks a pixel from 1/16 to 16, `opacity` 0.05 to 1) or
  `remove`; each change is one step (`Agent: reference on Front`), and every
  answer lists the drawings with each one's `span` on its plane.
- **`model_colour`** `{ replace?, swap_to?, from?, glow?, shade?, part?, block?,
  face?, steps?, twin_mirror?, variant?, delete?, on? }`: the model's colours across every
  part, as Model mode's COLOUR › IN THIS MODEL has them. Given nothing it
  reads them and writes nothing: `colours` (each one's hex, its `faces` in
  every part, hidden ones too, its `parts` and its `glowing` faces, the most
  used first), `variants` and the `palette` on show. One write a call, each
  one step: `replace` `{ "#from": "#to" }` every face of each in every
  unlocked part, all at once, each block's glow kept (`Agent: replace a
  colour`; a locked part keeps its own, `locked` naming it); `swap_to` a
  palette's name, the model's colours mapped onto it slot for slot from the
  palette on show (`from`: another), the answer's `pairs` and the colours
  that `stay`; `glow` `{ "#colour": true }` every face of it giving off its
  own light (unlit from every side, no darkened line, in a normal-map
  render's emission map), `false` taking the light again; `shade` `lighter`
  or `darker` on `part`'s `block` `face`, `steps` 1 to 8, along its ramp in
  the palette on show as Paint's Shade steps it, landing mirrored on the
  part's twin too in the same step (`twin_mirror: false` keeps it on the
  part; the answer's `twin` and `twin_changed`; the ramp's end, and a face
  another block of the part covers, refused);
  and `variant`, one of OUTPUT's VARIANTS: `{ name, colours, swaps, shown,
  on }` made or replaced by its name (`swaps` a swap group's pick by group,
  `shown` a part shown or hidden as the model rests), or a variant's name
  with `delete: true` or `on`. A variant renders the model otherwise
  (`render_model`'s `variants`) onto a hidden layer of its own, `Model ·
  Arctic`, and never changes it. `part`, `block`, `face`, `steps` and `twin_mirror`
  go with `shade` alone, `from` with `swap_to`, `delete` and `on` with a
  variant's name: given otherwise they are refused, never passed over. A
  glow's answer names the `locked` parts that keep their own.
- **`scale_model`** `{ by }`: the whole model twice as big (`2`) or half
  (`0.5`), one step (`Agent: scale the model ×2`): every part's blocks,
  pivots and rest moves, every action's Move keys (turns stay), sockets,
  lamps and their reach, the IK chains' tips, the mirror plane, the pose
  library's moves and the drawings, the box with them. ½ is refused where a
  part would lose blocks it can't halve (`Arm L is 3 blocks thick: ½ would
  break it`); it is exact where the blocks come in whole 2 × 2 × 2 cubes, as a
  ×2 leaves them. The answer gives the box (`size`), `tall` and `blocks`, and
  `capped` when something couldn't follow all the way and was held at its
  limit (a lamp's reach, 1 to 64 blocks; a drawing's scale, 1/16 to 16), the
  pill saying it too.
- **`render_model`** `{ into?, action?, actions?, names?, anchor?, ground_row?,
  directions?, angle?, tilt?, pixels_per_block?, outline?, by_lighting?,
  normal_maps?, lines_at_joints?, keep_details?, rest_light?, block_dither?,
  left_out?, tilts?, framing?, canvas?, sprite_size?, variants? }`
  turns the
  model into pixel art: every direction as frames with a tag each (every
  frame of the action's motion, at its own speed; `Walk S`, `Walk SW`... once
  there is more than one action), the last render updated in place, a
  turntable, the front view as a layer, or a new sprite. `into` is `update`
  (the last render's frames, tags and durations replaced on the same `Model`
  layer, its frames keeping their ids, a run's end growing or shrinking when
  its count changed, every other layer left as it is: fixes painted on a
  layer above `Model` stay; with nothing rendered yet, frames after the
  last), `after` (or `frames`, the default), `new_layer` (or `layer`),
  `turntable` or `new_sprite`. A fresh one-frame sprite with nothing drawn
  takes a render from its frame 1. `actions` (names, or `"all"`) renders a
  character sheet, action by action in the model's order, each at its own
  speed; `names` reads the tags `Walk S`, `walk_S` or `walk_down` (a model
  with one action keeps the bare `S`, `SW`...; two tags of one name are
  refused). What isn't given is the model's own, as the user's Render takes
  it: its `names`, its extra tilts and the directions it leaves out (with its
  own directions; with another `angle` asked, those facing as one it leaves
  out did, as the camera saved keeps them, so the same call twice renders
  the same sheet), and on an `update` the actions it has ticked, and the
  pixels per block, light (baked in, with normal maps, or by Lighting) and
  outline the last render was made with (a render recorded before this
  build: the model's own), so an update with nothing else asked renders again the sheet the
  last render made (an update rendered without normal maps clears those on
  its frames); any other render not asking them is fitted to the sprite
  (`pixels_per_block` 0), baked in and outlined. A `canvas` not asked is the
  model's own as OUTPUT shows it (its smallest square only with its pixels
  per block set, which it then takes).
  `actions` goes with `update`, `frames` or `new_sprite` only (a turntable, a
  layer or a picture renders one action). Model mode, open on the sprite,
  stays open with the render behind it; the answer says the `action` (the
  one rendered; null for a sheet of actions: asked with `actions`, or an
  update rendering the actions OUTPUT has ticked), the `actions`,
  `names` and `tags_made`, and the frames it put in and took out
  (`frames_added` and `frames_removed`: an update can do both). It renders
  from the model's sprite camera: its angle style, tilt and directions (2-64),
  as Model mode's header shows them. Those given become the model's sprite
  camera, one undo step in Model mode (`Agent: sprite camera`), so the next
  Render there uses the same sprite camera (its other settings, pixels per
  block and the rest, are the user's own); the answer says the
  `sprite_camera` it used. More of OUTPUT can be set for the render
  alone (Lock to the palette, the outline's Outside or Inside and the line's
  own colour stay the user's Render's: an agent's render draws without them): `left_out`
  (directions by name, one at least kept), `tilts` (more
  tilts), `framing` (`model`, centred on its blocks, or `box`), `canvas`
  (`sprite`, or `smallest_square` with pixels per block 1 to 6) and
  `sprite_size` (`[w, h]` or `"fit"`, the smallest that holds every
  direction as this render makes them, at its pixels per block, from its
  camera, tilts, framing, anchor and directions: the sprite resized round its middle
  first, or with `anchor` `feet` about the ground row, the frame's foot
  keeping its pixels and the row kept as the model's own, as Model mode's
  size card does, a step of its own, checked before anything changes); and `variants`
  renders OUTPUT's VARIANTS too, each onto a hidden layer of its own
  (`Model · Arctic`) over the same frames and tags, so the sprite and every
  flattened export show the model until its eye is opened (a new sprite: a
  sprite of its own each), an update replacing each on its layer, its eye as
  it was, and clearing on its frames the layer of one it no longer renders: `true` (the default) the
  model's ticked, `false` none, names of the model's, or variants given whole
  (`{ name, colours }`) for this render, two of one name refused. With a normal map, faces that glow
  come with an emission map too. The answer says the `variants`, `left_out`,
  `tilts` (those past the camera's own tilt it rendered: none from `iso`,
  each once), `framing`, `canvas` and `sprite_size` it rendered with. A
  layer, a turntable or a picture renders the camera's own tilt and leaves
  no direction out: `tilts` and `left_out` asked with one are refused, and
  its answer's `tilts` and `left_out` are empty. They keep the header's rules: a `tilt` names its
  style (0 `side`, 90 `top`, -90 `bottom`, anything else `three_quarter`), so
  `side`, `top` or `bottom` at a tilt not theirs is refused; `iso` has its own
  tilt and its 4 directions, so a `tilt`, or other `directions`, with it is
  refused. A refused render (an `action` the model hasn't got, a shared
  session) writes nothing, the sprite camera included. Steady pixels (Model
  mode's OUTPUT › MORE) are the model's own unless given for the render
  alone: `lines_at_joints` (false: between a part and the part it goes with a
  line needs the 1.5-block step it needs inside a part, so an elbow never
  flickers a seam line and an arm across the chest keeps its line),
  `keep_details` (a one-block painted detail that wins no pixel gets the
  pixel it covers most), `rest_light` (moving parts lit as they rest, so no
  face's shade pops mid-swing) and `block_dither` (the light's dither by the
  block a pixel shows, riding with the part). A character from
  `model_character` takes the cleaner look (no lines at joints, the other
  three on); models from before and models built in code render as they
  always did. The answer says the four it rendered with. `anchor` `feet` stands
  the floor point under the rest pose on one row and column of the sprite in
  every action, direction and tilt (the feet never hop), on `ground_row` (the
  sprite's row they stand on, 0 its top), and writes or updates the sprite's
  `Origin` slice with that point as its pivot, which the engine exports take
  as the sprite's origin; `middle` centres the model as before (a `middle`
  update, or frames, takes the `Origin` slice the last render wrote away).
  Left out, the model's own (a `model_character` anchors its feet). The
  answer says
  the `anchor`, the `ground_row` (where the feet stood, the `Origin` slice
  written or not) and the `points` it wrote: `points.Origin`
  (`{ x, y }`, where the feet stand) and each point ticked on OUTPUT's
  POINTS (a socket's, or a control's marked `export_point`) by its slice's
  name, `[{ x, y }, ...]` a sprite: a slice keyed on every frame it made (a
  point called `Origin` keeps `Origin point`), an update replacing the keys
  on its own frames and every render keeping the others' (a turntable
  writes none). `points` `{ name: true | false }` sets POINTS for this
  render by the same names, `Origin` the anchor's slice (a point called
  `Origin` goes by `Origin point`), the rest the model's own ticks.
  **`export_model`** `{ path }` writes it to an absolute path as `.glb` (parts,
  colours and each action as an animation named after it), `.obj` (with its
  `.mtl` and palette texture) or `.vox`. The answer says the `actions` the
  file carries and, for a model that anchors its feet, its `origin` (the
  floor point in blocks, kept in the `.glb` scene's `extras`) and
  `origin_pixel` (the sprite's `Origin` slice pivot). None of the three
  carries glow: a glowing face goes out in its colour, unlit, and the
  answer's `note` says so.

PixelAOI refuses changes while one of its dialogs or a filter is open, or while
you are drawing; the error says which, and the call can be made again after.
A change to the 3D model while the user holds a press waits for the let-go
instead, up to 25 s, and calls sent after it wait behind it, in order.

## Example

> "Take ./hero.png, pixelate it, put it on the canvas, then bake a noise
> texture behind it with a Canvas blueprint."

The agent calls `pixelate_image`, then builds CanvasNoise → CanvasOutput with
the Blueprint tools and runs `blueprint_bake`.

> "Draw a little red car from the front, the side and the top, make it 3D,
> spin its wheels, and give me sprites from eight directions and a .glb."

The agent draws the three views as PNGs and calls `model_carve`, then
`model_part` for each wheel (`split_from` the body with a cylinder along x,
`pivot` `centre`, so it goes with the body cut flush, keys turning it about
x), `model_light` for the sun, `render_model` for the frames and
`export_model` for the .glb.

> "Make me a hedgehog that walks, and give me its walk from eight
> directions."

The agent calls `model_character` with `plan` `small`, looks at it with
`look_model` (`direction` `all`), then `render_model` with `action` `Walk`.

## Config

- `PIXELAOI_BRIDGE_HOST` (default `127.0.0.1`)
- `PIXELAOI_BRIDGE_PORT` (default `48653`). PixelAOI reads the same variable
  when its link turns on, so to move the port, set it for both. On a moved
  port the token is in `agent-bridge-token-<port>`.
- `PIXELAOI_PROFILE`: the editor's profile, if it runs under one; it says
  which folder holds the token.
- `PIXELAOI_BRIDGE_TOKEN`: the token itself, in place of reading the file.

## If it can't connect

The error says what is wrong and how to fix it:

- **can't reach PixelAOI** or **agent link isn't on**: open PixelAOI and
  click **agent off** so it says **agent ready**. If it already says that and
  there is still no token file, the editor is older than the token handshake;
  update it. A PixelAOI running under `PIXELAOI_PROFILE` keeps its token in its
  profile's folder, so the server needs the same variable. A PixelAOI whose
  data folder the server cannot see (PixelAOI itself sandboxed, as a Flatpak
  or Snap app is) needs the token given to the server: set
  `PIXELAOI_BRIDGE_TOKEN` to the contents of its `agent-bridge-token` file.
- **the link to PixelAOI closed** while working: another agent connected with
  the token and took over (one agent at a time), or the link was turned off.
  Calls PixelAOI had not started yet are dropped, not run. Run one agent with
  PixelAOI at a time.
- **agent: port busy (retrying)** in PixelAOI's status bar: another PixelAOI,
  or another app, holds the port. PixelAOI tries it again every few seconds,
  so a port held for a moment frees itself. Otherwise close the other one, or
  move both to another port with `PIXELAOI_BRIDGE_PORT` (each port has its
  own token file).
- **refused the agent link** for any other reason (an old token, say): try
  again; the server reads the token afresh for every connection.

If the editor closes, or the link is turned off, while the agent works, the
next call reconnects once it is back. A call that times out may still be
carried out by PixelAOI once it catches up (say, after a dialog closes), so
the error asks the agent to look before running a change again.

## As a Claude Desktop extension

`manifest.json` and `icon.png` describe it as a Desktop Extension (its name,
icon, tools, and the editor's port as a setting: leave it at 48653 unless
PixelAOI runs with `PIXELAOI_BRIDGE_PORT`). Build the `.mcpb` with
`npx @anthropic-ai/mcpb pack` in this folder, then open it with Claude Desktop.

Get the editor at [pixelaoi.pro](https://pixelaoi.pro).

---
_Source: https://npm.io/package/pixelate-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
