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

HingeJoint3D

节点继承关系

继承链：Node → Node3D → Joint3D → HingeJoint3D

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 版本的铰链关节。两个物体围绕一条轴旋转，像门的铰链。

想象一扇门——门通过铰链连接在门框上，门可以绕着铰链旋转打开和关闭，但不能从门框上拆下来。HingeJoint3D 就是那副"铰链"。你可以设置旋转角度限制（比如门最多只能开 90 度）。

使用频率：★ 基本用不到——用于 3D 铰链连接。

节点用途

• 门（旋转开关）
• 车轮（绕轴旋转）
• 机械臂关节
• 风车叶片

使用场景

典型场景

• 可开关的门：门绕着门框的铰链旋转
• 3D 铰链：任何需要围绕固定轴旋转的连接

不适用场景

• 需要沿直线滑动 → 使用 SliderJoint3D
• 需要多轴旋转 → 使用 Generic6DOFJoint3D

常用节点搭配

搭配节点	用途	必需？
RigidBody3D（NodeA）	门框	必需
RigidBody3D（NodeB）	门	必需

典型节点树：

DoorSystem (Node3D)
├── DoorFrame (StaticBody3D)
├── HingeJoint3D（连接 DoorFrame 和 Door）
└── Door (RigidBody3D)
    ├── CollisionShape3D
    └── MeshInstance3D

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
NodeA	NodePath	""	Joint3D	第一个物体（如门框）
NodeB	NodePath	""	Joint3D	第二个物体（如门）
Params/Bias	float	0.3	—	铰链位置修正速度
Params/AngularLimit/Enable	bool	true	—	是否启用角度限制
Params/AngularLimit/Lower	float	-1.57	—	最小旋转角度（弧度，约 -90 度）
Params/AngularLimit/Upper	float	1.57	—	最大旋转角度（弧度，约 +90 度）
Params/Motor/Enable	bool	false	—	是否启用马达（自动旋转）
Params/Motor/MaxImpulse	float	0.0	—	马达最大冲量
DisableCollision	bool	true	Joint3D	是否禁用碰撞

信号

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

常用方法

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

代码示例

C

using Godot;

/// <summary>
/// 3D 可开关的门
/// </summary>
public partial class Door3D : Node3D
{
    private HingeJoint3D _joint;

    public override void _Ready()
    {
        _joint = GetNode<HingeJoint3D>("HingeJoint3D");
        _joint.NodeA = GetNode<StaticBody3D>("DoorFrame").GetPath();
        _joint.NodeB = GetNode<RigidBody3D>("Door").GetPath();

        // 设置门的旋转限制（-90 度到 +90 度）
        _joint.Set("params/angular_limit/lower", Mathf.DegToRad(-90f));
        _joint.Set("params/angular_limit/upper", Mathf.DegToRad(90f));
    }

    /// <summary>
    /// 用马达自动开门
    /// </summary>
    public void OpenDoor()
    {
        _joint.Set("params/motor/enable", true);
        _joint.Set("params/motor/target_velocity", Mathf.DegToRad(90f));
        _joint.Set("params/motor/max_impulse", 5.0f);
    }

    /// <summary>
    /// 关闭马达
    /// </summary>
    public void StopDoor()
    {
        _joint.Set("params/motor/enable", false);
    }
}

GDScript

# 3D 可开关的门
extends Node3D

@onready var joint: HingeJoint3D = $HingeJoint3D

func _ready() -> void:
	joint.node_a = $DoorFrame.get_path()
	joint.node_b = $Door.get_path()

	# 设置门的旋转限制（-90 度到 +90 度）
	joint.set("params/angular_limit/lower", deg_to_rad(-90.0))
	joint.set("params/angular_limit/upper", deg_to_rad(90.0))

## 用马达自动开门
func open_door() -> void:
	joint.set("params/motor/enable", true)
	joint.set("params/motor/target_velocity", deg_to_rad(90.0))
	joint.set("params/motor/max_impulse", 5.0)

## 关闭马达
func stop_door() -> void:
	joint.set("params/motor/enable", false)