GPUParticlesCollisionHeightField3D

Inherits: GPUParticlesCollision3D < VisualInstance3D < Node3D < Node < Object

Real-time heightmap-shaped 3D particle attractor affecting GPUParticles3D nodes.

Description

Real-time heightmap-shaped 3D particle attractor affecting GPUParticles3D nodes.

Heightmap shapes allow for efficiently representing collisions for convex and concave objects with a single "floor" (such as terrain). This is less flexible than GPUParticlesCollisionSDF3D, but it doesn't require a baking step.

GPUParticlesCollisionHeightField3D can also be regenerated in real-time when it is moved, when the camera moves, or even continuously. This makes GPUParticlesCollisionHeightField3D a good choice for weather effects such as rain and snow and games with highly dynamic geometry. However, since heightmaps cannot represent overhangs, GPUParticlesCollisionHeightField3D is not suited for indoor particle collision.

Note: ParticleProcessMaterial.collision_mode must be true on the GPUParticles3D's process material for collision to work.

Note: Particle collision only affects GPUParticles3D, not CPUParticles3D.

Properties

Vector3

extents

Vector3(1, 1, 1)

bool

follow_camera_enabled

false

Resolution

resolution

2

UpdateMode

update_mode

0

Enumerations

enum Resolution:

  • RESOLUTION_256 = 0 --- Generate a 256×256 heightmap. Intended for small-scale scenes, or larger scenes with no distant particles.

  • RESOLUTION_512 = 1 --- Generate a 512×512 heightmap. Intended for medium-scale scenes, or larger scenes with no distant particles.

  • RESOLUTION_1024 = 2 --- Generate a 1024×1024 heightmap. Intended for large scenes with distant particles.

  • RESOLUTION_2048 = 3 --- Generate a 2048×2048 heightmap. Intended for very large scenes with distant particles.

  • RESOLUTION_4096 = 4 --- Generate a 4096×4096 heightmap. Intended for huge scenes with distant particles.

  • RESOLUTION_8192 = 5 --- Generate a 8192×8192 heightmap. Intended for gigantic scenes with distant particles.

  • RESOLUTION_MAX = 6 --- Represents the size of the Resolution enum.


enum UpdateMode:

  • UPDATE_MODE_WHEN_MOVED = 0 --- Only update the heightmap when the GPUParticlesCollisionHeightField3D node is moved, or when the camera moves if follow_camera_enabled is true. An update can be forced by slightly moving the GPUParticlesCollisionHeightField3D in any direction.

  • UPDATE_MODE_ALWAYS = 1 --- Update the heightmap every frame. This has a significant performance cost. This update should only be used when geometry that particles can collide with changes significantly during gameplay.

Property Descriptions

Default

Vector3(1, 1, 1)

Setter

set_extents(value)

Getter

get_extents()

The collision heightmap's extents in 3D units. To improve heightmap quality, extents should be set as small as possible while covering the parts of the scene you need.


  • bool follow_camera_enabled

Default

false

Setter

set_follow_camera_enabled(value)

Getter

is_follow_camera_enabled()

If true, the GPUParticlesCollisionHeightField3D will follow the current camera in global space. The GPUParticlesCollisionHeightField3D does not need to be a child of the Camera3D node for this to work.

Following the camera has a performance cost, as it will force the heightmap to update whenever the camera moves. Consider lowering resolution to improve performance if follow_camera_enabled is true.


Default

2

Setter

set_resolution(value)

Getter

get_resolution()

Higher resolutions can represent small details more accurately in large scenes, at the cost of lower performance. If update_mode is UPDATE_MODE_ALWAYS, consider using the lowest resolution possible.


Default

0

Setter

set_update_mode(value)

Getter

get_update_mode()

The update policy to use for the generated heightmap.