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

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

Tween.tween_callback

定义

Tween.tween_callback 就像在动画时间轴上"定了一个闹钟"——当动画播放到这个时间点时，它会自动调用你指定的方法。

打个比方：你在看一部电影，想在 2 分 30 秒的时候自动弹一条消息提醒自己"主角快出场了"。tween_callback 就是这个定时提醒器，只不过它是在动画序列的某个时间点触发一个函数调用。

在游戏开发中，你经常需要在动画结束后做一些事情——比如播放完攻击动画后扣除敌人的血量、移动结束后切换场景、淡出动画结束后删除节点——这些就是 tween_callback 的典型应用。

函数签名

C#

// Tween.TweenCallback 在动画序列中插入一个回调
public Tween TweenCallback(Callable callback)

GDScript

func tween_callback(callback: Callable) -> Tween

参数说明

参数	类型	必需	说明
callback	Callable	是	要调用的函数，可以是任意零参数或带参数的 Callable

返回值

返回 Tween 对象本身，支持链式调用。

代码示例

基础用法：动画结束后打印消息

C#

using Godot;

public partial class MyScene : Node2D
{
    private Sprite2D _sprite;

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

        Tween tween = CreateTween();
        // 先移动 2 秒
        tween.TweenProperty(_sprite, "position", new Vector2(300, 100), 2.0);
        // 移动结束后打印消息
        tween.TweenCallback(Callable.From(() => GD.Print("移动完成！")));
        // 运行结果: 2 秒后控制台输出 "移动完成！"
    }
}

GDScript

extends Node2D

@onready var sprite = $Sprite2D

func _ready():
    var tween = create_tween()
    # 先移动 2 秒
    tween.tween_property(sprite, "position", Vector2(300, 100), 2.0)
    # 移动结束后打印消息
    tween.tween_callback(func(): print("移动完成！"))
    # 运行结果: 2 秒后控制台输出 "移动完成！"

实际场景：攻击动画结束后扣血

C#

using Godot;

public partial class Player : CharacterBody2D
{
    [Export] public float ExAttackDamage = 25.0f;

    private Sprite2D _sprite;

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

    public void Attack(Node2D target)
    {
        Tween tween = CreateTween();

        // 1. 播放攻击动画：向右冲刺 0.2 秒
        tween.TweenProperty(_sprite, "position:x", _sprite.Position.X + 50, 0.2);
        // 2. 对目标造成伤害
        tween.TweenCallback(Callable.From(() => _DealDamage(target)));
        // 3. 回到原位 0.2 秒
        tween.TweenProperty(_sprite, "position:x", _sprite.Position.X, 0.2);
        // 4. 攻击结束
        tween.TweenCallback(Callable.From(() => GD.Print("攻击结束")));

        // 运行结果: 冲刺(0.2秒) → 扣血 → 回位(0.2秒) → 打印"攻击结束"
    }

    private void _DealDamage(Node2D target)
    {
        GD.Print($"对 {target.Name} 造成 {ExAttackDamage} 点伤害！");
        // 运行结果: 对 Enemy 造成 25 点伤害！
    }
}

GDScript

extends CharacterBody2D

@export var attack_damage: float = 25.0

@onready var sprite = $Sprite2D

func attack(target):
    var tween = create_tween()

    # 1. 播放攻击动画：向右冲刺 0.2 秒
    tween.tween_property(sprite, "position:x", sprite.position.x + 50, 0.2)
    # 2. 对目标造成伤害
    tween.tween_callback(func(): _deal_damage(target))
    # 3. 回到原位 0.2 秒
    tween.tween_property(sprite, "position:x", sprite.position.x, 0.2)
    # 4. 攻击结束
    tween.tween_callback(func(): print("攻击结束"))

    # 运行结果: 冲刺(0.2秒) → 扣血 → 回位(0.2秒) → 打印"攻击结束"

func _deal_damage(target):
    print("对 ", target.name, " 造成 ", attack_damage, " 点伤害！")
    # 运行结果: 对 Enemy 造成 25.0 点伤害！

进阶用法：淡出后删除节点

C#

using Godot;

public partial class EffectManager : Node2D
{
    /// 让指定节点淡出后自动删除
    public void FadeOutAndRemove(CanvasItem node, double duration = 1.0)
    {
        Tween tween = CreateTween();
        // 透明度渐变到 0
        tween.TweenProperty(node, "modulate:a", 0.0, duration);
        // 动画结束后删除节点
        tween.TweenCallback(Callable.From(() =>
        {
            GD.Print($"{node.Name} 淡出完毕，已删除");
            node.QueueFree();
        }));
        // 运行结果: 节点在 duration 秒内变透明后被删除，打印 "XXX 淡出完毕，已删除"
    }
}

GDScript

extends Node2D

## 让指定节点淡出后自动删除
func fade_out_and_remove(node: CanvasItem, duration: float = 1.0):
    var tween = create_tween()
    # 透明度渐变到 0
    tween.tween_property(node, "modulate:a", 0.0, duration)
    # 动画结束后删除节点
    tween.tween_callback(func():
        print(node.name, " 淡出完毕，已删除")
        node.queue_free()
    )
    # 运行结果: 节点在 duration 秒内变透明后被删除，打印 "XXX 淡出完毕，已删除"

注意事项

• 回调会在动画的时间点执行：tween_callback 在动画序列中的位置决定了它何时被调用。如果前面有 2 秒的动画，回调会在 2 秒后执行。
• C# 中使用 Callable.From：在 C# 中，你需要用 Callable.From(() => ...) 把 lambda 表达式包装成 Callable。如果回调的是某个对象的方法，也可以用 Callable.From(MyMethod) 或 new Callable(this, MethodName.MyMethod)。
• 不要在回调中做耗时操作：回调在主线程上同步执行，如果里面做了大量计算或等待，会卡住游戏。
• 回调的时机：如果前面的动画被 Kill() 中断了，回调也不会被执行。