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

GrooveJoint2D

节点继承关系

继承链：Node → CanvasItem → Node2D → Joint2D → GrooveJoint2D

Joint2D

类型	名称	说明
属性	NodeA	连接的第一个物体
属性	NodeB	连接的第二个物体

Node2D

类型	名称	说明
属性	Position	本地位置（相对于父节点）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（弧度）
属性	Scale	缩放比例
属性	Skew	倾斜角度（弧度）
方法	Rotate()	旋转指定弧度
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

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

定义

像一个滑轨——物体 A 上有一条槽，物体 B 被限制在这条槽里来回滑动。

想象你玩过弹珠台——弹珠台面上有一条轨道，弹珠只能沿着轨道滑。GrooveJoint2D 就是那条"轨道"。它限制第二个物体只能沿着第一个物体上的某条线段移动。

使用频率：★ 基本用不到——用于滑轨类物理连接。

节点用途

• 电梯轨道
• 活塞运动
• 滑门
• 任何需要沿固定方向滑动的连接

使用场景

典型场景

• 电梯：电梯只能沿着竖直轨道上下移动
• 滑门：门只能沿着水平方向开关
• 活塞：沿固定方向来回运动

不适用场景

• 需要围绕一个点旋转 → 使用 PinJoint2D
• 需要弹性连接 → 使用 DampedSpringJoint2D

常用节点搭配

搭配节点	用途	必需？
RigidBody2D / StaticBody2D（NodeA）	提供滑槽的物体	必需
RigidBody2D（NodeB）	在滑槽里滑的物体	必需

典型节点树：

Elevator (Node2D)
├── Rail (StaticBody2D)
│   └── CollisionShape2D
├── GrooveJoint2D（连接 Rail 和 Platform）
└── Platform (RigidBody2D)
    ├── CollisionShape2D
    └── Sprite2D

生效必备素材/资源

资源	类型	说明
碰撞形状	Shape2D 资源	两个连接物体都需要

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
NodeA	NodePath	""	Joint2D	第一个物体（提供滑槽）
NodeB	NodePath	""	Joint2D	第二个物体（在滑槽里滑）
Length	float	50.0	—	滑槽长度
InitialOffset	float	0.0	—	物体 B 在滑槽中的初始偏移
Bias	float	0.3	—	约束求解偏差
DisableCollision	bool	true	Joint2D	是否禁用连接物体之间的碰撞

信号

信号	触发时机	继承自	说明
无自有信号	—	—	—

常用方法

方法	返回值	说明
GetNodeA()	NodePath	获取第一个物体路径
GetNodeB()	NodePath	获取第二个物体路径

代码示例

C

using Godot;

/// <summary>
/// 电梯轨道：平台只能沿着竖直方向移动
/// </summary>
public partial class ElevatorRail : Node2D
{
    public override void _Ready()
    {
        var joint = GetNode<GrooveJoint2D>("GrooveJoint2D");
        joint.NodeA = GetNode<StaticBody2D>("Rail").GetPath();
        joint.NodeB = GetNode<RigidBody2D>("Platform").GetPath();
        joint.Length = 300f;  // 滑槽长度 300 像素
        joint.InitialOffset = 0f;
    }
}

GDScript

# 电梯轨道：平台只能沿着竖直方向移动
extends Node2D

func _ready() -> void:
	var joint := $GrooveJoint2D
	joint.node_a = $Rail.get_path()
	joint.node_b = $Platform.get_path()
	joint.length = 300.0  # 滑槽长度 300 像素
	joint.initial_offset = 0.0