Luna UI Documentation

Luna UI Manager

LunaUIManager is a scene singleton (Singleton<LunaUIManager>) marked [DefaultExecutionOrder(-3000)] — it runs before every other Luna script, so its Awake wiring (registry, effect settings, breakpoint detection) completes before any PanelRenderer in the same scene processes its UXML tree.

Important: place exactly one LunaUIManager per scene. The first instance survives scene loads (DontDestroyOnLoad); any duplicate destroys its own GameObject in Awake.

Minimal setup: drag Assets/Samples/LunaUI/<version>/Essentials/Prefabs/LunaUIManager.prefab (from the Essentials sample) into the scene — it ships with the manager and its required UIInteractableAudioHandler pre-configured (effect settings, input icon database, UI audio). That one GameObject is the Luna infrastructure your scenes need: the manager constructs the navigation stack, owns and ticks the UI Attractor burst system, ticks the 3D-in-UI render manager once per frame, and seeds the initial responsive breakpoint class every view picks up at registration.

At Awake it also picks the initial responsive breakpoint from the actual screen size (via the optional Responsive Switcher asset), so every UIView that registers afterwards receives the right breakpoint-* USS class on its root element. After this boot call, only explicit SetBreakpoint calls change the breakpoint.

A single Update() is the per-frame tick for every Luna subsystem that needs one: it reads Time.deltaTime / Time.unscaledDeltaTime once and forwards them to the Attractor and to UIRenderManager.

Settings

Input Settings

Player Input

A Player Input reference is required for the proper functioning of Escape Action InputPrompt component. Represents a single player's input device. Sufficient for singleplayer games.

Player Input Manager

When set, overrides the standalone PlayerInput above. Solution for local multiplayer. Enables multiple players to join and leave the game dynamically. See documentation for more info.

Escape Action Names

Names of InputActions that will trigger escape when performed. See UIViewActionEscape for more info.

Input Icon Database

Input icons for InputPrompt components.

Loading Action Maps

Enables all other action maps on start. Optionally, loading transitions with input disables other action maps during the loading screen.

Effect Settings

Project-wide UIEffectSettings asset registered as the active effect-settings singleton at Awake, so UI Effects can find the filter definitions without a Resources folder.

Responsive Switcher

Optional ResponsiveViewStyleSwitcher ScriptableObject that drives breakpoint USS classes (e.g. breakpoint-lg) on all UIView roots. The manager auto-detects the initial breakpoint from the screen width at Awake; call SetBreakpoint(name) from your settings system to switch layouts.

Auto Install Fx

When enabled (default), every UIView registered via the manager has UIEffectPanelHook automatically installed on its ParentElement, enabling USS class-driven effects (.luna-fx + --luna-fx) with zero setup. Disable for manual control.

UI Page Manager Settings

Blacklist

List of VisualElement names to ignore. The page manager automatically adds hover and click sounds to focusable elements. Add elements here if you cannot disable their focusable state but do not want sounds applied to them.

Public Properties

Name	Type	Description
Navigation	LunaNavigationStack	Per-scene navigation stack, constructed in `Awake`. Reach the verbs through the static facade `LunaNavigation.Push("someId")` (preferred), or this instance for properties + events. See Navigation.
Attractor	UIAttractor	UI Toolkit particle attractor system (fly-to bursts). Ticked once per frame from the manager's `Update()`.
AudioHandler	UIInteractableAudioHandler	Hover/click audio feedback handler (required component on the same GameObject).
IconDatabase	InputIconDatabaseSO	Input icons for InputPrompt components.
EffectSettings	UIEffectSettings	The configured effect settings asset.
ResponsiveSwitcher	ResponsiveViewStyleSwitcher	The configured breakpoint switcher asset.
AutoInstallFx	bool	Whether the fx hook is auto-installed on registered views.

Integration with Other Components

InputDeviceManager Integration

LunaUIManager automatically initializes and manages the InputDeviceManager. It calls InputDeviceManager.OnEnable() with the configured escape action names and loading action maps. When a PlayerInputManager is set, player input registration is handled automatically by subscribing InputDeviceManager.AddPlayerInput / RemovePlayerInput to the manager's onPlayerJoined / onPlayerLeft events; with a standalone PlayerInput, that input is registered directly.

InputPrompt Integration

The LunaUIManager provides the IconDatabase property that InputPrompt components use to display appropriate input icons for different control schemes. InputPrompt components automatically query this database to get the correct sprites and text for the current input method.

UI Page Manager

The page manager is a feature within the Luna UI Manager.

Manages the registration and state of VisualElement instances within a hierarchy of VisualElement containers. It provides functionality for blocking and unblocking input on groups of elements, which is particularly useful for managing UI navigation.

Automatically adds audio feedback to interactable elements like buttons.

Additionally, it includes functionality for setting a blocker element.

How input blocking works

Blocked elements get pickingMode = PickingMode.Ignore and focusable = false — they ignore pointer events and are skipped by keyboard navigation, but their visual styling is untouched. Unlike SetEnabled(false), no :disabled USS rules fire, so nothing visibly greys out behind a modal during fade transitions.

Each element's original pickingMode is snapshotted at block time, and unblocking restores that exact value (some elements are intentionally Ignore even when focusable, e.g. transparent backgrounds with focusable children). Already-blocked elements are not re-snapshotted, so nested modals don't lose the outer modal's restore target, and unblocking is a no-op for elements that weren't tracked as blocked.

Public Methods

SetBlocker

Blocks input on all UI elements and sets a specified VisualElement as the active blocker, ensuring it remains interactive. When clicked, it will restore input on all previously blocked elements.

csharp

public void SetBlocker(VisualElement blocker)
// or
public void SetBlocker(string elementName)

RemoveBlocker

If you want, you can remove blocker manually.

csharp

public void RemoveBlocker()

SetInputBlockedAllPages

Info: The "disableOtherViewsOnFadeIn" option on UIView uses these functions — fade-in blocks every other page (blocked: true, except this view's own page) and fade-out restores exactly the elements it changed.

csharp

/// <param name="blocked">true to block input, false to restore it.</param>
/// <param name="exceptPages">Pages to ignore.</param>
/// <returns>
/// Set of elements whose state actually changed.
/// </returns>
public HashSet<VisualElement> SetInputBlockedAllPages(bool blocked, params VisualElement[] exceptPages)
// or
public HashSet<VisualElement> SetInputBlockedAllPages(bool blocked, HashSet<VisualElement> exceptPages)

SetInputBlockedPage

csharp

public HashSet<VisualElement> SetInputBlockedPage(VisualElement page, bool blocked,
  HashSet<VisualElement> exceptElements)

SetInputBlockedElements

Blocks or restores input on a specific set of VisualElements. Useful for controlling individual elements or custom groups.

csharp

public void SetInputBlockedElements(bool blocked, HashSet<VisualElement> elements)

RegisterPage

Info: You don't need to manually register elements when using UIViews.

However, for documentation purposes, the functions are detailed here.

csharp

public void RegisterPage(VisualElement parent)

UnregisterPage

csharp

public void UnregisterPage(VisualElement parent)

GetPage

csharp

public HashSet<VisualElement> GetPage(VisualElement parent)

RegisterElement

csharp

public void RegisterElement(VisualElement parent, VisualElement item)

UnregisterElement

csharp

public void UnregisterElement(VisualElement parent, VisualElement item)

Global UIView Registry

The Global UIView Registry tracks all UIViews in the scene, enabling you to apply USS classes to all views at once. This is particularly useful for locale-based styling and runtime USS class management.

Public Methods

GetAllUIViews

Returns a read-only collection of all registered UIViews in the scene. Automatically removes invalid views (where ParentElement is null or destroyed).

csharp

public IReadOnlyCollection<UIView> GetAllUIViews()

AddClassToAllUIViews

Adds a USS class to the root element of all registered UIViews. The class will be automatically applied to any UIViews that register in the future.

csharp

public void AddClassToAllUIViews(string className)

Use Case: Locale-based styling, runtime USS class management. See Runtime Style Switching for an example.

RemoveClassFromAllUIViews

Removes a USS class from the root element of all registered UIViews. The class will no longer be applied to UIViews that register in the future.

csharp

public void RemoveClassFromAllUIViews(string className)

RegisterUIView

Info: You don't need to manually register UIViews. Registration happens automatically when a UIView is constructed.

However, for documentation purposes, the function is detailed here.

Registers a UIView to the global registry. Applies any globally tracked classes to the newly registered view. When Auto Install Fx is enabled, also installs the UIEffectPanelHook on the view's ParentElement so USS class-driven UI Effects work with zero setup.

csharp

public void RegisterUIView(UIView view)

UnregisterUIView

Info: You typically don't need to manually unregister UIViews. Unregistration happens automatically when a UIView is destroyed via UIViewReference.OnDestroy().

However, for documentation purposes, the function is detailed here.

Unregisters a UIView from the global registry.

csharp

public void UnregisterUIView(UIView view)