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

AnimatableBody3D

节点继承关系

继承链：Node → Node3D → PhysicsBody3D → AnimatableBody3D

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 物理体——它会动，但推动其他物体的方式很"温和"。

AnimatableBody3D 是 AnimatableBody2D 的 3D 版本，原理完全相同。区别在于维度和速度类型使用 Vector3。

使用频率：★★★ 一般常用——用于特定的 3D 移动平台场景。

节点用途

• 通过 AnimationPlayer 驱动的 3D 移动平台
• 3D 自动门
• 3D 电梯
• 任何通过动画移动但不应产生冲击力的 3D 碰撞体（Collision Shape）

使用场景

典型场景

• 3D 移动平台：用 AnimationPlayer 让平台来回移动，站在上面的角色被带着走
• 3D 自动门：门缓缓打开，不会把人弹飞
• 3D 电梯：电梯上升时，里面的人跟着上去

不适用场景

• 需要自己精确控制移动的角色 → 使用 CharacterBody3D
• 需要受物理力影响的物体 → 使用 RigidBody3D

常用节点搭配

搭配节点	用途	必需？
CollisionShape3D	定义碰撞边界	必需
AnimationPlayer	驱动平台的移动动画	推荐
MeshInstance3D	显示 3D 模型	推荐

典型节点树：

MovingPlatform (AnimatableBody3D)
├── CollisionShape3D
├── MeshInstance3D
└── AnimationPlayer

生效必备素材/资源

资源	类型	说明
碰撞形状	Shape3D 资源	赋给 CollisionShape3D 子节点
动画资源	Animation 资源	赋给 AnimationPlayer，定义移动路径

节点属性与信号

物理属性

属性	类型	默认值	继承自	说明
Bounce	float	0.0	—	弹性系数
Friction	float	1.0	—	摩擦系数
PhysicsMaterialOverride	PhysicsMaterial	null	—	自定义物理材质
SyncToPhysics	bool	true	—	是否在物理步后同步位置

碰撞层

属性	类型	默认值	继承自	说明
CollisionLayer	uint	1	CollisionObject3D	所在碰撞层
CollisionMask	uint	1	CollisionObject3D	检测哪些碰撞层

信号

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

常用方法

方法	返回值	说明
GetCollisionExceptions()	GodotArray[Node]	获取碰撞例外列表
AddCollisionExceptionWith(body)	void	添加碰撞例外
RemoveCollisionExceptionWith(body)	void	移除碰撞例外

代码示例

C

using Godot;

/// <summary>
/// 用代码驱动的 3D 移动平台
/// 节点结构：MovingPlatform (AnimatableBody3D) + CollisionShape3D + MeshInstance3D
/// </summary>
public partial class CodeDrivenPlatform3D : AnimatableBody3D
{
    [Export] public float ExMoveSpeed = 2.0f;     // 移动速度（米/秒）
    [Export] public float ExMoveDistance = 5.0f;   // 移动距离（米）

    private Vector3 _startPosition;
    private float _progress;

    public override void _Ready()
    {
        _startPosition = Position;
    }

    public override void _PhysicsProcess(double delta)
    {
        float dt = (float)delta;

        // 来回移动
        _progress += dt * ExMoveSpeed / ExMoveDistance;
        float offset = Mathf.Sin(_progress * Mathf.Tau) * ExMoveDistance;

        // 直接修改 Position
        Position = _startPosition + new Vector3(offset, 0f, 0f);
    }
}

GDScript

# 用代码驱动的 3D 移动平台
# 节点结构：MovingPlatform (AnimatableBody3D) + CollisionShape3D + MeshInstance3D
extends AnimatableBody3D

@export var move_speed: float = 2.0     # 移动速度（米/秒）
@export var move_distance: float = 5.0   # 移动距离（米）

var _start_position: Vector3
var _progress: float = 0.0

func _ready() -> void:
	_start_position = position

func _physics_process(delta: float) -> void:
	# 来回移动
	_progress += delta * move_speed / move_distance
	var offset := sin(_progress * TAU) * move_distance

	# 直接修改 Position
	position = _start_position + Vector3(offset, 0.0, 0.0)