Skip to main content
Glama

pixel_compile

Idempotent

Compiles pixel-art animation, effects, fluid, terrain or lighting sources into an ordinary recipe revision and returns a contact sheet, with optional metadata for joints, timing, masks and counts.

Instructions

Build a character animation from parts (bipeds and four-legged animals, with idle, walk, trot, run, jump, attack and hurt templates, squash and tweens), a terrain tileset, particle effects (sparks, embers, dust, a sprite dissolving or teleporting away pixel by pixel) and spell shapes (slashes, shockwave rings, beams, lightning, magic circles, impact stars, fireballs, cel water streams and drops, auras hugging a sprite, smears trailing a sword tip), simulated smoke, fire, explosions, steam, magic swirls, water (splashes, waterfalls, drips, bubbling potions) and thick liquids (honey, slime, mud), rigid bodies (balls and blocks that bounce, stack, topple and rest, with joints, ropes and cloth), growing crystals (quartz clusters, geodes, cubes, snowflakes), falling-sand sandboxes (burning, collapse, lava meeting water, blasts), coherent interference and portal loops, or a lighting normal map. Compiles the source into an ordinary recipe revision and returns a contact sheet; metadata: true adds pose joints, contacts and timing, the autotile mask table, particle counts, fluid figures, wave counts, crystal counts, body paths, joint breaks, cloth tears or normal directions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "pixel_compile"
  }
}

Input Schema

NameRequiredDescriptionDefault
sizeNoA canvas size such as "32x32" for the compiled drawing: cut to the window holding the most of it, or given margins; never scaled.
framesNoKeep this many evenly spaced frames of each animation that has more, playing as long as before. The way to fewer frames: lowering frames in a source cuts the effect short.
presetNoInstead of source: a shipped preset by name, such as "smoke-puff" (pixel_help topic presets).
sourceNoA pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave, pixelforge-crystal, pixelforge-powder, pixelforge-bodies or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {"revision": id}.
metadataNo
sequenceNoBodies only: write numbered PNG video frames (pixel_render's sequence options, animation naming the effect) instead of a recipe; a match may run past 256 frames.
animationNoKeep only this animation (or these) of a source or preset that makes several.
draftViewsNoPoses only, instead of compiling: draft grid parts turned to these angles, {"boot": [30, 330]}, as views to correct and paste into parts.<name>.views, with a comparison sheet.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.15.0
    • addedInput schema / properties / animation
      Added value: +{
      +  "description": "Keep only this animation (or these) of a source or preset that makes several.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": [
      +    "string",
      +    "array"
      +  ]
      +}
    • addedInput schema / properties / draftViews
      Added value: +{
      +  "additionalProperties": {
      +    "items": {
      +      "maximum": 359,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "maxItems": 16,
      +    "type": "array"
      +  },
      +  "description": "Poses only, instead of compiling: draft grid parts turned to these angles, {\"boot\": [30, 330]}, as views to correct and paste into parts.<name>.views, with a comparison sheet.",
      +  "type": "object"
      +}
    • addedInput schema / properties / frames
      Added value: +{
      +  "description": "Keep this many evenly spaced frames of each animation that has more, playing as long as before. The way to fewer frames: lowering frames in a source cuts the effect short.",
      +  "maximum": 256,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / size
      Added value: +{
      +  "description": "A canvas size such as \"32x32\" for the compiled drawing: cut to the window holding the most of it, or given margins; never scaled.",
      +  "type": "string"
      +}
    • changedInput schema / properties / source / description
      Previous value: -"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave, pixelforge-bodies or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {\"revision\": id}."New value: +"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave, pixelforge-crystal, pixelforge-powder, pixelforge-bodies or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {\"revision\": id}."
  2. Changed2 schema fields changedv0.12.1
    • addedInput schema / properties / sequence
      Added value: +{
      +  "description": "Bodies only: write numbered PNG video frames (pixel_render's sequence options, animation naming the effect) instead of a recipe; a match may run past 256 frames.",
      +  "required": [
      +    "fps"
      +  ],
      +  "type": "object"
      +}
    • changedInput schema / properties / source / description
      Previous value: -"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {\"revision\": id}."New value: +"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave, pixelforge-bodies or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {\"revision\": id}."
  3. Changed2 schema fields changedv0.11.0
    • addedInput schema / properties / preset
      Added value: +{
      +  "description": "Instead of source: a shipped preset by name, such as \"smoke-puff\" (pixel_help topic presets).",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "source"
      -]
  4. Changed1 schema field changedv0.10.0
    • changedInput schema / properties / source / description
      Previous value: -"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave or pixelforge-normals document (see pixel_help topics). A normals source's recipe may be inline, a file under the server root or {\"revision\": id}."New value: +"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave or pixelforge-normals document (see pixel_help topics). A normals source's recipe, or an fx symbol's {recipe, frame}, may be inline, a file under the server root or {\"revision\": id}."
  5. Changed1 schema field changedv0.9.2
    • changedInput schema / properties / source / description
      Previous value: -"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid or pixelforge-normals document (see pixel_help topics). A normals source's recipe may be inline, a file under the server root or {\"revision\": id}."New value: +"A pixelforge-poses, pixelforge-autotile, pixelforge-fx, pixelforge-fluid, pixelforge-wave or pixelforge-normals document (see pixel_help topics). A normals source's recipe may be inline, a file under the server root or {\"revision\": id}."
  6. First observedv0.9.0

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=false, idempotent=true, destructive=false), the description discloses concrete outcomes: a compiled recipe revision plus a contact sheet, extra diagnostics under metadata, and that `sequence` writes numbered PNG video frames to disk as a side effect that may exceed 256 frames. It does not discuss failure modes or permission/size limits, but it adds real behavioral value on top of the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentence is a sprawling ~150-word catalog of every possible asset type before the reader learns what the tool actually does. The key statement (compile to a recipe revision, return a contact sheet) arrives last, so the description is badly back-loaded and repetitive with the listed parameter descriptions.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter tool with nested objects and no output schema, the description does explain the return artifact (contact sheet, recipe revision, optional metadata report), which is the biggest gap it could fill. It still leaves the relationship to pixel_render/pixel_scene and error behavior unstated, so it is adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 88%, so baseline is 3, and the description goes beyond it by explaining what `metadata: true` actually returns (pose joints, contacts, timing, autotile mask table, particle/fluid/wave/crystal counts, joint breaks, cloth tears, normal directions) even though the schema leaves that parameter undocumented. It also clarifies the accepted source forms (inline, file under server root, or {revision: id}) and the draftViews workflow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The core action is stated precisely: "Compiles the source into an ordinary recipe revision and returns a contact sheet." The resource scope is broad but concrete (poses, tilesets, fx, fluid, waves, crystals, powder, bodies, normals). However, the actual verb+object is buried at the end of a very long enumeration, and no sibling (pixel_render, pixel_scene) is named to differentiate the tool from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied through per-parameter notes: `preset` is "Instead of source", `draftViews` is "Poses only, instead of compiling", and `sequence` writes video frames "instead of a recipe" for bodies only. These are useful branch conditions, but there is no overall statement of when to call pixel_compile versus pixel_render or pixel_scene.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.