cuozg/unity-app-ui

App UI Expert for Unity

Expert assistant for building user interfaces in Unity using the App UI framework.

Overview

App UI is Unity's comprehensive framework for building beautiful, high-performance user interfaces. It supports multi-platform development (Android, iOS, Windows, macOS, WebGL) and is built on UI Toolkit.

Core Requirements

• Unity 2021.3 LTS or later
• Familiarity with UI Toolkit

Key Namespace

using Unity.AppUI.UI;

UXML Namespace Declaration

<UXML xmlns="UnityEngine.UIElements" xmlns:appui="Unity.AppUI.UI">
    <appui:Panel>
        <!-- Your UI elements -->
    </appui:Panel>
</UXML>

Essential Patterns

1. Always Start with Panel

The Panel component is mandatory -- it provides context (theme, language, layout direction) and the layering system for overlays. Without Panel as the root, contexts and overlays will not work.

<appui:Panel>
    <appui:Button title="Hello World!" />
</appui:Panel>

2. Theme Setup

Reference a theme in your PanelSettings:

• Default: Packages/com.unity.dt.app-ui/PackageResources/Styles/Themes/App UI.tss
• Variants: Dark/Light, Small/Medium/Large, Editor variants

3. Component Usage

Buttons and Actions:

<appui:Button title="Click me" />
<appui:IconButton icon="add" />
<appui:ActionButton icon="edit" label="Edit" />

Always use clickable for events (not ClickEvent):

button.clickable.clicked += () => Debug.Log("Clicked");

Input Components:

<appui:TextField />
<appui:TextArea />
<appui:Checkbox />
<appui:Toggle />
<appui:Dropdown />
<appui:SliderFloat low-value="0" high-value="100" />

Layout Components:

<appui:StackView />
<appui:SwipeView />
<appui:PageView />
<appui:SplitView direction="Horizontal" />

4. Overlays and Popups

// Popover
var popover = Popover.Build(target, content)
    .SetPlacement(PopoverPlacement.Bottom)
    .SetArrowVisible(true);
popover.Show();

// Modal
var modal = Modal.Build(content)
    .SetFullScreenMode(ModalFullScreenMode.None);
modal.Show();

// Toast
var toast = Toast.Build(panel, "Message", NotificationDuration.Short);
toast.Show();

// Menu
MenuBuilder.Build(anchor)
    .AddAction(1, "Item", "icon", evt => Debug.Log("clicked"))
    .Show();

5. Localization

var ctx = element.GetContext<LangContext>();
var text = await ctx.GetLocalizedStringAsync("@tableName:entryKey");

Important Guidelines

1. Always use Panel as root - Required for contexts and overlays
2. Use clickable.clicked - Not RegisterCallback<ClickEvent>
3. Use USS variables - From themes for consistent styling
4. Use source generators - [ObservableObject], [ObservableProperty], [RelayCommand]
5. RadioGroup uses string keys - Not int indices
6. Use AddCase for reducers - Not Add method

File Locations

• Themes: Packages/com.unity.dt.app-ui/PackageResources/Styles/Themes/
• Icons: Packages/com.unity.dt.app-ui/PackageResources/Icons/
• Fonts: Packages/com.unity.dt.app-ui/PackageResources/Fonts/

Reference Documentation

Consult reference.md when you need exact API signatures, component property tables, context system details, or platform integration methods beyond what's covered above. See examples/ for complete working code samples.

Specialized Skills

This skill covers App UI fundamentals -- components, overlays, and general patterns. For tasks that go deeper into specific areas, also consult the corresponding specialized skill:

• unity-app-ui-navigation - Consult for NavGraph, NavHost, NavController, screen navigation, AppBar/Drawer/BottomNavBar/NavigationRail setup, back stack management, and nested graphs.
• unity-app-ui-redux - Consult for Redux Store, Slices, Reducers, ActionCreators, AsyncThunks, middleware, subscriptions, and Redux DevTools.
• unity-app-ui-mvvm - Consult for ObservableObject, ObservableProperty, RelayCommand, AppBuilder, service registration, dependency injection, and data binding.
• unity-app-ui-theming - Consult for custom themes, USS variables/design tokens, dark/light mode, scale factors, BEM conventions, custom icons, and custom typography.