Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

ConcavePolygonShape3D

Inherits: Shape3D < Resource < RefCounted < Object

Concave polygon shape resource (also called "trimesh") for 3D physics.

Description

3D concave polygon shape resource (also called "trimesh") to be added as a direct child of a PhysicsBody3D or Area3D using a CollisionShape3D node.

The shape consists of a collection of triangle faces, and as such it does not include any "inside" that the faces might be enclosing. If the faces enclose anything, then the shape is hollow, as opposed to a ConvexPolygonShape3D which is solid. See also CollisionPolygon3D.

Being made out of triangle faces, this shape is the most freely configurable single 3D shape. Despite its name, it can be used to form (hollow) polyhedra of any nature, convex or concave.

Note: When used for collision, ConcavePolygonShape3D is intended to work with static PhysicsBody3D nodes like StaticBody3D and will not work with CharacterBody3D or RigidBody3D in a mode other than Static.

Warning: The nature of this shape makes it extra prone to being tunneled through by (small) fast physics bodies. For example, consider a (small) rigid body Ball traveling toward a static body Box at high speed. If the box uses a ConcavePolygonShape3D consisting of twelve triangle faces (two triangle faces for each of the six sides of the box), then the ball might end up inside the box or tunnel all the way through the box, if it goes fast enough. This is (partly) because the ball can only collide against the individual faces of the hollow box. In interactions with rigid bodies tunneling can be avoided by enabling continuous collision detection on the rigid body.

Warning: Using this shape for an Area3D (via a CollisionShape3D node, created e.g. by using the Create Trimesh Collision Sibling option in the Mesh menu that appears when selecting a MeshInstance3D node) may give unexpected results: the area will only detect collisions with the triangle faces in the ConcavePolygonShape3D (and not with any "inside" of the shape, for example); moreover it will only detect all such collisions if backface_collision is true.

Performance: Due to its complexity, ConcavePolygonShape3D is the slowest collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, using ConvexPolygonShape3D will perform better. For dynamic physics bodies that need concave collision, several ConvexPolygonShape3Ds can be used to represent its collision by using convex decomposition; see ConvexPolygonShape3D's documentation for instructions. However, consider using primitive collision shapes such as SphereShape3D or BoxShape3D first.

Tutorials

Properties

bool

backface_collision

false

Methods

PackedVector3Array

get_faces ( ) const

void

set_faces ( PackedVector3Array faces )

Property Descriptions

bool backface_collision = false

  • void set_backface_collision_enabled ( bool value )

  • bool is_backface_collision_enabled ( )

If set to true, collisions occur on both sides of the concave shape faces. Otherwise they occur only along the face normals.

Method Descriptions

PackedVector3Array get_faces ( ) const

Returns the faces of the trimesh shape as an array of vertices. The array (of length divisible by three) is naturally divided into triples; each triple of vertices defines a triangle.

void set_faces ( PackedVector3Array faces )

Sets the faces of the trimesh shape from an array of vertices. The faces array should be composed of triples such that each triple of vertices defines a triangle.