游戏引擎 / 系统课时
播放模型动画并切换动作
播放模型动画并切换动作
导入角色后,待机、奔跑和跳跃动画即使能在编辑器中预览,也不会自动响应玩家操作。本课在 Godot 4 中把三段骨骼动画连接到 CharacterBody3D 的运动结果,完成从导入检查、动作判断到运行验证的最小闭环。
学习目标
- 导入并核对
Idle、Run、Jump动画片段与骨骼绑定。 - 让离地状态优先于水平移动状态,避免错误动作覆盖跳跃。
- 使用
AnimationPlayer.play()在状态变化时切换并平滑衔接动作。
导入并核对动画片段
准备带 Skeleton3D、蒙皮网格和三段动画的 glTF/GLB 角色资源。模型须使用一致的骨架及绑定姿势;Idle 和 Run 应为原地循环动作,Jump 用于起跳和短暂腾空。如果从 Blender 导出多段动作,应确认它们确实作为独立动画写入文件,而不是只有一条合并时间线。
- 把 GLB 文件放入项目,从
FileSystem选中资源,在Import面板确认动画导入已启用,再执行Reimport。 - 在高级导入预览或实例化后的场景中检查
AnimationPlayer,逐段预览动作,确认骨骼不会散架、脚底朝向正确。 - 将循环要求设置为
Idle、Run循环,Jump不循环;若资源重导入会覆盖修改,应优先配置源动画、导入选项或外部保存的动画资源。
下面的脚本约定动作键名恰好为 Idle、Run、Jump,且处于默认动画库。若检查器显示 movement/Run 这样的前缀,必须改用完整键名,或者统一整理动画库,不能只改显示标题。
根据运动结果决定动作
在最小控制器中,空中状态优先级最高:只要离地就选择 Jump;落地后,水平实际速度足够大才选择 Run,否则返回 Idle。状态判断应放在 move_and_slide() 之后,因为 is_on_floor() 描述的是最近一次物理移动之后的碰撞结果。

把角色控制器和模型动画分开:CharacterBody3D 负责碰撞、位移、重力与跳跃;AnimationPlayer 只改变模型的骨骼姿态。使用原地动作可以避免动画根骨自身平移与脚本位移叠加,造成角色滑行或从碰撞胶囊中跑出去。
接入可运行的三动作控制器
创建 Player 根节点,类型为 CharacterBody3D,添加 CollisionShape3D,并将导入的角色场景实例命名为 Model。以下代码假设 AnimationPlayer 位于 Player/Model/AnimationPlayer;如果导入结构不同,必须按实际层级调整 $Model/AnimationPlayer。场景中还要有带碰撞形状的地面。
打开 Project → Project Settings → Input Map,创建 move_left、move_right、move_forward、move_back 和 jump,分别绑定 A、D、W、S 和空格。把下列脚本挂到 Player,运行后用移动和跳跃键测试。
extends CharacterBody3D
@export var move_speed: float = 4.0
@export var jump_speed: float = 5.0
@export var gravity: float = 16.0
@onready var anim: AnimationPlayer = $Model/AnimationPlayer
var current_state: StringName = &""
func _ready() -> void:
# 缺少动画时不进入运动循环,避免反复报错。
for clip in [&"Idle", &"Run", &"Jump"]:
if not anim.has_animation(clip):
push_error("缺少动画: %s" % clip)
set_physics_process(false)
return
_change_animation(&"Idle")
func _physics_process(delta: float) -> void:
var axis: Vector2 = Input.get_vector(
"move_left", "move_right", "move_forward", "move_back"
)
var direction := Vector3(axis.x, 0.0, axis.y)
velocity.x = direction.x * move_speed
velocity.z = direction.z * move_speed
if is_on_floor():
if Input.is_action_just_pressed("jump"):
velocity.y = jump_speed
else:
velocity.y -= gravity * delta
move_and_slide()
# 使用碰撞后的状态和实际水平速度,避免顶墙时原地奔跑。
var actual: Vector3 = get_real_velocity()
var horizontal_speed_sq := Vector2(actual.x, actual.z).length_squared()
var next_state: StringName = &"Idle"
if not is_on_floor():
next_state = &"Jump"
elif horizontal_speed_sq > 0.04:
next_state = &"Run"
_change_animation(next_state)
func _change_animation(target: StringName) -> void:
# 仅在状态变化时调用 play,避免每帧从头播放动画。
if target == current_state:
return
anim.play(target, 0.15)
current_state = target
print("animation: ", target)预期输出:从站立开始,按住 W、移动中按空格、落地后继续移动,最后松开 W。输出只在动作变化时新增记录,而不是每个物理帧刷屏。
animation: Idle
animation: Run
animation: Jump
animation: Run
animation: Idle这里 0.15 是 play() 的混合秒数,适合用于观察动作切换是否过硬,并非所有动作的固定最佳值。真正发生移动时应看到网格运动、动画和碰撞胶囊保持一致;空中即使按住 W,也应保持 Jump 状态。
修复不播放、跳变和脚底打滑
如果报缺少动画,先核对库前缀和大小写,再检查导入设置;若 AnimationPlayer 路径不存在,查看导入场景内部的真实层级。动作切换后静止不动,通常需要检查动画轨道是否指向当前 Skeleton3D,以及是否启用了正确的骨骼绑定。
如果按住 W 动作反复从第一帧开始,多半是每帧直接调用 play(),上例用 current_state 保证只在改变状态时触发。Jump 是单次动作,长时间悬空时可能停留在末帧;正式角色可增加 Fall 循环和落地片段,而不是不断重播跳跃起始帧。
脚底打滑时,先核对原地动画的速度节奏,再调 move_speed 或动作播放速度;如果模型在运动中脱离碰撞体,检查动画是否含有根骨位移。保持“物理控制实际位置、动画表现姿态”的分工,才能安全地扩展到转向、攻击和受击动作。