godot-sprite-mcp

Overview Schema Source Related Servers Discussions Admin

extract_collision_polygon

Extracts a simplified outer collision polygon from opaque sprite pixels for static props and irregular scenery, returning points and a ready-to-paste CollisionPolygon2D snippet.

Instructions

Extract a simplified outer collision polygon from opaque pixels.

This optional tool is intended for static objects and irregular scenery. For moving characters and monsters, use build_body_collider instead to get a stable feet-aligned RectangleShape2D or CapsuleShape2D.

The largest external alpha contour is traced and simplified with the Ramer-Douglas-Peucker algorithm. The result is a simple clockwise polygon with at most 24 vertices, suitable for a CollisionPolygon2D.

Args: image_path: Absolute path, relative path, or res:// URI to a PNG. region: Optional sub-region {"x": int, "y": int, "w": int, "h": int} in image pixels. When omitted, the whole image is used. Returned coordinates are relative to this region's top-left corner. epsilon: RDP simplification tolerance in pixels. Defaults to 2.0. Larger values produce fewer vertices. If necessary the tolerance is increased internally to keep the polygon at or below 24 vertices. centered: When true (the default, matching Godot 4 Sprite2D), every point is shifted so the coordinate origin is the image/region centre. For a region of size w x h the conversion is x - w / 2 and y - h / 2. Set to false to keep pixel-space coordinates with a top-left origin. project_root: Optional Godot project root directory for resolving res:// URIs.

Returns: A dictionary with points (list of [x, y]), vertex_count, packed_vector2_array (Godot text such as PackedVector2Array(0.0, -16.0, ...)) and tscn_snippet (a CollisionPolygon2D node block ready to paste into a .tscn file).

Input Schema

Name	Required	Description	Default
`region`	No
`epsilon`	No
`centered`	No
`image_path`	Yes
`project_root`	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.6/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 tracing algorithm (RDP), the clockwise winding, the hard 24-vertex cap and the internal tolerance escalation needed to enforce it. It does not say what happens on failure paths (missing file, no opaque pixels/alpha channel), which is the main remaining gap for a file-reading tool.

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?

Purpose and the sibling alternative are front-loaded in the first three lines, then Args/Returns sections follow a predictable structure. It is on the long side, but every sentence adds either routing guidance or coordinate semantics; only the Returns block partially duplicates the output schema.

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 five-parameter computation tool with an output schema, the definition covers inputs, coordinate conventions, algorithmic limits and output shape. Missing only error/edge-case behavior (empty alpha, invalid path) and any note on cost for large images, which keeps it just short of complete.

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, and it documents all five parameters in detail: path forms accepted for image_path, the region dictionary shape and that returned coordinates are region-relative, epsilon as RDP tolerance with larger-means-fewer behavior, the centered offset math (x - w/2, y - h/2), and project_root's role for res:// resolution. This is meaning well beyond anything the schema conveys.

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?

States a specific verb and resource ('Extract a simplified outer collision polygon from opaque pixels') and immediately scopes it to static objects and irregular scenery. It also names the sibling build_body_collider and the condition that selects it, so the tool is distinguishable from alternatives without opening any 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?

Explicitly says when to use this tool ('static objects and irregular scenery') and when not to ('moving characters and monsters'), pointing to build_body_collider as the alternative with the reason (stable feet-aligned RectangleShape2D or CapsuleShape2D). Nothing is left to inference.

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

Deploy Server