Samples And Tutorials

Use the samples to see the patterns from the manual working inside Unity.

Deep references:

• Events, Tokens, And Token Bags
• Priority Events
• State

AzState Sample Scene

The AzStateSample is the best first sample because it shows state ownership, state updates, UI reading, and lifecycle cleanup.

Open the provided sample scene:

Assets/Azkar Industries/Azkar EDA/Samples/AzState Sample/AzStateSample.unity

Suggested walkthrough:

1. Open the sample scene.
2. Enter Play Mode.
3. Interact with the UI controls that change state.
4. Watch which UI elements update from the state.
5. Open Window/Azkar EDA/Tracking.
6. Inspect the State mode and Graph mode while changing values.
7. Find where the sample subscribes and confirm tokens are disposed by the owning lifecycle.

What to look for:

• AzState<T> stores the current value.
• Readers subscribe to state instead of asking the writer directly.
• Writers use state setters or SourceSet updates.
• UI objects own their token bags.

Minimal Sample To Build Yourself

Create one state, one writer, and one reader.

using Azkar.Eda;

public static class TutorialState
{
    public static readonly AzState<int> Coins = new(0);
}

using UnityEngine;
using Azkar.Eda;

public sealed class CoinButton : MonoBehaviour
{
    public void AddCoin()
    {
        TutorialState.Coins.SourceSet(TutorialState.Coins.Value + 1);
    }
}

using UnityEngine;
using UnityEngine.UIElements;
using Azkar.Eda;

public sealed class CoinLabel : MonoBehaviour
{
    [SerializeField] private UIDocument document;

    private readonly AzEventTokenBag _tokens = new();
    private Label _label;

    private void OnEnable()
    {
        _label = document.rootVisualElement.Q<Label>("coinLabel");
        TutorialState.Coins.Subscribe(OnCoinsChanged).AddTo(_tokens);
    }

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

    private void OnCoinsChanged(int coins)
    {
        _label.text = coins.ToString();
    }
}

Benchmark And Performance Showcase Examples

The repository includes benchmark and performance-oriented examples under the Azkar EDA example areas. Use them to compare:

• Plain event invocation.
• Payload event invocation.
• Ref payload invocation.
• Priority dispatch.
• Token lifecycle operations.
• State write and notification behavior.

When reviewing benchmark code, focus on the shape of the hot path:

• Where subscriptions are created.
• Whether the benchmark measures subscription cost or invocation cost.
• Whether values are captured for tracking.
• Whether safe invocation or fast invocation is being measured.
• Whether the benchmark includes Unity object work, which can dominate the event cost.

Performance examples are teaching tools, not rules for all gameplay code. Start with clear lifecycle ownership, then optimize only the specific path that profiling proves is hot.

Threaded Demo Pattern

Threaded examples should follow this conservative Unity pattern:

1. Worker code produces plain data.
2. Worker code queues that data.
3. Main thread drains the queue.
4. Main thread invokes AzEvent, AzPriorityEvent, or writes AzState<T>.

using System.Collections.Concurrent;
using UnityEngine;
using Azkar.Eda;

public sealed class ThreadedScoreBridge : MonoBehaviour
{
    private readonly ConcurrentQueue<int> _pendingScores = new();

    public void QueueFromWorker(int score)
    {
        _pendingScores.Enqueue(score);
    }

    private void Update()
    {
        while (_pendingScores.TryDequeue(out int score))
        {
            GameEvents.ScoreChanged.Invoke(score);
        }
    }
}

This keeps Unity object access and most gameplay notification on the main thread.

DOTS Examples

DOTS-oriented examples in this repository should be treated as integration patterns unless a sample scene explicitly marks them as ready for direct use. The safe bridge is:

• Job or ECS system produces plain data.
• Data is stored in a native container, buffer, or queue appropriate for that system.
• A main-thread bridge reads the result.
• The bridge publishes an Azkar EDA event or updates an Azkar EDA state.

Avoid calling Unity object APIs or scene-object handlers from jobs. Keep the boundary explicit.

Suggested Learning Order

1. Run the AzState sample scene.
2. Build the minimal coin state sample above.
3. Add tracking attributes and inspect it in the tracking window.
4. Convert the coin state sample to use an AzEvent<int> notification.
5. Convert a small ordered workflow to AzPriorityEvent.
6. Review benchmarks only after the lifecycle patterns feel natural.