Skip to content

README.md

Latest commit

 

History

History
206 lines (144 loc) · 7.32 KB

README.md

File metadata and controls

206 lines (144 loc) · 7.32 KB
Raw

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:

Delegate Name Generated Property Name
IsDeadEventHandler IsDead
DeadEventHandler IsDead
IslandEventHandler IsIsland
IsIslandEventHandler IsIsland
IslandTimeEventHandler IsIslandTime
IsIslandTimeEventHandler IsIslandTime
IsNotNotarizedEventHandler IsNotarized
IsNoteInverselyInverseEventHandler IsNoteInversely

🔁 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:

Inverse Name Inferred Target Name
NotVisibleEventHandler VisibleEventHandler
InverseHiddenEventHandler HiddenEventHandler
IsNotNotarizedEventHandler IsNotarizedEventHandler ✅ no strip inside word
IsNoteInverselyInverseEventHandler IsNoteInverselyEventHandler ✅ no strip
IsInvisible InvisibleEventHandler ❗ no automatic mapping to IsVisible

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

✅ Supported Signal Signatures

Delegate Type Observable Type Emission
delegate void JumpEventHandler() Observable<Unit> EmitSignal("Jump")
delegate void DamageEventHandler(int) Observable<int> EmitSignal("Damage", dmg)
delegate void HitEventHandler(Vector3, Node) Observable<(Vector3, Node)> EmitSignal("Hit", ...)
delegate void IsDeadEventHandler(bool) IRxProp<bool> ([RxProperty]) EmitSignal("IsDead", value)
Attribute Observable Type Parameter Count
[RxProperty] IRxProp<T>,RxVar<T> 0 or 1 (e.g. or )
[RxObservable] Observable<int>, Subject<T> 5 (e.g. <T1,T2,T3,T4,T5>
[InverseSignal] N/A 1 bool
delegate void IsDeadEventHandler(bool) IRxProp<bool> ([RxProperty]) EmitSignal("IsDead", value)

Up to 5 parameters are supported.

🚨 Generator Diagnostics

ID Reason
SIGOBS001 Missing R3.Unit for zero-arg signals
SIGOBS002 Signal delegate has more than 5 parameters
SIGOBS003 Manual EmitSignal("X") bypasses observable
SIGOBS004 [InverseSignal] used with [RxProperty] or [RxObservable]
SIGOBS005 More than one [InverseSignal] targets a single signal
SIGOBS009 [RxProperty] and [RxObservable] used together
SIGOBS010 Could not resolve nameof(...) in [InverseSignal]
SIGOBS011 Malformed attribute body in generated code
SOEG0001 Generator is running (informational)

💡 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