最后更新日期：2026-04-16

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

AnimationPlayer.play

定义

AnimationPlayer.play 就像按下了动画的"播放键"——告诉 AnimationPlayer 节点："从现在开始播放指定的动画"。

打个比方：AnimationPlayer 就像一个音乐播放器，你在编辑器里制作好的每一段动画就是一首歌。调用 Play() 就相当于在播放器上点了一下"播放"按钮，指定的那首"歌"（动画）就开始播放了。

在游戏开发中，AnimationPlayer 通常用来管理角色动画（走、跑、跳、攻击）、UI 动画（弹窗出现、按钮闪烁）、场景动画（门打开、桥落下）等。这些动画通常在编辑器中预先制作好（有关键帧），然后在代码中用 Play() 按需触发播放。

函数签名

C#

// AnimationPlayer.Play 播放指定动画
public void Play(StringName name = "", double customBlend = -1.0, float customSpeed = 1.0f, bool fromEnd = false)

GDScript

func play(name: String = "", custom_blend: float = -1.0, custom_speed: float = 1.0, from_end: bool = false) -> void

参数说明

参数	类型	必需	默认值	说明
name	StringName / String	否	""	要播放的动画名称。留空则播放当前动画或默认动画
custom_blend	float / double	否	-1.0	混合时间（秒），用于从上一个动画平滑过渡到新动画。-1 表示使用默认混合时间
custom_speed	float	否	1.0	播放速度倍率。1.0 为正常速度，2.0 为两倍速，0.5 为半速
from_end	bool	否	false	是否从动画末尾开始播放（倒放）

返回值

无返回值（void）。

代码示例

基础用法：播放指定动画

C#

using Godot;

public partial class Player : CharacterBody2D
{
    private AnimationPlayer _animPlayer;

    public override void _Ready()
    {
        _animPlayer = GetNode<AnimationPlayer>("AnimationPlayer");

        // 播放名为 "walk" 的动画
        _animPlayer.Play("walk");
        // 运行结果: 角色开始播放走路动画

        GD.Print($"正在播放: {_animPlayer.CurrentAnimation}");
        // 运行结果: 正在播放: walk
    }
}

GDScript

extends CharacterBody2D

@onready var anim_player = $AnimationPlayer

func _ready():
    # 播放名为 "walk" 的动画
    anim_player.play("walk")
    # 运行结果: 角色开始播放走路动画

    print("正在播放: ", anim_player.current_animation)
    # 运行结果: 正在播放: walk

实际场景：根据角色状态切换动画

C#

using Godot;

public partial class Player : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 200.0f;

    private AnimationPlayer _animPlayer;
    private string _currentAnim = "";

    public override void _Ready()
    {
        _animPlayer = GetNode<AnimationPlayer>("AnimationPlayer");
    }

    public override void _PhysicsProcess(double delta)
    {
        Vector2 velocity = Velocity;

        // 获取移动方向
        float direction = Input.GetAxis("ui_left", "ui_right");

        if (direction != 0)
        {
            velocity.X = direction * ExMoveSpeed;
            _PlayAnimation("run");
        }
        else
        {
            velocity.X = 0;
            _PlayAnimation("idle");
        }

        Velocity = velocity;
    }

    private void _PlayAnimation(string animName)
    {
        // 避免重复触发同一动画
        if (_currentAnim != animName)
        {
            _animPlayer.Play(animName);
            _currentAnim = animName;
            // 运行结果: 只在动画需要切换时才调用 Play()
        }
    }
}

GDScript

extends CharacterBody2D

@export var move_speed: float = 200.0

@onready var anim_player = $AnimationPlayer
var _current_anim: String = ""

func _physics_process(delta):
    var velocity = velocity

    # 获取移动方向
    var direction = Input.get_axis("ui_left", "ui_right")

    if direction != 0:
        velocity.x = direction * move_speed
        _play_animation("run")
    else:
        velocity.x = 0
        _play_animation("idle")

    velocity = velocity

func _play_animation(anim_name: String):
    # 避免重复触发同一动画
    if _current_anim != anim_name:
        anim_player.play(anim_name)
        _current_anim = anim_name
        # 运行结果: 只在动画需要切换时才调用 play()

进阶用法：以不同速度和混合时间播放

C#

using Godot;

public partial class BattleUnit : Node2D
{
    private AnimationPlayer _animPlayer;

    public override void _Ready()
    {
        _animPlayer = GetNode<AnimationPlayer>("AnimationPlayer");
    }

    public void PlayAttack()
    {
        // 播放攻击动画，速度 1.5 倍，混合过渡 0.2 秒
        _animPlayer.Play("attack", customBlend: 0.2, customSpeed: 1.5f);
        // 运行结果: 攻击动画以 1.5 倍速播放，与前一个动画有 0.2 秒的平滑过渡
    }

    public void PlayDeath()
    {
        // 播放死亡动画，正常速度，混合过渡 0.3 秒
        _animPlayer.Play("death", customBlend: 0.3);
        // 运行结果: 死亡动画正常速度播放，从当前状态平滑过渡
    }

    public void PlayHitStagger()
    {
        // 受击动画以 0.8 倍速播放（慢一点更有打击感）
        _animPlayer.Play("hit", customSpeed: 0.8f);
        // 运行结果: 受击动画以 0.8 倍速播放
    }
}

GDScript

extends Node2D

@onready var anim_player = $AnimationPlayer

func play_attack():
    # 播放攻击动画，速度 1.5 倍，混合过渡 0.2 秒
    anim_player.play("attack", 0.2, 1.5)
    # 运行结果: 攻击动画以 1.5 倍速播放，与前一个动画有 0.2 秒的平滑过渡

func play_death():
    # 播放死亡动画，正常速度，混合过渡 0.3 秒
    anim_player.play("death", 0.3)
    # 运行结果: 死亡动画正常速度播放，从当前状态平滑过渡

func play_hit_stagger():
    # 受击动画以 0.8 倍速播放（慢一点更有打击感）
    anim_player.play("hit", -1.0, 0.8)
    # 运行结果: 受击动画以 0.8 倍速播放

注意事项

• 重复调用同一动画会重新开始：如果正在播放 "walk" 又调用了 Play("walk")，动画会从头开始。建议先检查 CurrentAnimation 避免不必要的重播。
• 动画必须事先在编辑器中制作：Play() 只能播放在 AnimationPlayer 中已经存在的动画（有关键帧的）。如果你需要代码动态创建动画，应该使用 Tween。
• custom_blend 用于平滑过渡：当从一个动画切换到另一个动画时，设置混合时间可以让过渡更自然，而不是突然跳变。
• customSpeed 可以实现慢动作或快进：设为负数会让动画倒放。设为 0 会暂停动画（等同于 Pause()）。
• 与 Tween 的区别：AnimationPlayer 适合预先制作好的复杂关键帧动画（如角色骨骼动画），Tween 适合简单的属性渐变（如位置、颜色变化）。