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

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

AnimationPlayer.queue

定义

AnimationPlayer.queue 就像在音乐播放器里"添加到播放队列"——当当前动画播放完毕后，自动接着播放你指定的下一个动画。

打个比方：你在听歌，当前正在听"第一首歌"。你点了一下"下一首播放"，把"第二首歌"加到了队列里。第一首播完后，播放器会自动开始第二首，中间不需要你手动操作。Queue() 就是这个"下一首播放"按钮。

在游戏开发中，你经常需要动画无缝衔接——比如"攻击"动画播完后自动接"站立"动画、或者"跳跃"动画播完后自动接"着地"动画。用 Queue() 可以轻松实现这种"播完一个自动播下一个"的逻辑。

函数签名

C#

// AnimationPlayer.Queue 将动画加入播放队列
public void Queue(StringName name)

GDScript

func queue(name: StringName) -> void

参数说明

参数	类型	必需	说明
name	StringName / String	是	当前动画播完后要自动播放的下一个动画名称

返回值

无返回值（void）。

代码示例

基础用法：攻击后自动回到站立

C#

using Godot;

public partial class Player : CharacterBody2D
{
    private AnimationPlayer _animPlayer;

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

        // 播放攻击动画
        _animPlayer.Play("attack");
        // 攻击动画播完后，自动播放 idle（站立）动画
        _animPlayer.Queue("idle");

        // 运行结果: 角色先播放攻击动画 → 攻击结束后自动切到站立动画
    }
}

GDScript

extends CharacterBody2D

@onready var anim_player = $AnimationPlayer

func _ready():
    # 播放攻击动画
    anim_player.play("attack")
    # 攻击动画播完后，自动播放 idle（站立）动画
    anim_player.queue("idle")

    # 运行结果: 角色先播放攻击动画 → 攻击结束后自动切到站立动画

实际场景：技能连招动画链

C#

using Godot;

public partial class Warrior : CharacterBody2D
{
    private AnimationPlayer _animPlayer;

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

    /// 执行三连击技能
    public void PerformCombo()
    {
        // 第一击
        _animPlayer.Play("slash_1");
        // 第一击结束后自动接第二击
        _animPlayer.Queue("slash_2");
        // 注意：Queue 只能排一个动画，所以需要在 slash_2 开始后再排 slash_3

        // 运行结果: 第一击 → 自动接第二击

        GD.Print("连招开始！");
        // 运行结果: 连招开始！
    }

    public override void _Process(double delta)
    {
        // 当 slash_2 开始播放时，排队 slash_3
        if (_animPlayer.CurrentAnimation == "slash_2" &&
            !_animPlayer.IsQueued())
        {
            _animPlayer.Queue("slash_3");
            // 第二击结束后自动接第三击

            // 第三击结束后回到站立
            // 需要在 slash_3 开始后再排队 idle
        }

        if (_animPlayer.CurrentAnimation == "slash_3" &&
            !_animPlayer.IsQueued())
        {
            _animPlayer.Queue("idle");
            // 运行结果: 三连击完成后自动回到站立
        }
    }
}

GDScript

extends CharacterBody2D

@onready var anim_player = $AnimationPlayer

## 执行三连击技能
func perform_combo():
    # 第一击
    anim_player.play("slash_1")
    # 第一击结束后自动接第二击
    anim_player.queue("slash_2")
    # 注意：queue 只能排一个动画，所以需要在 slash_2 开始后再排 slash_3

    # 运行结果: 第一击 → 自动接第二击

    print("连招开始！")
    # 运行结果: 连招开始！

func _process(delta):
    # 当 slash_2 开始播放时，排队 slash_3
    if anim_player.current_animation == "slash_2" and not anim_player.is_queued():
        anim_player.queue("slash_3")
        # 第二击结束后自动接第三击

    if anim_player.current_animation == "slash_3" and not anim_player.is_queued():
        anim_player.queue("idle")
        # 运行结果: 三连击完成后自动回到站立

进阶用法：跳跃着地动画链

C#

using Godot;

public partial class PlatformPlayer : CharacterBody2D
{
    private AnimationPlayer _animPlayer;
    private bool _isJumping = false;

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

    public override void _PhysicsProcess(double delta)
    {
        if (Input.IsActionJustPressed("jump") && IsOnFloor())
        {
            // 跳起时播放起跳动画，结束后自动接空中动画
            _animPlayer.Play("jump_start");
            _animPlayer.Queue("jump_air");
            _isJumping = true;
            // 运行结果: 起跳动画 → 空中待机动画（持续到着地）
        }

        // 着地时从空中动画切到着地动画
        if (_isJumping && IsOnFloor())
        {
            _animPlayer.Play("jump_land");
            _animPlayer.Queue("idle");
            _isJumping = false;
            // 运行结果: 着地动画 → 站立动画
        }
    }
}

GDScript

extends CharacterBody2D

@onready var anim_player = $AnimationPlayer
var _is_jumping = false

func _physics_process(delta):
    if Input.is_action_just_pressed("jump") and is_on_floor():
        # 跳起时播放起跳动画，结束后自动接空中动画
        anim_player.play("jump_start")
        anim_player.queue("jump_air")
        _is_jumping = true
        # 运行结果: 起跳动画 → 空中待机动画（持续到着地）

    # 着地时从空中动画切到着地动画
    if _is_jumping and is_on_floor():
        anim_player.play("jump_land")
        anim_player.queue("idle")
        _is_jumping = false
        # 运行结果: 着地动画 → 站立动画

注意事项

• 只能排队一个动画：每次调用 Queue() 只能安排一个"下一首"。如果你想实现三连动画（A → B → C），需要在 B 开始播放后再 Queue("C")。
• 可以用 IsQueued() 检查：调用 _animPlayer.IsQueued() 可以判断是否已经有动画在排队等待，避免重复排队。
• 如果当前动画被 Stop() 终止：排队的动画也不会播放了，因为当前动画没有"自然播完"。
• 排队的动画会在当前动画自然结束后播放：如果当前动画设置了循环播放，它永远不会自然结束，排队的动画也就永远不会被触发。