PhysicsServer2DExtension in Godot – Complete Guide

Learning new programming techniques and tools can be a thrilling part of a developer’s journey, particularly when it involves game development. Delving into the intricacies of physics simulation adds that extra layer of realism to any game, making things like collisions and movement feel more authentic. In this article, we explore the PhysicsServer2DExtension class in Godot 4, an exciting feature that allows you to extend the capabilities of the built-in physics server, opening up a realm of possibilities for more complex and nuanced physics interactions in your 2D games.

What Is PhysicsServer2DExtension?

The PhysicsServer2DExtension in Godot is essentially an advanced interface for custom physics behavior. Inheriting from PhysicsServer2D, it equips the developer with a set of virtual methods that can be overridden to craft tailored physics responses and interactions. This is a powerful feature for creating gameplay that requires physics beyond the standard behaviors provided out of the box with Godot.

What Is It Used For?

The extended capabilities of PhysicsServer2DExtension can be applied to an array of custom needs in a game. Whether it’s intricate collision detection, creating unique movement paradigms, or any form of physics-based game logic, this class helps in customizing your game’s physics to a T.

Why Should You Learn It?

Understanding and utilizing the PhysicsServer2DExtension can be crucial for games where the built-in physics don’t entirely suit your needs. The flexibility to define your physics allows for more creative control and can lead to more engaging gameplay experiences. Learning to work with this tool means you don’t have to compromise on how you envision your game’s mechanics and it pushes you to become a more proficient and versatile Godot developer.

CTA Small Image

Getting Started with PhysicsServer2DExtension

To implement your own physics behaviors using the PhysicsServer2DExtension, you need to first understand how to set it up within your Godot project. Let’s start by creating a custom physics extension script. In Godot, scripts that extend C++ classes can be written in GDScript, providing a mix of simplicity and performance.

extends PhysicsServer2DExtension

func _body_created_callback(body_id):
    print("A physics body was created with ID: ", body_id)

func _init():
    # Override the '_body_created' callback.
    _body_created = _body_created_callback

Notice how we define a “_body_created_callback” function that prints the ID of a newly created body. Then we override the “_body_created” method of the PhysicsServer2DExtension by assigning our custom callback to it.

Custom Collision Detection

One of the most crucial aspects of physics in games is collision detection. With PhysicsServer2DExtension, we can create custom collision logic that activates whenever an object collides.

extends PhysicsServer2DExtension

func _pre_solve_callback(body_id, other_body_id, area):
    print("Pre solve event between body ", body_id, " and ", other_body_id)

func _init():
    # Override the '_body_pair_pre_solve' callback.
    _body_pair_pre_solve = _pre_solve_callback

Above, the “_pre_solve_callback” is called just before the physics solver resolves the collision. You can define custom collision responses or filter collisions here.

Modifying Physics Properties

Beyond detecting collisions, you might want to alter the physics properties of objects at runtime. The following example demonstrates how to adjust the gravity scale of a physics body.

extends PhysicsServer2DExtension

var custom_gravity_scale = 2.0

func _body_created_callback(body_id):
    PhysicsServer2D.body_set_param(body_id, PhysicsServer2D.BODY_PARAM_GRAVITY_SCALE, custom_gravity_scale)

func _init():
    # Override the '_body_created' callback.
    _body_created = _body_created_callback

When a body is created, the “_body_created_callback” is triggered, setting its gravity scale to whatever we define in “custom_gravity_scale.”

Custom Movement Behaviors

Imagine you’re creating a platformer, and you need a platform that follows a wave-like movement path. The PhysicsServer2DExtension makes it simple to apply such custom motion.

extends PhysicsServer2DExtension

func _integrate_forces_callback(state):
    var body_id = state.get_body_id()
    var time = OS.get_system_time_secs()
    var new_position = Vector2(200 * sin(time), state.get_transform().origin.y)
    PhysicsServer2D.body_set_state(body_id, PhysicsServer2D.BODY_STATE_TRANSFORM, Transform2D(0, new_position))

func _init():
    # Override the '_body_integrate_forces' callback.
    _body_integrate_forces = _integrate_forces_callback

The “_integrate_forces_callback” method is used to override the default motion with a sine wave movement based on system time, perfect for a moving platform behavior.

These examples provide a foundation to start working with the PhysicsServer2DExtension in Godot. More advanced implementations might involve combining multiple callbacks and extensive state management, but the basics covered here give you the tools to start experimenting with your physics interactions in your 2D games.

To further enhance your understanding of the advanced physics manipulation you can achieve with Godot’s PhysicsServer2DExtension, let’s look at additional examples showcasing different scenarios and solutions.

Advanced Collision Response

Manipulating the outcome of a collision can add satisfying tactile feedback or create unique game mechanics. Here, we adjust the bounciness of an object when it collides with another specific object type.

func _area_pair_pre_solve_callback(area_id, area_body_id, body_id, other_body_id):
    var body_shape = 0 # The shape index of the body
    var other_body_shape = 0 # The shape index of the other body
    PhysicsServer2D.area_set_shape_as_one_way_collision(area_id, body_shape, true, Vector2.UP, 1.0, other_body_id, other_body_shape)

func _init():
    # Override the '_area_pair_pre_solve' callback.
    _area_pair_pre_solve = _area_pair_pre_solve_callback

In this example, we use “_area_pair_pre_solve” to make a body’s collision one-way, allowing it to only collide in a specific direction.

Physics States and Queries

Sometimes you need to query physics states or details about bodies in the simulation. Here we gather information about a body’s velocity.

func _body_pair_post_solve_callback(body_id, other_body_id, state):
    var velocity = PhysicsServer2D.body_get_state(body_id, PhysicsServer2D.BODY_STATE_LINEAR_VELOCITY)
    print("The body's current velocity is: ", velocity)

func _init():
    # Override the '_body_pair_post_solve' callback.
    _body_pair_post_solve = _body_pair_post_solve_callback

Post-collision, “_body_pair_post_solve_callback” is used to print the current velocity, showing how you can access and utilize the PhysicsServer2D’s state information.

Custom Force Application

Applying forces to bodies to simulate effects like wind or explosions is another potential use case. We can apply a custom impulse to a body as shown below:

func _body_created_callback(body_id):
    var impulse = Vector2(100, 0)
    var position = Vector2() # Apply the impulse at the body's center
    PhysicsServer2D.body_apply_impulse(body_id, position, impulse)

func _init():
    # Override the '_body_created' callback.
    _body_created = _body_created_callback

Upon creation, this script applies a horizontal impulse to the body, simulating a push or gust of wind.

Collision Layers and Masking

Fine-tuning which bodies collide with which other bodies often involves adjusting collision layers and masks. Let’s set this up programmatically:

func _body_created_callback(body_id):
    var collision_layer = 1 # Assign to the first layer
    var collision_mask = 2 # Will only collide with bodies in the second layer
    PhysicsServer2D.body_set_collision_layer(body_id, collision_layer)
    PhysicsServer2D.body_set_collision_mask(body_id, collision_mask)

func _init():
    # Override the '_body_created' callback.
    _body_created = _body_created_callback

By manipulating the collision layers and masks, we can control interaction between different game elements, defining friends and obstacles for the individual bodies.

The power of PhysicsServer2DExtension lies in its ability to let you tailor the physics of your game down to the smallest detail, allowing for unique interactions tailored to the requirements of your game. From basic collision responses to advanced movement dynamics and state querying, these are just a few examples of how we can begin to shape our game world’s behavior using Godot’s flexible physics engine.

As with any system involving physics and mathematics, experimentation is key. With these tools at our disposal, we can ensure that we’re not just simulating physics — we’re creating a physics system that complements the gameplay and enhances the overall player experience.

Exploring further depths of the PhysicsServer2DExtension’s capabilities, let’s look at how we can craft even more intricate behaviors that can truly bring our game physics to life.

Synchronizing Physics with Animation

Binding physics body states to animation frames can achieve a high degree of realism or visual flair. Consider synchronizing a character’s animation to its in-game physics state:

func _sync_animation_with_physics(body_id, animation_player):
    var velocity = PhysicsServer2D.body_get_state(body_id, PhysicsServer2D.BODY_STATE_LINEAR_VELOCITY)
    if velocity.length() > 10:"run")

func _init():
    # Assume we have a reference to an AnimationPlayer node
    var body_id = get_node("Character").get_rid()
    var animation_player = get_node("Character/AnimationPlayer")
    var process_callback = funcref(self, "_sync_animation_with_physics")
    PhysicsServer2D.body_set_force_integration_callback(body_id, process_callback, animation_player)

Here, we register a callback to run each physics frame. It checks the velocity of the character’s body and plays the corresponding animation.

Creating Trigger Zones

Physics triggers let us detect when objects enter specific zones without causing a physical collision. This is essential for traps, secret areas, or pickups:

func _area_body_entered_callback(area_id, body_id):
    print("Body ", body_id, " entered the trigger zone with ID ", area_id)

func _init():
    # Set up the callback for when a body enters an area
    _area_body_entered = _area_body_entered_callback

By using “_area_body_entered”, our game can react whenever a body enters the defined area.

Modifying Physical Properties on the Fly

For dynamic gameplay, you might need to change a body’s physical properties, such as its mass or damping, in response to in-game events:

func _change_body_properties(body_id, new_mass, new_linear_damp):
    PhysicsServer2D.body_set_param(body_id, PhysicsServer2D.BODY_PARAM_MASS, new_mass)
    PhysicsServer2D.body_set_param(body_id, PhysicsServer2D.BODY_PARAM_LINEAR_DAMP, new_linear_damp)

func _init():
    var body_id = get_node("Rigidbody").get_rid()
    var new_mass = 4.0
    var new_damp = 5.0
    _change_body_properties(body_id, new_mass, new_damp)

With the “_change_body_properties” function, our bodies can alter their behavior depending on their environment, actions, or power-ups.

Advanced Raycasting

Raycasting is a way to detect objects in a line, used for shooting mechanics, line-of-sight checks, and more. You can cast rays directly from the PhysicsServer2D to check for collisions:

func _cast_ray(from, to, exclude=[]):
    var space_state = PhysicsServer2D.space_get_direct_state(PhysicsServer2D.get_default_space())
    var result = space_state.intersect_ray(from, to, exclude)
    if result:
        print("Ray hit: ",

func _init():
    var from = Vector2(100, 100)
    var to = Vector2(400, 400)
    var exclude = [get_node("Player").get_rid()]
    _cast_ray(from, to, exclude)

In this snippet, “_cast_ray” checks for anything in the path between two points, ignoring certain objects if needed.

Handling Continues Collision Detection (CCD)

For fast-moving objects that might pass through other objects without registering a collision, Godot’s PhysicsServer2DExtension offers CCD support:

func _enable_ccd_for_body(body_id):
    PhysicsServer2D.body_set_continuous_collision_detection_mode(body_id, PhysicsServer2D.CCD_MODE_CAST_SHAPE)

func _init():
    var body_id = get_node("FastMovingObject").get_rid()

By calling “_enable_ccd_for_body”, we can set up fast-moving bodies so they don’t tunnel through other objects between frames, ensuring reliable collision detection.

The examples showcase the adaptability of PhysicsServer2DExtension in creating polished, physical interactions within your 2D games. By leveraging these advanced features, your game won’t just have physics—it will have personality and responsiveness that resonates with the player’s every action and decision.

Whether you’re designing a fast-paced action game, a detailed simulator, or just want to add some extra juice to your game’s interactions, mastering the PhysicsServer2DExtension expands your toolkit as a Godot developer, letting you craft experiences that feel grounded and immersive. Use these examples as jumping-off points, and you’ll be on your way to personalizing your game’s physics system to best suit the adventures that await your players.

Next Steps in Your Game Development Journey

Congratulations on taking this step into customizing 2D Physics with Godot’s PhysicsServer2DExtension! But, don’t stop here. Game development is a vast and rewarding field that continues to evolve, offering endless learning opportunities. To further explore the wonders of Godot and take your skills to the next level, we at Zenva encourage you to dive into our Godot Game Development Mini-Degree. This comprehensive course collection will guide you through the creation of cross-platform games, using a variety of assets and in-depth lessons on gameplay mechanics.

From crafting immersive RPGs to adrenaline-fueled platformers, the mini-degree encompasses essential knowledge for both beginners and seasoned developers looking to refresh or upgrade their skill set. With access to rich content and project-based learning, you’ll solidify your expertise and build a professional portfolio that showcases your abilities. Learn at your own pace with our flexible learning structure, and join a community of developers on the same path.

Interested in broadening your horizons even more? Explore our full range of Godot courses, each designed to empower you with practical, job-ready skills in game development. Wherever your interests lie within the realm of Godot, we’re here to support your learning and help you achieve your goals. Let’s continue creating amazing game experiences together!


Embarking on a journey through Godot’s PhysicsServer2DExtension has hopefully opened your eyes to the vast potential and customizability of game physics. Remember, the games that stand out are those that push the boundaries, that offer players something unique and memorable. By leveraging the powerful features of Godot, you’re well on your way to delivering those standout experiences. Harness these tools, blend them with your creativity, and watch as your virtual worlds come to life with unparalleled interactivity.

We at Zenva are committed to helping you turn your game development dreams into reality. Our Godot Game Development Mini-Degree is the perfect companion on this exciting path. With Zenva, you’re not just learning to code; you’re learning to create, to innovate, and to bring joy to players around the world. So keep experimenting, keep learning, and most importantly, keep enjoying every step of your game creation adventure. Here’s to the countless possibilities that await you in the world of Godot!

Python Blog Image

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