用途:在 Godot 4.x 中用 C# 实现信号(signals)与事件驱动架构,仅限 C#,通用 C# 约定与项目搭建见 csharp-godot 技能。
主要能力:用 [Signal] 声明 public delegate void,委托名必须以 EventHandler 结尾(否则报 GD0201),Godot 会去掉后缀作为引擎信号名;参数须为 Godot 可编组类型(int、float、bool、string、Vector2/3、Color、GodotObject 子类、GodotDictionary、GodotArray),不支持普通 C# 类、结构体与泛型。用 EmitSignal(SignalName.X, args...) 发射,SignalName 常量由源生成器生成,调试构建会校验参数数量与类型。用 += / -= 连接与断开,也可用 lambda(需断开时存入字段)。用 await ToSignal(node, SignalName.X) 等待信号,可配合 Task.WhenAny 或 CancellationTokenSource 设超时。还涵盖自定义信号模式(类型化事件参数、静态事件总线、泛型辅助)、从 C# 连接 GDScript 信号(node.Connect("signal_name", new Callable(this, MethodName.Handler)))。
使用方式:在 _Ready()(或可反复进出树的节点用 _EnterTree())中连接,不要在构造函数或字段初始化器中连接。
限制与注意:接收方被释放而发射方仍存活时,自定义 [Signal] 的 += 与捕获变量的 lambda 不会被自动清理,需在 _ExitTree() 中手动 -=,否则下次发射抛 ObjectDisposedException;内置信号加方法处理器会自动清理。避免重复连接、参数不匹配、连接已释放对象(用 IsInstanceValid 防护)、在 _Ready() 中过早 await。GDScript 需接收的信号必须用 Godot [Signal],静态 C# 事件仅用于纯 C# 通信。