文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载HeightMapShape3D 是 Godot 引擎中专门为 3D 地形碰撞设计的物理形状以固定间距的顶点网格描述起伏地形是大型开放世界、跑酷与沙盒类游戏地面碰撞的常用方案。本文以 HeightMapShape3D 类参考 为骨架结合仓库中相关物理文档与 Image 格式定义系统讲解其数据结构、三种属性、两个查询方法与贴图驱动的工作流并给出可复制的 GDScript 示例、缩放与物理引擎兼容性注意事项以及与其他碰撞形状的取舍建议。HeightMapShape3D 是什么HeightMapShape3D是一种 3D 高度图碰撞形状继承自 Shape3D其完整继承链为HeightMapShape3D Shape3D Resource RefCounted Object专门用于为 CollisionShape3D 提供地形碰撞。它通常挂载在 StaticBody3D 等静态物理体下用于承载地形这类规模大、表面起伏复杂的几何体。与常见的凸包或三角形网格形状不同高度图采用一种规则且紧凑的表示方式高度图是一个2D 高度值网格每个网格点的高度代表该点在Y 轴上的位置网格点在X 轴与 Z 轴上的间距固定为 1 个单位网格以 CollisionShape3D 节点的原点为中心在引擎内部每个网格方格会被划分为两个三角形用于最终的碰撞检测。从 PhysicsServer3D 的常量定义可以看到HeightMapShape3D 对应SHAPE_HEIGHTMAP 8是 PhysicsServer3D 原生支持的一类形状这也解释了为什么它能获得比通用三角形网格形状更好的碰撞检测性能。高度图与山体碰撞的适用边界高度图数据结构决定了它的能力边界不能表达悬垂与洞穴。因为网格的每个 XZ 位置只允许一个高度值垂直方向同一位置无法存在多个顶点可以通过 NaN 打洞。将目标顶点的值赋为GDScript.NAN就可以在碰撞中挖出孔洞然后在这些孔洞处放置自带独立碰撞的网格用来表现悬垂、洞穴等复杂结构因此 HeightMapShape3D 最适合单一表面、垂直可见的地形场景如山地、平原、坡道。与外观相关的一点材质的高度贴图Height只是沿视线方向做射线步进制造视觉上的凹凸感并不会产生真实几何真正用于物理碰撞如地形的形状应使用 HeightMapShape3D详见 StandardMaterial3D 的 Height 章节。性能定位优于凹多边形慢于图元形状在碰撞检测开销上HeightMapShape3D 处于中间档位相比 ConcavePolygonShape3DHeightMapShape3D 的碰撞检测更快但相比 BoxShape3D 等图元形状它显著更慢。这一结论在 Shape3D 基类文档 中也有呼应图元形状尤其是 SphereShape3D检测最快ConvexPolygonShape3D 与 HeightMapShape3D 居中ConcavePolygonShape3D 最慢。因此实践中动态物体RigidBody3D、CharacterBody3D优先使用 BoxShape3D、SphereShape3D 等图元数量尽量少地形这类大尺度静态几何才使用 HeightMapShape3D若地形细节过多、需要完全贴合复杂网格再考虑 ConcavePolygonShape3D但要接受其最慢的检测性能。关于碰撞形状选择与性能的一般性建议还可参考 碰撞形状 3D 指南。三个核心属性map_data高度数据本体类型PackedFloat32Array默认值PackedFloat32Array(0, 0, 0, 0)访问器set_map_data(value)/get_map_data()map_data保存全部顶点高度数组长度必须等于map_width × map_depth。数据按网格行列顺序排列数值即各顶点在 Y 轴上的高度。需要注意两个细节get_map_data()返回的是拷贝修改返回数组不会影响原属性需要写回时请使用set_map_data()重新赋值高度值存为 32 位浮点PackedFloat32Array理论上可以表达连续、平滑的高度变化。map_width宽度方向顶点数类型int默认值2访问器set_map_width(value)/get_map_width()表示高度图宽度方向X 轴的顶点数量。修改该值会自动调整map_data的尺寸因此设置顺序通常是先定宽高、再填充数据。map_depth深度方向顶点数类型int默认值2访问器set_map_depth(value)/get_map_depth()表示高度图**深度方向Z 轴**的顶点数量同样会触发map_data的自动扩容/收缩。一个由map_width × map_depth个顶点构成的网格实际会形成(map_width - 1) × (map_depth - 1)个方格每个方格内部再细分为两个三角形。两个查询方法get_max_height()返回map_data中最大的高度值。仅在map_data变化时重新计算因此对地形范围包围盒有实时需求时可以高效地反复调用。get_min_height()返回map_data中最小的高度值同样只在数据变化时重算。两个方法均为const无副作用、不修改成员变量常用于动态调整相机与地形 LOD 的范围判断计算地形碰撞体的包围盒调试地形数据是否落在预期高度区间。用 Image 一键生成高度图数据HeightMapShape3D 提供了update_map_data_from_image(image, height_min, height_max)方法可直接从一张图片构建碰撞数据这是从美术资源到物理碰撞最快的通路方法会自动读取图片的完整宽高并将map_width、map_depth调整为图片尺寸每个像素被读取为一个0.0黑色到1.0白色的浮点值再线性映射到height_min与height_max区间得到最终高度。官方文档给出的完整 GDScript 示例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)对应的编辑器内操作流程为在场景中创建StaticBody3D并添加子节点CollisionShape3D为CollisionShape3D的shape属性新建HeightMapShape3D资源通过上述代码加载 EXR/HDR 高度图、转换为FORMAT_RF后调用update_map_data_from_image()配合height_min/height_max把灰度值映射成实际地形高度上例为 0 到 10 个单位。支持的图片格式与精度update_map_data_from_image()要求图片必须是以下三种单通道格式之一格式位深说明Image.FORMAT_RF32 位浮点GL_R32F精度最高官方示例采用的格式Image.FORMAT_RH16 位半精度浮点GL_R16FEXR/HDR 常用Image.FORMAT_R88 位无符号RED单通道 8 位精度最低三种格式的具体定义可在 Image 格式枚举 中查阅FORMAT_RF 8、FORMAT_RH 12、FORMAT_R8 2。官方明确建议优先使用 16 位或 32 位数据、并以 EXR 或 HDR 格式存储的高度图如果使用 8 位高度数据或使用 PNG 这类会被 Godot 导入为 8 位的格式地形会出现**阶梯状terrace**现象即相邻高度被量化成明显的平台破坏地形的平滑感。位深选择的实操含义32 位浮点EXR能完整保留浮点精度适合需要大高度落差、高细节的地形16 位半精度浮点HDR在精度与体积之间取得平衡是大多数地形的推荐起点8 位PNG 等只提供 256 级高度若高度范围被拉大台阶感会非常明显。非 1 单位网格间距缩放与预缩放高度图默认的顶点间距是 1 个单位若需要更宽的间距可调整形状所在 Node3D.scale或 CollisionShape3D 的缩放来实现。但这里存在两条必须遵守的约束约束一GodotPhysics3D 不支持非均匀缩放X、Z 轴与 Y 轴的缩放必须一致。同时缩放后map_data中的数值需要预先乘以该缩放的倒数才能保证地形实际高度正确。也就是说放大网格间距的同时要按比例缩小存储的高度值。约束二GodotPhysics3D 对动态刚体完全不支持缩放对于非冻结non-frozen的 RigidBody3D 这类动态刚体GodotPhysics3D 不提供缩放支持。如果确实需要在动态刚体上使用带缩放的 HeightMapShape3D官方文档明确指出需要使用 Jolt Physics即启用 Jolt 物理引擎的项目。需要提醒的是CollisionShape3D 类参考 同样警告非均匀缩放的 CollisionShape3D 很可能表现异常应尽量保持各轴缩放一致并把形状差异放在 shape 资源本身。物理引擎兼容性与相关项目设置HeightMapShape3D 作为基于三角形网格的碰撞形状在不同物理引擎下还有一些细节需要了解GodotPhysics3D内置如上所述非均匀缩放与动态刚体缩放都不支持动态刚体需改用 JoltJolt Physics支持带缩放的 HeightMapShape3D同时针对幽灵碰撞ghost collision提供了两项优化详见 Jolt 物理使用指南Active Edge Detection根据相邻三角形夹角将 HeightMapShape3D 等形状的三角形边标记为 active/inactive碰撞到 inactive 边时用法线替换缓解幽灵碰撞阈值由Physics Jolt Physics 3D Collisions Active Edge Threshold项目设置控制Enhanced Internal Edge Removal基于接触点的运行时检查不仅适用于 HeightMapShape3D/ConcavePolygonShape3D还覆盖同一刚体内任意形状之间的边可通过Physics Jolt Physics 3D Simulation Use Enhanced Internal Edge Removal等设置开关。此外在 ProjectSettings 中可以找到相邻三角形间边缘判定为不活跃的最大角度这一项目设置它同时作用于 ConcavePolygonShape3D 与 HeightMapShape3D可用于调节地形的边缘碰撞表现。常见问题与最佳实践小结出现台阶状地形检查高度图是否用了 8 位格式如 PNG换成 EXR/HDR 16 位或 32 位浮点数据地形需要 2 单位以上的网格间距均匀缩放 X/Y/Z并预缩放map_data高度值乘以缩放倒数动态刚体场景请使用 Jolt Physics需要洞穴与悬垂HeightMapShape3D 无法表达用NAN打洞后配合自带独立碰撞的网格补充追求地形碰撞性能HeightMapShape3D 比 ConcavePolygonShape3D 快但仍明显慢于图元形状动态物体请勿使用高度图做碰撞体修改数据不生效get_map_data()返回拷贝改完必须通过set_map_data()写回或直接调用update_map_data_from_image()整体重建。延伸阅读HeightMapShape3D 类参考本文依据Shape3D 基类性能对比与继承关系CollisionShape3D形状挂载与缩放警告Image 格式枚举FORMAT_RF/RH/R8 定义碰撞形状 3D 指南形状选型与性能建议Jolt Physics 使用指南主动边检测与内部边移除StandardMaterial3D 的 Height 章节外观高度 vs 物理高度图赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 3D 碰撞多边形详解用 CollisionPolygon3D 构建棱柱形碰撞体Godot 3D 碰撞多边形详解用 CollisionPolygon3D 构建棱柱形碰撞体 导读 CollisionPolygon3D 是 Godot 引擎中文档教程游戏开发Kafka-King终极Kafka图形化管理工具完整指南Kafka King终极Kafka图形化管理工具完整指南 还在为复杂的Kafka命令行操作而头疼吗Kafka King作为一款现代化的Kafka图形界面客户开发工具数据库客户端桌面应用Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优 本文围绕 Godot 官方文档仓库中的 Collisi文档教程游戏开发上一篇终极Gofile批量下载解决方案5分钟实现自动化文件管理下一篇Display Driver Uninstaller终极指南简单三步彻底解决显卡驱动问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载HeightMapShape3D 是 Godot 引擎中专门为 3D 地形碰撞设计的物理形状以固定间距的顶点网格描述起伏地形是大型开放世界、跑酷与沙盒类游戏地面碰撞的常用方案。本文以 HeightMapShape3D 类参考 为骨架结合仓库中相关物理文档与 Image 格式定义系统讲解其数据结构、三种属性、两个查询方法与贴图驱动的工作流并给出可复制的 GDScript 示例、缩放与物理引擎兼容性注意事项以及与其他碰撞形状的取舍建议。HeightMapShape3D 是什么HeightMapShape3D是一种 3D 高度图碰撞形状继承自 Shape3D其完整继承链为HeightMapShape3D Shape3D Resource RefCounted Object专门用于为 CollisionShape3D 提供地形碰撞。它通常挂载在 StaticBody3D 等静态物理体下用于承载地形这类规模大、表面起伏复杂的几何体。与常见的凸包或三角形网格形状不同高度图采用一种规则且紧凑的表示方式高度图是一个2D 高度值网格每个网格点的高度代表该点在Y 轴上的位置网格点在X 轴与 Z 轴上的间距固定为 1 个单位网格以 CollisionShape3D 节点的原点为中心在引擎内部每个网格方格会被划分为两个三角形用于最终的碰撞检测。从 PhysicsServer3D 的常量定义可以看到HeightMapShape3D 对应SHAPE_HEIGHTMAP 8是 PhysicsServer3D 原生支持的一类形状这也解释了为什么它能获得比通用三角形网格形状更好的碰撞检测性能。高度图与山体碰撞的适用边界高度图数据结构决定了它的能力边界不能表达悬垂与洞穴。因为网格的每个 XZ 位置只允许一个高度值垂直方向同一位置无法存在多个顶点可以通过 NaN 打洞。将目标顶点的值赋为GDScript.NAN就可以在碰撞中挖出孔洞然后在这些孔洞处放置自带独立碰撞的网格用来表现悬垂、洞穴等复杂结构因此 HeightMapShape3D 最适合单一表面、垂直可见的地形场景如山地、平原、坡道。与外观相关的一点材质的高度贴图Height只是沿视线方向做射线步进制造视觉上的凹凸感并不会产生真实几何真正用于物理碰撞如地形的形状应使用 HeightMapShape3D详见 StandardMaterial3D 的 Height 章节。性能定位优于凹多边形慢于图元形状在碰撞检测开销上HeightMapShape3D 处于中间档位相比 ConcavePolygonShape3DHeightMapShape3D 的碰撞检测更快但相比 BoxShape3D 等图元形状它显著更慢。这一结论在 Shape3D 基类文档 中也有呼应图元形状尤其是 SphereShape3D检测最快ConvexPolygonShape3D 与 HeightMapShape3D 居中ConcavePolygonShape3D 最慢。因此实践中动态物体RigidBody3D、CharacterBody3D优先使用 BoxShape3D、SphereShape3D 等图元数量尽量少地形这类大尺度静态几何才使用 HeightMapShape3D若地形细节过多、需要完全贴合复杂网格再考虑 ConcavePolygonShape3D但要接受其最慢的检测性能。关于碰撞形状选择与性能的一般性建议还可参考 碰撞形状 3D 指南。三个核心属性map_data高度数据本体类型PackedFloat32Array默认值PackedFloat32Array(0, 0, 0, 0)访问器set_map_data(value)/get_map_data()map_data保存全部顶点高度数组长度必须等于map_width × map_depth。数据按网格行列顺序排列数值即各顶点在 Y 轴上的高度。需要注意两个细节get_map_data()返回的是拷贝修改返回数组不会影响原属性需要写回时请使用set_map_data()重新赋值高度值存为 32 位浮点PackedFloat32Array理论上可以表达连续、平滑的高度变化。map_width宽度方向顶点数类型int默认值2访问器set_map_width(value)/get_map_width()表示高度图宽度方向X 轴的顶点数量。修改该值会自动调整map_data的尺寸因此设置顺序通常是先定宽高、再填充数据。map_depth深度方向顶点数类型int默认值2访问器set_map_depth(value)/get_map_depth()表示高度图**深度方向Z 轴**的顶点数量同样会触发map_data的自动扩容/收缩。一个由map_width × map_depth个顶点构成的网格实际会形成(map_width - 1) × (map_depth - 1)个方格每个方格内部再细分为两个三角形。两个查询方法get_max_height()返回map_data中最大的高度值。仅在map_data变化时重新计算因此对地形范围包围盒有实时需求时可以高效地反复调用。get_min_height()返回map_data中最小的高度值同样只在数据变化时重算。两个方法均为const无副作用、不修改成员变量常用于动态调整相机与地形 LOD 的范围判断计算地形碰撞体的包围盒调试地形数据是否落在预期高度区间。用 Image 一键生成高度图数据HeightMapShape3D 提供了update_map_data_from_image(image, height_min, height_max)方法可直接从一张图片构建碰撞数据这是从美术资源到物理碰撞最快的通路方法会自动读取图片的完整宽高并将map_width、map_depth调整为图片尺寸每个像素被读取为一个0.0黑色到1.0白色的浮点值再线性映射到height_min与height_max区间得到最终高度。官方文档给出的完整 GDScript 示例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)对应的编辑器内操作流程为在场景中创建StaticBody3D并添加子节点CollisionShape3D为CollisionShape3D的shape属性新建HeightMapShape3D资源通过上述代码加载 EXR/HDR 高度图、转换为FORMAT_RF后调用update_map_data_from_image()配合height_min/height_max把灰度值映射成实际地形高度上例为 0 到 10 个单位。支持的图片格式与精度update_map_data_from_image()要求图片必须是以下三种单通道格式之一格式位深说明Image.FORMAT_RF32 位浮点GL_R32F精度最高官方示例采用的格式Image.FORMAT_RH16 位半精度浮点GL_R16FEXR/HDR 常用Image.FORMAT_R88 位无符号RED单通道 8 位精度最低三种格式的具体定义可在 Image 格式枚举 中查阅FORMAT_RF 8、FORMAT_RH 12、FORMAT_R8 2。官方明确建议优先使用 16 位或 32 位数据、并以 EXR 或 HDR 格式存储的高度图如果使用 8 位高度数据或使用 PNG 这类会被 Godot 导入为 8 位的格式地形会出现**阶梯状terrace**现象即相邻高度被量化成明显的平台破坏地形的平滑感。位深选择的实操含义32 位浮点EXR能完整保留浮点精度适合需要大高度落差、高细节的地形16 位半精度浮点HDR在精度与体积之间取得平衡是大多数地形的推荐起点8 位PNG 等只提供 256 级高度若高度范围被拉大台阶感会非常明显。非 1 单位网格间距缩放与预缩放高度图默认的顶点间距是 1 个单位若需要更宽的间距可调整形状所在 Node3D.scale或 CollisionShape3D 的缩放来实现。但这里存在两条必须遵守的约束约束一GodotPhysics3D 不支持非均匀缩放X、Z 轴与 Y 轴的缩放必须一致。同时缩放后map_data中的数值需要预先乘以该缩放的倒数才能保证地形实际高度正确。也就是说放大网格间距的同时要按比例缩小存储的高度值。约束二GodotPhysics3D 对动态刚体完全不支持缩放对于非冻结non-frozen的 RigidBody3D 这类动态刚体GodotPhysics3D 不提供缩放支持。如果确实需要在动态刚体上使用带缩放的 HeightMapShape3D官方文档明确指出需要使用 Jolt Physics即启用 Jolt 物理引擎的项目。需要提醒的是CollisionShape3D 类参考 同样警告非均匀缩放的 CollisionShape3D 很可能表现异常应尽量保持各轴缩放一致并把形状差异放在 shape 资源本身。物理引擎兼容性与相关项目设置HeightMapShape3D 作为基于三角形网格的碰撞形状在不同物理引擎下还有一些细节需要了解GodotPhysics3D内置如上所述非均匀缩放与动态刚体缩放都不支持动态刚体需改用 JoltJolt Physics支持带缩放的 HeightMapShape3D同时针对幽灵碰撞ghost collision提供了两项优化详见 Jolt 物理使用指南Active Edge Detection根据相邻三角形夹角将 HeightMapShape3D 等形状的三角形边标记为 active/inactive碰撞到 inactive 边时用法线替换缓解幽灵碰撞阈值由Physics Jolt Physics 3D Collisions Active Edge Threshold项目设置控制Enhanced Internal Edge Removal基于接触点的运行时检查不仅适用于 HeightMapShape3D/ConcavePolygonShape3D还覆盖同一刚体内任意形状之间的边可通过Physics Jolt Physics 3D Simulation Use Enhanced Internal Edge Removal等设置开关。此外在 ProjectSettings 中可以找到相邻三角形间边缘判定为不活跃的最大角度这一项目设置它同时作用于 ConcavePolygonShape3D 与 HeightMapShape3D可用于调节地形的边缘碰撞表现。常见问题与最佳实践小结出现台阶状地形检查高度图是否用了 8 位格式如 PNG换成 EXR/HDR 16 位或 32 位浮点数据地形需要 2 单位以上的网格间距均匀缩放 X/Y/Z并预缩放map_data高度值乘以缩放倒数动态刚体场景请使用 Jolt Physics需要洞穴与悬垂HeightMapShape3D 无法表达用NAN打洞后配合自带独立碰撞的网格补充追求地形碰撞性能HeightMapShape3D 比 ConcavePolygonShape3D 快但仍明显慢于图元形状动态物体请勿使用高度图做碰撞体修改数据不生效get_map_data()返回拷贝改完必须通过set_map_data()写回或直接调用update_map_data_from_image()整体重建。延伸阅读HeightMapShape3D 类参考本文依据Shape3D 基类性能对比与继承关系CollisionShape3D形状挂载与缩放警告Image 格式枚举FORMAT_RF/RH/R8 定义碰撞形状 3D 指南形状选型与性能建议Jolt Physics 使用指南主动边检测与内部边移除StandardMaterial3D 的 Height 章节外观高度 vs 物理高度图赞分享文档教程游戏开发【免费下载链接】godot-docsGodot Engine official documentation项目地址https://gitcode.com/GitHub_Trending/go/godot-docs点击查看免费下载相关推荐Godot 3D 碰撞多边形详解用 CollisionPolygon3D 构建棱柱形碰撞体Godot 3D 碰撞多边形详解用 CollisionPolygon3D 构建棱柱形碰撞体 导读 CollisionPolygon3D 是 Godot 引擎中文档教程游戏开发Kafka-King终极Kafka图形化管理工具完整指南Kafka King终极Kafka图形化管理工具完整指南 还在为复杂的Kafka命令行操作而头疼吗Kafka King作为一款现代化的Kafka图形界面客户开发工具数据库客户端桌面应用Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优Godot 2D 碰撞形状节点 CollisionShape2D 完全指南属性详解、单向碰撞与性能调优 本文围绕 Godot 官方文档仓库中的 Collisi文档教程游戏开发上一篇终极Gofile批量下载解决方案5分钟实现自动化文件管理下一篇Display Driver Uninstaller终极指南简单三步彻底解决显卡驱动问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
