Table of Contents

Class GPUParticlesCollisionHeightField3D

A real-time heightmap-shaped 3D particle collision shape affecting GPUParticles3D nodes.

Inheritance
GPUParticlesCollisionHeightField3D

Remarks

A real-time heightmap-shaped 3D particle collision shape 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, this class is limited since heightmaps cannot represent overhangs (e.g. indoors or caves).

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

Note: Particle collision only affects GPUParticles3D, not CPUParticles3D.

Properties

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.

var follow_camera_enabled : bool = false

Property Value

bool

Remarks

  • void set_follow_camera_enabled(bool value)
  • bool is_follow_camera_enabled

heightfield_mask

The visual layers to account for when updating the heightmap. Only MeshInstance3Ds whose layers match with this heightfield_mask will be included in the heightmap collision update. By default, all 20 user-visible layers are taken into account for updating the heightmap collision.

Note: Since the heightfield_mask allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting heightfield_mask using a script allows you to toggle those reserved layers, which can be useful for editor plugins.

To adjust heightfield_mask more easily using a script, use GPUParticlesCollisionHeightField3D.get_heightfield_mask_value and GPUParticlesCollisionHeightField3D.set_heightfield_mask_value.

var heightfield_mask : int = 1048575

Property Value

int

Remarks

  • void set_heightfield_mask(int value)
  • int get_heightfield_mask

resolution

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

var resolution : int = 2

Property Value

int

Remarks

  • void set_resolution(int value)
  • int get_resolution

size

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

var size : Vector3 = Vector3(2, 2, 2)

Property Value

Vector3

Remarks

update_mode

The update policy to use for the generated heightmap.

var update_mode : int = 0

Property Value

int

Remarks

  • void set_update_mode(int value)
  • int get_update_mode

Methods

get_heightfield_mask_value(int)

Qualifiers: const

Returns true if the specified layer of the heightfield_mask is enabled, given a layer_number between 1 and 20, inclusive.

bool get_heightfield_mask_value(int layer_number)

Parameters

layer_number int

set_heightfield_mask_value(int, bool)

Based on value, enables or disables the specified layer in the heightfield_mask, given a layer_number between 1 and 20, inclusive.

void set_heightfield_mask_value(int layer_number, bool value)

Parameters

layer_number int
value bool