Phaser home
Log inCreate a game

← Expansion packsVector

Phaser AE

Vector Hulls

Free packv3.0.0-32DVector

What a physics engine needs and a vector outline never has. Hulls, convex pieces and triangles, so an outline you drew can become a collider or a fill.

This is a Free pack. Every phaser.io account can use it in their games.

Released October 14, 2026 · updated October 20, 2026

Vector Hulls: a screenshot of its demo
A note about these graphics

Expansion packs don't come with graphics. This screenshot is one way of drawing what the pack does, made for its demo: none of the sprites, tiles or backgrounds in it are in the pack.

That's by design. A pack is a game's logic, mechanics and effects, and it works with whatever art you give it. Some packs draw effects, backdrops or 3D scenes of their own, but none carries a game's sprites.

So the look is yours. Make the art on phaser.io, bring your own, or let your agent draw it in code: the same pack can look like anything.

What it does

A 2D physics solver wants convex polygons, and refuses or quietly truncates one with too many points. A lumpy rock, a ship with swept wings or a horseshoe is neither convex nor small. The pack gives four steps, and the one you want depends on how faithful the collider has to be.

convexHull wraps a point set in its convex hull: the fastest, and wrong for anything with a real concavity, since a horseshoe becomes a disc. simplifyHull cuts a hull down to a vertex budget while keeping its extent. hullFor does both, outline in and physics-ready convex polygon out, and is the call most games want. convexPieces decomposes a concave outline into a set of convex polygons, each within the budget, so a body built from several fixtures keeps its notch; it merges neighbouring pieces back together where the join stays convex, so a shape ends up as six polygons rather than forty triangles.

Beside those, isConvex tests a polygon, and triangulate ear-clips an outline into triangles, returned as index triples, for filling it.

Features

  • Convex hulls — convexHull of any point set.
  • A vertex budget — simplifyHull and hullFor cut a hull to a maximum, 8 by default (MAX_HULL_POINTS), and keep its extent.
  • Convex decomposition — convexPieces splits a concave outline into merged convex pieces within the budget.
  • Triangulation — triangulate ear-clips a simple polygon into index triples for a fill.
  • A convexity test — isConvex.
  • Deterministic — the same outline always gives the same collider, so replays and tests agree.

Good for

  • Physics games with line art — ships, rocks and props that must collide as real bodies.
  • Generated shapes — an outline made at run time turned into a collider on the spot.
  • Drawing games — a shape the player draws becoming a physics object, once it is checked for crossings.
  • Filled vector shapes — triangles to give an outline a solid face.

Make it yours

Every hull call takes its own vertex budget, so a game can match its physics engine's limit or trade accuracy for speed. A small asteroid can be one hullFor polygon, cheap and close enough; a space station with a docking bay can be convexPieces, several fixtures on one body, so a ship can fly into the bay rather than bouncing off a lid that is not drawn. Filling is separate: triangulate the same outline for its face, and keep the hull for the collider.

Works with

  • physics-box2d — hulls outlines with hullFor for a polygon body and keeps every concavity with convexPieces for a decomposed one, within Box2D's eight-vertex limit.
  • vector-hit — point tests and circle overlaps, when a full collider is more than the game needs.
  • vector-art — the drawn outlines that most often need a collider.

Good to know

  • triangulate wants a simple polygon, one that does not cross itself. A self-intersecting outline gives nonsense rather than an error, so if players draw shapes, check them first.
  • Decomposition is a heuristic, not an optimal cover: it produces a good set quickly rather than the smallest possible one.
  • A plain hull fills in every concavity; reach for convexPieces whenever the notch is the point.

More Vector packs

Show all →