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

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

AnimationPlayer.stop

定义

AnimationPlayer.stop 就像按下动画的"暂停/停止键"——让正在播放的动画立刻停下来。

打个比方：你在看视频时按了暂停按钮，视频画面就冻结在了当前这一帧。Stop() 也是一样的效果：动画停在了当前帧，角色的姿势、位置等所有属性保持在动画被停止那一刻的状态。

和 Pause() 不同的是，Stop() 会将 AnimationPlayer 的内部状态重置（比如播放位置归零），下次再 Play() 时会从头开始播放。

函数签名

C#

// AnimationPlayer.Stop 停止当前动画
public void Stop(bool keepState = false)

GDScript

func stop(keep_state: bool = false) -> void

参数说明

参数	类型	必需	默认值	说明
keep_state	bool	否	false	是否保持动画的当前状态。false（默认）会将所有被动画修改的属性恢复到动画开始前的值

返回值

无返回值（void）。

代码示例

基础用法：停止当前动画

C#

using Godot;

public partial class Player : CharacterBody2D
{
    private AnimationPlayer _animPlayer;

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

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

        // 假设 2 秒后停止
        GetTree().CreateTimer(2.0).Timeout += () =>
        {
            _animPlayer.Stop();
            GD.Print("动画已停止");
            // 运行结果: 动画停止，被动画修改的属性恢复原值
        };
    }
}

GDScript

extends CharacterBody2D

@onready var anim_player = $AnimationPlayer

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

    # 假设 2 秒后停止
    get_tree().create_timer(2.0).timeout.connect(func():
        anim_player.stop()
        print("动画已停止")
        # 运行结果: 动画停止，被动画修改的属性恢复原值
    )

实际场景：角色死亡时停止所有动画

C#

using Godot;

public partial class Enemy : CharacterBody2D
{
    [Export] public int ExMaxHealth = 100;

    private AnimationPlayer _animPlayer;
    private int _health;

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

    public void TakeDamage(int amount)
    {
        _health -= amount;
        GD.Print($"敌人受到 {amount} 伤害，剩余血量: {_health}");

        if (_health <= 0)
        {
            _Die();
        }
    }

    private void _Die()
    {
        // 停止当前所有动画（比如走路动画）
        _animPlayer.Stop(keepState: true);
        // keepState = true，保持角色在停止瞬间的姿势
        // 运行结果: 动画停止，角色保持当前姿势不变

        GD.Print("敌人已死亡，动画已停止");
        // 运行结果: 敌人已死亡，动画已停止
    }
}

GDScript

extends CharacterBody2D

@export var max_health: int = 100

@onready var anim_player = $AnimationPlayer
var _health: int

func _ready():
    _health = max_health

func take_damage(amount: int):
    _health -= amount
    print("敌人受到 ", amount, " 伤害，剩余血量: ", _health)

    if _health <= 0:
        _die()

func _die():
    # 停止当前所有动画（比如走路动画）
    anim_player.stop(true)
    # keep_state = true，保持角色在停止瞬间的姿势
    # 运行结果: 动画停止，角色保持当前姿势不变

    print("敌人已死亡，动画已停止")
    # 运行结果: 敌人已死亡，动画已停止

进阶用法：keepState 参数对比

C#

using Godot;

public partial class StopDemo : Node2D
{
    private AnimationPlayer _animPlayer;
    private Sprite2D _sprite;

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

        // 播放一个会移动精灵位置的动画
        _animPlayer.Play("move_right");

        // 假设动画播放到一半时停止
        GetTree().CreateTimer(1.0).Timeout += () =>
        {
            Vector2 posBefore = _sprite.Position;

            // 方式1：不保持状态（默认）
            // _animPlayer.Stop();
            // 精灵位置会回到动画开始前的位置

            // 方式2：保持状态
            _animPlayer.Stop(keepState: true);
            Vector2 posAfter = _sprite.Position;

            GD.Print($"停止前位置: {posBefore}");
            // 运行结果: 停止前位置: (150, 100)（动画中间的某个位置）
            GD.Print($"停止后位置: {posAfter}");
            // 运行结果: 停止后位置: (150, 100)（保持不变，因为 keepState=true）
        };
    }
}

GDScript

extends Node2D

@onready var anim_player = $AnimationPlayer
@onready var sprite = $Sprite2D

func _ready():
    # 播放一个会移动精灵位置的动画
    anim_player.play("move_right")

    # 假设动画播放到一半时停止
    get_tree().create_timer(1.0).timeout.connect(func():
        var pos_before = sprite.position

        # 方式1：不保持状态（默认）
        # anim_player.stop()
        # 精灵位置会回到动画开始前的位置

        # 方式2：保持状态
        anim_player.stop(true)
        var pos_after = sprite.position

        print("停止前位置: ", pos_before)
        # 运行结果: 停止前位置: (150, 100)（动画中间的某个位置）
        print("停止后位置: ", pos_after)
        # 运行结果: 停止后位置: (150, 100)（保持不变，因为 keep_state=true）
    )

注意事项

• keepState 默认为 false：不传参数时，Stop() 会把所有被动画修改的属性恢复到动画开始前的值。如果你希望角色保持当前姿势，需要传入 true。
• Stop 和 Pause 的区别：Stop() 重置播放位置，下次 Play() 从头开始；Pause() 只是暂停，下次 Play() 会从暂停处继续。
• 停止后可以立即播放新动画：Stop() 之后可以马上调用 Play("other_anim") 播放另一个动画。
• 连续停止是安全的：即使当前没有动画在播放，调用 Stop() 也不会报错。