Documentation

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 happening.
• 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

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

Which Thing Should I Use?

| Need | Use | Why | | --- | --- | --- | | Tell listeners that something happened | AzEvent or AzEvent<T> | Simple discrete event dispatch with token-based cleanup. | | Send a large struct without copying it to every listener | AzEventRef<T> | Delivers the payload by ref readonly, where T is a struct. | | Run listeners in explicit order | AzPriorityEvent, AzPriorityEvent<T>, or AzPriorityEventRef<T> | Each subscription has a priority slot, so phases can be deterministic. | | Keep a meaningful current value | AzState<T> | Subscribers can receive the current value and later changes. | | Clean up one subscription | AzEventToken | The token is the lifecycle handle for a single subscription. | | Clean up many subscriptions together | AzEventTokenBag | The bag owns a group of tokens and disposes them together. | | See buses, handlers, publishers, and states in the editor | Tracking | 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

| Guide | Best for | | --- | --- | | 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 | Fast answers for common surprises. | | Events, Tokens, And Token Bags | Full event and token guide. | | Priority Events | Full priority event guide. | | State | Full state guide. |