VitalRouter Documentation

VitalRouter.MRuby is an extension that allows you to use Ruby scripting to control the publishing of commands within VitalRouter. This is particularly useful for implementing game scenarios, branching logic, or complex state management using a Domain Specific Language (DSL) that is more readable than C# code.

Key benefits include:

• Natural Language DSLs: Ruby's syntax allows for creating highly readable scripts.
• Non-blocking Async/Await: While C# handlers are executing async/await, the mruby side suspends and waits using mruby's Fiber without blocking the main thread. This makes it compatible with single-threaded environments like Unity WebGL.
• Platform Support: Starting with version 2, the extension uses ChibiRuby (a pure C# implementation), meaning it runs on any platform where C# is supported.

VitalRouter supports several DI libraries to manage object lifecycles, dependencies, and state (such as Subscribe/Unsubscribe). Using DI allows for automatic Interceptor dependency resolution.

Supported libraries include:

• Unity:
  • VContainer
• .NET:
  • Microsoft.Extensions.DependencyInjection

VitalRouter supports VContainer's hierarchical scope system:

• Inheritance (Default): By default, a RegisterVitalRouter call in a child scope inherits the Router defined in the parent scope. If a parent publishes via ICommandPublisher, both parent and child presenters receive the command. If a child publishes, both parent and child presenters receive it.
• Isolation: If you want a child scope to have its own dedicated Router that does not share commands with the parent, set routing.Isolated = true during registration.

Use routing.Isolated = true when you want to prevent child scope commands from leaking to the parent or vice versa.

// In a ChildLifetimeScope
builder.RegisterVitalRouter(routing =>  
{
    // Creates a dedicated Router for this scope only
    routing.Isolated = true;
    routing.Map<PresenterB>();  
});

When UniTask integration is enabled via the VITALROUTER_UNITASK_INTEGRATION compiler switch, VitalRouter applies the following optimization:

• Locking Mechanism: Instead of the default SemaphoreSlim used for locking async methods, the framework selects IUniTaskSource-based implementations to improve performance in UniTask-heavy environments.

The [Filter] attribute allows you to insert processing logic (similar to middleware or interceptors) before and after a command is delivered to a handler.

Filters can be applied at two levels:

1. Class-wide: Applied to the class declaration, affecting all routes within that class.
2. Method-level: Applied to a specific [Route] method, affecting only that handler.

[Routes]
[Filter(typeof(Filter1))] // Class-wide filter
public partial class FooPresenter
{
    [Route]
    [Filter(typeof(Filter2))] // Method-specific filter
    async ValueTask On(FooCommand cmd)
    {
        // ...
    }
}

VitalRouter is designed for high-performance messaging, comparable to plain event dispatching. To achieve zero extra heap memory allocation during publishing, ensure that your commands implement ICommand as a struct. This prevents boxing when the command is passed to the router. This makes it suitable for granular messaging in performance-critical environments like games.

// Using a struct for ICommand ensures zero-allocation publishing
public record struct MyCommand(int Id) : ICommand;

VitalRouter follows a unidirectional messaging flow designed for high performance and zero allocation. The flow consists of three main stages:

1. Publisher: Sends a Command (a lightweight data structure) to a Router using PublishAsync.
2. Pipeline (Interceptors): The Router passes the command through an optional chain of Interceptors (middleware) that can process, filter, or modify the flow.
3. Handler (Presenter): The command is finally dispatched to one or more Handlers that implement the logic for that specific command.

Commands should ideally be defined as readonly record struct to ensure zero-allocation messaging.

// 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;

By default, VitalRouter delivers the next command immediately, even if a previous asynchronous command handler has not yet completed. To change this behavior and ensure commands are processed one after another, use the CommandOrdering parameter in the [Routes] attribute.

Use CommandOrdering.Sequential to hold off the delivery of the next command until the current [Route] method has completed. This is useful for managing sequences or conversations in game logic.

[Routes(CommandOrdering.Sequential)]
public partial class FooPresenter
{
    async ValueTask On(FooCommand cmd)
    {
        // The next command will wait for this to finish
    }
}