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

NavigationLink3D

节点继承关系

继承链：Node -> Node3D -> NavigationLink3D

Node

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

定义

NavigationLink3D 是 NavigationLink2D 的 3D 版本，用来在三维空间中连接两块本来不相连的导航区域。想象 3D 场景中一座桥连接了悬崖两端——两端各有自己的 NavigationRegion3D，而桥就是 NavigationLink3D。

使用频率：★★ 偶尔使用——在 3D 游戏中有关卡跳跃、电梯、传送等特殊通行方式时使用

节点用途

• 连接两个不连续的 NavigationRegion3D，让 AI 可以在 3D 空间中穿越
• 实现 3D 跳跃点、电梯、传送门、梯子等特殊通行方式
• 支持单向和双向连接
• 可以设置 entry_cost 来控制 AI 经过此连接的优先级

使用场景

1. 3D 跳跃平台：连接两个高低不同的平台
2. 电梯/升降机：连接不同楼层的 3D 导航区域
3. 传送门：连接 3D 地图上两个远距离位置
4. 攀爬点：连接地面和墙壁顶部
5. 断桥：单向跳崖，从高处跳到低处

常用节点搭配

搭配节点	搭配方式
NavigationRegion3D	Link 连接两个 Region 的边缘位置
NavigationAgent3D	Agent 在寻路时会自动使用 Link 来穿越不连续区域

生效必备素材/资源

• 两个独立的 NavigationRegion3D，导航网格没有物理连接
• start_position 和 end_position 需要分别落在两个 Region 内

节点属性与信号

属性

属性名	类型	默认值	说明
start_position	Vector3	—	连接起点，通常位于一个 NavigationRegion3D 内
end_position	Vector3	—	连接终点，通常位于另一个 NavigationRegion3D 内
bidirectional	bool	true	是否双向通行
enabled	bool	true	是否启用此连接
entry_cost	float	1.0	通行成本，值越大 AI 越倾向于选择其他路线

信号

NavigationLink3D 没有特有信号，继承自 Node 的通用信号。

常用方法

方法	返回值	说明
is_enabled()	bool	是否已启用
set_enabled(enabled)	void	设置是否启用
get_start_position()	Vector3	获取连接起点
set_start_position(position)	void	设置连接起点
get_end_position()	Vector3	获取连接终点
set_end_position(position)	void	设置连接终点
is_bidirectional()	bool	是否双向连接
set_bidirectional(enabled)	void	设置是否双向连接

代码示例

创建 3D 电梯连接

以下示例展示如何创建连接两个楼层的导航链接：

C

using Godot;

public partial class ElevatorLinkSetup : Node3D
{
    public override void _Ready()
    {
        var navLink = new NavigationLink3D();

        // 设置连接起点（1 楼电梯口）
        navLink.StartPosition = new Vector3(0, 0, 0);

        // 设置连接终点（2 楼电梯口）
        navLink.EndPosition = new Vector3(0, 4, 0);

        // 电梯可以双向使用
        navLink.Bidirectional = true;

        // 乘电梯比走路稍微"贵"一些（需要等待时间）
        navLink.EntryCost = 1.5f;

        AddChild(navLink);

        GD.Print("3D 电梯连接已创建！");
    }
}

GDScript

extends Node3D

func _ready() -> void:
    var nav_link = NavigationLink3D.new()

    # 设置连接起点（1 楼电梯口）
    nav_link.start_position = Vector3(0, 0, 0)

    # 设置连接终点（2 楼电梯口）
    nav_link.end_position = Vector3(0, 4, 0)

    # 电梯可以双向使用
    nav_link.bidirectional = true

    # 乘电梯比走路稍微"贵"一些
    nav_link.entry_cost = 1.5

    add_child(nav_link)

    print("3D 电梯连接已创建！")