messagepipe
MessagePipe pub/sub for Unity — readonly struct messages, broker registration in the LifetimeScope, IPublisher/ISubscriber injection, disposal discipline, buffered and async variants. The only permitt
SKILL.md.claude/skills/messagepipe/SKILL.md
GitHubMessagePipe — Zero-Allocation Pub/Sub
MessagePipe (Cysharp) is the only messaging system permitted here
(.claude/rules/architecture.md). No ScriptableObject event channels, no static
EventBus, no C# events for cross-system communication.
It is a DI-first library: publishers and subscribers are resolved from the container,
never constructed. That is what makes a System testable — a stub IPublisher<T> is
four lines.
Messages are readonly structs
namespace PoFootball.Systems
{
/// <summary>
/// Published when a defender brings the carrier down. Carries the closing speed
/// that satisfied the threshold so presentation can scale the impact and
/// telemetry can histogram hit strength.
/// </summary>
public readonly struct Systems_TackleMessage
{
public readonly int TacklerId;
public readonly int CarrierId;
public readonly float ClosingSpeed;
public Systems_TackleMessage(int tacklerId, int carrierId, float closingSpeed)
{
TacklerId = tacklerId;
CarrierId = carrierId;
ClosingSpeed = closingSpeed;
}
}
}
readonly struct— zero allocation on publish, and no subscriber can mutate what the next subscriber sees.- Carry ids and values, not references. A message holding a
GameObjectoutlives the frame in a buffered broker and hands subscribers a destroyed object. - Carry what a consumer would otherwise have to recompute.
ClosingSpeedis already known at the publish site; making a subscriber re-derive it duplicates the rule. - One message type per file, named
*Message.
Every broker must be registered
An unregistered message type throws at resolution, not at publish — you get a container error on scene load, which is the good case. Register in the LifetimeScope alongside everything else:
protected override void Configure(IContainerBuilder builder)
{
builder.Register<Systems_PlayModel>(Lifetime.Singleton);
builder.RegisterEntryPoint<Systems_Referee>().AsSelf();
MessagePipeOptions messagePipeOptions = builder.RegisterMessagePipe();
builder.RegisterMessageBroker<Systems_PlaySnappedMessage>(messagePipeOptions);
builder.RegisterMessageBroker<Systems_PlayEndedMessage>(messagePipeOptions);
builder.RegisterMessageBroker<Systems_TackleMessage>(messagePipeOptions);
builder.RegisterMessageBroker<Systems_ScoreMessage>(messagePipeOptions);
}
RegisterMessagePipe() is called once per scope and returns the options every
RegisterMessageBroker<T> call needs. Requires the
com.cysharp.messagepipe.vcontainer package, and the assembly must reference both
MessagePipe and MessagePipe.VContainer.
Publishing
Inject IPublisher<T> — never a concrete broker.
public sealed class Systems_Referee : IFixedTickable
{
private readonly IPublisher<Systems_TackleMessage> _tacklePublisher;
public Systems_Referee(IPublisher<Systems_TackleMessage> tacklePublisher)
{
_tacklePublisher = tacklePublisher;
}
private void EndPlay(int tacklerId, int carrierId, float closingSpeed)
{
_tacklePublisher.Publish(new Systems_TackleMessage(tacklerId, carrierId, closingSpeed));
}
}
Publish is synchronous and re-entrant: every subscriber runs to completion inside
the Publish call, on the caller's stack. Two consequences worth internalizing:
- A subscriber that publishes back into the same broker recurses. Guard with a state flag on the model, not with a queue.
- Publishing from
FixedUpdatemeans subscribers run in the physics loop. Keep them cheap, or hand off with [[unitask]].
Subscribing
Subscribe once, in Start — not in the constructor. A constructor that subscribes
can be reached by a publish before the rest of the object graph is built.
public sealed class Systems_Telemetry : IStartable, IDisposable
{
private readonly ISubscriber<Systems_PlayEndedMessage> _endedSubscriber;
private IDisposable _subscription;
public Systems_Telemetry(ISubscriber<Systems_PlayEndedMessage> endedSubscriber)
{
_endedSubscriber = endedSubscriber;
}
public void Start()
{
_subscription = _endedSubscriber.Subscribe(OnPlayEnded);
}
private void OnPlayEnded(Systems_PlayEndedMessage message) { /* ... */ }
public void Dispose()
{
_subscription?.Dispose();
}
}
Disposal is not optional
Subscribe returns an IDisposable. Dropping it leaks the handler, and the handler
holds the subscriber alive — across scene loads, and across domain reloads in the
Editor. The symptom is a callback firing N times after N play-mode entries.
| Consumer | Pattern |
|---|---|
| System (plain C#) | Implement IDisposable, dispose in Dispose(). VContainer calls it when the scope dies. |
| View (MonoBehaviour) | CompositeDisposable, .AddTo(_disposables), dispose in OnDestroy. |
| Many subscriptions | DisposableBag.CreateBuilder() → builder.Build(). |
public sealed class Systems_ScoreView : MonoBehaviour, Systems_IInjectableView
{
private readonly CompositeDisposable _disposables = new();
[Inject]
public void Construct(ISubscriber<Systems_ScoreMessage> scoreSubscriber)
{
scoreSubscriber.Subscribe(OnScored).AddTo(_disposables);
}
private void OnDestroy() => _disposables.Dispose();
}
Variants
| Interface | Use when |
|---|---|
IPublisher<T> / ISubscriber<T> |
The default. Keyless, synchronous. |
IBufferedPublisher<T> / IBufferedSubscriber<T> |
Late subscribers need the last value — a HUD spawned mid-play needs the current score, not the next change. |
IAsyncPublisher<T> / IAsyncSubscriber<T> |
Handlers do async work. Pair with UniTask and pass a CancellationToken. |
IPublisher<TKey, TMessage> |
Per-entity routing, e.g. keyed by player id. Prefer one message with an id field until routing cost is measured. |
Filters
Filters wrap handlers — logging, dedup, rate-limiting — without touching either side:
builder.RegisterMessageBroker<Systems_TackleMessage>(messagePipeOptions);
messagePipeOptions.AddGlobalMessageHandlerFilter(typeof(LoggingFilter<>));
Use sparingly. A filter that changes whether a message is delivered is game logic hidden one level below where anyone will look for it.
Testing
Because Systems depend on IPublisher<T>, not a broker, a stub is trivial — no
container, no Unity, EditMode-runnable:
private sealed class StubPublisher<T> : IPublisher<T>
{
public int Count { get; private set; }
public T Last { get; private set; }
public void Publish(T message)
{
Count++;
Last = message;
}
}
[Test]
public void SustainedContact_EndsThePlay()
{
var ended = new StubPublisher<Systems_PlayEndedMessage>();
var referee = new Systems_Referee(/* ... */ ended);
// ...
Assert.That(ended.Count, Is.EqualTo(1));
Assert.That(ended.Last.Outcome, Is.EqualTo(Systems_PlayOutcome.Tackle));
}
If a System is hard to test this way, it is usually reaching for something it did not declare — which is the design feedback, not a reason to add a container to the test.
Rules
- Messages are
readonly struct, one per file, named*Message - Every message type gets a
RegisterMessageBroker<T>call — no exceptions - Inject
IPublisher<T>/ISubscriber<T>; never resolve a broker directly - Every
Subscriberesult is disposed - Subscribe in
Start/Construct, not in a constructor - Systems publish; Views subscribe. A View that publishes is doing logic
- Cross-system communication goes through MessagePipe, never a direct reference
Related
- [[vcontainer]] — the container that owns broker registration and disposal
- [[unitask]] — for async handlers and for offloading work out of a publish
- [[event-systems]] — why the alternatives (SO channels, static EventBus) are not used