Tracing, simplifying, and handing the points to an engine
The outline runs along the edges between opaque and transparent pixels, not through pixel centres, so every vertex sits on a whole pixel corner: a 16 × 16 opaque square becomes exactly (0, 0), (16, 0), (16, 16), (0, 16). Outer outlines come back clockwise on screen (y down), and specks smaller than 4 px² are dropped.
Simplification (Ramer–Douglas–Peucker) removes points that lie close to a straight line. The tolerance starts at 1 px and is raised until the polygon has no more vertices than the cap; a tolerance that would make the outline cross itself is rejected, because a self-crossing outline is not a usable physics shape. Raising the tolerance happens in steps, so a cap can be met with fewer vertices than it allows, and a low cap can round away gaps such as the space between two legs.
Engines take such polygons as point lists relative to the object. Godot's CollisionPolygon2D accepts concave polygons and, in its default solids mode, splits them into convex parts itself; it must be the child of an Area2D or a physics body. Unity's PolygonCollider2D takes points in local space, and Unity can also build its own outline from a sprite's Custom Physics Shape. In both, subtract the frame's pivot first; in Unity also flip y and divide by Pixels Per Unit.
- Alpha threshold
- The highest alpha still counted as transparent; 127 keeps pixels that are at least half opaque.
- Vertex cap
- The most points a polygon may have after simplification.
- Tolerance
- How far (in pixels) simplification may move the outline.
Example: one 32 × 48 character frame at three settings
A head, a body and two legs with a 4 px gap between them, plus a faint glow (alpha 60) around the head. Numbers from Nerulio's tracer:
traced outline (alpha > 127) 48 vertices, area 544 px²
cap 64 tolerance 1 px 16 vertices, area 540 px² (−0.7 %), max deviation 1.0 px, legs kept apart
cap 12 tolerance 3.8 px 5 vertices, area 428 px² (−21 %), max deviation 3.8 px, leg gap gone
threshold 40, cap 12 glow counted: area 628 px², 12 vertices at tolerance 2.0 px
Godot, pivot (16, 48) polygon point (22, 48) → node space (22 − 16, 48 − 48) = (6, 0)
A cap of 12 did not give 12 points here: the next tolerance step already went down to 5. If the shape matters, raise the cap and compare the vertex count the Studio reports after Auto from alpha.
Where the polygons go
| Target | Polygons in the export | What you build in the engine |
|---|
| Godot 4 | collision per frame in metadata/nerulio, each polygon as a flat list x0, y0, x1, y1 … | A CollisionPolygon2D under an Area2D or a body, its polygon set from the list minus the pivot, per frame by your script |
|---|
| Generic JSON | frames[key].collision: each polygon as [[x, y], …] | Any engine that takes a point list |
|---|
| Unity 6 | None; the export notes point to the generic JSON | PolygonCollider2D points from the generic JSON, or Unity's own Custom Physics Shape |
|---|
| Aseprite, Phaser, PixiJS, LÖVE, Spine, Starling, Defold, GameMaker, CSS | None | Load the generic JSON next to the atlas |
|---|
Check the result
- After Auto from alpha the toast reports how many frames and vertices were made; step through the tag and look at the outline on each frame.
- Toggle the threshold between 127 and a low value on a frame with glow or smoke and compare the outlines.
- In Godot, add a CollisionPolygon2D under an Area2D with the converted points and turn on Debug › Visible Collision Shapes to see it over the sprite.
Troubleshooting
| Symptom | Likely cause | How to check | Fix |
|---|
| The polygon swallows gaps such as the space between the legs | The vertex cap forced a tolerance larger than the gap | The vertex count after Auto is far below the cap, or the outline bridges the gap | Raise the cap (for example to 24) and run Auto again |
|---|
| Glow or smoke is inside the collision shape | Its alpha is above the threshold | Lower and raise the threshold and compare | Raise the threshold so faint pixels count as transparent |
|---|
| The shape is offset in the engine | Points are frame-canvas pixels from the top-left, not relative to the pivot | Compare one point with the worked example | Subtract the pivot; in Unity also flip y and divide by Pixels Per Unit |
|---|
| Only some parts got a polygon | Up to 8 separate shapes per frame are kept, and specks under 4 px² are dropped | The Auto message mentions dropped specks or extra shapes | Join the parts in the art, or draw the missing polygon by hand |
|---|
Other ways to do it
| Option | When it is the better choice |
|---|
| Unity's Custom Physics Shape in the Sprite Editor | Unity only: Unity generates and edits the outline itself, and a Polygon Collider 2D uses it for new instances of the sprite. |
|---|
| A box or circle per frame | Most platformer bodies; cheaper and steadier than a detailed polygon. Draw it with the hitbox editor, or use the convex hull, rectangle and circle options of the classic Sprite Lab. |
|---|
What this page does not cover
- Polygons are data in the export: no CollisionPolygon2D nodes or Unity colliders are created.
- Collision polygons do not reach Unity, Aseprite or the atlas formats; use the generic JSON.
- Holes inside a shape are not part of the Studio's polygons.
Versions and sources
The tracer and the numbers in the example come from Nerulio's own module (src/game/contour.js). The Godot bundle that carries the metadata was loaded by Godot 4.7.2; the collision polygons in it were not used as physics shapes in that run. Engine behaviour follows the Godot 4.7 and Unity 6 documentation.
Official documentation used
Collision Polygon Generator
Trace collision polygons from the alpha silhouette and see the vertex count and the error.
How it works
- Add images
- Adjust settings and review the result
- Download a new file
Supported formats
PNG / JPG / WebP / AVIF / HEIC → PNG + JSON (ZIP) — Input decoding depends on browser support and optional engines.
What this tool does
Trace collision polygons from the alpha silhouette and see the vertex count and the error.
Implementation and verified quality
advanced · Studio Sprite workspace: measured grid (margin, spacing) or alpha islands, colour key, previewed import decisions; GIF/APNG/.aseprite decoders; timeline, pivots, boxes, alpha contour collision. Quality qualification is in progress. Pro/Flagship quality has not been established.
Before you export
No convex decomposition: use the convex hull when an engine needs convex shapes.