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.

Checking the stable version of the documentation...

NavigationMesh

实验性： This class may be changed or removed in future versions.

继承： Resource < RefCounted < Object

用于定义可达区域和障碍物的导航网格。

描述

导航网格是多边形的集合，用于定义环境中的哪些区域是可以穿越的，帮助代理在复杂的空间中寻路。

教程

• 使用 NavigationMesh

• 3D 导航演示

属性

float	agent_height	1.5
float	agent_max_climb	0.25
float	agent_max_slope	45.0
float	agent_radius	0.5
float	border_size	0.0
float	cell_height	0.25
float	cell_size	0.25
float	detail_sample_distance	6.0
float	detail_sample_max_error	1.0
float	edge_max_error	1.3
float	edge_max_length	0.0
AABB	filter_baking_aabb	AABB(0, 0, 0, 0, 0, 0)
Vector3	filter_baking_aabb_offset	Vector3(0, 0, 0)
bool	filter_ledge_spans	false
bool	filter_low_hanging_obstacles	false
bool	filter_walkable_low_height_spans	false
int	geometry_collision_mask	4294967295
ParsedGeometryType	geometry_parsed_geometry_type	2
SourceGeometryMode	geometry_source_geometry_mode	0
StringName	geometry_source_group_name	&"navigation_mesh_source_group"
float	region_merge_size	20.0
float	region_min_size	2.0
SamplePartitionType	sample_partition_type	0
float	vertices_per_polygon	6.0

方法

void	add_polygon(polygon: PackedInt32Array)
void	clear()
void	clear_polygons()
void	create_from_mesh(mesh: Mesh)
bool	get_collision_mask_value(layer_number: int) const
PackedInt32Array	get_polygon(idx: int)
int	get_polygon_count() const
PackedVector3Array	get_vertices() const
void	set_collision_mask_value(layer_number: int, value: bool)
void	set_vertices(vertices: PackedVector3Array)

---

枚举

enum SamplePartitionType: 🔗

SamplePartitionType SAMPLE_PARTITION_WATERSHED = 0

分水岭分区。如果你预先计算导航网格，通常是最佳选择，如果你有大的开放区域，请使用它。

SamplePartitionType SAMPLE_PARTITION_MONOTONE = 1

单调分区。如果你想要快速生成导航网格，请使用此选项。

SamplePartitionType SAMPLE_PARTITION_LAYERS = 2

层分区。用于具有中小型图块的平铺导航网格的不错选择。

SamplePartitionType SAMPLE_PARTITION_MAX = 3

代表 SamplePartitionType 枚举的大小。

---

enum ParsedGeometryType: 🔗

ParsedGeometryType PARSED_GEOMETRY_MESH_INSTANCES = 0

将网格实例解析为几何体。包括 MeshInstance3D、CSGShape3D、GridMap 等节点。

ParsedGeometryType PARSED_GEOMETRY_STATIC_COLLIDERS = 1

将 StaticBody3D 碰撞器解析为几何体。碰撞器应在由 geometry_collision_mask 指定的层中。

ParsedGeometryType PARSED_GEOMETRY_BOTH = 2

PARSED_GEOMETRY_MESH_INSTANCES 和 PARSED_GEOMETRY_STATIC_COLLIDERS.

ParsedGeometryType PARSED_GEOMETRY_MAX = 3

代表 ParsedGeometryType 枚举的大小。

---

enum SourceGeometryMode: 🔗

SourceGeometryMode SOURCE_GEOMETRY_ROOT_NODE_CHILDREN = 0

在根节点的子节点中递归扫描几何体。

SourceGeometryMode SOURCE_GEOMETRY_GROUPS_WITH_CHILDREN = 1

以递归方式扫描组中的节点及其子节点以获取几何图形。该组由 geometry_source_group_name 指定。

SourceGeometryMode SOURCE_GEOMETRY_GROUPS_EXPLICIT = 2

使用一个组中的节点进行几何运算。该组由 geometry_source_group_name 指定。

SourceGeometryMode SOURCE_GEOMETRY_MAX = 3

代表 SourceGeometryMode 枚举的大小。

---

属性说明

float agent_height = 1.5 🔗

• void set_agent_height(value: float)

• float get_agent_height()

地板到天花板的最小高度，仍然允许被认为是可行走的地板。

注意：烘焙时，这个值会向上取整到最接近的 cell_height 的倍数。

---

float agent_max_climb = 0.25 🔗

• void set_agent_max_climb(value: float)

• float get_agent_max_climb()

被认为仍可穿越的最小墙壁高度。

注意：烘焙时，该值将向下舍入到最接近的 cell_height 的倍数。

---

float agent_max_slope = 45.0 🔗

• void set_agent_max_slope(value: float)

• float get_agent_max_slope()

认为可行走的最大坡度，单位是度。

---

float agent_radius = 0.5 🔗

• void set_agent_radius(value: float)

• float get_agent_radius()

侵蚀/缩小远离障碍物的高度场的可行走区域距离。

注意：烘焙时，这个值会向上取整到最接近的 cell_size 的倍数。

---

float border_size = 0.0 🔗

• void set_border_size(value: float)

• float get_border_size()

烘焙区域边界不可导航的边框大小。

要烘焙与图块对齐的导航网格，防止图块边缘被 agent_radius 收缩，请与 filter_baking_aabb 配合使用并将 edge_max_error 设为 1.0 或小于边框大小的值。

注意：烘焙时，这个值如果不等于零，就会被向上取整到 cell_size 的整数倍。

---

float cell_height = 0.25 🔗

• void set_cell_height(value: float)

• float get_cell_height()

单元格高度，用于将导航网格的顶点在 Y 轴上进行栅格化。必须与导航地图的单元格高度匹配。

---

float cell_size = 0.25 🔗

• void set_cell_size(value: float)

• float get_cell_size()

单元格大小，用于将导航网格的顶点在 XZ 平面上进行栅格化。必须与导航地图的单元格大小匹配。

---

float detail_sample_distance = 6.0 🔗

• void set_detail_sample_distance(value: float)

• float get_detail_sample_distance()

生成细分网格时使用的采样距离，以单元格为单位。

---

float detail_sample_max_error = 1.0 🔗

• void set_detail_sample_max_error(value: float)

• float get_detail_sample_max_error()

细节网格表面应偏离高度场的最大距离，以单元格为单位。

---

float edge_max_error = 1.3 🔗

• void set_edge_max_error(value: float)

• float get_edge_max_error()

简化轮廓的边界边缘偏离原始轮廓的最大距离。

---

float edge_max_length = 0.0 🔗

• void set_edge_max_length(value: float)

• float get_edge_max_length()

沿网格边界的轮廓的最大允许长度。值为 0.0 将禁用该功能。

注意：烘焙时，这个值会向上取整到最接近的 cell_size 的倍数。

---

AABB filter_baking_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

• void set_filter_baking_aabb(value: AABB)

• AABB get_filter_baking_aabb()

如果烘焙 AABB 存在体积，对该导航网格的烘焙会被限制在其内部区域中。

---

Vector3 filter_baking_aabb_offset = Vector3(0, 0, 0) 🔗

• void set_filter_baking_aabb_offset(value: Vector3)

• Vector3 get_filter_baking_aabb_offset()

应用于 filter_baking_aabb AABB 的位置偏移量。

---

bool filter_ledge_spans = false 🔗

• void set_filter_ledge_spans(value: bool)

• bool get_filter_ledge_spans()

如果为 true，则标记边缘间的跨度为不可行走。

---

bool filter_low_hanging_obstacles = false 🔗

• void set_filter_low_hanging_obstacles(value: bool)

• bool get_filter_low_hanging_obstacles()

如果为 true，如果它们的最大值在可行走邻域的 agent_max_climb 内，则将不可行走范围标记为可行走。

---

bool filter_walkable_low_height_spans = false 🔗

• void set_filter_walkable_low_height_spans(value: bool)

• bool get_filter_walkable_low_height_spans()

如果为 true，如果跨度上方的间隙小于 agent_height，则将可行走范围标记为不可行走。

---

int geometry_collision_mask = 4294967295 🔗

• void set_collision_mask(value: int)

• int get_collision_mask()

用于扫描静态碰撞的物理层。

仅在 geometry_parsed_geometry_type 是 PARSED_GEOMETRY_STATIC_COLLIDERS 或 PARSED_GEOMETRY_BOTH 时才使用。

---

ParsedGeometryType geometry_parsed_geometry_type = 2 🔗

• void set_parsed_geometry_type(value: ParsedGeometryType)

• ParsedGeometryType get_parsed_geometry_type()

决定哪种类型的节点可解析为几何图形。可能的取值见 ParsedGeometryType。

---

SourceGeometryMode geometry_source_geometry_mode = 0 🔗

• void set_source_geometry_mode(value: SourceGeometryMode)

• SourceGeometryMode get_source_geometry_mode()

烘焙时使用的几何体的来源。可能的取值见 SourceGeometryMode。

---

StringName geometry_source_group_name = &"navigation_mesh_source_group" 🔗

• void set_source_group_name(value: StringName)

• StringName get_source_group_name()

分组的名称，会在该分组中扫描几何体。

只有当 geometry_source_geometry_mode 是 SOURCE_GEOMETRY_GROUPS_WITH_CHILDREN 或 SOURCE_GEOMETRY_GROUPS_EXPLICIT 时才使用。

---

float region_merge_size = 20.0 🔗

• void set_region_merge_size(value: float)

• float get_region_merge_size()

如果可能的话，任何小于这个尺寸的区域将与较大的区域合并。

注意：这个值将被平方来计算单元格的数量。例如，值为 20 时将把单元格的数量设为 400。

---

float region_min_size = 2.0 🔗

• void set_region_min_size(value: float)

• float get_region_min_size()

区域被创建所需的最小尺寸。

注意：该值将被平方，以计算出允许形成孤岛区域的最小单元数。例如，值为 8 时将把单元格的数量设为 64。

---

SamplePartitionType sample_partition_type = 0 🔗

• void set_sample_partition_type(value: SamplePartitionType)

• SamplePartitionType get_sample_partition_type()

创建导航网格多边形单元的分割算法。可能的取值见 SamplePartitionType。

---

float vertices_per_polygon = 6.0 🔗

• void set_vertices_per_polygon(value: float)

• float get_vertices_per_polygon()

在轮廓到多边形转换过程中生成的多边形允许的最大顶点数。

---

方法说明

void add_polygon(polygon: PackedInt32Array) 🔗

使用调用 get_vertices() 得到的顶点的索引添加一个多边形。

---

void clear() 🔗

清除顶点和多边形索引的内部数组。

---

void clear_polygons() 🔗

清除多边形数组，但不清除顶点数组。

---

void create_from_mesh(mesh: Mesh) 🔗

通过根据 Mesh 设置顶点和索引来初始化导航网格。

注意：给定的 mesh 必须是 Mesh.PRIMITIVE_TRIANGLES 类型，并且有一个索引数组。

---

bool get_collision_mask_value(layer_number: int) const 🔗

返回是否启用了 geometry_collision_mask 中的指定层，给定的 layer_number 在 1 和 32 之间。

---

PackedInt32Array get_polygon(idx: int) 🔗

返回创建多边形的顶点索引，形式为 PackedInt32Array。

---

int get_polygon_count() const 🔗

返回导航网格中的多边形数量。

---

PackedVector3Array get_vertices() const 🔗

返回用于创建该多边形的所有顶点，形式为 PackedVector3Array。

---

void set_collision_mask_value(layer_number: int, value: bool) 🔗

根据 value 启用或禁用 geometry_collision_mask 中的指定层，给定的 layer_number 在 1 和 32 之间。

---

void set_vertices(vertices: PackedVector3Array) 🔗

设置顶点，可以使用 add_polygon() 方法对其进行索引，创建多边形。