Inspect a PNG spritesheet and return frame rectangles.

Use this tool before building animations when you need to discover the frame layout of a spritesheet. The alpha channel is analysed; pixels with alpha strictly greater than alpha_threshold count as opaque.

Args: image_path: Absolute path, relative path, or res://... URI to the source PNG. alpha_threshold: Opaque-pixel cutoff in the inclusive range 0..255. Defaults to 10, so nearly transparent antialiasing is ignored. mode: Detection strategy: "grid" finds fully transparent horizontal/vertical separator lines, "islands" finds 8-connected opaque islands and their tight bounding boxes, and "auto" tries "grid" first and falls back to "islands" when cell sizes are not uniform. project_root: Optional Godot project root directory used to resolve res:// URIs or relative paths.

Returns: A JSON-compatible dictionary with image_width, image_height, the detected mode, frame_count, and frames. Every frame is {"id": int, "x": int, "y": int, "w": int, "h": int, "pivot_bottom_center": [float, float]}. Frames are ordered top to bottom (row-clustered), then left to right.

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.

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).

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.

Write a complete Godot 4 .tscn character scene with AnimatedSprite2D and feet-aligned body collider.

Args: project_root: Path to the Godot project directory containing project.godot. image_path: Path or res:// URI to the spritesheet PNG. sprite_frames_tres: Path or res:// URI to the generated SpriteFrames .tres resource. output_tscn: Destination .tscn file path or res:// URI. collider_frames: Frame regions (typically the idle animation row) used to compute the body collider. root_name: Root node name in the scene (default: "Character"). root_type: Root node Godot class (default: "CharacterBody2D"). default_animation: Default animation name for the AnimatedSprite2D (default: "idle"). shape: "rectangle" (default) or "capsule". alpha_threshold: Opaque alpha cutoff 0..255 (default: 10). thickness_ratio: Minimum vertical column thickness ratio (default: 0.30).

Returns: Metadata including the written output_tscn path, sprite_frames_res URI, and collider details.