GPUParticlesAttractorBox3D in Godot – Complete Guide

Welcome to our latest tutorial, where we’ll explore the exciting world of particle systems in Godot 4, focusing on the GPUParticlesAttractorBox3D class. Particle systems are a fantastic way to add life and realism to games, creating effects like fire, smoke, rain, and magic. In this tutorial, we’ll delve into how we can manipulate these particles using the GPUParticlesAttractorBox3D, creating visually dynamic environments for our game projects. So, whether you’re new to Godot or an experienced developer looking to enhance your skills, this comprehensive guide will take you through everything you need to know about this powerful feature.

What is GPUParticlesAttractorBox3D?

A particle attractor is essentially a magnet for particles within a particle system, and GPUParticlesAttractorBox3D does exactly that, but with a twist. It’s a specialized node within the Godot engine designed to attract particles to a defined box-shaped region in 3D space. This offers developers a precise way to control where particles move, adding an extra layer of interaction in 3D environments.

What is it for?

The GPUParticlesAttractorBox3D is used when you want to simulate particles being influenced by an invisible force within a specific area. This could be used to create effects such as objects disintegrating into the air, leaves swirling inside a gust of wind, or the gravitational pull of a black hole influencing space debris.

Why Should I Learn It?

Understanding how to use the GPUParticlesAttractorBox3D class can significantly amplify the dynamism and realism of your game’s environments. It’s a versatile tool that can help you to create unique visual effects that respond to the game’s logic, enhancing the overall player experience. Moreover, mastering this aspect of Godot’s particle system can give you a competitive edge in the game development scene.

CTA Small Image

Setting Up a Simple Particle System

Before we can use the GPUParticlesAttractorBox3D, we need a basic particle system. In Godot, this is done using the GPUParticles node.

var particles =

Next, let’s assign a simple process material to our particles to give them a default appearance. This is where you define the look and behavior of individual particles.

var material =
material.gravity_vector = Vector3(0, -9.81, 0)
particles.process_material = material

Introducing the Particle Attractor

To control our particles, we’ll add a GPUParticlesAttractorBox3D node as a child of our particles.

var attractor =

Next, we’ll set the extents of our attractor box, determining the area of effect. We’ll also enable the attractor and set its strength.

attractor.extents = Vector3(1, 1, 1)
attractor.enabled = true
attractor.strength = 10

Adjusting Attraction Parameters

The appeal of the attractor comes from its customizability. Below, we adjust its damping and attenuation properties, which affect how particles slow down as they approach the attractor and how the attractor’s strength diminishes with distance.

attractor.damping = 0.5
attractor.attenuation = 1.0

We can also define the attractor’s falloff. Falloff determines how the strength of the attraction force fades over the distance from the attractor’s center to its extents. A value of 0 means no falloff; the attraction force is constant across the whole volume.

attractor.falloff = 0.2

Animating the Attractor

Attractors in motion can create particularly interesting effects. Here’s how we might animate the attractor’s position over time to create a sweeping motion.

func _process(delta):
    var time = OS.get_ticks_msec() / 1000.0
    attractor.global_transform.origin.x = sin(time) * 2.0

We could also animate the strength of the attractor to create a pulsing effect, simulating a beating heart or a flickering flame.

func _process(delta):
    var time = OS.get_ticks_msec() / 1000.0
    attractor.strength = sin(time) * 10.0 + 10.0

To fine-tune our particle system, we can go beyond basic properties. Let’s explore how adjusting the attractor’s directionality and reaction to particles can create diverse effects.

One way to tweak the behavior is by using a directional factor, which influences the direction in which the particles are attracted. Setting this to a vector that points upwards, for example, means the particles will be attracted in that direction.

attractor.directionality = Vector3(0, 1, 0)

If we want to make the attractor affect only particles within a certain distance, we can set a radius of influence. Particles outside this radius will be unaffected by the attractor.

attractor.radius = 2.0

We can adjust the particle system’s emission shape to emit particles from a specific form. Let’s create a box-shaped emission area that matches our attractor.

var box_shape =
box_shape.extents = Vector3(1, 1, 1)
material.emission_shape = ParticlesMaterial.EMISSION_SHAPE_BOX
material.emission_box_extents = box_shape.extents

A more complex effect involves adding a force field using the GPUParticlesAttractorBox3D node to impact particles’ velocity. We can create a wind-like force by setting a direction and magnitude.

attractor.force = Vector3(5, 0, 0)

Randomness can give our particle system a more organic feel. By introducing randomness to our attractor, we can simulate natural variances within the environment.

attractor.strength_randomness = 0.3
attractor.damping_randomness = 0.3

Finally, we could also keyframe the attractor properties to change over time, like slowly increasing the strength to simulate a growing force or vortex.

attractor.strength = lerp(attractor.strength, 50, delta * 0.1)

By manipulating these properties and experimenting with different combinations, we can achieve an array of effects, from subtle, natural movements to dramatic, physics-defying visuals. As we continue to explore Godot’s capabilities, we always find new ways to push the boundaries of in-game realism and the overall immersive experience.

Now that we’ve covered the basics, let’s enhance our particle system with some advanced techniques and code examples to truly make it shine.

For a more complex interplay of forces, we could add another attractor with opposing properties. This can create a tug-of-war effect. Here’s how:

var attractor2 =
attractor2.extents = Vector3(1, 1, 1)
attractor2.global_transform.origin = Vector3(4, 0, 0)  # Position it away from the first attractor
attractor2.strength = -10  # Negative strength to repel particles

A random movement effect creates a more chaotic and natural look for the particles. We’ll use the Godot built-in random number generator to vary the position of the attractor each frame.

func _process(delta):
    attractor.global_transform.origin = Vector3(
      rand_range(-1.0, 1.0),
      rand_range(-1.0, 1.0),
      rand_range(-1.0, 1.0)

To simulate magnetic fields, we can have particles orbit around the attractor. We adjust the damping and attenuation to maintain a near-constant distance.

attractor.strength = 20
attractor.damping = 0.1
attractor.attenuation = 0

It’s also possible to dynamically adjust the size of the attractor box during gameplay. This can be used for effects such as an expanding shockwave or an increasing gravitational pull.

func _process(delta):
    attractor.extents += Vector3(delta, delta, delta)  # Expanding the box each frame

Colliders can be used in conjunction with an attractor for particles to bounce off or stick to surfaces. Adding a collision shape as a child of our particles system can achieve this effect.

var collider =
collider.radius = 2
collider.damping = 0.8

To visualize the attractor box, we can draw a gizmo in the editor. This helps designers to better position and size the attractor directly within the scene editor.

func _draw():
    draw_box(attractor.extents, Color(0.25, 0.75, 1.0, 0.5))

These advanced techniques show the vast potential and flexibility of the Godot engine’s particle system. By combining multiple attractors, utilizing randomness, simulating orbital forces, and dynamically adjusting attractor properties, you can create immersive, responsive environments that react to the game’s logic and player actions.

Whether you’re looking to add nuanced atmospheric effects or elaborate visual spectacles, Godot and its GPUParticlesAttractorBox3D offer the tools necessary to elevate your game’s aesthetic to the next level. Continue experimenting and discovering new ways to incorporate these elements to craft compelling, interactive game worlds.

Where to Go Next

Your journey with Godot 4 and particle systems doesn’t have to end here! There’s an entire universe of knowledge waiting for you to explore. To continue sharpening your skills and expanding your game development repertoire, we at Zenva encourage you to dive into our Godot Game Development Mini-Degree. This comprehensive learning path covers a wide range of topics to help you build cross-platform games with confidence.

The courses included in the Mini-Degree are crafted to cater to both beginners and those with prior experience, ensuring you can progress at your ideal pace. While we can’t claim it covers GPUParticlesAttractorBox3D specifically, Godot’s rich features are thoroughly explored, giving you the tools to create compelling 2D and 3D gameplay experiences.

For those seeking a more extensive collection of Godot tutorials, be sure to check out our full selection of Godot courses. With Zenva, you can go from a beginner to a professional game developer, all while learning at your own pace and earning certificates to showcase your accomplishments.


Expanding your knowledge in game development, particularly with versatile tools like the Godot engine, opens up a world of creative possibilities. The GPUParticlesAttractorBox3D in Godot 4 is just one example of the powerful features at your disposal. With it, you can breathe dynamic life into your virtual worlds, captivating players with stunning visual effects. The only real limit is your imagination combined with the skills you cultivate along the way.

To take your game development journey even further and transform your ideas into playable realities, our Godot Game Development Mini-Degree is the perfect next step. We at Zenva are dedicated to guiding you through each stride in your educational adventure, offering the very best tools, resources, and courses to help you achieve your game creation dreams. So why wait? Dive in and start crafting the incredible gaming experiences you’ve always envisioned!

Python Blog Image

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