LokiCat.Godot.R3.ObservableSignals 1.0.37

LokiCat.Godot.R3.ObservableSignals

A source generator that turns [Signal]-annotated delegates into fully reactive R3 Observable<T> properties.
Supports zero to five signal arguments, automatic EmitSignal(...) wiring, and full Godot editor compatibility.

✨ What It Does

This generator lets you define a signal once using Godot's [Signal] attribute:

[Signal]
public delegate void JumpEventHandler();

💥 And automatically provides:

• ✅ A backing Subject<T> (_onJump)
• ✅ A public observable property (OnJump)
• ✅ A lazy .Subscribe(...) that calls EmitSignal(...) with proper arguments

No need to write Connect(), EmitSignal(), or observable plumbing by hand.

🚀 Quick Start

✅ Define your signal:

[Signal]
public delegate void DamageTakenEventHandler(int amount);

✅ Emit it in your code:

_onDamageTaken.OnNext(42);

✅ Observe it reactively:

OnDamageTaken.Subscribe(amount => GD.Print($"Took {amount} damage!"));

✅ The Godot editor will show a DamageTaken signal.
✅ R3 observers will get updates when the signal fires.

🧠 How It Works

For this:

[Signal]
public delegate void HitEventHandler(Vector3 point, Node target);

The generator emits:

private readonly Subject<(Vector3, Node)> _onHit = new();
private bool _hitConnected;

public Observable<(Vector3, Node)> OnHit {
  get {
    if (!_hitConnected) {
      _hitConnected = true;
      _onHit.Subscribe(value =>
        EmitSignal(nameof(Hit), value.Item1, value.Item2)
      ).AddTo(this);
    }
    return _onHit;
  }
}

✅ One subject powers both EmitSignal(...) and the reactive pipeline.

📦 Installation

dotnet add package LokiCat.Godot.R3.ObservableSignals

Make sure your consumer project defines:

public readonly struct Unit {} // in namespace R3

(Only needed for 0-arg signals.)

✅ Supported Signal Signatures

Up to 5 arguments supported. More than 5 triggers a warning.

🚨 Generator Warnings

⚡ Best Practices

• Declare signals once with [Signal]
• Emit signals using _onX.OnNext(...) — not EmitSignal(...)
• Observe using OnX.Subscribe(...)
• Use .Where, .Throttle, .TakeUntil(...) for filtered pipelines
• Expose Observable<T>s in interfaces to keep logic clean

💡 Advanced

If you manually call EmitSignal(...), observers on OnX will not receive anything.
Only _onX.OnNext(...) propagates to both EmitSignal(...) and the observable.

📜 License

MIT License