Physics Tools for Defold

Editor scripts to generate Defold physics shapes from 2D images (convex hulls and concave silhouette chains).

Translations: Русский | 中文

Installation

Add this extension as a dependency to your game.project and click Project → Fetch Libraries:

https://github.com/indiesoftby/defold-physics-tools/archive/main.zip

Then you can use the editor scripts from the Assets or Outline panels.

Editor scripts (Defold UI)

The main way to use this project is via two Defold editor scripts. They appear as context menu commands in the Assets and Outline panels and open simple dialogs where you choose parameters.

1. Convex shape generator (convex hull)

Menu commands

• Assets panel (right‑click an image resource): Generate Convex Shape...
• Outline panel (right‑click a Sprite component): Generate Convex Shape...

When run on a Sprite, the script automatically finds the image used by the sprite’s atlas/animation, generates a .convexshape from it.

Dialog fields

• Image Read‑only. Shows the selected image filename that will be used as the source.

• Max vertices Drop‑down with values from 4 to 16.

  • Controls how many vertices the resulting convex hull is simplified to.
  • Lower values → more coarse, simpler shape.
  • Higher values → closer to the original silhouette, but still within Defold’s Box2D limit of 16 vertices.
  • The value is stored in project preferences and reused next time.

• Inset % Drop‑down with values from 0 to 10.

  • Uniformly shrinks the generated shape by the given percentage, moving each vertex toward the centroid.
  • 0 → no shrinking, the shape matches the silhouette exactly.
  • 1–10 → the shape is slightly smaller than the silhouette, which can help avoid false collisions at the edges.
  • The value is stored in project preferences and reused next time.

What it generates

• A .convexshape file placed next to the image (same name, .convexshape extension).

Internally the tool computes a convex hull of all non‑transparent pixels, simplifies it to the requested vertex count, optionally applies the inset, centers it on the image origin, and writes a Defold‑compatible .convexshape.

---

2. Silhouette chain generator (concave walls)

Menu commands

• Assets panel (right‑click an image resource): Generate Silhouette Chain...
• Outline panel (right‑click a Sprite component): Generate Silhouette Chain...

When run on a Sprite, the script resolves the image from the sprite’s atlas/animation and generates the collision asset next to that image.

Dialog fields

• Image
  Read‑only. The image whose silhouette will be traced.

• Epsilon (px)
  Drop‑down with values such as 0.5, 1.0, 1.5, 2.0, 3.0, 4.0, 5.0, 8.0, 10.0.

  • Ramer–Douglas–Peucker simplification tolerance in pixels.
  • Smaller values (e.g. 0.5–1.0): more detailed contour, more boxes, heavier collision.
  • Larger values (e.g. 4.0–10.0): smoother contour, fewer boxes, lighter collision.
  • The last used value is stored in project preferences.

• Thickness (px)
  Drop‑down with values such as 1.0, 1.5, 2.0, 3.0, 4.0, 5.0.

  • Half‑thickness of each generated TYPE_BOX wall in pixels.
  • Visually, this is how “thick” your collision walls are around the silhouette.
  • The last used value is stored in project preferences.

What it generates

• A .collisionobject file placed next to the image (same name, .collisionobject extension).
• The collision object is COLLISION_OBJECT_TYPE_STATIC with many embedded TYPE_BOX shapes whose positions and rotations follow the simplified contour of the image.

This effectively gives you concave static collision suitable for race tracks, terrain outlines, and other complex shapes, built from a chain of thin boxes.

---

Advanced: command line tools

For batch processing or custom pipelines, you can also run the underlying executables from the command line:

• physics_tools/plugins/bin/<platform>/gen_convexshape.<exe> — generates convex hull shapes
• physics_tools/plugins/bin/<platform>/gen_silhouette_chain.<exe> — generates silhouette chain collision

Executables are available for Windows, macOS (Intel & Apple Silicon), and Linux. Run with --help to see available arguments.

Contributing

Contributions are welcome! Feel free to open issues and pull requests.

• 🌍 Issues can be written in any language — AI will translate and understand everything.

License

This project is dedicated to the public domain under the CC0 1.0 Universal license.