Luna UI Documentation

Luna UI provides a complete notification system with support for toast notifications, notification history, and custom actions.

Components

The notification system consists of several interconnected classes:

NotificationData: Data model for a single notification
NotificationHistory: Manages notification storage and retrieval
SingleNotification: Renders individual toast notifications
NotificationHistoryView: UI for viewing notification history

NotificationData

The data model for notifications.

csharp

public class NotificationData
{
    public Guid Id;
    public string Title;
    public string Body;
    public INotificationImageSource ImageSource;
    public bool IsDismissed;
    public NotificationSize Size;
    public NotificationAction OnClickAction;
}

Property	Type	Description
Id	Guid	Unique identifier (auto-generated)
Title	string	Notification title (optional)
Body	string	Notification body text (optional)
ImageSource	INotificationImageSource	Image source interface
IsDismissed	bool	Whether the notification has been dismissed
Size	NotificationSize	Display size (Small, Default, Large)
OnClickAction	NotificationAction	Custom action to execute on click

Constructor

csharp

public NotificationData(
    string title, 
    string body, 
    INotificationImageSource imageSource, 
    NotificationSize size
)

NotificationSize

csharp

public enum NotificationSize
{
    Small,
    Default,
    Large
}

NotificationHistory

Manages the notification history with a configurable maximum size.

Properties

Property	Type	Description
History	ReadOnlyCollection<NotificationData>	Read-only access to history
MaxNotifications	int	Maximum notifications to store (default: 20)

Methods

PushNotification

Adds a new notification to history.

csharp

public void PushNotification(NotificationData notificationData)

GetLastNonDismissed

Gets the most recent non-dismissed notifications.

csharp

public List<NotificationData> GetLastNonDismissed(int amount)

GetNotification

Retrieves a notification by ID.

csharp

public NotificationData GetNotification(Guid id)

ClearHistory

Clears all notifications from history.

csharp

public void ClearHistory()

Events

OnPushNotification

Fired when a new notification is pushed.

csharp

public event Action<Guid> OnPushNotification;

SingleNotification

Creates and manages a single toast notification UI element.

Constructor

csharp

public SingleNotification(
    VisualElement parent, 
    NotificationData notificationData, 
    UIColorName color
)

Parameter	Type	Description
parent	VisualElement	The notification container element
notificationData	NotificationData	The notification data
color	UIColorName	Color theme for the dismiss button

Required UXML Structure

The notification template must contain:

Label with name "Title"
Label with name "Body"
VisualElement with name "Image"
Button with name "DismissButton"

Events

OnDismiss

Fired when the notification is dismissed.

csharp

public event Action OnDismiss;

USS Classes

The following classes are automatically applied:

Class	Condition
`notification`	Always applied
`notification-sm`	When Size is Small
`notification-lg`	When Size is Large

INotificationImageSource

Interface for providing notification images.

csharp

public interface INotificationImageSource
{
    Sprite GetImage();
}

Example Implementation

csharp

[Serializable]
public class SpriteImageSource : INotificationImageSource
{
    [SerializeField] private Sprite _sprite;
    
    public Sprite GetImage() => _sprite;
}

[Serializable]
public class AddressableImageSource : INotificationImageSource
{
    [SerializeField] private AssetReferenceSprite _spriteRef;
    private Sprite _loadedSprite;
    
    public async Task LoadAsync()
    {
        _loadedSprite = await _spriteRef.LoadAssetAsync<Sprite>().Task;
    }
    
    public Sprite GetImage() => _loadedSprite;
}

NotificationAction

Abstract base class for notification click actions.

csharp

public abstract class NotificationAction
{
    public virtual void Execute(string title, string body);
}

Example Implementation

csharp

[Serializable]
public class OpenURLAction : NotificationAction
{
    [SerializeField] private string _url;
    
    public override void Execute(string title, string body)
    {
        base.Execute(title, body);
        Application.OpenURL(_url);
    }
}

[Serializable]
public class ShowDetailAction : NotificationAction
{
    public override void Execute(string title, string body)
    {
        base.Execute(title, body);
        // Show detail panel with title and body
        NotificationDetailPanel.Show(title, body);
    }
}

NotificationHistoryView

A UIViewComponent that displays the notification history in a ListView.

Setup

Create a UXML with:
- ListView with name "NotificationList"
- Button with name "ReturnButton"
Create a notification static template UXML with Title, Body, and Image elements
Assign the template in the inspector

Initialize

csharp

public void Initialize(NotificationHistory notificationHistory)

The view automatically:

Populates the ListView with history (reversed, newest first)
Sets up keyboard navigation with ListViewWrapper
Handles dismiss via return button

Complete Example

csharp

using System;
using UnityEngine;
using UnityEngine.UIElements;
using CupkekGames.Luna;

public class NotificationManager : MonoBehaviour
{
    [SerializeField] private UIDocument _uiDocument;
    [SerializeField] private VisualTreeAsset _notificationTemplate;
    [SerializeField] private UIColorName _notificationColor = UIColorName.PRIMARY;
    
    private NotificationHistory _history = new NotificationHistory();
    private VisualElement _notificationContainer;
    private List<SingleNotification> _activeNotifications = new();
    
    private void Start()
    {
        _notificationContainer = _uiDocument.rootVisualElement.Q<VisualElement>("NotificationContainer");
        _history.OnPushNotification += OnNotificationPushed;
    }
    
    public void ShowNotification(string title, string body, Sprite image = null)
    {
        var imageSource = image != null ? new SpriteImageSource(image) : null;
        var data = new NotificationData(title, body, imageSource, NotificationSize.Default);
        _history.PushNotification(data);
    }
    
    private void OnNotificationPushed(Guid id)
    {
        var data = _history.GetNotification(id);
        
        // Create notification UI
        var container = _notificationTemplate.Instantiate();
        _notificationContainer.Add(container);
        
        var notification = new SingleNotification(container, data, _notificationColor);
        notification.OnDissmiss += () => OnNotificationDismissed(notification, container, data);
        
        _activeNotifications.Add(notification);
        
        // Auto-dismiss after 5 seconds
        _uiDocument.rootVisualElement.schedule.Execute(() =>
        {
            if (!data.IsDismissed)
            {
                notification.Dismiss();
            }
        }).ExecuteLater(5000);
    }
    
    private void OnNotificationDismissed(
        SingleNotification notification, 
        VisualElement container,
        NotificationData data)
    {
        data.IsDismissed = true;
        _activeNotifications.Remove(notification);
        _notificationContainer.Remove(container);
    }
    
    private void OnDestroy()
    {
        _history.OnPushNotification -= OnNotificationPushed;
    }
}

Tips

Use NotificationSize.Small for quick updates, Large for important messages
Implement INotificationImageSource for different asset loading strategies
Subscribe to OnPushNotification to show toast notifications
Use GetLastNonDismissed() to show a badge count of unread notifications
The history automatically removes oldest notifications when exceeding MaxNotifications