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

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

Tween.kill

定义

Tween.kill 就像按下动画的"紧急停止按钮"——它会立刻停止这个 Tween 上所有正在播放和排队等待的动画，并且把这个 Tween 对象销毁掉。

打个比方：你正在用微波炉加热食物，定时 5 分钟。突然你发现放错了东西，需要马上按"停止"键。Kill() 就是这个停止键，一按下去，微波炉立刻停止加热，之前设定的定时也作废了。

在游戏开发中，你经常需要在中途取消动画——比如玩家在角色移动到一半时突然改变了方向、或者在淡入动画还没播完时就切换了场景，这时就需要用 Kill() 来中断并清理动画。

函数签名

C#

// Tween.Kill 停止并销毁 Tween
public void Kill()

GDScript

func kill() -> void

参数说明

此方法没有参数。

返回值

无返回值（void）。

代码示例

基础用法：中途停止动画

C#

using Godot;

public partial class MyScene : Node2D
{
    private Tween _moveTween;
    private Sprite2D _sprite;

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

        // 开始一个 5 秒的移动动画
        _moveTween = CreateTween();
        _moveTween.TweenProperty(_sprite, "position", new Vector2(500, 300), 5.0);
        // 运行结果: 精灵开始花 5 秒移动到 (500, 300)
    }

    public override void _Input(InputEvent ev)
    {
        // 按空格键立刻停止移动
        if (ev.IsActionPressed("ui_accept") && _moveTween != null)
        {
            _moveTween.Kill();
            _moveTween = null;
            GD.Print("动画已被强制停止！");
            // 运行结果: 动画立即停止，精灵停在当前位置不动
        }
    }
}

GDScript

extends Node2D

var _move_tween: Tween
@onready var sprite = $Sprite2D

func _ready():
    # 开始一个 5 秒的移动动画
    _move_tween = create_tween()
    _move_tween.tween_property(sprite, "position", Vector2(500, 300), 5.0)
    # 运行结果: 精灵开始花 5 秒移动到 (500, 300)

func _input(ev):
    # 按空格键立刻停止移动
    if ev.is_action_pressed("ui_accept") and _move_tween != null:
        _move_tween.kill()
        _move_tween = null
        print("动画已被强制停止！")
        # 运行结果: 动画立即停止，精灵停在当前位置不动

实际场景：玩家改变方向时取消旧动画

C#

using Godot;

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

    private Tween _moveTween;

    public void MoveTo(Vector2 target)
    {
        // 如果有正在播放的移动动画，先停止它
        if (_moveTween != null && _moveTween.IsValid())
        {
            _moveTween.Kill();
            GD.Print("取消了之前的移动动画");
        }

        // 计算移动时间（距离除以速度）
        float distance = GlobalPosition.DistanceTo(target);
        float duration = distance / ExMoveSpeed;

        _moveTween = CreateTween();
        _moveTween.TweenProperty(this, "global_position", target, duration);
        _moveTween.TweenCallback(Callable.From(() => GD.Print("到达目标！")));

        // 运行结果: 连续点击不同位置时，旧的移动会被取消，开始向新位置移动
    }
}

GDScript

extends CharacterBody2D

@export var move_speed: float = 200.0

var _move_tween: Tween

func move_to(target: Vector2):
    # 如果有正在播放的移动动画，先停止它
    if _move_tween != null and _move_tween.is_valid():
        _move_tween.kill()
        print("取消了之前的移动动画")

    # 计算移动时间（距离除以速度）
    var distance = global_position.distance_to(target)
    var duration = distance / move_speed

    _move_tween = create_tween()
    _move_tween.tween_property(self, "global_position", target, duration)
    _move_tween.tween_callback(func(): print("到达目标！"))

    # 运行结果: 连续点击不同位置时，旧的移动会被取消，开始向新位置移动

进阶用法：场景切换时清理所有 Tween

C#

using Godot;

public partial class GameManager : Node
{
    private Tween _bgTween;
    private Tween _uiTween;
    private Tween _sfxTween;

    public void TransitionToScene(string scenePath)
    {
        // 停止所有正在进行的动画，防止场景切换后动画继续跑导致报错
        _bgTween?.Kill();
        _uiTween?.Kill();
        _sfxTween?.Kill();

        GD.Print("所有动画已清理，准备切换场景...");
        // 运行结果: 所有动画已清理，准备切换场景...

        GetTree().ChangeSceneToFile(scenePath);
    }
}

GDScript

extends Node

var _bg_tween: Tween
var _ui_tween: Tween
var _sfx_tween: Tween

func transition_to_scene(scene_path: String):
    # 停止所有正在进行的动画，防止场景切换后动画继续跑导致报错
    if _bg_tween: _bg_tween.kill()
    if _ui_tween: _ui_tween.kill()
    if _sfx_tween: _sfx_tween.kill()

    print("所有动画已清理，准备切换场景...")
    # 运行结果: 所有动画已清理，准备切换场景...

    get_tree().change_scene_to_file(scene_path)

注意事项

• Kill 之后 Tween 对象不可复用：被 Kill 掉的 Tween 不能再添加新的动画步骤或重新启动，你需要创建一个新的 Tween。
• 属性停在当前值：Kill() 不会把属性恢复到动画开始前的值，属性会停留在被 Kill 时的中间值。
• 推荐用 IsValid() 检查：在调用 Kill() 之前，建议先用 IsValid() 检查 Tween 是否还存在，避免对已销毁的对象调用方法导致错误。
• 节点销毁时 Tween 会自动 Kill：如果一个节点被 QueueFree() 删除了，挂在这个节点上的 Tween 也会自动被 Kill。