Skip to main content
Glama

pixel_scene

Compose pixel art scenes or rooms from sprites, tilemaps, and lighting, then render them to images with placements, lights, and warnings for quick validation.

Instructions

Compose a pixel art scene or room from sprites, tilemaps and lighting. Renders a pixelforge-scene manifest (placements, autotiled tilemaps, cues, motion, ground sorting, camera and parallax, haze, lights and shadows; pixel_help topic scenes) at a time in milliseconds and returns the image, placements, lights and warnings. Assets may be inline recipes, files under the server root or {"revision": id}. view: depth shows who covers whom; export: true writes a replayable scene bundle; gif: {} the whole scene as one looping GIF.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "scene": "<scene>"
    },
    "name": "pixel_scene"
  }
}

Input Schema

NameRequiredDescriptionDefault
gifNoAlso write the whole scene as one looping GIF, through its duration once ({} for defaults).
litNo
timeNo
viewNo
scaleNo
sceneYes
exportNo
guidesNoPerspective guides: {horizon: row, vanish: [[x, y], …up to 3], iso: {tile: [32, 16], at: [x, y]}}.
densityNo
sequenceNoAlso write numbered PNG frames for a video editor: pixel_render's sequence options, without animation and step.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.17.0
    • addedInput schema / properties / gif
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Also write the whole scene as one looping GIF, through its duration once ({} for defaults).",
      +  "properties": {
      +    "fps": {
      +      "description": "Default 25.",
      +      "type": [
      +        "number",
      +        "string"
      +      ]
      +    },
      +    "scale": {
      +      "maximum": 16,
      +      "minimum": 1,
      +      "type": "integer"
      +    }
      +  },
      +  "type": "object"
      +}
  2. Changed5 schema fields changedv0.9.2
    • addedInput schema / properties / guides
      Added value: +{
      +  "description": "Perspective guides: {horizon: row, vanish: [[x, y], …up to 3], iso: {tile: [32, 16], at: [x, y]}}.",
      +  "type": "object"
      +}
    • removedInput schema / properties / sequence / additionalProperties
      Removed value: -false
    • changedInput schema / properties / sequence / description
      Previous value: -"Also write a numbered PNG sequence for a video editor into sequence/: one PNG per video frame with alpha, plus sequence.json and a README with the ffmpeg command for a .mov. The result reports timing changes and whether a loop closes on the frame grid."New value: +"Also write numbered PNG frames for a video editor: pixel_render's sequence options, without animation and step."
    • removedInput schema / properties / sequence / properties
      Removed value: -{
      -  "align": {
      -    "enum": [
      -      "top-left",
      -      "top",
      -      "top-right",
      -      "left",
      -      "center",
      -      "right",
      -      "bottom-left",
      -      "bottom",
      -      "bottom-right"
      -    ]
      -  },
      -  "background": {
      -    "description": "Palette name or opaque hex colour. Default: transparent.",
      -    "type": "string"
      -  },
      -  "fit": {
      -    "description": "contain (default): the whole sprite fits the canvas. cover: the smallest scale that covers the canvas; the overhang is cropped.",
      -    "enum": [
      -      "contain",
      -      "cover"
      -    ]
      -  },
      -  "fps": {
      -    "description": "Frame rate: 24, 25, 30, 60, or \"23.976\", \"29.97\", \"59.94\" (exact n000/1001), or a fraction such as \"30000/1001\".",
      -    "type": [
      -      "number",
      -      "string"
      -    ]
      -  },
      -  "loops": {
      -    "maximum": 1000,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  "offset": {
      -    "description": "[x, y] canvas pixels added to the aligned position.",
      -    "items": {
      -      "type": "integer"
      -    },
      -    "maxItems": 2,
      -    "minItems": 2,
      -    "type": "array"
      -  },
      -  "scale": {
      -    "description": "Whole-number enlargement. Default: the largest that fits the canvas, or 1 without a size.",
      -    "maximum": 256,
      -    "minimum": 1,
      -    "type": "integer"
      -  },
      -  "seconds": {
      -    "description": "Length of the clip instead of loops.",
      -    "exclusiveMinimum": 0,
      -    "maximum": 3600,
      -    "type": "number"
      -  },
      -  "size": {
      -    "description": "Canvas: 720p, 1080p, 1440p, 4k, vertical, square or WIDTHxHEIGHT. Default: the sprite at scale.",
      -    "type": "string"
      -  }
      -}
    • changedInput schema / properties / view / enum
      Previous value: -[
      -  "color",
      -  "grayscale"
      -]New value: +[
      +  "color",
      +  "grayscale",
      +  "depth"
      +]
  3. First observedv0.9.0

TDQS

A3.5/5.0
Behavior4/5

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

Annotations only declare the generic profile (readOnly=false, idempotent=false, destructive=false, openWorld=false); the description adds the substantive behavior an agent needs: it renders at a given time in milliseconds, returns image/placements/lights/warnings, and writes files when export, gif or sequence are set. That file-writing side effect is the key non-obvious trait and it is disclosed, though no note on cost, determinism, or how long a full GIF render takes.

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

Conciseness3/5

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

The purpose sentence is front-loaded and strong, but the following sentences are dense semicolon-and-parenthesis stacks that pack many concepts into single lines, making the option semantics harder to scan than a short list would be. Little is redundant, yet the structure sacrifices readability for compression.

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 a 10-parameter, nested-object tool with no output schema, the description does the essential work of naming the return payload and the main output modes. It is still incomplete on several parameters and on the practical limits of the heavier modes (GIF/sequence rendering over the 60s time cap), which an agent would need before committing to a call.

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

Parameters3/5

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

With only 30% schema description coverage across 10 parameters, the description has to compensate, and it partially does: it explains time (milliseconds), view depth, export, gif, and what the scene manifest may contain (placements, autotiled tilemaps, cues, motion, ground sorting, camera and parallax, haze, lights and shadows). It says nothing about scale, lit, density, guides, or the remaining view enum values, and the nested sequence object is deferred entirely to pixel_render.

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?

States a specific verb and resource: 'Compose a pixel art scene or room from sprites, tilemaps and lighting', then names the input artifact (pixelforge-scene manifest) and the outputs (image, placements, lights, warnings). It does not explicitly contrast itself with the close sibling pixel_render, leaving the boundary between 'render' and 'compose a scene' partly inferential.

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?

Useful per-option cues are given ('view: depth shows who covers whom', 'export: true writes a replayable scene bundle', 'gif: {} the whole scene as one looping GIF'), plus a pointer to pixel_help topic scenes. However there is no statement of when to prefer this over pixel_render or pixel_validate, and no prerequisites or failure conditions are described.

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