Bravasoft.Herald 0.1.2

Herald

A multi-event observer pattern for C# implemented via Roslyn source generation. Herald sits between C# events (one field per event) and Rx observables (one object per event): you define an interface grouping related events, annotate a partial class, and Herald generates a thread-safe fan-out notifier with IDisposable subscriptions.

Quick Start

Install the package:

dotnet add package Bravasoft.Herald

Define an event interface and annotate a partial class:

using Bravasoft.Herald;

public interface IPlayerEvents
{
    void OnDied(string playerName);
    void OnScored(int points, string reason);
}

[Notifier(typeof(IPlayerEvents))]
public partial class PlayerNotifier { }

Herald generates the implementation at compile time. Use it:

// Create the notifier (e.g. register in your DI container)
var notifier = new PlayerNotifier();

// Subscribe — returns IDisposable for automatic unsubscription
using var subscription = notifier.Add(myListener); // myListener implements IPlayerEvents

// Fire events (fan-out to all listeners)
notifier.OnScored(100, "headshot");

// Or unsubscribe manually
notifier.Remove(myListener);

Listeners implement the event interface:

public class HUDController : IPlayerEvents
{
    public void OnDied(string playerName) => ShowDeathScreen(playerName);
    public void OnScored(int points, string reason) => UpdateScore(points);
}

Generated Code

For the IPlayerEvents example above, Herald generates roughly:

public partial class PlayerNotifier : IPlayerEvents, INotifier<IPlayerEvents>
{
    private struct UnregisterDisposable : IDisposable
    {
        public INotifier<IPlayerEvents> Notifier;
        public IPlayerEvents Delegate;
        public void Dispose() => Notifier?.Remove(Delegate);
    }

    private readonly List<IPlayerEvents> _delegates = new List<IPlayerEvents>();

    public IDisposable Add(IPlayerEvents d)
    {
        lock (_delegates)
        {
            _delegates.Add(d);
            return new UnregisterDisposable { Notifier = this, Delegate = d };
        }
    }

    public void Remove(IPlayerEvents d)
    {
        lock (_delegates) { _delegates.Remove(d); }
    }

    public void OnDied(string playerName)
    {
        var delegates = _delegates.ToArray();
        foreach (var d in delegates)
            d.OnDied(playerName);
    }

    public void OnScored(int points, string reason)
    {
        var delegates = _delegates.ToArray();
        foreach (var d in delegates)
            d.OnScored(points, reason);
    }
}

Diagnostics

Unity Setup

Herald supports Unity 2022.3 LTS and newer (Roslyn 4.3+).

1. Download Bravasoft.Herald.<version>.nupkg and Bravasoft.Herald.SourceGenerator.<version>.nupkg from NuGet.
2. Extract each .nupkg (rename to .zip).
3. Copy Herald.dll (from lib/netstandard2.0/) into your Unity project's Assets/Plugins/ folder.
4. Copy Herald.SourceGenerator.dll (from analyzers/dotnet/cs/) into Assets/Plugins/ and set its Select platforms for plugin to Editor only, then enable RoslynAnalyzer in the inspector.

Alternatively, use NuGetForUnity to install both packages directly from the Unity Package Manager.

License

MIT — see LICENSE.