跳至主要內容

Object.emit_signal

EVOCOSMOS2026/4/14大约 7 分钟

最后同步日期：2026-04-16 | Godot 官方原文 — Object.emit_signal

Object.emit_signal

定义

emit_signal 就像按下门铃按钮——之前用 connect 接好的电线已经就位，现在你按下按钮（触发信号），连接在电线另一端的门铃（处理方法）就会响起来。

再打个比方：你在公司用钉钉群发了一条消息，所有加入了这个群的人都会收到通知。emit_signal 就是你发消息这一步，而"加入群"就是之前 connect 做的事。

信号被触发后，所有连接到这个信号的处理方法都会被依次调用。你可以把信号想象成广播电台——电台发射信号（emit_signal），所有收音机（connect 过的方法）都能收到。

一句话总结

emit_signal 的作用是"按下按钮"：主动触发一个信号，让所有连接了这个信号的方法自动执行。

函数签名

C#
// 方式一：使用 EmitSignal 方法
public Error EmitSignal(StringName signal, params Variant[] args)

// 方式二（推荐）：使用 C# 信号触发语法
// 对于自定义信号，直接调用信号名：
EmitSignal(SignalName.MySignal);
EmitSignal(SignalName.HealthChanged, newValue);

参数说明

参数类型必需说明
signalStringName是要触发的信号名称
...argsVariant（可变参数）否信号携带的参数。比如 HealthChanged 信号可以携带新的血量值

返回值

类型说明
Error (C#) / int (GDScript)返回 Error.Ok（值为 0）表示信号触发成功

代码示例

基础用法

最简单的用法——定义一个自定义信号并手动触发它：

C#
using Godot;

public partial class MyButton : Button
{
    // 声明一个自定义信号（无参数）
    [Signal]
    public delegate void ButtonClickedEventHandler();

    public override void _Ready()
    {
        // 先连接自己的信号
        ButtonClicked += OnButtonClicked;

        // 手动触发信号
        EmitSignal(SignalName.ButtonClicked);

        // 运行结果: 自定义按钮点击信号被触发了！
    }

    private void OnButtonClicked()
    {
        GD.Print("自定义按钮点击信号被触发了！");
    }
}

实际场景

在实际游戏开发中，emit_signal 最常用的场景是"数值变化通知"：当角色的血量、分数、等级等数据发生变化时，通过信号通知 UI 更新显示。下面是一个完整的血量系统示例：

C#
using Godot;

public partial class HealthSystem : Node
{
    // 声明带参数的自定义信号
    [Signal]
    public delegate void HealthChangedEventHandler(int newHealth, int maxHealth);

    [Signal]
    public delegate void PlayerDiedEventHandler();

    [Export] public int ExMaxHealth = 100;

    private int _currentHealth;

    public override void _Ready()
    {
        _currentHealth = ExMaxHealth;

        // 连接信号到 UI
        HealthChanged += OnHealthChanged;
        PlayerDied += OnPlayerDied;

        // 初始触发一次，更新 UI
        EmitSignal(SignalName.HealthChanged, _currentHealth, ExMaxHealth);

        GD.Print($"血量系统初始化完成，当前血量: {_currentHealth}/{ExMaxHealth}");
        // 运行结果: 血量系统初始化完成，当前血量: 100/100
    }

    public void TakeDamage(int damage)
    {
        _currentHealth -= damage;

        if (_currentHealth <= 0)
        {
            _currentHealth = 0;
            // 血量归零，触发死亡信号
            EmitSignal(SignalName.HealthChanged, 0, ExMaxHealth);
            EmitSignal(SignalName.PlayerDied);

            GD.Print("角色已死亡！");
            // 运行结果（收到致命伤害后）:
            // 血量变化: 0/100
            // 角色已死亡！
        }
        else
        {
            // 触发血量变化信号
            EmitSignal(SignalName.HealthChanged, _currentHealth, ExMaxHealth);

            GD.Print($"受到 {damage} 点伤害，剩余血量: {_currentHealth}/{ExMaxHealth}");
            // 运行结果（受到30点伤害后）:
            // 血量变化: 70/100
            // 受到 30 点伤害，剩余血量: 70/100
        }
    }

    private void OnHealthChanged(int newHealth, int maxHealth)
    {
        GD.Print($"血量变化: {newHealth}/{maxHealth}");
        // 运行结果: 血量变化: 70/100
    }

    private void OnPlayerDied()
    {
        GD.Print("游戏结束，显示复活界面");
        // 运行结果: 游戏结束，显示复活界面
    }
}

进阶用法

多个对象监听同一个信号、跨节点触发信号、以及使用 call_deferred 延迟触发：

C#
using Godot;

public partial class QuestSystem : Node
{
    // 自定义信号：任务完成，携带任务名和奖励金币数
    [Signal]
    public delegate void QuestCompletedEventHandler(string questName, int rewardGold);

    private int _totalGold = 0;

    public override void _Ready()
    {
        // 多个系统监听同一个信号
        QuestCompleted += OnQuestCompletedLog;
        QuestCompleted += OnQuestCompletedReward;
        QuestCompleted += OnQuestCompletedNotify;

        // 完成几个任务
        CompleteQuest("消灭史莱姆", 50);
        CompleteQuest("收集草药", 30);
        CompleteQuest("击败Boss", 200);

        GD.Print($"所有任务完成，总计获得金币: {_totalGold}");
        // 运行结果:
        // [日志] 任务完成: 消灭史莱姆，奖励 50 金币
        // [奖励] 获得 50 金币，总计: 50
        // [通知] 恭喜完成任务：消灭史莱姆！
        // [日志] 任务完成: 收集草药，奖励 30 金币
        // [奖励] 获得 30 金币，总计: 80
        // [通知] 恭喜完成任务：收集草药！
        // [日志] 任务完成: 击败Boss，奖励 200 金币
        // [奖励] 获得 200 金币，总计: 280
        // [通知] 恭喜完成任务：击败Boss！
        // 所有任务完成，总计获得金币: 280
    }

    public void CompleteQuest(string questName, int rewardGold)
    {
        // 触发信号，所有监听者都会收到通知
        EmitSignal(SignalName.QuestCompleted, questName, rewardGold);
    }

    private void OnQuestCompletedLog(string questName, int rewardGold)
    {
        GD.Print($"[日志] 任务完成: {questName}，奖励 {rewardGold} 金币");
    }

    private void OnQuestCompletedReward(string questName, int rewardGold)
    {
        _totalGold += rewardGold;
        GD.Print($"[奖励] 获得 {rewardGold} 金币，总计: {_totalGold}");
    }

    private void OnQuestCompletedNotify(string questName, int rewardGold)
    {
        GD.Print($"[通知] 恭喜完成任务：{questName}！");
    }
}

注意事项

  • 信号触发是同步的：emit_signal 调用后，所有连接的处理方法会立即依次执行，然后 emit_signal 才会返回。这意味着如果你的处理方法里写了耗时逻辑，会阻塞后续代码的执行。
  • 不检查是否有监听者：即使没有任何方法连接到这个信号，emit_signal 也不会报错，只是什么都不会发生。这就像对着空房间喊话——没人回应，但也不会出错。
  • 带参数的信号类型要匹配：如果你声明的信号带有参数（如 HealthChanged(int newHealth)），触发时传入的参数类型必须匹配。C# 中如果类型不匹配会编译报错，GDScript 中会在运行时报错。
  • C# 中用 SignalName 触发：在 C# 中，推荐使用 EmitSignal(SignalName.XXX) 的方式触发信号，而不是手动写字符串。SignalName 是 Godot 自动生成的常量，可以避免拼写错误。
  • Godot 内置信号无需手动触发：像 Button.Pressed、Timer.Timeout、Area2D.BodyEntered 这些内置信号由引擎自动触发，你不需要手动调用 emit_signal。只有自定义信号才需要手动触发。
  • C# 差异：C# 中方法名用 PascalCase（EmitSignal），GDScript 中用 snake_case（emit_signal）。
最近更新:
贡献者: zefeng.peng,bobokaka
EVOCOSMOS
Copyright © 2026 EVOCOSMOS