HeightMapShape3D

继承： Shape3D < Resource < RefCounted < Object

A 3D heightmap shape used for physics collision.

描述

3D 高度图形状，用于物理为 CollisionShape3D 提供形状。这种类型最常用于在固定宽度的栅格中放置顶点的地形。

高度图表示为 2D 栅格中的高度值，每个值代表格点在 Y 轴上的位置。 格点在 X 轴和 Z 轴上各自间隔为 1 个单位，且栅格的中心恰好在 CollisionShape3D 节点的原点。在内部，每个栅格正方形被划分为两个三角形。

由于高度图的特性，它无法用于建模悬垂或洞穴，因为这些情况在同一垂直位置上存在多个顶点。若要在碰撞中打孔，可以将所需位置的顶点高度设为 @GDScript.NAN（受 GodotPhysics3D 和 Jolt Physics 双方支持）。你也可以接着在其中加入具有独立碰撞的网格来提供悬垂、洞穴等效果。

性能：对 HeightMapShape3D 的碰撞检测比 ConcavePolygonShape3D 快，但相比 BoxShape3D 等基本体形状显著要慢。

高度图碰撞形状也可以由 Image 构建：

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)

注意： 如果需要使用 1 个单位以外的间距，可以调整形状的 Node3D.scale。不过，注意 GodotPhysics3D 不支持非均一的缩放：你需要在 Y 轴上进行和 X 轴与 Z 轴相同的缩放，这就意味着 map_data 需要提前被相同程度的逆缩放。还要注意 GodotPhysics3D 不支持动态物体（亦即，未冻结的 RigidBody3D 节点）的任何缩放。若要同时使用缩放了的 HeightMapShape3D 和动态物体，你必须使用 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) 🔗

Heightmap data. The array's size must be equal to map_width multiplied by 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()

Number of vertices in the depth of the heightmap. Changing this will resize the map_data.

int map_width = 2 🔗

  • void set_map_width(value: int)

  • int get_map_width()

Number of vertices in the width of the heightmap. Changing this will resize the 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 位的格式，将导致阶梯状地形。