Polygon Collider

The PolygonCollider defines a convex polygon shape with up to 8 vertices. It is useful for custom collision shapes that cannot be represented by boxes, circles, or capsules.

Properties

Property	Type	Default	Description
vertices	Vec2[]	[]	Polygon vertices in physics units (local space). Max 8 vertices
radius	number	0.0	Skin radius applied around the polygon. Creates a rounded polygon when > 0
density	number	1.0	Mass density
friction	number	0.6	Surface friction
restitution	number	0.0	Bounciness
isSensor	boolean	false	Trigger zone without physical response
categoryBits	number	1	Collision filter category bits

Caution

Box2D enforces a maximum of 8 vertices per polygon. Polygons with more vertices will be rejected. If you need more complex shapes, decompose them into multiple convex polygons or use a ChainCollider for static boundaries.

Vertex Editing in Scene View

When an entity with a PolygonCollider is selected in the editor, vertex handles appear in the Scene View:

• Drag a handle to move a vertex
• Double-click on an edge to add a new vertex (if under the 8-vertex limit)
• Right-click a handle to remove a vertex

Note

Vertices must form a convex polygon. The editor will enforce convexity — if a drag would create a concave shape, the vertex position is clamped.

Usage

commands.spawn(
    Transform.default(),
    RigidBody.with({ bodyType: 2 }),
    PolygonCollider.with({
        vertices: [
            { x: -0.5, y: -0.5 },
            { x: 0.5, y: -0.5 },
            { x: 0.3, y: 0.5 },
            { x: -0.3, y: 0.5 },
        ],
    }),
);

Tips

• Keep polygons simple. Fewer vertices means better performance.
• The radius property adds a skin around the polygon, which can reduce collision jitter for stacking scenarios.
• For concave shapes, split them into multiple convex PolygonCollider entities and parent them under a single root entity.

See Also

• Colliders Overview — all collider types
• Segment Collider — line segment shapes
• Chain Collider — chain of connected segments