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

PhysicalBone3D

节点继承关系

继承链：Node → Node3D → PhysicsBody3D → PhysicalBone3D

PhysicsBody3D

类型	名称	说明
方法	MoveAndCollide()	移动并检测碰撞
方法	TestMove()	测试移动是否会碰撞（不实际移动）

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 骨骼的物理版本——把角色的一根根骨头变成独立的物理体，让角色在死亡后像布娃娃一样瘫软倒地。

想象一个木偶——它有很多关节连接的肢体。正常时候你控制它做出各种动作，但松手之后它就软塌塌地倒下来。PhysicalBone3D 就是那些"肢体"，关节连接着它们。

通常你不需要手动创建 PhysicalBone3D 节点。Godot 可以从角色的骨骼（Skeleton3D）自动生成物理骨骼。

使用频率：★★ 偶尔使用——仅在需要布娃娃物理效果时使用。

节点用途

• 布娃娃物理（角色死亡后倒地）
• 角色肢体与环境的物理交互
• 被击飞后的肢体散落效果

使用场景

典型场景

• 死亡效果：角色被击杀后，身体像布娃娃一样倒下
• 物理交互：角色被风吹动、被爆炸掀飞

不适用场景

• 角色活着时的正常移动 → 使用 CharacterBody3D
• 不需要布娃娃效果的游戏 → 不使用

常用节点搭配

搭配节点	用途	必需？
Skeleton3D	骨骼系统（Skeleton）	必需
CollisionShape3D	每根骨头的碰撞形状	必需
MeshInstance3D	角色模型	推荐
PhysicalBoneSimulator3D	物理骨骼模拟器（自动管理）	推荐

典型节点树（自动生成后）：

Character (CharacterBody3D)
├── MeshInstance3D
├── Skeleton3D
│   ├── PhysicalBone3D（自动生成的骨骼物理体）
│   │   ├── CollisionShape3D
│   │   └── ...
│   └── ...
└── PhysicalBoneSimulator3D

生效必备素材/资源

资源	类型	说明
角色模型（带骨骼）	.glb/.gltf 文件	包含 Skeleton3D 的模型
碰撞形状资源	Shape3D 资源	每根骨头需要碰撞形状

节点属性与信号

物理属性

属性	类型	默认值	继承自	说明
Mass	float	1.0	—	单根骨头的质量
Bounce	float	0.0	—	弹性系数
Friction	float	1.0	—	摩擦系数
GravityScale	float	1.0	—	重力倍数
LinearDamp	float	0.0	—	线性阻尼
AngularDamp	float	0.0	—	角度阻尼
CanSleep	bool	true	—	是否可以休眠
Bounce	float	0.0	—	弹性系数

骨骼绑定

属性	类型	默认值	继承自	说明
BoneName	StringName	""	—	对应的骨骼名称
JointType	枚举	None	—	关节类型
JointOffset	Transform3D	—	—	关节偏移
BodyOffset	Transform3D	—	—	物理体偏移

信号

信号	触发时机	继承自	说明
继承 PhysicsBody3D 的所有信号	—	PhysicsBody3D	body_entered、body_exited 等

常用方法

方法	返回值	说明
GetJointType()	枚举	获取关节类型
IsSimulatingPhysics()	bool	是否正在模拟物理
StartPhysicsSimulation()	void	开始物理模拟（激活布娃娃）
StopPhysicsSimulation()	void	停止物理模拟（恢复动画控制）

代码示例

C

using Godot;

/// <summary>
/// 角色死亡时激活布娃娃物理
/// </summary>
public partial class RagdollCharacter : CharacterBody3D
{
    private PhysicalBoneSimulator3D _simulator;

    public override void _Ready()
    {
        _simulator = GetNode<PhysicalBoneSimulator3D>("PhysicalBoneSimulator3D");
    }

    /// <summary>
    /// 角色死亡 → 激活布娃娃
    /// </summary>
    public void Die()
    {
        // 停止角色控制
        SetProcess(false);
        SetPhysicsProcess(false);

        // 激活物理骨骼模拟
        _simulator.PhysicalBonesStartSimulation();

        // 给身体施加一个向后的冲击力（模拟被击飞）
        foreach (var child in GetChildren())
        {
            if (child is PhysicalBone3D bone)
            {
                bone.ApplyCentralImpulse(new Vector3(0f, 2f, -5f));
            }
        }

        // 延迟一段时间后销毁
        var timer = GetTree().CreateTimer(5.0);
        timer.Timeout += QueueFree;
    }
}

GDScript

# 角色死亡时激活布娃娃物理
extends CharacterBody3D

@onready var simulator: PhysicalBoneSimulator3D = $PhysicalBoneSimulator3D

## 角色死亡 → 激活布娃娃
func die() -> void:
	# 停止角色控制
	set_process(false)
	set_physics_process(false)

	# 激活物理骨骼模拟
	simulator.physical_bones_start_simulation()

	# 给身体施加一个向后的冲击力（模拟被击飞）
	for child in get_children():
		if child is PhysicalBone3D:
			child.apply_central_impulse(Vector3(0.0, 2.0, -5.0))

	# 延迟一段时间后销毁
	var timer := get_tree().create_timer(5.0)
	timer.timeout.connect(queue_free)

自动生成物理骨骼

在编辑器中，选中 Skeleton3D 节点，在菜单中选择 Skeleton → Create Physical Skeleton，Godot 会自动为每根骨骼创建 PhysicalBone3D 和碰撞形状。这是最简单的创建布娃娃的方式。