LokiCat.Godot.R3.ObservableSignals 1.0.15

LokiCat.Godot.R3.ObservableSignals

R3-compatible source generator for turning [RxSignal]-annotated observables in Godot C# into fully reactive Godot signals and cached Observable<T> properties.

This package eliminates boilerplate when exposing Godot signals through R3 observables.
It generates real [Signal] Godot events, connects them to your observable streams, and automatically emits signals when your code pushes data.

✨ Features

• Automatically detects [RxSignal]-annotated observable fields (e.g., Subject<T>) in Godot C# partial classes
• Generates matching [Signal] Godot delegate declarations automatically
• Generates a ConnectGodotSignals() method for wiring Observables to Godot signals
• Supports 0 to 5 parameters in emitted signals
• No runtime Connect needed for custom signals
• Full R3 compatibility for reactive pipelines and disposal
• Clean, manual control over when signals are fired via .OnNext()
• Fully supports Godot Editor and visual signal connections
• Supports Subject<T>, ReplaySubject<T>, BehaviorSubject<T>, ReactiveProperty<T>, and any other Observable<T>-derived types
• Still includes dynamic .Signal(...) extension methods for wrapping built-in Godot signals (e.g., Button.Pressed, Area2D.BodyEntered)

👍 Why This is Useful

Before, exposing Godot signals in a reactive way required manual wiring, manual Connect(...) calls, and custom observable creation:

Old Way (Manual)

[Signal]
public delegate void PressedEventHandler(BaseButton button);

private Observable<BaseButton> _onPressed;
public Observable<BaseButton> OnPressed => _onPressed ??= Observable.Create<BaseButton>(observer => {
    var callable = Callable.From((BaseButton button) => observer.OnNext(button));
    Connect(nameof(Pressed), callable);
    return Disposable.Empty;
});

New Way (With This Package)

[RxSignal]
private readonly Subject<BaseButton> _onButtonPressed = new();

public Observable<BaseButton> OnButtonPressed => _onButtonPressed;

public override void _Ready()
{
    ConnectGodotSignals();
}

public void PressButton(BaseButton button)
{
    _onButtonPressed.OnNext(button);
}

✅ Much less code. ✅ No manual Connect() needed for custom signals. ✅ Full control when you fire signals with .OnNext(). ✅ Safer, reactive, and easier to test. ✅ Dynamic wrapping still available for built-in signals if needed.

📦 Installation

1. Add this NuGet package to your project:

dotnet add package LokiCat.Godot.R3.ObservableSignals

2. Define your interfaces and classes:

Interface

public partial interface IPauseMenu
{
    Observable<Unit> OnMainMenuSelected { get; }
}

Class Implementation

public partial class PauseMenu : Control, IPauseMenu
{
    [RxSignal]
    private readonly Subject<Unit> _onMainMenuSelected = new();

    public Observable<Unit> OnMainMenuSelected => _onMainMenuSelected;

    public override void _Ready()
    {
        ConnectGodotSignals();
    }

    public void SelectMainMenu()
    {
        _onMainMenuSelected.OnNext(Unit.Default);
    }
}

✅ That's it. No manual Connect, no manual EmitSignal needed for your own signals.

✅ Supported Signal Forms

Signals with more than 5 parameters are not supported and will trigger a generator warning.

Supported Field Types

You can annotate fields of type:

• Subject<T>
• ReplaySubject<T>
• BehaviorSubject<T>
• ReactiveProperty<T>
• Any custom type inheriting Observable<T> that supports emitting values

🛠 Using Both Systems Together

• Use [RxSignal] and ConnectGodotSignals() for your own custom signals.
• Use .Signal(this Node node, string signalName, ref cache) extension methods for wrapping built-in Godot signals you cannot modify (e.g., Button.Pressed, Area2D.BodyEntered).

✅ Both systems can coexist cleanly. ✅ No conflicts.

🧠 How It Works

• You define [RxSignal] observable fields (Subject<T>, ReplaySubject<T>, etc.)
• You expose public Observable<T> properties
• The generator emits:
  • A [Signal] Godot delegate for each signal
  • A ConnectGodotSignals() method that wires the Observables to EmitSignal calls
• When you call .OnNext(), it automatically fires the Godot signal and notifies any R3 subscribers.

🛠 Example: Full Class

public partial class ButtonGroup : Control
{
    [RxSignal]
    private readonly Subject<BaseButton> _onButtonPressed = new();

    public Observable<BaseButton> OnButtonPressed => _onButtonPressed;

    public override void _Ready()
    {
        ConnectGodotSignals();
    }

    public void PressButton(BaseButton button)
    {
        _onButtonPressed.OnNext(button);
    }
}

⬇️ The generator automatically emits:

[Signal]
public delegate void ButtonPressedEventHandler();

private void ConnectGodotSignals()
{
    OnButtonPressed.Subscribe(button => EmitSignal(nameof(ButtonPressed), button)).AddTo(this);
}

🧪 Troubleshooting

• Make sure your classes are marked partial
• Annotate observable fields with [RxSignal]
• Expose observables with public Observable<T> properties
• Call ConnectGodotSignals() in _Ready()
• Use #nullable enable if you are using nullable types in your fields or properties

📄 License

MIT License

💡 Bonus Tip

Pair this generator with Chickensoft, R3, Godot, and other LokiCat Godot/.NET packages to create fully reactive, signal-driven gameplay systems that are easy to extend, test, and maintain.