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

PinJoint3D

节点继承关系

继承链：Node → Node3D → Joint3D → PinJoint3D

Joint3D

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

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

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

定义

3D 版本的钉子关节。两个物体围绕一个点旋转，不会分开。

PinJoint3D 是 PinJoint2D 的 3D 版本。在 3D 中，物体可以围绕任意轴旋转，不像 2D 中只能在一个平面上旋转。

使用频率：★★ 偶尔使用——用于 3D 物理连接。

节点用途

• 3D 钟摆
• 3D 绳索、链条
• 3D 悬挂物体

使用场景

典型场景

• 3D 吊灯：从天花板悬挂下来
• 3D 链条：多个物体首尾相连

不适用场景

• 需要限制旋转轴 → 使用 HingeJoint3D
• 需要弹性连接 → 使用其他弹簧关节

常用节点搭配

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

典型节点树：

Pendulum3D (Node3D)
├── Anchor (StaticBody3D)
├── PinJoint3D
└── Bob (RigidBody3D)
    ├── CollisionShape3D
    └── MeshInstance3D

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
NodeA	NodePath	""	Joint3D	第一个物体
NodeB	NodePath	""	Joint3D	第二个物体
Params/Bias	float	0.3	—	约束求解偏差
DisableCollision	bool	true	Joint3D	是否禁用连接物体之间的碰撞

信号

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

常用方法

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

代码示例

C

using Godot;

/// <summary>
/// 3D 钟摆
/// </summary>
public partial class Pendulum3D : Node3D
{
    public override void _Ready()
    {
        var joint = GetNode<PinJoint3D>("PinJoint3D");
        joint.NodeA = GetNode<StaticBody3D>("Anchor").GetPath();
        joint.NodeB = GetNode<RigidBody3D>("Bob").GetPath();
    }
}

GDScript

# 3D 钟摆
extends Node3D

func _ready() -> void:
	var joint := $PinJoint3D
	joint.node_a = $Anchor.get_path()
	joint.node_b = $Bob.get_path()