Ui Module

Base UI framework for KairoEngine using Unity UI Toolkit (UIElements) with a view/controller pattern.

Overview

The Ui module provides a lightweight, event-driven UI management system built on top of Unity's UI Toolkit. It enables creation, registration, and management of UI views with support for show/hide animations, view grouping, and integration with KairoEngine's event and initialization systems.

Installation

Add to your Unity project's Packages/manifest.json:

"at.kairoscope.kairoengine.ui": "https://forgejo.jamesperet.com/kairoengine/ui.git"

Or use the Unity Package Manager: Add package from git URL → https://forgejo.jamesperet.com/kairoengine/ui.git

Key Features

• View-based architecture: Abstract base class for creating modular UI views
• Event-driven control: Show/hide views via KairoEngine's event system
• View grouping: Organize and control multiple views as groups
• Service integration: Implements IServiceGenericUi for service locator pattern
• Initialization management: Seamless integration with InitializationManager
• UIElements-based: Built on Unity's modern UI Toolkit

Dependencies

• KairoEngine.Events - Event-driven UI commands via EventManager
• UnityEngine.UIElements - Unity's UI Toolkit (built-in, Unity 2021.3+)

Note: UiInitializer.cs is currently commented out. When re-enabled, it will require KairoEngine.Core, InitializationManager, UniTask, and Odin Inspector. The active codebase only depends on Events.

Core Components

UiView

Abstract base class for all UI views. Inherit from this to create custom UI views.

Properties:

• viewName - Unique identifier for the view
• viewGroup - Optional group name for batch operations

Methods:

• Show() - Display the view and trigger show animations
• Hide() - Hide the view and trigger hide animations
• Update() - Called every frame, even when hidden
• Destroy() - Clean up resources

Example:

using KairoEngine.UI;
using UnityEngine.UIElements;

public class MyCustomView : UiView
{
    private VisualElement rootElement;

    public override void Show()
    {
        rootElement.style.display = DisplayStyle.Flex;
        // Trigger show animations
    }

    public override void Hide()
    {
        rootElement.style.display = DisplayStyle.None;
        // Trigger hide animations
    }

    public override void Update()
    {
        // Update logic runs every frame
    }

    public override void Destroy()
    {
        UiViewList.UnregisterUiView(this);
    }
}

UiManagerSystem

Main MonoBehaviour that manages all UI views. Listens to global events and processes view commands.

Service Interface: Implements IServiceGenericUi

Events Listened:

• ShowUiView - Show a specific view by name
• HideUiView - Hide a specific view by name
• ShowUiGroupView - Show all views in a group
• HideUiGroupView - Hide all views in a group

Usage via Events:

using KairoEngine.Events;

// Show a view
EventManager.broadcast.TriggerEvent("ShowUiView", "MainMenu");

// Hide a view
EventManager.broadcast.TriggerEvent("HideUiView", "MainMenu");

// Show all views in a group
EventManager.broadcast.TriggerEvent("ShowUiGroupView", "HUD");

// Hide all views in a group
EventManager.broadcast.TriggerEvent("HideUiGroupView", "HUD");

Usage via Service Locator:

using KairoEngine.Core;

var uiService = ServiceLocator.Get<IServiceGenericUi>();
uiService.ShowView("MainMenu");
uiService.HideView("MainMenu");
uiService.ShowGroupView("HUD");
uiService.HideGroupView("HUD");

UiViewList

Static registry that manages all active UiView instances.

Methods:

• RegisterUiView(UiView) - Add a view to the registry
• UnregisterUiView(UiView) - Remove a view from the registry
• GetUiView(string) - Find a view by name
• GetUiViewGroup(string) - Find all views in a group
• GetUiViews() - Get all registered views
• Update() - Update all registered views
• Destroy() - Destroy all registered views

UiViewInitializer

ScriptableObject base class for initializing custom views. Create concrete implementations to set up your views during initialization.

Methods:

• Initialize(UIDocument) - Called when the UI system initializes
• Start() - Called after initialization completes
• Destroy() - Called when the UI system is destroyed

Example:

using KairoEngine.UI;
using UnityEngine;
using UnityEngine.UIElements;

[CreateAssetMenu(menuName = "UI/My View Initializer")]
public class MyViewInitializer : UiViewInitializer
{
    public override void Initialize(UIDocument uiDocument)
    {
        // Create and setup your view
        var view = new MyCustomView();
        view.viewName = "MyView";
        view.viewGroup = "Menu";

        // Register with the system
        UiViewList.RegisterUiView(view);
    }
}

UiInitializer

Initializes the entire UI system. Configure this in your InitializationManager.

Configuration:

• defaultPanelSettings - Panel settings for the UIDocument
• defaultVisualTreeAsset - Root UXML template
• sortingOrder - Canvas sorting order
• uiViewInitializers - List of view initializers to run

Setup Guide

1. Create a UiInitializer Asset

The UiInitializer is typically configured as part of your game's initialization setup.

2. Create Custom Views

Inherit from UiView and implement the abstract methods:

public class HealthBarView : UiView
{
    private ProgressBar healthBar;

    public HealthBarView(VisualElement root)
    {
        viewName = "HealthBar";
        viewGroup = "HUD";
        healthBar = root.Q<ProgressBar>("health-bar");
    }

    public override void Show()
    {
        healthBar.style.display = DisplayStyle.Flex;
    }

    public override void Hide()
    {
        healthBar.style.display = DisplayStyle.None;
    }

    public override void Update()
    {
        // Update health bar value
    }

    public override void Destroy()
    {
        UiViewList.UnregisterUiView(this);
    }
}

3. Create View Initializers

Create ScriptableObject initializers for your views:

[CreateAssetMenu(menuName = "UI/Health Bar Initializer")]
public class HealthBarInitializer : UiViewInitializer
{
    public override void Initialize(UIDocument uiDocument)
    {
        var view = new HealthBarView(uiDocument.rootVisualElement);
        UiViewList.RegisterUiView(view);
    }
}

4. Configure Initialization

Add your view initializers to the UiInitializer's uiViewInitializers list.

View Groups

Views can be organized into groups for batch operations:

// Create views in the same group
var menu1 = new MenuView { viewName = "MainMenu", viewGroup = "Menus" };
var menu2 = new MenuView { viewName = "SettingsMenu", viewGroup = "Menus" };

// Show/hide all views in the group
EventManager.broadcast.TriggerEvent("ShowUiGroupView", "Menus");
EventManager.broadcast.TriggerEvent("HideUiGroupView", "Menus");

Architecture

The Ui module follows a command pattern for view operations:

1. Event triggered via EventManager.broadcast
2. Command queued in UiManagerSystem
3. Command executed in next Update cycle
4. View updated via UiViewList

This ensures all UI operations are processed in a predictable order within the Unity lifecycle.

Integration with Other Systems

The Ui module integrates with:

• ServiceLocatorSystem: Register UiManagerSystem as IServiceGenericUi
• Events: Trigger view show/hide via events
• InitializationManager: Initialize UI system on game startup
• UiDesignElements: Pre-built UI components (separate module)

Best Practices

1. Always register views: Call UiViewList.RegisterUiView() in your initializer
2. Unregister on destroy: Call UiViewList.UnregisterUiView() in Destroy()
3. Use unique names: Ensure each view has a unique viewName
4. Group related views: Use viewGroup to organize related UI
5. Keep Update lightweight: Update() runs every frame, optimize accordingly
6. Use events for decoupling: Prefer events over direct method calls

Debugging

Enable debug logging in UiManagerSystem:

uiManagerSystem.showDebug = true;

This will log all view show/hide operations to the console.