Luna UI Documentation

Prerequisites: you've finished the Quick Start and have the Showcase demo running. If you're brand-new to UI Toolkit, read UI Toolkit Basics first — this page assumes you know what UXML, USS, and a VisualElement are.

This page walks you from "the demo plays" to "my own scene plays my own view" in five steps. The end state: an empty scene with a Luna-themed UI showing a label and a button you wired up in C#.

1. Set up the scene

Create a fresh scene (File > New Scene > Empty).

You need three things in the scene:

LunaUIManager — drag Assets/Samples/LunaUI/<version>/Essentials/Prefabs/LunaUIManager.prefab into the scene. This GameObject hosts the LunaUIManager component plus input wiring. Every view subscribes to it for focus management and input handling. See Luna UI Manager for what it does.
EventSystem — add GameObject > UI > Event System if the scene doesn't have one yet. UI Toolkit input dispatch requires it.
Your view GameObject — GameObject > UI > UI Document. This creates an empty GameObject with a UIDocument component.

Select the new UI Document GameObject and fill its Inspector:

Panel Settings: drag Essentials/Theme/LunaPanelSettings.asset (screen-space) or LunaPanelSettingsWorldSpace.asset (world-space). This is what wires Luna's full theme into your view.
Source Asset: leave empty for now — you'll create a UXML file in step 2.

2. Create the UXML

Right-click in the Project view → Create > UI Toolkit > UI Document. Name it MyView.uxml. Open it in UI Builder (double-click).

Add a VisualElement as a container, then drop in a Label and a Button from the Library panel. Give them names you can find from code:

Label → name: my-label, set text to "Hello, Luna"
Button → name: my-button, set text to "Click me"

Save the UXML file. Back on your UI Document GameObject in the scene, assign MyView.uxml to Source Asset.

If you press Play now, the label and button render but do nothing — and they're un-themed because UIViewComponent is what wires the LunaUIManager / fade system in.

3. Write the view script

Create Assets/Scripts/MyView.cs:

csharp

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

public class MyView : UIViewComponent
{
    private Label _label;
    private Button _button;
    private int _clicks;

    protected override void Awake()
    {
        base.Awake();

        // ParentElement is the root VisualElement of the UIDocument
        // (or the named sub-element if you set _parentName on the component).
        _label = ParentElement.Q<Label>("my-label");
        _button = ParentElement.Q<Button>("my-button");
    }

    private void OnEnable()
    {
        // Unity's Button exposes a `clicked` Action — simpler than
        // RegisterCallback<ClickEvent>(...) for the common case.
        _button.clicked += OnClicked;
    }

    private void OnDisable()
    {
        _button.clicked -= OnClicked;
    }

    private void OnClicked()
    {
        _clicks++;
        _label.text = $"Hello, Luna ({_clicks} clicks)";
    }
}

Attach this script to the same GameObject as your UIDocument. Make sure the GameObject also has a UIViewComponent parent class — adding MyView adds it automatically (it's a UIViewComponent subclass).

Inspector defaults you can leave as-is:

UIDocument — auto-resolves from the same GameObject if left empty.
Parent Name — leave empty to use the UXML root; set to a VisualElement name to scope the view to a sub-tree.
Focus Name — element to focus when the view fades in (used for keyboard navigation).
Fade Duration / Easing Mode — fade-in fade animation. 0.5 / EaseOutCirc is the Luna default.
Start Visibility — FadeIn makes the view fade in on Awake.

Press Play. The button increments the label on click.

4. Add fade transitions

UIViewComponent exposes a Fade property — a FadeUIElement that animates opacity + interactability.

To fade the view out programmatically:

csharp

Fade.FadeOut();

To destroy the GameObject after the fade completes (the standard "close this view" flow):

csharp

FadeOutThenDestroy();

Subscribe to fade events for state-aware logic:

csharp

private void OnEnable() {
    Fade.OnFadeIn  += OnFadedIn;
    Fade.OnFadeOut += OnFadedOut;
}

private void OnDisable() {
    Fade.OnFadeIn  -= OnFadedIn;
    Fade.OnFadeOut -= OnFadedOut;
}

private void OnFadedIn()  { /* view fully visible */ }
private void OnFadedOut() { /* view fully hidden */ }

For modal-style views that open on demand (e.g. an inventory popup):

Instantiate the view's prefab from another view's button handler.
Or use AddDefaultEscapeAction on UIViewComponent to auto-close on Esc — see the UIViewActionEscape section.

For full-screen views that stack (Main Menu → Settings → Credits), see the Views section — Main Menu / Pause Menu / Settings / Save & Load are all pre-built UIViewComponent subclasses you can extend.

For a complete multi-page UI example with navigation, see Example: Multi Page UI.

Next steps

Pre-built views — Views section covers Main Menu, Pause, Settings, Save & Load, Inventory, Credits, Dialogue.
Components — Components section has per-component pages for Button, Slider, Dropdown, Toggle, ProgressBar, Tooltip, Tabview, and more.
Style your view — Theme Stack explains how to override colors / fonts; Styling covers per-property USS reference.
Effects — Transition Animation for entry/exit animation; UI Effects for glow/outline/shadow/gradient via USS.
UI Actions — UI Actions — a slot-based action system for view-level behaviors (escape handling, hotkey wiring).

First View

1. Set up the scene

2. Create the UXML

3. Write the view script

4. Add fade transitions

5. Wire it into navigation

Next steps