godot-sprite-mcp

Overview Schema Source Related Servers Discussions Admin

build_sprite_frames

Create a Godot 4 SpriteFrames .tres resource from spritesheet atlas regions, defining animation names, frame rectangles, FPS, and loop settings for use in Godot projects.

Instructions

Create a Godot 4.x SpriteFrames .tres resource from atlas regions.

This writes a format=3 Godot 4 resource. The image must live inside project_root because Godot needs a res:// URI. Each animation becomes an entry in the SpriteFrames animations array, and each frame becomes an AtlasTexture sub-resource referencing the image.

Args: project_root: Absolute path to the Godot project directory (the folder containing project.godot). image_path: Path to the spritesheet. It may be absolute, relative to the project root, or already written as res://.... It must be inside project_root. animations: List of animation dictionaries. Example: [{"name": "idle", "fps": 10.0, "loop": True, "frames": [ {"x": 0, "y": 0, "w": 32, "h": 32}, {"x": 32, "y": 0, "w": 32, "h": 32}]}]. Every animation requires a unique name and a frames list. fps defaults to 10.0 and loop defaults to true. An optional per-frame duration defaults to 1.0; playback timing is normally controlled by the animation speed. output_tres: Destination .tres path. An absolute path or res:// URI is recommended; a relative path is resolved against project_root. Parent directories are created automatically.

Returns: Metadata including the absolute output_tres path, the Godot texture_path URI, load_steps, animation_count and frame_count.

Input Schema

Name	Required	Description	Default
`animations`	Yes
`image_path`	Yes
`output_tres`	Yes
`project_root`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that the output is a format=3 Godot 4 resource, that the image must be inside project_root because Godot requires a res:// URI, that each animation becomes an animations entry and each frame an AtlasTexture sub-resource, and that parent directories are created automatically. It stops short of stating overwrite behavior if the .tres already exists and says nothing about permissions or error conditions.

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

Conciseness4/5

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

Structure is front-loaded with a one-line summary followed by Args/Returns sections, which makes it scannable. It is somewhat long and the Returns block partly duplicates the output schema, but nearly every sentence carries real information.

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

Completeness4/5

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

For a four-parameter write tool with no annotations, the description covers purpose, all parameter semantics, path scoping, sub-resource structure, and directory creation. An output schema exists so return values needn't be explained, yet they are — a minor redundancy. The one real gap is what happens when output_tres already exists.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must compensate entirely, and it does — all four parameters are documented, including a concrete JSON example for the nested animations structure and the defaults for fps (10.0), loop (true), and per-frame duration (1.0). The path-resolution rules for image_path and output_tres (absolute, relative-to-project, or res://) are spelled out rather than left to inference.

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 opening sentence gives a precise verb+resource+target format: 'Create a Godot 4.x SpriteFrames .tres resource from atlas regions.' This is unambiguous and clearly distinct in domain from the sibling tools (inspect_spritesheet, extract_collision_polygon, build_body_collider, build_character_scene), though the description never explicitly names or contrasts with 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 by the constraints ('The image must live inside project_root', path forms accepted for image_path and output_tres) rather than stated as when-to-use guidance. There is no explicit statement of when to pick this over inspect_spritesheet or build_character_scene, and no exclusions or prerequisites beyond the path-scoping rule.

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

Deploy Server