Azkar Industries

Priority events

AzPriorityEvent

Use no-payload priority events for ordered phases.

  • No payload
  • Priority slots
  • Mental model
  • Phases

Use AzPriorityEvent for no-payload ordered phases.

What AzPriorityEvent Is

AzPriorityEvent is the priority-slot event backend. It behaves like an event bus, but every subscription goes into one of 9 ordered priority slots.

Slot 1 runs first. Slot 9 runs last. Slot 5 is the default.

The core types are:

AzPriorityEvent

Use it when

The event has no payload.

Handler shape
Action
Invoke shape
Invoke()

AzPriorityEvent<T>

Use it when

The event has a small or cheap-to-copy payload.

Handler shape
Action<T>
Invoke shape
Invoke(value)

AzPriorityEventRef<T>

Use it when

The event has a large struct payload and you want readonly-ref passing.

Handler shape

AzRefHandler<T> / void Handler(in T value)

Invoke shape
Invoke(in value)

Every normal Subscribe call returns an AzEventToken. Priority tokens use the same token type as AzEvent, so AzEventTokenBag, .AddTo(...), Pause(), Resume(), and Dispose() all work the same way.

using Azkar.Eda;
using UnityEngine;

public static class CombatPriorityEvents
{
    public static readonly AzPriorityEvent CombatTick = new();
    public static readonly AzPriorityEvent<int> HealthChanged = new();
    public static readonly AzPriorityEventRef<DamageReport> DamageReported = new();
}

public readonly struct DamageReport
{
    public readonly int Amount;
    public readonly Vector3 Point;

    public DamageReport(int amount, Vector3 point)
    {
        Amount = amount;
        Point = point;
    }
}

The Mental Model

An AzPriorityEvent is not one flat ordered list. It is 9 slot lists.

When you invoke the event, it visits the slots in order:

slot 1, slot 2, slot 3, slot 4, slot 5, slot 6, slot 7, slot 8, slot 9

That means you can separate broad phases of work:

1..3

critical or early systems

4..6

normal gameplay

7..9

UI, analytics, late observers

These meanings are conventions, not hard rules. The only hard rule is execution order: lower slot number runs earlier.

CombatPriorityEvents.CombatTick.Subscribe(ValidateState, slot: 1);
CombatPriorityEvents.CombatTick.Subscribe(ApplyGameplay, slot: 5);
CombatPriorityEvents.CombatTick.Subscribe(UpdateHud, slot: 9);

CombatPriorityEvents.CombatTick.Invoke();

Invocation order:

ValidateState
ApplyGameplay
UpdateHud

Use a lower slot when something must run earlier than another category of work. Use a higher slot when something should observe results after core logic has run.

Use AzPriorityEvent for No-Payload Phases

public static readonly AzPriorityEvent RoundAdvanced = new();

private readonly AzEventTokenBag _subscriptions = new();

private void OnEnable()
{
    GameBus.RoundAdvanced.Subscribe(OnRoundAdvanced, slot: 5).AddTo(_subscriptions);
}

private void OnDisable()
{
    _subscriptions.DisposeAll();
}

private void OnRoundAdvanced()
{
}