ConvexPolygonShape2D in Godot – Complete Guide

Welcome to this in-depth exploration of the ConvexPolygonShape2D class in Godot 4. Whether you’re embarking on your first game development adventure or you’re a seasoned coder looking to expand your knowledge, understanding this class will enhance your ability to handle collision physics in your 2D games. Collision detection is a fundamental aspect of game development, and learning to use Godot’s built-in shapes effectively can be a game-changer. Let’s dive into the world of ConvexPolygonShape2D and discover how this tool can be a valuable addition to your game development toolkit.

What Is ConvexPolygonShape2D?

ConvexPolygonShape2D is a class in the Godot game engine, designed for use in 2D physics simulations. As the name suggests, this shape represents a convex polygon, meaning each internal angle of the polygon is less than 180 degrees, and the shape bulges outward. This characteristic is crucial for efficient collision detection and response in physics engines.

What Is It For?

In game development, physics collision is a routine concern, and ConvexPolygonShape2D serves as one of the possible shapes you can use to define the boundaries of an object for collision purposes. It’s typically used when a simple rectangle or circle won’t accurately reflect the actual shape of an object, and a more tailored collision boundary is required.

Why Should I Learn It?

Learning to use ConvexPolygonShape2D means you can:

– Create more complex and realistic collision shapes for your game objects.
– Optimize game performance by using shapes that are quicker to compute for collision detection than concave counterparts.
– Understand and implement advanced techniques like convex decomposition, allowing you to make concave shapes from multiple convex shapes.

Understanding the nuances of ConvexPolygonShape2D can enable you to build games that feel more responsive and natural, which is pivotal in game design. Engaging physics can elevate the gaming experience, and your skillset in this area could become a significant asset.

CTA Small Image

Creating a ConvexPolygonShape2D

To start working with ConvexPolygonShape2D in Godot, you first need to create the shape and attach it to a physics body, like a RigidBody2D or StaticBody2D. Below is an example of how to create a ConvexPolygonShape2D in code and attach it to a StaticBody2D node:

var static_body =
var collision_shape =
var convex_polygon =

# Assuming you have an array of points that define the vertices of your polygon
var points = PoolVector2Array([Vector2(10, 20), Vector2(50, 70), Vector2(100, 20)])

collision_shape.shape = convex_polygon


This code creates a triangular polygon shape using three points. It establishes a collision shape for the static body, defining its collision boundaries in the physics world.

Editing a ConvexPolygonShape2D Vertices

In case you need to alter the vertices of your polygon dynamically, you can use the `set_point_cloud` method. Here’s how you can update the vertices of an existing ConvexPolygonShape2D:

# Reference your ConvexPolygonShape2D
var convex_polygon = $StaticBody2D/CollisionShape2D.shape

# Your new set of points
var new_points = PoolVector2Array([Vector2(30, 40), Vector2(60, 90), Vector2(120, 40)])

# Update the point cloud with the new points

This code snippet demonstrates changing the ConvexPolygonShape2D vertices during runtime, providing flexibility to change collision boundaries as your game’s state changes.

Optimizing Collision Shapes

Efficiency in your collision shapes can significantly improve your game’s performance. It’s best to use the minimum number of vertices necessary to define the shape. Here’s an example of creating a ConvexPolygonShape2D with unnecessary points and optimizing it:

# An over-defined pentagon with redundant points
var redundant_points = PoolVector2Array([
    Vector2(10, 20), Vector2(25, 45), Vector2(40, 70),
    Vector2(70, 70), Vector2(100, 45), Vector2(85, 20),
    Vector2(50, 10)])

# An optimized version of the same pentagon with fewer points
var optimized_points = PoolVector2Array([
    Vector2(10, 20), Vector2(50, 70), Vector2(100, 45),
    Vector2(85, 20), Vector2(50, 10)])


Optimization means simplifying the shape to reflect the collision boundary without unnecessarily detailed geometry.

Convex Decomposition

For objects with a concave shape, you need to perform convex decomposition, where you split the concave shape into several convex polygons. Here’s how you might handle this for a complex shape:

# Original concave points (pseudo-code, as actual decomposition requires complex algorithm)
var concave_points = PoolVector2Array([/* ... concave shape points ... */])

# Resulting convex shapes after decomposition (simplified example)
var convex_shapes = [
    PoolVector2Array([/* ... first convex shape points ... */]),
    PoolVector2Array([/* ... second convex shape points ... */]),
    PoolVector2Array([/* ... third convex shape points ... */]),
    # More convex shapes as needed

for points in convex_shapes:
    var convex_polygon =
    var collision_shape =
    collision_shape.shape = convex_polygon

This code snippet outlines the conceptual process of splitting a concave shape into multiple convex polygons and applying them to a physical body. The actual decomposition algorithm would be beyond the scope of this introduction. However, in practice, Godot provides tools to assist with this, or you might utilize third-party libraries or tools to calculate the convex decomposition.In Godot, handling collisions efficiently means understanding not just how to create collision shapes, but also how to interact with other objects during collisions. Let’s continue with more practical examples of how to use `ConvexPolygonShape2D` in game development scenarios.

# Detecting if a point is inside the ConvexPolygonShape2D
var convex_polygon = $StaticBody2D/CollisionShape2D.shape
var point_to_check = Vector2(50, 50)

if convex_polygon.collide_with_point(point_to_check):
    print("Point is inside the polygon")
    print("Point is outside the polygon")

In this example, we’ve used the `collide_with_point` method to check whether a specific point is inside the area defined by our `ConvexPolygonShape2D`. This can be especially useful for point-and-click games or other gameplay mechanics that require precise interactions.

Handling collisions between two convex polygons can also be performed with ease. Here’s an example:

# Checking collision between two ConvexPolygonShape2D
var convex_polygon_1 = $StaticBody2D/CollisionShape2D.shape
var convex_polygon_2 = $OtherStaticBody2D/CollisionShape2D.shape
var transform_1 = $StaticBody2D.global_transform
var transform_2 = $OtherStaticBody2D.global_transform

if convex_polygon_1.collide_with_motion(transform_1, Vector2.ZERO, convex_polygon_2, transform_2, Vector2.ZERO):
    print("The polygons are colliding or intersecting")

In the `collide_with_motion` method, we’re checking for collision or intersection between two polygons using their global transforms. This is critical in dynamics scenes where objects may be moving and possibly rotating.

You might also want to not only know that a collision has occurred but also receive detailed information about it. God’s `ConvexPolygonShape2D` class can provide collision information:

# Getting collision information
var collision_info = convex_polygon_1.collide_and_get_contacts(transform_1, Vector2.ZERO, convex_polygon_2, transform_2, Vector2.ZERO)

if collision_info:
    print("Collision Point: ", collision_info.point)
    print("Collision Normal: ", collision_info.normal)
    print("Collision Depth: ", collision_info.depth)

This snippet demonstrates how to extract detailed collision data, including the collision point, normal, and penetration depth. This is useful for creating realistic physical responses like bounces or ricochets.

However, during a game, you might want to change not only the shape’s vertices but also the shape’s properties like `scale` or `rotation`. You can also create animations directly on the `ConvexPolygonShape2D`:

# Animating the ConvexPolygonShape2D
var tween =
var original_scale = $StaticBody2D/CollisionShape2D.scale
tween.interpolate_property($StaticBody2D/CollisionShape2D, "scale",
                           original_scale, original_scale * Vector2(2, 2),
                           1, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This code uses a `Tween` node to animate the scale property of the `CollisionShape2D` node that contains our `ConvexPolygonShape2D`. This can produce effects like a pulsating collision area, which can be visually appealing or serve gameplay purposes like indicating an attack zone.

Finally, when optimizing for many collisions or checking large numbers of points, you may want to use Godot’s direct space state for efficient physics queries:

# Using direct space state for efficient physics queries
var direct_space_state = get_world_2d().direct_space_state
var result = direct_space_state.intersect_point(point_to_check)

for collision in result:
    if "collider" in collision and collision.collider is StaticBody2D:
        # Handle collision with StaticBody2D here
        print("Collided with a StaticBody2D at ", collision.position)

Here we access the `direct_space_state` to perform a point intersection test across the entire physics world, which is much more efficient than testing individual shapes if you expect a high number of dynamic objects.

We hope these examples have given you a solid understanding of how the `ConvexPolygonShape2D` class can be used in your Godot projects. Whether you’re dealing with real-time collision detection, creating complex interactive shapes, or simply animating your game’s physics elements, `ConvexPolygonShape2D` provides the versatility and performance necessary for professional-quality game development. Happy coding!Another interesting application of `ConvexPolygonShape2D` is in the context of sensors. Sensors are used to detect whether objects are overlapping without causing a physical response. Here’s an example of making a ConvexPolygonShape2D into a sensor:

# Setting up a ConvexPolygonShape2D as a sensor
var collision_shape = $StaticBody2D/CollisionShape2D
collision_shape.shape =

In this snippet, we’ve set the `collision_shape`’s `set_as_trigger` property to `true`, creating a sensor that can detect overlaps without affecting the physical movement of the overlapping objects.

You may also want to apply an area of effect where anything that enters the area experiences a change or trigger an event. This is managed by monitoring the `area_entered` and `area_exited` signals of an `Area2D` node:

# Connecting signals for an Area2D with a ConvexPolygonShape2D
var area =
var convex_polygon =
var collision_shape =
collision_shape.shape = convex_polygon

# Connect the entered and exited signals to custom functions
area.connect("area_entered", self, "_on_area_entered")
area.connect("area_exited", self, "_on_area_exited")

# Place area in the world

func _on_area_entered(area):
    print("An area entered:",

func _on_area_exited(area):
    print("An area exited:",

Next, imagine you want to create a destructible environment, such as breaking a window into smaller pieces. You would dynamically adjust the `ConvexPolygonShape2D` to represent the changes in your environment:

# Dynamically modifying ConvexPolygonShape2D for destructible environments
func shatter_object():
    var shattered_pieces = [] # This would be calculated based on your shattering logic

    # Remove the original shape

    # Create new physics bodies for each piece
    for piece_points in shattered_pieces:
        var piece_body =
        var piece_shape =
        var piece_collision_shape =
        piece_collision_shape.shape = piece_shape

In the above `shatter_object` function, we’re simulating a destructible object by replacing the original `StaticBody2D` with new ones that have their own `ConvexPolygonShape2D` shapes to represent the shards.

When dealing with multiple moving objects, you might frequently need to check for potential collisions before an object actually moves. You can simulate the motion of an object using `test_motion` in `Physics2DDirectSpaceState`:

# Simulating motion to test for potential collisions
var body = $MovableBody2D
var transform = body.global_transform
var motion = Vector2(100, 0) # The intended motion vector

var collision = get_world_2d().direct_space_state.test_motion(

if collision.collided:
    print("Motion will result in a collision at ", collision.collision_point)
    print("Motion is clear")

This method can alert a moving object to potential collisions, allowing your game’s AI or physics system to react appropriately before the move is made.

Finally, we might look at integrating ConvexPolygonShape2D with Godot’s physics layers and masks. Physics layers and masks allow you to filter which objects will interact with others based on their assigned layer. Here’s a code snippet for setting up layers and masks for a ConvexPolygonShape2D:

# Configuring physics layers and masks
var body = $PhysicsBody2D
body.collision_layer = 1 # Assign to layer 1
body.collision_mask = 2 # Will only collide with objects in layer 2

var collision_shape =
var polygon_shape =
collision_shape.shape = polygon_shape


In this example, we have assigned the physics body to layer 1 and set its mask to detect collisions only with objects in layer 2, demonstrating how to set up interaction filters between objects.

These examples show a range of what `ConvexPolygonShape2D` can do in the Godot engine. By mastering this versatile tool, developers can create engaging and dynamic game experiences.

Where to Go Next?

Congratulations on taking the first steps toward mastering ConvexPolygonShape2D in Godot 4! But, don’t stop here—continue your game development journey with us at Zenva. Whether you are starting from the basics or looking to level up your skills, our Godot Game Development Mini-Degree is a perfect next step. Dive into our comprehensive courses that will teach you to build incredible cross-platform games using the powerful and user-friendly Godot 4 engine. Explore topics ranging from 2D and 3D assets to complete game mechanics for various game genres.

If you’re interested in expanding your Godot knowledge even further, take a look at our broad collection of Godot courses. These courses are tailored for a range of experience levels and are accessible anytime, anywhere, allowing you to learn at your own pace. By joining us, you get to take part in a learning experience with over 250 supported courses that not only hones your coding and game development skills but also helps you earn certificates to showcase your achievements. So, ready to go from beginner to professional? We’re here to help you make that leap with Zenva, your partner in learning and growth.


As we’ve explored, the ConvexPolygonShape2D class is an indispensable tool in the Godot 4 engine that opens up a world of possibilities for creating more dynamic and realistic physics in your 2D games. Understanding and effectively utilizing this class to its fullest potential can significantly enhance the player experience, making your games stand out. Remember, a well-implemented physics system can be the difference between a good game and a great one.

We at Zenva are excited to see the incredible games you’ll create with your newfound knowledge of Godot’s ConvexPolygonShape2D. Keep pushing the boundaries of what you can achieve, and when you’re ready to take your skills to the next level, explore our extensive curriculum of high-quality Godot courses. Start your journey today and unlock your potential in game development with Zenva’s Godot courses, where we craft each tutorial to guide you through every step of your learning path. Happy developing!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.