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

ConeTwistJoint3D

节点继承关系

继承链：Node → Node3D → Joint3D → ConeTwistJoint3D

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

定义

像球窝关节（人体的肩关节）——允许在一个锥形范围内旋转，可以设定扭转限制。

想象你的肩膀——你的手臂可以向前抬、向侧面抬、旋转，但不能 360 度随便转。肩关节就是一个"球窝关节"，它限制手臂在一个锥形范围内运动。ConeTwistJoint3D 就是模拟这种关节。

使用频率：★ 基本用不到——用于布娃娃物理和角色关节。

节点用途

• 角色关节（肩膀、髋部）
• 布娃娃物理
• 球形关节连接

使用场景

典型场景

• 布娃娃的肩关节：限制手臂在一定范围内摆动
• 布娃娃的髋关节：限制腿在一定范围内摆动

不适用场景

• 只需要单轴旋转 → 使用 HingeJoint3D
• 需要完全自由的运动 → 使用 Generic6DOFJoint3D

常用节点搭配

搭配节点	用途	必需？
RigidBody3D（NodeA）	上半身	必需
RigidBody3D（NodeB）	手臂/腿	必需

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
NodeA	NodePath	""	Joint3D	第一个物体
NodeB	NodePath	""	Joint3D	第二个物体
SwingSpan	float	1.57	—	摆动范围（锥角，弧度。约 90 度）
TwistSpan	float	1.57	—	扭转范围（弧度。约 90 度）
Bias	float	0.3	—	约束求解偏差
Softness	float	0.4	—	关节柔软度
Relaxation	float	1.0	—	松弛系数
DisableCollision	bool	true	Joint3D	是否禁用碰撞

信号

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

常用方法

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

代码示例

C

using Godot;

/// <summary>
/// 布娃娃肩关节设置
/// </summary>
public partial class RagdollShoulder : Node3D
{
    public override void _Ready()
    {
        var joint = GetNode<ConeTwistJoint3D>("ConeTwistJoint3D");
        joint.NodeA = GetNode<RigidBody3D>("UpperBody").GetPath();
        joint.NodeB = GetNode<RigidBody3D>("Arm").GetPath();

        // 肩膀的摆动范围（前后左右 120 度）
        joint.SwingSpan = Mathf.DegToRad(120f);
        // 扭转范围（小臂旋转 45 度）
        joint.TwistSpan = Mathf.DegToRad(45f);
    }
}

GDScript

# 布娃娃肩关节设置
extends Node3D

func _ready() -> void:
	var joint := $ConeTwistJoint3D
	joint.node_a = $UpperBody.get_path()
	joint.node_b = $Arm.get_path()

	# 肩膀的摆动范围（前后左右 120 度）
	joint.swing_span = deg_to_rad(120.0)
	# 扭转范围（小臂旋转 45 度）
	joint.twist_span = deg_to_rad(45.0)

SwingSpan 和 TwistSpan 的含义

• SwingSpan：像一个倒扣的锥子，控制"摆动"的范围。比如手臂向前抬和向侧面抬的角度
• TwistSpan：控制"扭转"的范围。比如你的前臂旋转（手掌朝上翻到朝下翻）
• 两个值都是弧度制，1 弧度约等于 57.3 度