Build a screen with the UI Setup Manager

Start here

See where you are heading first: the showcase app, a complete mobile game UI built only with UI Framework, with an intro, four tabs under shared bars, and reward, purchase and settings popups. Then build your own, one short video per step.

Video series

Steps

1. Create the config and check the canvas defaults

   Open the General tab and press Create Config. It finds or creates a UiEditorConfig asset that tells the tools where your scripts and scenes live and which namespaces to generate into.

   • Set ElementNamespace and StateNamespace to your game's namespaces.
   • In Global Canvas Settings, choose the render mode and the Canvas Scaler values (default: Scale With Screen Size, 1080 × 1920, Expand). Every new element scene starts with them.

   Defaults, not enforcement

   Changing the global settings never edits existing scenes. Each element can still differ, or adopt the defaults with Use Default Settings…

   

   Screenshot: General tabdocs/images/setup-general.png

2. Create a UI element

   Open the Elements tab and press ➕ New Element. The form opens in the right panel:

   Name	The class and scene name, e.g. StoreUiElement
   From Existing Scene	Optional: convert a scene you already have. Its objects move under the new root, and you are offered a structure fix
   Include Parameters Class	Also generates StoreUiElementParams for the data you pass in
   Include Reference Class	Also generates a StoreUiElementReference helper

   Press Create. You get the script and a scene built to the scene contract. After Unity compiles, the script is attached to StoreUiElementRoot automatically. An existing script with the same name is never overwritten.

   

   Screenshot: New Element formdocs/images/setup-new-element.png

3. Build the screen under Root

   Open the scene (double-click it in the list). Every element scene has the same shape. Put all of your content under Root: that object is what animates.

   • Lay things out with normal anchors; the Canvas Scaler handles screen sizes.
   • Nested canvases are fine under Root (for example a layer with a high sorting order).
   • Nothing may sit next to Root under the Canvas, or it won't animate.
   • Popups usually put a full-screen dimmed backdrop as the first child of Root.

   StoreUiElementRoot UiElement script, the only root object └─ Canvas Canvas + CanvasScaler + GraphicRaycaster └─ Root stretched, the animation target ├─ Header ├─ ItemsGrid └─ … all your content

   

   Screenshot: element scene in the Hierarchy and Scene viewdocs/images/scene-hierarchy.png

4. Pick the show and hide animations

   Select the element in the list. In its Animations section, choose a Show and a Hide preset. Each choice shows one line describing what it looks like, and the change is written straight into the scene.

   See every preset moving on the Animations tab. Code can still override them for a single call with UiTransition.

   

   UI Setup Manager

   UI ConfigUiEditorConfig (UiEditorConfig)

   GeneralElementsStates

   store ➕ New Element Refresh Validate All Fix All Structure… Only show elements with issues

   ✓ 9 OK⚠ 1 fixable✖ 0 need manual work

   ✓IntroUiElement

   ✓MainMenuUiElement

   ✓NavBarUiElement

   ⚠ProfileUiElement

   ✓StoreUiElement (open)

   ✓TopBarUiElement

   StoreUiElement Open SceneSelect Asset

   Structure

   ✓ Follows the UI element scene contract.

   Animations

   ShowSlide Left ▾

   Fades in while entering from the right edge, moving left.

   HideSlide Left ▾

   Keeps moving left and fades out as it leaves past the left edge.

   Canvas

   Render ModeScreen Space - Camera ▾

   Sorting Order0

   Reference Resolution1080 × 1920

   Addressables

   Addressableon

   GroupUiElements ▾

5. Validate and fix scene structure

   Every scene in the list has a status: ✓ OK, ⚠ fixable, ✖ needs work by hand.

   • Validate All logs one line per scene with its issues.
   • Fix Structure… (one element) or Fix All Structure… shows exactly what will change, with a Now / After preview of the hierarchy, before it touches anything.
   • Fixes only create and reparent objects, with Undo. They never delete anything; what needs manual work is listed under What to fix by hand….
   • Only show elements with issues filters the list.

   

   Screenshot: Fix Structure confirmation with the Now / After previewdocs/images/setup-fix-dialog.png

6. Canvas, sorting and Addressables per element

   The Canvas section edits this scene's Render Mode, Sorting Order, UI Scale Mode, Reference Resolution, Screen Match Mode and Reference PPU in place. Use sorting order to stack layers, for example screens 0, bars 10, popups 100.

   The Addressables section shows whether the scene is Addressable, its group and labels. Build Runtime UiConfig registers every scene a state uses for you.

7. Create a state and add its scenes

   Open the States tab. Type the state name next to New state (for example StoreUiState) and press ➕. It generates the state class: a type marker for ShowState<StoreUiState>(). Its name must equal the state key.

   Select the state and use Add element scene: start typing and pick from the suggestions. Add the screen and every shared element it shows, for example StoreUiElement, TopBarUiElement and NavBarUiElement.

   Shared elements

   List your nav bar in every tab state. While you switch tabs it stays loaded and on screen, and only the screens animate.

   

   Screenshot: States tabdocs/images/setup-states.png

8. Build the runtime config

   Back in General, press Build Runtime UiConfig. It turns your state definitions into the runtime UiConfig, makes every element scene Addressable (group UiElements) and registers the config under the address UiConfig (group GlobalConfigs).

   Run it after every change

   New state, renamed scene, added element: build again. The config is generated, so never edit it by hand. For player builds, also build Addressables content.

9. Show it from code and press Play

   Initialize once at startup, then show states from anywhere: buttons, game events, your flow controller.

   From a buttonCopy

   private async void OnStoreClicked()
   {
       try
       {
           await UiManager.ShowState<StoreUiState>();
       }
       catch (Exception exception)
       {
           Debug.LogError("[MainMenuUiElement] Could not open the store: " + exception);
       }
   }

10. Add a popup

    A popup is a state shown with additive: true. It goes on top; the screen below stays loaded and visible. HideUI pops it again.

    1. Create ConfirmPurchaseUiElement, give it a dimmed backdrop and a panel, and set its Canvas Sorting Order above your screens.
    2. Create ConfirmPurchaseUiState with just that scene, and build the runtime config.
    3. Open it with data, close it from its buttons:

    PopupCopy

    // ConfirmPurchaseUiElementParams is generated by "Include Parameters Class".
    ConfirmPurchaseUiElementParams purchase = new ConfirmPurchaseUiElementParams();
    purchase.ItemName = "Neon Blade";
    purchase.Price = 250;
    
    await UiManager.ShowState<ConfirmPurchaseUiState>(purchase, additive: true);
    
    // In the popup's Cancel / Buy handler:
    await UiManager.HideUI();

Checklist when something doesn't show

• The state class name equals the state key exactly.
• Build Runtime UiConfig ran after your last change.
• The Addressables play mode script is Use Asset Database, or content is built.
• The element's scene shows ✓ in the Elements tab.
• There is one EventSystem and, for Screen Space – Camera canvases, a camera assigned at runtime.
• The Console has no [UiManager] errors.