最后同步日期：2026-04-15 | Godot 官方原文 — NavigationRegion3D

NavigationRegion3D

节点继承关系

继承链：Node -> Node3D -> NavigationRegion3D

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

NavigationRegion3D 是 NavigationRegion2D 的 3D 版本，用来定义 3D 游戏世界中哪些区域是可以行走的。想象你在一个 3D 城市模型中，用半透明的绿色地板铺满了所有的人行道和马路——AI 角色只能在这块"绿色地板"上行走。

使用频率：★★★★ 常用——做任何有 AI 角色移动的 3D 游戏都离不开它

节点用途

• 告诉 3D 寻路系统"这个区域可以走"
• 配合 NavigationMesh 资源定义可行走区域的几何形状
• 多个 NavigationRegion3D 可以拼接覆盖整个 3D 关卡
• 支持导航层来区分不同类型的可行走区域（地面、楼梯、水面等）

使用场景

1. 3D 开放世界：在大地图上放置多个 NavigationRegion3D，覆盖所有可行走地形
2. FPS 游戏：标记玩家和 AI 可以移动的室内地板和室外地面
3. 3D 即时战略：标记部队可以行走的 3D 地形区域
4. 多楼层建筑：用不同的导航层区分不同楼层的地面

常用节点搭配

搭配节点	搭配方式
NavigationAgent3D	Agent 在 Region 定义的区域内寻路移动
NavigationLink3D	连接两个不连续的 Region（比如桥的两端）
NavigationObstacle3D	在 Region 内添加动态障碍物
MeshInstance3D	用网格几何体烘焙生成导航网格

生效必备素材/资源

• NavigationMesh 资源：必须分配一个 NavigationMesh 资源。通常通过编辑器的"烘焙"（Bake）功能，根据场景中的 StaticBody3D 和网格几何体自动生成导航网格。

节点属性与信号

属性

属性名	类型	默认值	说明
navigation_mesh	NavigationMesh	—	导航网格资源，定义可行走区域的形状
enabled	bool	true	是否启用此导航区域
navigation_layers	int	1	导航层位掩码，用于区分不同类型的可行走区域

信号

信号名	触发时机
navigation_mesh_changed	导航网格资源发生变化时

常用方法

方法	返回值	说明
get_navigation_map_rid()	RID	获取底层导航地图的 RID
is_enabled()	bool	是否已启用
set_enabled(enabled)	void	设置是否启用
get_navigation_layers()	int	获取导航层位掩码
set_navigation_layers(layers)	void	设置导航层位掩码
bake_navigation_mesh(on_thread: bool)	void	烘焙导航网格（Godot 4.x 中可用）

代码示例

通过代码烘焙导航网格

以下示例展示如何在 3D 场景中用代码创建导航区域：

C

using Godot;

public partial class NavRegion3DSetup : Node3D
{
    private NavigationRegion3D _navRegion;

    public override void _Ready()
    {
        _navRegion = GetNode<NavigationRegion3D>("NavigationRegion3D");

        // 创建一个简单的矩形导航网格
        var navMesh = new NavigationMesh();
        navMesh.SetVertices(new Godot.Collections.Array<Vector3>
        {
            new Vector3(-5, 0, -5),
            new Vector3(5, 0, -5),
            new Vector3(5, 0, 5),
            new Vector3(-5, 0, 5)
        });

        // 添加多边形面（使用顶点索引）
        navMesh.AddPolygon(new int[] { 0, 1, 2, 3 });

        _navRegion.NavigationMesh = navMesh;

        GD.Print("3D 导航区域已设置完成！");
    }
}

GDScript

extends Node3D

@onready var _nav_region: NavigationRegion3D = $NavigationRegion3D

func _ready() -> void:
    # 创建一个简单的矩形导航网格
    var nav_mesh = NavigationMesh.new()
    nav_mesh.vertices = PackedVector3Array([
        Vector3(-5, 0, -5),
        Vector3(5, 0, -5),
        Vector3(5, 0, 5),
        Vector3(-5, 0, 5)
    ])

    # 添加多边形面（使用顶点索引）
    nav_mesh.add_polygon(PackedInt32Array([0, 1, 2, 3]))

    _nav_region.navigation_mesh = nav_mesh

    print("3D 导航区域已设置完成！")