Up to date

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

3D Particle collisions

Since GPU particles are processed entirely on the GPU, they don't have access to the game's physical world. If you need particles to collide with the environment, you have to set up particle collision nodes. There are four of them: GPUParticlesCollisionBox3D, GPUParticlesCollisionSphere3D, GPUParticlesCollisionSDF3D, and GPUParticlesCollisionHeightField3D.

Примечание

GPU Particle collision is not yet implemented for 2D particle systems.

Common properties

Common collision properties

There are some properties that you can find on all collision nodes. They're located in the GPUParticlesCollision3D section in the inspector.

The Cull Mask property controls which particle systems are affected by a collision node based on each system's visibility layers. A particle system collides with a collision node only if at least one of the system's visibility layers is enabled in the collider's cull mask.

Предупреждение

There is a known issue with GPU particle collision that prevent the cull mask from working properly in Godot 4.0. We will update the documentation as soon as it is fixed.

Box collision

Box collision in the node list

Box collision nodes are shaped like a solid, rectangular box. You control their size with the Extents property. Box extents always measure half of the sides of its bounds, so a value of (X=1.0,Y=1.0,Z=1.0) creates a box that is 2 meters wide on each side. Box collision nodes are useful for simulating floor and wall geometry that particles should collide against.

To create a box collision node, add a new child node to your scene and select GPUParticlesCollisionBox3D from the list of available nodes. You can animate the box position or attach it to a moving node for more dynamic effects.

Two particle systems collide with a box collision node

Sphere collision

Sphere collision in the node list

Sphere collision nodes are shaped like a solid sphere. The Radius property controls the size of the sphere. While box collision nodes don't have to be perfect cubes, sphere collision nodes will always be spheres. If you want to set width independently from height, you have to change the Scale property in the Node3D section.

To create a sphere collision node, add a new child node to your scene and select GPUParticlesCollisionSphere3D from the list of available nodes. You can animate the sphere's position or attach it to a moving node for more dynamic effects.

Two particle systems collide with a sphere collision node

Height field collision

Height field collision in the node list

Столкновение частиц в поле высот очень полезно для больших открытых областей, которым необходимо сталкиваться с частицами. Во время выполнения узел создает поле высоты из всех ячеек в пределах его границ, которые соответствуют его маске отсечения. Частицы сталкиваются с сеткой, которую представляет это поле высоты. Поскольку генерация поля высот выполняется динамически, оно может следовать за камерой игрока и реагировать на изменения уровня. Различные настройки плотности поля высот предлагают широкий диапазон настроек производительности.

Чтобы создать узел столкновения поля высот, добавьте в сцену новый дочерний узел и выберите GPUParticlesCollisionHeightField3D из списка доступных узлов.

A height field collision node is shaped like a box. The Extents property controls its size. Extents always measure half of the sides of its bounds, so a value of (X=1.0,Y=1.0,Z=1.0) creates a box that is 2 meters wide on each side. Anything outside of the node's extents is ignored for height field creation.

Свойство Resolution управляет детализацией поля высоты. Более низкое разрешение работает быстрее за счет точности. Если разрешение поля высот слишком низкое, это может выглядеть так, будто частицы проникают в геометрию уровня или застревают в воздухе во время столкновений. Они также могут полностью игнорировать некоторые более мелкие сетки.

При низком разрешении при столкновении полей высот упускаются некоторые мелкие детали (слева)

The Update Mode property controls when the height field is recreated from the meshes within its bounds. Set it to When Moved to make it refresh only when it moves. This performs well and is suited for static scenes that don't change very often. If you need particles to collide with dynamic objects that change position frequently, you can select Always to refresh every frame. This comes with a cost to performance and should only be used when necessary.

Примечание

Важно помнить, что когда для параметра Update Mode установлено значение When Moved, именно height field node, перемещение которого запускает обновление. Поле высоты не обновляется, когда одна из ячеек внутри него перемещается.

Свойство Follow Camera Enabled заставляет поле высоты следовать за текущей камерой, если оно включено. Он будет обновляться при каждом движении камеры. Это свойство можно использовать, чтобы гарантировать, что вокруг игрока всегда происходит столкновение частиц, не теряя при этом производительности в областях, которые находятся вне поля зрения или слишком далеко.

SDF столкновения

Столкновения SDF в списке узлов

SDF collision nodes create a signed distance field that particles can collide with. SDF collision is similar to height field collision in that it turns multiple meshes within its bounds into a single collision volume for particles. A major difference is that signed distance fields can represent holes, tunnels and overhangs, which is impossible to do with height fields alone. The performance overhead is larger compared to height fields, so they're best suited for small-to-medium-sized environments.

To create an SDF collision node, add a new child node to your scene and select GPUParticlesCollisionSDF3D from the list of available nodes. SDF collision nodes have to be baked in order to have any effect on particles in the level. To do that, click the Bake SDF button in the viewport toolbar while the SDF collision node is selected and choose a directory to store the baked data. Since SDF collision needs to be baked in the editor, it's static and cannot change at runtime.

SDF particle collision allows for very detailed 3-dimensional collision shapes

An SDF collision node is shaped like a box. The Extents property controls its size. Extents always measure half of the sides of its bounds, so a value of (X=1.0,Y=1.0,Z=1.0) creates a box that is 2 meters wide on each side. Anything outside of the node's extents is ignored for collision.

The Resolution property controls how detailed the distance field is. A lower resolution performs faster at the cost of accuracy. If the resolution is too low, it may look like particles penetrate level geometry or get stuck in the air during collision events. They might also ignore some smaller meshes completely.

Одна и та же область, покрытая полем расстояний со знаком при разных разрешениях: 16 (слева) и 256 (справа)

The Thickness property gives the distance field, which is usually hollow on the inside, a thickness to prevent particles from penetrating at high speeds. If you find that some particles don't collide with the level geometry and instead shoot right through it, try setting this property to a higher value.

The Bake Mask property controls which meshes will be considered when the SDF is baked. Only meshes that render on the active layers in the bake mask contribute to particle collision.