🛠️ Sprite StaticBody Builder for Godot 4

Automated 2D Physics Generation & Real-Time Dynamic Shadow Toolset

A high-performance, developer-friendly Godot 4 editor plugin that bridges the gap between 2D concept art and physics-ready game assets. It automatically vectorizes arbitrary sprite textures into optimized StaticBody2D nodes with pixel-perfect polygon collision, intelligent polygon decimation, convex decomposition, live viewport previews, and rotation-invariant real-time dynamic shadows.

🌟 Executive Summary & Problem Solved

Creating collision geometry for irregular 2D sprites in game engines is traditionally tedious, manual, and error-prone:

1. Manual Polygon Tracing: Hand-placing dozens of collision vertices wastes artist and developer time.
2. Concave Physics Issues: 2D physics engines struggle with complex concave polygons without decomposition.
3. Rigid Shadow Artifacts: Standard 2D drop-shadows are locked to the object's local transform; rotating the object causes the shadow to swing unnaturally across the screen, violating consistent world lighting.

Sprite StaticBody Builder solves all three problems in one unified dock interface with a single click.

🚀 Key Highlights & Capabilities

• 🎯 One-Click Vectorization: Converts any Sprite2D or FileSystem texture into a physics-ready StaticBody2D instantly.
• 📐 Ramer-Douglas-Peucker (RDP) Simplification: Reduces thousands of pixel boundary points into lightweight, performant polygons (32 to 128 points) tailored for mobile and desktop budgets.
• 🧩 Convex Decomposition Engine: Automatically decomposes complex concave shapes into convex partitions using ear-clipping to prevent physics clipping and tunneling.
• 💡 Real-Time Dynamic Shadows (RealtimeShadow2D): A specialized tool script that counter-rotates shadow displacement in world space. Shadows stay anchored to the global light source in real-time as objects or levels rotate.
• 👁️ Live Viewport Canvas Overlay: Renders collision wireframes, vertex indicators, and projected shadow contours directly inside the Godot 2D editor before committing.
• ⏪ Full Engine Undo/Redo: Seamlessly integrated into Godot's EditorUndoRedoManager (Ctrl+Z / Ctrl+Y).

🎛️ Dock Window Reference Guide

The plugin adds a clean, native tab to your Godot editor dock titled "StaticBody". Below is an in-depth breakdown of every section and control.

┌─────────────────────────────────────────────────────────┐
│ [Icon] Target: Detected Sprite: Obstacle_Rock           │
│        res://art/rock.png (128x128)                     │
├─────────────────────────────────────────────────────────┤
│ ▼ ALPHA & TRACE                                         │
│   Alpha Threshold:     [====|====] 0.50                 │
│   Simplification:      [ Medium (Balanced - 64 pts) ▼ ] │
│   Max Points:          [ 64 ]                           │
│   Collision Mode:      [ Single Polygon             ▼ ] │
│   Build Mode:          [ Solids (Filled Area)       ▼ ] │
├─────────────────────────────────────────────────────────┤
│ ▼ GAMEPLAY ARCHETYPES & PRESETS                         │
│   Preset:              [ 🧱 Static Wall / Platform  ▼ ] │
├─────────────────────────────────────────────────────────┤
│ ▼ REAL SHADOW SPRITE                                    │
│   [x] Generate Real Shadow Sprite                       │
│   Anchor / Base:       [ Center (Top-Down)          ▼ ] │
│   Offset (X, Y):       X: [ 6.0 ]   Y: [ 8.0 ]          │
│   Light Angle / Dist:  Angle: [ 53.1° ]  Dist: [ 10.0px]│
│   Color / Alpha:       [ ■ rgba(0, 0, 0, 0.45) ]        │
│   Shadow Scale:        [ 1.00 ]                         │
│   [x] Realtime Rotation Sync                            │
├─────────────────────────────────────────────────────────┤
│ ▼ WORKFLOW OPTIONS                                      │
│   [x] Create StaticBody2D   [x] Keep Main Sprite        │
│   [x] Auto-Generate Collision                           │
├─────────────────────────────────────────────────────────┤
│ [ 🔨 Create StaticBody ]       [ 🔄 Regenerate ]        │
│ [ 👁️ Live Preview ]           [ 🗑️ Remove Collision ]   │
│ Status: Generated 1 polygon, 42 vertices total.         │
└─────────────────────────────────────────────────────────┘

1. Target Detection Header

Automatically monitors editor selection without manual dragging:

• Sprite2D in Scene: Detects the sprite and inspects its texture, centered mode, offsets, and regions.
• StaticBody2D in Scene: Detects existing bodies and reads previously generated collisions and shadow configurations.
• Texture in FileSystem: Allows building physics bodies straight from the asset drawer into the center of the active viewport.

2. Alpha & Trace Settings

3. Gameplay Archetypes & Presets

Provides standardized physics and interactive mechanics across multiple game genres:

• 🧱 Static Wall / Platform: Standard StaticBody2D collision for level geometry, platforms, and boundaries.
• 🌀 Rotating Obstacle / Spinner: Creates an AnimatableBody2D (with sync_to_physics = true and RotatingObstacle in _physics_process) ensuring accurate Godot 4 momentum transfer and zero tunneling. Unlocks an interactive Rotation Speed (°/s) spinbox.
• ⚠️ Hazard / Trap: Creates an Area2D trigger with HazardArea attached and registered into the "hazards" group with player_hit signal and damage callbacks.
• 🏁 Goal / Checkpoint: Creates an Area2D trigger with GoalArea attached and registered into the "goals" group with goal_reached signal for level-exit triggers.
• 🦘 Bumper / Spring Pad: Creates an Area2D with BumperPad attached. Launches player slimes in local/normal direction with interactive Bounce Force (px/s) spinbox and spring squish tween.
• 🛡️ One-Way Jelly Membrane: Creates a StaticBody2D with OneWayMembrane and automatically configures one_way_collision = true on all collision polygons, allowing slimes to pass in one direction while blocking return.
• 🌀 Teleport Portal: Creates an Area2D with TeleportPortal attached. Supports node linking to destination portals with momentum preservation and cooldown protection.
• ⭐ Collectible Star / Gem: Creates an Area2D with CollectibleStar attached. Provides configurable Star Index (1, 2, 3), smooth sine-wave hover bobbing, and pickup celebration pop animations.
• 🔑 Key Pickup: Creates an Area2D with KeyItem attached with customizable Key ID tag, registering to player inventory or metadata on contact.
• 🚪 Locked Door: Creates a StaticBody2D with LockedDoor attached. Automatically detects player contact with the matching Key ID, disables collision, and slides/fades open.
• 💥 Crumbling Platform: Creates an AnimatableBody2D with CrumblingPlatform attached. Features customizable Collapse Delay (e.g. 0.6s) and Respawn Time (e.g. 2.5s), shake-warning animation upon player landing, collision collapse, and smooth regeneration.
• 💨 Wind Vent: Creates an Area2D with WindVent attached. Applies continuous directional acceleration (Wind Force default 450 px/s) along the vent's pointing angle to push floating or jumping slimes.
• 🔘 Pressure Plate Switch: Creates an Area2D with PressurePlate attached. Provides physical depression sink tween and trigger dispatching (activated/deactivated signals and target method calls) when stepped on.
• 🧊 Ice Slippery Floor: Creates a StaticBody2D with zero-friction PhysicsMaterial (friction = 0.0) and IcePlatform attached, making slimes slide uncontrollably unless they hit a wall.

4. Real Shadow Sprite & Dynamic Lighting

A standout technical feature of this tool is its rotation-invariant dynamic shadow system.

[!TIP] Direct Viewport Repositioning: Developers can click the generated Sprite2DShadow node directly in the Godot 2D Viewport and move it with the Move Tool (W). The tool automatically recalculates and saves the new world offset without snapping back.

5. Workflow Options

• Create StaticBody2D: Wraps generated nodes under a new physics body (StaticBody2D, AnimatableBody2D, or Area2D depending on preset). If unchecked, attaches collision nodes and shadows directly to the target sprite/parent.
• Keep Main Sprite: Retains and parents the primary visual Sprite2D under the body. If unchecked, removes the visual sprite, leaving an invisible physics/trigger shape.
• Auto-Generate Collision: Automatically computes contours upon pressing Create. If unchecked, only creates the physics body and shadow without collision geometry.

6. Action Buttons & Feedback

• 🔨 Create StaticBody: Executes the creation pipeline with full EditorUndoRedoManager registration (add_do_reference memory safety ensuring clean Undo and Redo).
• 🔄 Regenerate Collision: Updates collision polygons and shadow parameters on an existing body without disturbing its transform, scripts, or scene hierarchy.
• 👁️ Live Preview (Toggle): Draws semi-transparent green polygons, yellow vertex indicators, and projected shadow contours directly on the editor viewport canvas (supports both scene nodes and standalone FileSystem textures).
• 🗑️ Remove Collision: Cleanly strips all CollisionPolygon2D children from the target body with full undo capability.
• Status Bar & Warnings: Real-time diagnostic readouts showing generated polygon count and vertex count, with instant warning alerts if an image has 0 opaque pixels or if vertex budgets exceed recommended thresholds (>256 vertices).

🔬 Technical Architecture & Math

[ Sprite2D Texture ]
        │
        ▼
[ BitMap Extraction ] ──── (Alpha Threshold Evaluation)
        │
        ▼
[ Contour Tracing ] ────── (Marching Squares / Opaque Boundary)
        │
        ▼
[ RDP Simplification ] ─── (Epsilon Tolerance & Max Points Budget)
        │
        ▼
[ Ear-Clipping / Convex ]─ (Single Poly OR Convex Decomposition)
        │
        ├─────────────────────────────┬─────────────────────────────┐
        ▼                             ▼                             ▼
[ CollisionPolygon2D Nodes ]   [ Sprite2D (Main) ]   [ RealtimeShadow2D Node ]

Counter-Rotation Math (RealtimeShadow2D)

In top-down or side-scrolling games, a global light source (e.g. sun from the top-left) remains fixed relative to the screen. When an object rotates by angle $\theta$, rigid children rotate with it:

$$\vec{v}_{\text{rigid}} = \mathbf{R}(\theta) \cdot \vec{v}_{\text{offset}}$$

To keep the shadow's world displacement constant, RealtimeShadow2D calculates the parent's global transformation matrix $\mathbf{T}_{\text{parent}}$ and applies affine inversion in _process and _physics_process:

$$\vec{p}_{\text{local}} = \mathbf{T}_{\text{parent}}^{-1} \cdot (\vec{p}_{\text{world_origin}} + \vec{v}_{\text{shadow_offset}})$$

Result:

• $\text{Global Rotation}$: Matches the parent, rotating the shadow silhouette with the object.
• $\text{Global Displacement}$: Strictly preserved at $\vec{v}_{\text{shadow_offset}}$, ensuring lighting stays completely natural.

📦 File Structure

addons/sprite_staticbody_builder/
├── plugin.cfg                  # Plugin metadata and entry script declaration
├── sprite_staticbody_plugin.gd # EditorPlugin lifecycle, Undo/Redo & Viewport overlays
├── sprite_staticbody_dock.gd   # Dock UI logic, signal dispatching & target sync
├── sprite_staticbody_dock.tscn # Clean Godot 4 Control scene for the dock UI
├── collision_generator.gd      # Bitmap tracing & ear-clipping decomposition
├── polygon_simplifier.gd       # Ramer-Douglas-Peucker (RDP) algorithm
├── collision_preview.gd        # Viewport canvas overlay renderer
└── resources/
    ├── realtime_shadow.gd      # RealtimeShadow2D tool script
    ├── rotating_obstacle.gd    # Continuous rotation archetype script (AnimatableBody2D)
    ├── hazard_area.gd          # Hazard trigger script (Area2D)
    ├── goal_area.gd            # Level exit trigger script (Area2D)
    ├── bumper_pad.gd           # Launch/bounce spring pad script (Area2D)
    ├── one_way_membrane.gd     # One-way directional barrier script (StaticBody2D)
    ├── teleport_portal.gd      # Momentum-preserving wormhole portal (Area2D)
    ├── collectible_star.gd     # 3-star rating collectible script (Area2D)
    ├── key_item.gd             # Key item pickup script (Area2D)
    ├── locked_door.gd          # Proximity key-unlockable door (StaticBody2D)
    ├── crumbling_platform.gd   # Step-activated collapse & respawn platform (AnimatableBody2D)
    ├── wind_vent.gd            # Directional acceleration wind updraft/vent (Area2D)
    ├── pressure_plate.gd       # Step depression switch & trigger dispatcher (Area2D)
    └── ice_platform.gd         # Zero-friction slippery floor (StaticBody2D)

🛠️ Installation & Setup

1. Copy the addons/sprite_staticbody_builder folder into your Godot 4 project's res://addons/ directory.
2. In the Godot editor, navigate to Project → Project Settings → Plugins.
3. Locate Sprite StaticBody Builder and check the Enable box.
4. The dock will appear in your editor panels ready for use.

📄 License & Attribution

• Author: Rohan Choudhary
• License: MIT License

This project is open-source software licensed under the MIT License (see LICENSE). Feel free to use, modify, and integrate it into commercial and personal games.