一款快速、零分配的内存消息传递库。具有源生成器的声明式异步流程,适用于 Unity 和 .NET。
VitalRouter is a high-performance, zero-allocation in-memory messaging library for C#. It is specifically designed for environments where performance and decoupling are critical, such as Unity games or complex .NET applications.
By using simple attributes, you can implement asynchronous handlers, middleware (interceptors), and advanced sequence control. VitalRouter leverages Roslyn Source Generators to produce highly efficient code, promoting a clean, unidirectional control flow with minimal overhead.
Visit vitalrouter.hadashikick.jp for the full documentation.
[Routes] and [Route] to define handlers.VitalRouter follows a simple messaging flow. A Publisher sends a Command to a Router, which then dispatches it through optional Interceptors to one or more Handlers.
---
config:
theme: dark
---
graph LR
Publisher[Publisher] -- PublishAsync --> Router[Router]
subgraph Pipeline
Router -- next --> Interceptor1[Interceptor A]
Interceptor1 -- next --> Interceptor2[Interceptor B]
end
Interceptor2 -- Invoke --> Handler[Handler/Presenter]Commands are lightweight data structures representing events or actions.
// record structs are recommended for zero-allocation messaging
public readonly record struct MoveCommand(Vector3 Destination) : ICommand;[!TIP] AOT/HybridCLR Note: While
record structis valid, ensure your AOT metadata is correctly generated for iOS/AOT environments if using tools like HybridCLR.
Use the [Routes] attribute on a partial class to receive commands.
[Routes]
public partial class PlayerPresenter
{
// Use ValueTask for performance in pure .NET projects
[Route]
public async ValueTask On(MoveCommand cmd)
{
await MoveToAsync(cmd.Destination);
}
// Use UniTask for Unity-specific async handling
[Route]
public async UniTask On(SomeAsyncCommand cmd)
{
await DoSomethingAsync();
}
}Connect your handler to a router and start sending commands.
var router = new Router();
var presenter = new PlayerPresenter();
// MapTo returns a Subscription (IDisposable)
using var subscription = presenter.MapTo(router);
// Publish a message
await router.PublishAsync(new MoveCommand(new Vector3(1, 0, 0)));
You can also subscribe with lambdas instead of using the source generator.
…One of VitalRouter's standout features is declarative control over how concurrent async handlers run. This matters most in games, where dialogue, cutscenes, and tutorials must play in order — never overlapping.
Take a cutscene. You just publish commands, and VitalRouter plays them back-to-back:
…// Fire-and-forget. VitalRouter queues these and runs them strictly in order.
router.PublishAsync(new WalkCommand(stage.Center));
router.PublishAsync(new SpeakCommand("Hello there!"));
router.PublishAsync(new WaitCommand(0.5f));
router.PublishAsync(new SpeakCommand("Welcome to our little town."));Without ordering, all four handlers would start at the same time and the scene would be a mess. With Sequential, the character walks in, then speaks, then pauses, then speaks again — no manual coroutine chaining or hand-rolled state machine required.
Pick the strategy that fits each case:
| Ordering | Behavior | Typical use |
|---|---|---|
Parallel (default) |
Run all handlers concurrently | Independent reactions |
Sequential |
Queue, then run one at a time in order | Dialogue, cutscenes, tutorials |
Drop |
Ignore new commands while one is still running | Debounce buttons, prevent double-firing |
Switch |
Cancel the running handler, start the new one | "Latest wins" — re-targeting, search-as-you-type |
Ordering can be set globally, per Router, per [Routes] class, per [Route] method, or per SubscribeAwait call.
VitalRouter is highly optimized for Unity, especially when combined with UniTask.
When using MapTo in a MonoBehaviour, always bind the subscription to the object's lifecycle.
[Routes]
public partial class CharacterController : MonoBehaviour
{
private void Start()
{
// Bind the subscription to this GameObject's lifecycle
this.MapTo(Router.Default).AddTo(destroyCancellationToken);
}
[Route]
public void On(MoveCommand cmd)
{
transform.position = cmd.Destination;
}
}[!IMPORTANT] Assembly Definition (.asmdef): You must reference
VitalRouterin your.asmdeffile for the Source Generator to process your[Routes]attributes.
UniTask is a fast async/await library for Unity. VitalRouter actively supports UniTask. Requires: UniTask >= 2.5.5
[!TIP] If UniTask is installed, the
VITALROUTER_UNITASK_INTEGRATIONflag is defined automatically, enabling optimized GC-free code paths.
[!NOTE] Since version 2.0, Unity distribution has moved to NuGet.
VitalRouter packages in the NuGet window.Optional Extensions for Unity
Install the following package to use Unity-specific features, including integration with VContainer/UniTask.
https://github.com/hadashiA/VitalRouter.git?path=/src/VitalRouter.Unity/Assets/VitalRouter#2.8.0You can pipeline async interceptors for published messages. This is a powerful general-purpose pattern for message processing.
R3 is a next-generation Reactive Extensions implementation for C#. VitalRouter integrates with R3.
Control command publishing via external MRuby scripts. MRuby fibers and C# async/await are fully integrated.
Publishing allocates zero extra heap memory; if ICommand is a struct, no boxing occurs.
Performance is on the same level as plain event dispatching, so it can be used for very granular messaging in games.
Below are simple Publish benchmarks (8 subscribers per message; BenchmarkDotNet v0.14.0, .NET 9.0.5, Apple M4).
Asynchronous subscribers (awaiting until all subscribers complete):
| Method | Mean | Allocated |
|---|---|---|
| 'Publish (ZeroMessenger)' | 26.63 ns | - |
| 'Publish (VitalRouter)' | 27.01 ns | - |
| 'Publish (MessagePipe)' | 36.06 ns | 40 B |
| 'Publish (MediatR)' | 39.70 ns | 64 B |
| 'Publish (PubSub)' | 102.57 ns | 192 B |
Based on large-scale production usage (e.g., HybridFrame):
record struct provides equality comparison and zero-allocation benefits..AddTo(destroyCancellationToken) or manual Dispose() to avoid memory leaks and ghost event handling.UniTask or UniTaskVoid as return types in Unity handlers to leverage optimized pooling. Use ValueTask for pure .NET projects.PublishContext for cross-cutting concerns (logging IDs, cancellation tokens, user permissions) instead of adding those fields to your command structs.CommandOrdering.Sequential for UI animations or dialogue sequences to prevent race conditions.MIT
@hadashiA
暂无开放 Issues,或尚未同步最近议题。