PhysicsTestMotionResult2D in Godot – Complete Guide

Discovering the intricacies of game development can be an exhilarating ride, especially when delving into physics simulation in 2D environments. One critical class that handles the outcomes of simulated physics motions in Godot Engine 4 is `PhysicsTestMotionResult2D`. This class is a powerhouse behind the scenes, determining how objects interact and collide within your 2D world. Throughout this tutorial, you’ll gain a deeper understanding of this class, using it to enrich your game projects with realistic and engaging physics-based interactions.

What is PhysicsTestMotionResult2D?

`PhysicsTestMotionResult2D` is a Godot Engine class that provides detailed information about the result of a motion test performed by `PhysicsServer2D.body_test_motion`. This test is essential for predicting if an object’s movement will result in a collision. The class is filled with methods that give you access to key pieces of information regarding the collision—such as the colliding object’s information, the point of collision, and the remaining movement after the interaction.

What is it for?

The `PhysicsTestMotionResult2D` class is designed for scenarios where you need to know the outcome of an object’s motion—like if it’s going to hit something and what will happen as a result. This is crucial in game development for:

– Collision prediction and response
– Character movement handling
– Implementing custom physics interactions
– Debugging complex scenes

Why should I learn it?

A solid grip on `PhysicsTestMotionResult2D` is invaluable for crafting intuitive and responsive game mechanics. Learning how to implement and interpret motion tests allows you to:

– Improve performance by optimizing collision handling
– Create more immersive and believable game worlds
– Solve common problems faced in 2D game development
– Bolster your toolkit with professional techniques that can be transferred to a plethora of projects

Equipping yourself with this knowledge not only enhances your current projects but also sets a foundation for future game development endeavors.

CTA Small Image

Setting Up the Physics Environment

Before we dive into the specifics of using `PhysicsTestMotionResult2D`, let’s set up our physics environment to see this class in action. Here, we will create a basic 2D scene with a physics body that we intend to move and test for potential collisions.

var body =
var shape =
shape.extents = Vector2(10, 10)

In this snippet, we’re creating a new physics body and assigning it a rectangular shape. We also add the newly created physics body to the scene. Now, let’s set up the environment obstacles.

var obstacle =
var obstacle_shape =
obstacle_shape.extents = Vector2(50, 50)
obstacle.position = Vector2(300, 300)

This creates a static body that will serve as an obstacle in our scene.

Testing Motion Without Collisions

It’s essential to understand how to perform a simple test to predict motion without collisions. Here, we’ll move our body across the scene smoothly without hitting any obstacles.

var motion = Vector2(100, 0)
var from = body.transform.origin
var to = from + motion
var motion_test_result =

if PhysicsServer2D.body_test_motion(body.get_rid(), from, motion, motion_test_result):
    # Motion test succeeded but there's no collision.
    # We can safely move our body.
    body.transform.origin = to

In the code above, we use the `body_test_motion` method to test if our body can move 100 pixels to the right without colliding.

Handling Collisions with PhysicsTestMotionResult2D

Next, let’s use `PhysicsTestMotionResult2D` to determine the results of a collision during motion testing, and adjust our movement accordingly.

var motion = Vector2(300, 0)
var from = body.transform.origin
var motion_test_result =

if PhysicsServer2D.body_test_motion(body.get_rid(), from, motion, motion_test_result):
    # Collision occurred. motion_test_result now contains the collision information.
    body.transform.origin += motion_test_result.motion
    # No collision, we can move normally.
    body.transform.origin += motion

Here, the `motion_test_result.motion` indicates how far the body can move before it collides with an obstacle.

Extracting Collision Information

When a collision is detected, `PhysicsTestMotionResult2D` provides useful collision information which we can use to build advanced physics interactions.

if PhysicsServer2D.body_test_motion(body.get_rid(), from, motion, motion_test_result):
    # Get the collision point
    var collision_point = motion_test_result.collision_point

    # Get the normal of the collision surface
    var collision_normal = motion_test_result.collision_normal

    # Output the results
    print("Collision point: " + str(collision_point))
    print("Collision normal: " + str(collision_normal))

Always keep in mind that the collision information is only reliable when the `body_test_motion` method returns `true`, indicating a collision.

Adjusting Movement After Collisions

Finally, let’s deal with adjusting the movement after the initial collision using the remainder of the motion vector.

if PhysicsServer2D.body_test_motion(body.get_rid(), from, motion, motion_test_result):
    # Move to the collision point
    body.transform.origin += motion_test_result.motion

    # Adjust the remaining motion to slide along the obstacle
    var slide_motion = motion_test_result.remainder.slide(motion_test_result.collision_normal)
    body.transform.origin += slide_motion

The `slide()` method uses the collision normal to calculate the remaining movement vector that slides along the surface of the obstacle. This enables smoother collision responses, especially in platformers or physics-based puzzles.

These examples give you a taste of how `PhysicsTestMotionResult2D` operates within Godot Engine. As you integrate these elements into your games, you’ll find they offer a robust foundation for complex and realistic physics interactions.Great! Let’s delve even deeper into the working of `PhysicsTestMotionResult2D` and explore how to use it for more nuanced game mechanics such as predicting collisions before they happen, which can be extremely useful for AI movement or preemptive collision response systems.

Advanced Collision Detection Techniques

Imagine you are developing a game where the player can charge up a dash move that propels them forward at high speed. We want to predict whether the dash will result in a collision and, if so, stop the move before it happens.

var dash_motion = Vector2(400, 0)
if PhysicsServer2D.body_test_motion(body.get_rid(), body.global_position, dash_motion, motion_test_result):
    # A collision will occur if the dash is performed.
    # Do not perform the dash.
    print("Dash move blocked by obstacle!")
    # No collision detected, safe to dash.
    body.global_position += dash_motion

In this example, we test the motion before enacting the dash to ensure the path is clear—enhancing game strategy and preventing player frustration.

Let’s build on this to calculate what would happen if we want to continue moving after a collision, perhaps to ricochet or bounce backward.

if PhysicsServer2D.body_test_motion(body.get_rid(), body.global_position, dash_motion, motion_test_result):
    # A collision will occur. Let's bounce back.
    var bounce_motion = motion_test_result.motion.bounce(motion_test_result.collision_normal)
    body.global_position += bounce_motion

Utilizing `bounce` with the collision normal inverts the motion vector, effectively simulating a bounce effect on collision.

Now, consider an enemy character that predicts its trajectory to avoid running into walls:

var enemy_speed = Vector2(200, 0)
if not PhysicsServer2D.body_test_motion(enemy_body.get_rid(), enemy_body.global_position, enemy_speed, motion_test_result):
    # Path is clear, continue moving
    enemy_body.global_position += enemy_speed
    # Collision ahead! Let's change direction.
    enemy_speed.x *= -1

In this scenario, the enemy can foresee a collision with `body_test_motion` and use this prediction to change its path of motion, thus demonstrating a simple yet effective AI mechanic.

Optimizing Game Physics with Collision Layers

Collision layers and masks add another layer of sophistication by allowing you to specify which objects should be considered during the motion test. For instance, you might want your player’s dash move to ignore coins or power-ups and only stop for walls:

body.collision_layer = 1
body.collision_mask = 1

# Coin collision layer and mask
coin.collision_layer = 2
coin.collision_mask = 0 # Coins do not need to detect collisions

# Perform the motion test taking into account only the layers that the body reacts to
if PhysicsServer2D.body_test_motion(body.get_rid(), body.global_position, dash_motion, motion_test_result, body.collision_mask):
    # Collision detected with an object on the appropriate layer.

In this example, the `collision_layer` identifies the layer the body is on, while the `collision_mask` determines which layers the body will consider for collisions.

Utilizing Collision Data for Game Mechanics

Collision data can also control more complex behaviors, such as platforms that collapse when a player steps on them. By examining collision details, you can trigger events:

var platform_body =

if PhysicsServer2D.body_test_motion(platform_body.get_rid(), platform_body.global_position, Vector2.ZERO, motion_test_result):
    if motion_test_result.collider == player:
        # Player has stepped on the platform - let's make it fall.
        platform_body.mode = RigidBody2D.MODE_RIGID

Here, we test if the platform is colliding with the player (or any other body). If the test detects a collision and identifies the player as the collider, the platform switches to a rigid body and will fall due to gravity.

Remember that making the most of the Godot Engine’s physics system means understanding and leveraging every bit of collision data you can. As you practice and apply these techniques, you’ll find that your game mechanics will reach new heights in terms of responsiveness and immersion. Keep experimenting, and you’ll be a master of the Godot physics engine in no time!Let’s further explore practical applications of collision data obtained from `PhysicsTestMotionResult2D` in game mechanics. We’ll examine more hands-on examples, often encountered in game development.

Consider a scenario where the player can push objects. When the player attempts a push, we need to test if the object can be moved in the intended direction without running into obstacles.

var push_strength = Vector2(50, 0)
if PhysicsServer2D.body_test_motion(pushable_object.get_rid(), pushable_object.global_position, push_strength, motion_test_result):
    if motion_test_result.collider.is_in_group("pushable"):
        # The object can be pushed and there's space to push it towards.
        pushable_object.global_position += motion_test_result.motion
        # There's an obstacle that prevents pushing the object.
        print("Object cannot be pushed in that direction!")

In this example, the player’s push motion is calculated, and we test if there’s sufficient space to push the object without hitting other objects, specifically looking for those in the “pushable” group.

Next up, let’s address environmental effects, such as wind or currents that redirect the player’s movement.

var wind_direction = Vector2(1, 0)
var wind_strength = 10

func _physics_process(delta):
    var motion = wind_direction * wind_strength * delta
    if not PhysicsServer2D.body_test_motion(player.get_rid(), player.global_position, motion, motion_test_result):
        # Apply wind effect only if there's no immediate obstacle.
        player.global_position += motion

This snippet applies a force simulating wind to the player each physics frame, but only if the immediate path is unhindered by obstacles.

Another typical use case is the detection of fall damage. You could predict if a fall will be too high and cause damage to the player.

var fall_distance = Vector2(0, 200)  # Distance representing a fatal fall.

if PhysicsServer2D.body_test_motion(player.get_rid(), player.global_position, fall_distance, motion_test_result):
    if motion_test_result.collision_point.y >= fall_distance.y:
        # The fall is going to be harsh; apply damage.
        # Safe landing; no damage needed.

A character’s fall motion is tested, and if the collision point indicates a long fall, damage is applied to the character.

Let’s also consider a character with a grappling hook that can pull them up to ledges.

var grapple_point = get_grapple_point()  # Assume this function calculates where the grappling hook lands.
var grapple_motion = grapple_point - player.global_position

if PhysicsServer2D.body_test_motion(player.get_rid(), player.global_position, grapple_motion, motion_test_result):
    # Move the player straight to the ledge pointed by the grappling hook.
    var safe_to_grapple = motion_test_result.collision_point == grapple_point
    if safe_to_grapple:
        player.global_position = grapple_point

In this sample, before the grappling hook pulls the character, the potential motion to the intended grapple point is tested to ensure it’s clear, delivering a smooth grappling experience.

Finally, let’s implement an example for a character that ducks to avoid projectiles, taking advantage of `PhysicsTestMotionResult2D` to check if there’s adequate clearance overhead.

func try_ducking(player):
    var duck_motion = Vector2(0, -20)  # Slight upward motion to test clearance.

    if PhysicsServer2D.body_test_motion(player.get_rid(), player.global_position, duck_motion, motion_test_result, ~0):
        if motion_test_result.collision_point.is_zero():
            # There's enough room to duck.
            # Something is obstructing the space needed to duck.
            print("Not enough space to duck!")

In this script, a ducking action is contingent on whether there’s space for the character to duck without their head colliding with an object above. If there’s an obstruction, the character cannot duck.

These examples illustrate the versatile nature of `PhysicsTestMotionResult2D`, showcasing its vital role in creating dynamic and responsive game mechanics. By effectively leveraging this class, you can design immersive, interactive worlds with a high level of polish that players will certainly appreciate.

Continuing Your Game Development Journey

Mastering the intricacies of game physics with classes like PhysicsTestMotionResult2D is just the beginning. If you’re ready to take your Godot game development skills further, we invite you to explore our Godot Game Development Mini-Degree. This comprehensive selection of courses will guide you through building cross-platform games with Godot 4, catering to both beginners looking to get started and experienced developers aiming to polish their skills.

Learn to craft detailed game worlds with engaging 2D and 3D gameplay, master GDScript, and understand the mechanics behind different game genres. With our self-paced learning, you’ll have the flexibility to grow your skills on your own terms, supported by our extensive range of courses. For a broader look at what’s available, check out our full selection of Godot courses.

As you continue to learn and create, remember that game development is a journey of constant discovery and innovation. We’re excited to see the games you’ll build and the challenges you’ll overcome. Let your creativity flow, and happy coding!


Armed with a deeper understanding of the PhysicsTestMotionResult2D class and its applications, you’re now equipped to elevate the physical dynamism of your Godot Engine-powered games. Being able to predict and respond to collisions before they occur opens up a new realm of interactive possibilities, ensuring your gameplay experiences stand out with their refined physics mechanics.

Remember, the journey doesn’t end here! There’s always more to learn, more to create, and more to explore with Godot. If this tutorial stirred your passion for game development, we encourage you to continue honing your skills with our Godot Game Development Mini-Degree. See you in the virtual classroom, and in the meantime, may your game development path be as collision-free as your in-game characters!

Python Blog Image

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