Unity package · UGUI · Addressables · free and open source

Smooth, organized game UI, AI-ready

Building with AI? AI tools write a lot of code fast, and without a structure it piles up in places nobody can track. This framework gives every screen the same shape: its own Addressable scene, its own script, its own place in the state stack. Generated code always has a clear place to go, so your project stays easy to follow as it grows. Transitions animate with no flash, and an editor window writes the scripts, scenes and config for you.

Add it to your Unity project Why it matters

Unity 2022.3 – Unity 6 Package Manager Production-ready by default Merge-friendly AI-friendly async / await MIT license

Move across to pull the screen apart

–

FileEditAssetsGameObjectComponentUiFrameworkWindowHelp

Hierarchy

Bootstrapper

BootStrapper

DontDestroyOnLoad

PersistentRoot

Main Camera

EventSystem

UiManager

MainMenuUiElement

MainMenuUiElementRoot

TopBarUiElement

TopBarUiElementRoot

NavBarUiElement

NavBarUiElementRoot

Each UI element is its own scene, loaded additively by UiManager and unloaded when no state uses it.

SceneGame1080x1920 Portrait

NQ

Nova QuinnNeon Rookie

1,250

40

Good evening, NovaReady for today's run?

SEASON 3

Neon Nights

Race through 40 new levels and earn the legendary Neon Crown.

▶ PLAY

Daily rewardCLAIM

2 / 3

380 / 500

1 / 1

HomeStoreRanksProfile

InspectorUI Setup Manager

GeneralElementsStates

UI Elements

✓IntroUiElement

✓MainMenuUiElement

✓NavBarUiElement

✓StoreUiElement

✓TopBarUiElement

Animations

ShowScale ▾

Fades in while growing slightly to full size.

HideFade ▾

Fades out.

Structure

✓ Follows the scene contract.

⚙ Build Runtime UiConfig

Package ManagerAdd by git URL, pin a version

Editor windowWindow → UI Framework → UI Setup Manager

Scenes as screensAddressable, loaded additively

UGUI nativeCanvas, Text, TMP, your components

TestedEditMode and PlayMode tests

Game UI turns into a tangle. It doesn't have to.

Almost every game starts its UI the same way, and almost every game hits the same wall a few months in. If any of this sounds familiar, the framework was made for you.

What changes when you use it

Watch a screen come together

This is the showcase app, pulled apart into the element scenes it is made of. Press Next to run each call, and the figure tells you what UiManager loaded, kept and unloaded. Point at any layer to see what it is.

Why teams use it

Made for teams: no config to lock

Many UI tools keep every screen in one shared registry. Adding a screen means locking that file and pushing it to dev before anyone else can add theirs. UI Framework has no such file to fight over, so the whole team adds screens and states at the same time.

Four ideas, live

The whole framework rests on four ideas. Each figure below is live: move your pointer over it, or tap it on a phone.

How it works, in one picture

You define states (a screen, a popup) as lists of element scenes. At runtime, UiManager loads the scenes a state needs, hands every element its data, plays the transitions and unloads what nothing uses any more.

As simple as it looks

private async void Start()
{
    try
    {
        await UiManager.InitializeAsync();
        await UiManager.ShowState<MainMenuUiState>();
    }
    catch (Exception exception)
    {
        Debug.LogError("[Bootstrap] UI failed to start: " + exception);
    }
}

RewardParams reward = new RewardParams();
reward.Coins = 250;

// additive: true pushes the popup on top of the current screen.
await UiManager.ShowState<RewardUiState>(reward, additive: true);

// Later, from the popup's Claim button:
await UiManager.HideUI();

The professional approach, ready on day one

Large games don't keep their UI in one scene. They split it into content the team can load, own and ship separately. A state machine drives what is on screen, data is passed in, and tooling guards the structure. UI Framework gives you that approach from the first screen. An indie team builds like a professional studio, and a prototype is production-ready by default: when the game grows, nothing gets rewritten.

Built for production

Requirements

1. Install the package

In Unity, open Window → Package Manager → + → Add package from git URL… and paste:

https://github.com/dawaniyah-games/UiFramework.git?path=Packages/com.dawaniyahgames.uiframework

To pin a version, append #vX.Y.Z (see Releases), or add it to Packages/manifest.json:

{
  "dependencies": {
    "com.dawaniyahgames.uiframework": "https://github.com/dawaniyah-games/UiFramework.git?path=Packages/com.dawaniyahgames.uiframework#v1.3.6"
  }
}

2. Set up the project

1. Open Window → UI Framework → UI Setup Manager.
2. In the General tab press Create Config. Set your script and scene folders and your game's namespaces on the created UiEditorConfig.
3. Check the Global Canvas Settings in the same tab: every new element scene starts with them.

3. Make your first screen

1. Elements tab → ➕ New Element → name it MainMenuUiElement → Create. You get the script and a scene laid out as MainMenuUiElementRoot → Canvas → Root.
2. Build your UI under Root and pick a show and hide animation in the element's Animations section.
3. States tab → type MainMenuUiState next to New state → ➕. Add the MainMenuUiElement scene to it.
4. General tab → Build Runtime UiConfig. Run it again after every state or scene change.

4. Show it from code

UiManager creates itself; don't add it to a scene. It loads the generated config from Addressables.

using System;
using UiFramework.Runtime.Manager;
using UnityEngine;

public class GameBootstrap : MonoBehaviour
{
    // async void is fine for Unity messages, as long as exceptions are caught and logged.
    private async void Start()
    {
        try
        {
            if (!UiManager.IsInitialized)
            {
                await UiManager.InitializeAsync();
            }

            await UiManager.ShowState<MainMenuUiState>();
        }
        catch (Exception exception)
        {
            Debug.LogError("[GameBootstrap] UI failed to start: " + exception);
        }
    }
}

5. Give the screen its data

Whatever you pass to ShowState reaches every element of the state in Populate. Keep Populate idempotent: it runs again when another state reuses the scene.

using UiFramework.Core;
using UnityEngine;
using UnityEngine.UI;

public class MainMenuParams : UiPopulationParams
{
    public string PlayerName { get; set; }
}

public class MainMenuUiElement : UiElement
{
    [SerializeField] private Text welcomeLabel;

    public override void Populate(object context = null)
    {
        base.Populate(context);

        MainMenuParams data = context as MainMenuParams;
        if (data == null)
        {
            return;
        }

        welcomeLabel.text = "Welcome back, " + data.PlayerName;
    }
}

MainMenuParams data = new MainMenuParams();
data.PlayerName = "Alex";

await UiManager.ShowState<MainMenuUiState>(data);

Default project layout

All paths are settings on your UiEditorConfig; these are the defaults.

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.

Vocabulary

An element's lifecycle

The state stack

Shared elements and reference counting

Scenes are identified by their Addressables GUID and counted per state on the stack. The new state's scenes are counted before the old ones are released, so a scene used by both never unloads and reloads in between. A scene unloads only when its count reaches zero.

State classes are type markers

ShowState<StoreUiState>() finds the state whose key equals the class name. The runtime builds the state from the config, so code inside a UiState subclass never runs: keep behaviour in your elements. For keys without a class, use ShowStateByKey("StoreUiState").

The element scene contract

Animation targets the one object under the Canvas, so every element scene has the same shape. The Elements tab checks it and fixes it in one click.

Good to know

The ten presets

Each card loops: show, hold, hide.

What makes them feel good

Override the animation for one call

UiTransition replaces the presets for a single ShowState or HideUI call, without changing the elements' configuration. Shared elements stay still either way.

// Show the Store with a zoom this time, whatever its elements are configured to do.
await UiManager.ShowState<StoreUiState>(context, transition: UiTransition.ShowWith(TweenPresets.ScaleKey));

// Close the top state by sliding it out to the right.
await UiManager.HideUI(UiTransition.HideWith(TweenPresets.SlideRightKey));

// Both sides at once: the new screen enters moving left, the old screen leaves moving left.
await UiManager.ShowStateByKey("ProfileUiState", context, false,
    new UiTransition(TweenPresets.SlideLeftKey, TweenPresets.SlideLeftKey));

Recipe: tabs that slide in the direction you tap

// Moving to a tab on the right slides everything left (like swiping), and the other way round.
private static UiTransition GetTabTransition(ShowcaseTab from, ShowcaseTab to)
{
    if (from == to)
    {
        return UiTransition.Default;
    }

    string preset = (int)to > (int)from ? TweenPresets.SlideLeftKey : TweenPresets.SlideRightKey;
    return new UiTransition(preset, preset);
}

Button feedback

The pops and shake also work on any transform, without fading, as feedback:

await TweenPresets.ClickPop(buyButton.transform);    // quick 1.08x pop
await TweenPresets.SettlePop(coinIcon.transform);    // gentle 1.04x pulse
await TweenPresets.ShakeLocal(buyButton.transform);  // "no": not enough coins

Your own animation

ShowAsync, HideAsync and PrepareForShow are virtual. Run extra motion next to the preset, or replace it completely. Tween.RunAsync gives you the same interruptible, frame-capped loop the presets use.

public class StoreUiElement : UiElement
{
    [SerializeField] private RectTransform[] cards;

    public override void PrepareForShow()
    {
        base.PrepareForShow();
        for (int i = 0; i < cards.Length; i++)
        {
            cards[i].localScale = Vector3.zero;
        }
    }

    public override async Task ShowAsync(string presetKey = null)
    {
        Task screen = base.ShowAsync(presetKey);
        for (int i = 0; i < cards.Length; i++)
        {
            RectTransform card = cards[i];
            await Tween.RunAsync(card, 0.18f, TweenCurves.EaseOut, true, CancellationToken.None, null, eased =>
            {
                card.localScale = Vector3.one * eased;
            });
        }

        await screen;
    }
}

Introshowcase-intro.png

Homeshowcase-home.png

Storeshowcase-store.png

Leaderboardshowcase-leaderboard.png

Profileshowcase-profile.png

Reward popupshowcase-reward.png

Confirm purchaseshowcase-purchase.png

Settings popupshowcase-settings.png

Run it

1. Clone dawaniyah-games/UiFramework and open it in Unity 6.
2. Open Assets/Scenes/Bootstrapper.unity, set the Game view to portrait 1080 × 1920, and press Play.
3. Open Window → UI Framework → UI Setup Manager → Elements, change a screen's animation, and play again.

States in the app

Patterns worth copying

See it in motion

UiManager UiFramework.Runtime.Manager

UiElement UiFramework.Core

UiTransition UiFramework.Core

Preset names are matched ignoring case. An unknown name logs a warning and falls back to the elements' own animations, so a typo never breaks navigation.

TweenPresets and Tween UiFramework.Tweening

Other types

Troubleshooting

Questions