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[]	Unit square	Polygon vertices in physics units (local space). Max 8 vertices. Default: [{x:-0.5,y:-0.5}, {x:0.5,y:-0.5}, {x:0.5,y:0.5}, {x:-0.5,y:0.5}]
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.3	Surface friction
restitution	number	0.0	Bounciness
isSensor	boolean	false	Trigger zone without physical response
enabled	boolean	true	Enable/disable the collider
categoryBits	number	1	Collision filter category bits
maskBits	number	0xFFFF	Collision filter mask 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()
    .insert(Transform)
    .insert(RigidBody, { bodyType: 2 })
    .insert(PolygonCollider, {
        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