NavigationMesh

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

继承： Resource < RefCounted < Object

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

描述

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

教程

• 使用 NavigationMesh

• 3D 导航演示

属性

方法

枚举

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 = 0 🔗

• 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 方法对其进行索引，创建多边形。