Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

HeightMapShape3D

繼承: Shape3D < Resource < RefCounted < Object

3D 高度圖形狀,用於物理碰撞。

說明

A 3D heightmap shape, intended for use in physics to provide a shape for a CollisionShape3D. This type is most commonly used for terrain with vertices placed in a fixed-width grid.

The heightmap is represented as a 2D grid of height values, which represent the position of grid points on the Y axis. Grid points are spaced 1 unit apart on the X and Z axes, and the grid is centered on the origin of the CollisionShape3D node. Internally, each grid square is divided into two triangles.

Due to the nature of the heightmap, it cannot be used to model overhangs or caves, which would require multiple vertices at the same vertical location. Holes can be punched through the collision by assigning @GDScript.NAN to the height of the desired vertices. You could then insert meshes with their own separate collision to provide overhangs, caves, and so on.

Performance: HeightMapShape3D is faster to check collisions against than ConcavePolygonShape3D, but it is significantly slower than primitive shapes like BoxShape3D.

A heightmap collision shape can also be built by using an Image reference:

var heightmap_texture = ResourceLoader.load("res://heightmap_image.exr")
var heightmap_image = heightmap_texture.get_image()
heightmap_image.convert(Image.FORMAT_RF)

var height_min = 0.0
var height_max = 10.0

update_map_data_from_image(heightmap_image, height_min, height_max)

Note: If you need to use a spacing different than 1 unit, you can adjust the Node3D.scale of the shape. However, keep in mind that GodotPhysics3D does not support non-uniform scaling: you'll need to scale the Y axis by the same amount as the X and Z axes, which means the values in map_data will need to be pre-scaled by the inverse of that scale. Also note that GodotPhysics3D does not support scaling at all for dynamic bodies (that is, non-frozen RigidBody3D nodes); to use a scaled HeightMapShape3D with those, you will need to use Jolt Physics.

屬性

PackedFloat32Array

map_data

PackedFloat32Array(0, 0, 0, 0)

int

map_depth

2

int

map_width

2

方法

float

get_max_height() const

float

get_min_height() const

void

update_map_data_from_image(image: Image, height_min: float, height_max: float)


屬性說明

PackedFloat32Array map_data = PackedFloat32Array(0, 0, 0, 0) 🔗

高度圖資料。該陣列的大小必須等於 map_width 乘以 map_depth。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedFloat32Array for more details.


int map_depth = 2 🔗

  • void set_map_depth(value: int)

  • int get_map_depth()

高度圖深度中的頂點數。更改該項將調整 map_data 的大小。


int map_width = 2 🔗

  • void set_map_width(value: int)

  • int get_map_width()

高度圖寬度中的頂點數。更改該項將調整 map_data 的大小。


方法說明

float get_max_height() const 🔗

回傳在 map_data 中找到的最大高度值。僅當 map_data 更改時重新計算。


float get_min_height() const 🔗

回傳在 map_data 中找到的最小高度值。僅當 map_data 更改時重新計算。


void update_map_data_from_image(image: Image, height_min: float, height_max: float) 🔗

使用從 Image 參照讀取的資料更新 map_data。自動調整高度圖的寬度 map_width 和高度 map_depth,適應整個影像的寬度和高度。

影像格式需要為 Image.FORMAT_RF(32 位元)、Image.FORMAT_RH(16 位元)或 Image.FORMAT_R8(8 位元)。

每個影像像素都以浮點數形式讀入,範圍從 0.0(黑色像素)到 1.0(白色像素)。該範圍值重新映射到最小高度 height_min 和最大高度 height_max,形成最終的高度值。

注意:使用 16 位元或 32 位元資料的高度圖時建議儲存為 EXR 或 HDR 格式。使用 8 位元高度資料或像 PNG 這樣 Godot 會匯入為 8 位元的格式,將導致階梯狀地形。