LokiCat.Godot.R3.ObservableSignals 1.0.70

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, [RxProperty] bindings, [InverseSignal] auto-generation, and full Godot editor compatibility.

✨ What It Does

This generator lets you define signals with [Signal] in combination with [RxObservable] or [RxProperty]:

[Signal]
[RxObservable]
public delegate void JumpEventHandler();

💥 And automatically provides:

• ✅ A backing Subject<T> or RxVar<T>
• ✅ A public observable or reactive property (OnJump, IsDead, etc.)
• ✅ Lazy .Subscribe(...) wiring that calls EmitSignal(...) automatically

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

🚀 Quick Start

✅ Define a signal:

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

✅ Emit it:

_onDamageTaken.OnNext(42);

✅ Observe it:

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

🚫 [Signal] alone will not generate code. You must pair it with [RxObservable] or [RxProperty].

🔄 RxProperty Support

Use [RxProperty] to generate a reactive IRxProp<T> that syncs with a signal:

[Signal]
[RxProperty]
public delegate void IsDeadEventHandler(bool isDead);

Generates:

public IRxProp<bool> IsDead => _isDead;
private RxVar<bool> _isDead = new RxVar<bool>(false);
/* And wiring to the Godot signal */

🧠 Naming Rules

The generated property name:

• Always starts with Is
• Removes a leading Is only if it's a full word prefix (i.e. Is followed by an uppercase letter)
• Does not remove Is from words like Island, Isotope, etc.
• Strips the EventHandler suffix

Examples:

🔁 Inverse Signal Support

Generate inverse signals from a single source:

🗒️ Godot does not support easy transformation of signals. This generator allows you to define a signal and automatically generate its inverse.

💡 TODO: Add more robust signal transformation support via [SignalTransform(<TBD Syntax>)] attribute.

[Signal]
[RxObservable]
public delegate void VisibleEventHandler(bool value);

// inferred from name
[Signal]
[InverseSignal]
public delegate void NotVisibleEventHandler(bool value);

// explicit source:
[Signal]
[InverseSignal(nameof(IsVisibleEventHandler))]
public delegate void HiddenEventHandler(bool value);

✅ Emits EmitSignal("Hidden", !value) when OnIsVisible is triggered. 🚫 Only valid for bool signals 🚫 Cannot be used with [RxProperty]

🔍 Inferred Naming Behavior

When no nameof(...) is used, the generator infers the target by removing the words Not or Inverse only when they are complete words — using word-boundary-aware matching. It does not remove them when embedded in words:

For symmetric relationships (e.g. IsVisible/IsInvisible), use [InverseSignal(nameof(...))] explicitly.

✅ Supported Signal Signatures

Up to 5 parameters are supported.

🚨 Generator Diagnostics

💡 Best Practices

• ✅ Use _onX.OnNext(...) to emit signals
• ✅ Subscribe using OnX.Subscribe(...)
• ⚠️ Do not call EmitSignal(...) manually — it will not notify observers
• 🧠 Prefer [RxProperty] for stateful values
• 🔁 Use [InverseSignal] for UI toggles, state flips, or binding inverses

📦 Installation

dotnet add package LokiCat.Godot.R3.ObservableSignals

Also define:

namespace R3 {
  public readonly struct Unit {} // required for 0-arg signals
}

📜 License

MIT License