godot-sprite-mcp

Overview Schema Source Related Servers Discussions Admin

build_body_collider

Builds a feet-aligned RectangleShape2D or CapsuleShape2D body collider for moving characters by analyzing animation frames, filtering thin limbs, and returning ready-to-use Godot collision snippets.

Instructions

Build a stable single-shape body collider for a moving character.

This is the recommended collision tool for player/enemy movement. It consumes all frames of one animation, overlays their alpha masks, measures the full character height and a thickness-filtered body width, and returns a feet-aligned RectangleShape2D (default) or CapsuleShape2D. The older extract_collision_polygon tool remains available for static objects.

Args: image_path: Path or res:// URI to the spritesheet image. frames: Every frame region of the selected animation, for example [{"x": 0, "y": 264, "w": 66, "h": 66}, ...]. All frames must have the same width and height. shape: "rectangle" (default) or "capsule". Wide bodies such as slimes use a rotated capsule automatically when capsule is chosen. alpha_threshold: Pixels with alpha strictly greater than this are opaque. Defaults to 10. thickness_ratio: A column must have at least this fraction of the character height to count as core body. Defaults to 0.30, which filters thin weapons and arms. project_root: Optional Godot project root directory for resolving res:// URIs.

Returns: A JSON-compatible dictionary containing height/top/bottom, filtered body width and raw width, sprite_offset for the AnimatedSprite2D, collision_position (feet at origin), shape parameters, and ready-to-paste sub-resource and CollisionShape2D snippets.

Input Schema

Name	Required	Default
`shape`	No	rectangle
`frames`	Yes
`image_path`	Yes
`project_root`	No
`alpha_threshold`	No
`thickness_ratio`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.7/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 the algorithm (overlays alpha masks across all frames, measures full height plus thickness-filtered width), the output alignment ('feet-aligned', 'feet at origin'), and an automatic behavior (wide bodies like slimes get a rotated capsule). It stops short of failure modes beyond the frame-size constraint, so a 4 rather than 5.

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?

Front-loaded with the one-sentence purpose, then cleanly split into Args and Returns. The Returns block restates shape parameters and snippets that partly duplicate the existing output schema, which is the only wasted text.

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

Completeness5/5

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

For a six-parameter geometry tool with no annotations, the description supplies algorithm, defaults, constraints, per-parameter meaning, and output shape. An output schema exists, so the Returns listing is mild redundancy rather than a gap — nothing an agent needs in order to call it correctly is missing.

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 coverage is 0%, so the description must do all the work — and it does, defining all six parameters: a concrete frames example, the two valid shape values (absent from the schema, which has no enum), the 'strictly greater than' alpha semantics, thickness_ratio's meaning and default of 0.30 with the rationale (filters thin weapons/arms), and project_root's role for res:// URIs.

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

Purpose5/5

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

Opens with a specific verb and artifact ('Build a stable single-shape body collider for a moving character') and explicitly positions itself against the sibling extract_collision_polygon by naming which case each serves (moving characters vs static objects). An agent can select between them without reading either schema.

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

Usage Guidelines5/5

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

States 'This is the recommended collision tool for player/enemy movement' and routes static objects to extract_collision_polygon, giving an explicit use/use-instead pair. The constraint that all frames must share width and height is also stated up front.

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

Deploy Server