Azkar EDA

Documentation

Azkar EDA is a Unity event, state, priority dispatch, lifecycle token, and editor tracking toolkit for event-driven architecture workflows.

Manual map
Primitive chooser
Core lifecycle pattern
Where to go next

Azkar EDA is a Unity event, state, priority dispatch, lifecycle token, and editor tracking toolkit. It is built around a small set of primitives:

Use an event for a discrete signal.
Use state for a value with current meaning.
Use a token as one subscription handle.
Use a bag to own tokens for a Unity lifecycle.
Use tracking for editor observability while you debug.

This documentation set is the new-user manual. The deep API guides are linked from the pages below.

Start Here

Getting Started - import assumptions, first event, first state, cleanup, and first tracking pass.
Choosing The Right Primitive - decide between AzEvent, AzPriorityEvent, AzState, tokens, and tracking.
Events, Tokens, And Token Bags - deep guide for AzEvent, payload events, ref payload events, tokens, and token bags.
Priority Events - deep guide for ordered priority dispatch and priority-specific token behavior.
State - deep guide for AzState<T>, SourceSet, binding, validation, and advanced state helpers.
Tracking And Debugging - annotate systems, open the tracking window, inspect live connections, and troubleshoot missing data.
Performance And Threading - hot-path guidance, Invoke variants, scheduling, threading, and token lifecycle costs.
Samples And Tutorials - walk through sample scenes and performance examples.
Migration Guide - migrate from C# events, ordered phase code, property-change events, and manual cleanup.
FAQ - common issues and direct answers.

Which Primitive Should I Use?

Publish a discrete event

Use: AzEvent or AzEvent<T>
Why: Simple discrete event dispatch with token-based cleanup.

Send a large struct without copying it to every listener

Use: AzEventRef<T>
Why: Delivers the payload by ref readonly, where T is a struct.

Run listeners in explicit order

Use: AzPriorityEvent, AzPriorityEvent<T>, or AzPriorityEventRef<T>
Why: Each subscription has a priority slot, so phases can be deterministic.

Keep a meaningful current value

Use: AzState<T>
Why: Subscribers can receive the current value and later changes.

Clean up one subscription

Use: AzEventToken
Why: The token is the lifecycle handle for a single subscription.

Clean up many subscriptions together

Use: AzEventTokenBag
Why: The bag owns a group of tokens and disposes them together.

See buses, handlers, publishers, and states in the editor

Use: Tracking
Why: Authored attributes and runtime registration feed the tracking window.

The Core Pattern

Most Unity usage follows the same shape:

using UnityEngine;
using Azkar.Eda;

public sealed class HealthView : MonoBehaviour
{
    private readonly AzEventTokenBag _tokens = new();

    private void OnEnable()
    {
        HealthEvents.PlayerDamaged.Subscribe(OnPlayerDamaged).AddTo(_tokens);
    }

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

    private void OnPlayerDamaged(int damage)
    {
        Debug.Log($"Player took {damage} damage.");
    }
}

Subscribe, keep the token, then dispose it from the Unity lifecycle that owns the listener. That one rule prevents most duplicate callback, destroyed-object callback, and scene-unload bugs.

Manual Map

Getting Started: A first working setup.
Choosing The Right Primitive: Design decisions before writing code.
Tracking And Debugging: Editor observability and troubleshooting.
Samples And Tutorials: Learning from sample scenes and demos.
Performance And Threading: Hot paths, queues, token costs, and threading rules.
Migration Guide: Moving existing Unity code into Azkar EDA patterns.
FAQ: Direct answers for common setup and lifecycle issues.
Events, Tokens, And Token Bags: Full event and token guide.
Priority Events: Full priority event guide.
State: Full state guide.