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

PinJoint2D

节点继承关系

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

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()	获取父节点

定义

像用一根钉子把两个物体钉在一起。两个物体可以围绕钉子点旋转，但不会分开。

想象墙上挂着一个钟——钟通过一根钉子挂在墙上，可以左右摆动但不会掉下来。PinJoint2D 就是那根"钉子"，它把两个物体连在一个点上。

使用频率：★★ 偶尔使用——用于特定的物理连接场景。

节点用途

• 绳索、链条
• 钟摆
• 挂饰物
• 任何需要围绕一个固定点旋转的连接

使用场景

典型场景

• 钟摆效果：一个物体悬挂在固定点上摆动
• 链条：多个物体通过钉子关节首尾相连
• 吊灯：从天花板悬挂下来

不适用场景

• 物体需要沿一条线滑动 → 使用 GrooveJoint2D
• 物体之间需要弹性连接 → 使用 DampedSpringJoint2D

常用节点搭配

搭配节点	用途	必需？
RigidBody2D（NodeA）	第一个连接物体	必需
RigidBody2D（NodeB）	第二个连接物体	必需

典型节点树：

Pendulum (Node2D)
├── Anchor (StaticBody2D)
│   └── CollisionShape2D
├── PinJoint2D（连接 Anchor 和 Bob）
└── Bob (RigidBody2D)
    ├── CollisionShape2D
    └── Sprite2D

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
NodeA	NodePath	""	Joint2D	第一个物体（必须是 RigidBody2D 或 StaticBody2D）
NodeB	NodePath	""	Joint2D	第二个物体（必须是 RigidBody2D）
Softness	float	0.0	—	柔软度（0 = 刚性连接，值越大越"软"）
Bias	float	0.3	—	约束求解偏差（影响关节的稳定性）
DisableCollision	bool	true	Joint2D	是否禁用两个连接物体之间的碰撞

信号

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

常用方法

方法	返回值	说明
GetNodeA()	NodePath	获取第一个物体路径
GetNodeB()	NodePath	获取第二个物体路径
SetNodeA(path)	void	设置第一个物体路径
SetNodeB(path)	void	设置第二个物体路径

代码示例

C

using Godot;

/// <summary>
/// 钟摆效果：一个钉子关节把摆锤挂在固定点上
/// 节点结构：
///   Pendulum (Node2D)
///   ├── Anchor (StaticBody2D)
///   │   └── CollisionShape2D
///   ├── PinJoint2D（连接 Anchor 和 Bob）
///   └── Bob (RigidBody2D)
///       ├── Sprite2D（摆锤图片）
///       └── CollisionShape2D
/// </summary>
public partial class Pendulum : Node2D
{
    public override void _Ready()
    {
        // 获取关节节点
        var joint = GetNode<PinJoint2D>("PinJoint2D");

        // 设置连接的两个物体
        joint.NodeA = GetNode<StaticBody2D>("Anchor").GetPath();
        joint.NodeB = GetNode<RigidBody2D>("Bob").GetPath();

        // 设置关节柔软度
        joint.Softness = 0.0f;  // 0 = 完全刚性
    }
}

GDScript

# 钟摆效果：一个钉子关节把摆锤挂在固定点上
# 节点结构：
#   Pendulum (Node2D)
#   ├── Anchor (StaticBody2D)
#   │   └── CollisionShape2D
#   ├── PinJoint2D（连接 Anchor 和 Bob）
#   └── Bob (RigidBody2D)
#       ├── Sprite2D（摆锤图片）
#       └── CollisionShape2D
extends Node2D

@onready var joint: PinJoint2D = $PinJoint2D
@onready var anchor: StaticBody2D = $Anchor
@onready var bob: RigidBody2D = $Bob

func _ready() -> void:
	# 设置连接的两个物体
	joint.node_a = anchor.get_path()
	joint.node_b = bob.get_path()

	# 设置关节柔软度
	joint.softness = 0.0  # 0 = 完全刚性