CUI — Code-Driven UI for Unity

CUI is a small Unity 6 library designed for coding agents to build interfaces with UGUI directly from C#, without authoring UI Toolkit UXML or USS. Its declarative API style is inspired by ImGui, while the generated interface remains a retained UGUI hierarchy. Layouts stay diffable, support edit-mode preview, and use runtime-generated built-in shapes.

using CodeUI;

public class GameHud : UIScreen
{
    private UILabel m_Score;

    protected override void Build()
    {
        using (CUI.Plate(Anchor.TopCenter, 320f, 108f, margin: 40f))
        {
            m_Score = CUI.Label("0", 76f);
        }

        CUI.IconButton(Shape.Pause, 110f, Anchor.TopRight, margin: 40f, onClick: Pause);
    }

    protected override void Tick()
    {
        m_Score.Value = Score.Current;
    }
}

Add the screen component to an empty GameObject. CUI creates its canvas and widgets below a temporary generated child, so preview objects are never written into the scene.

Standalone example

BasicScreenExample.cs is a self-contained counter screen. Attach it to an empty GameObject and press its button in Play mode.

The editable PlantUML source is Ressource/CUI-Simple-Screen-Flow.puml.

Architecture

The editable PlantUML source is Ressource/CUI-Architecture.puml.

Features

• Code-defined, reviewable layouts with no UI prefabs.
• Edit-mode Game view preview and a global preview toggle.
• Safe-area support, reference-resolution scaling, sorting, and unscaled-time fades.
• Runtime-generated atlas for reusable shapes without imported artwork.
• Theme assets for fonts, colors, metrics, and named project sprites.
• Buttons, images, labels, horizontal sliders, rows, columns, plates, and invisible groups.
• Allocation-free integer updates through UILabel.Value and SetValue.

The generated atlas reduces texture switches for built-in shapes. Actual batches and draw calls still depend on canvas boundaries, materials, clipping, fonts, and custom sprites.

Requirements

• Unity 6; currently tested with 6000.4.
• Unity UI (com.unity.ugui 2.x).
• TextMeshPro essential resources. Import them from Window > TextMeshPro > Import TMP Essential Resources if the project does not already contain them.

Installation

Download or clone the repository, then copy the complete CUI directory into Assets/Plugins/CUI. Keep the tracked .cs.meta and .asmdef.meta files when moving it between Unity projects.

Core model

CUI is retained UI with an immediate-mode-looking declaration API:

Method	When it runs	Purpose
Build()	Once per build	Declare the hierarchy and retain widget handles
Tick()	Every frame in Play mode	Push live values into retained handles
Preview()	After an edit-mode build	Fill preview-only placeholder values
Rebuild()	On demand	Re-declare a screen after structural state changes
Spawn<T>()	On demand	Create secondary screens without scene references

Layout belongs in creation arguments. Returned handles are for changing values and state later.

API overview

Containers must be used in a using scope:

Call	Purpose
CUI.Box(...)	Invisible parent group
CUI.Plate(...)	Parent group with a background
CUI.Column(...)	Vertically arranged, content-sized children
CUI.Row(...)	Horizontally arranged, content-sized children

Widgets:

Call	Returns
CUI.Label(...)	UILabel
CUI.Image(...)	UIImage
CUI.Button(...)	UIButton
CUI.IconButton(...)	UIButton
CUI.Slider(...)	UISlider
CUI.Dim(...)	UIImage
CUI.Space(...)	No handle

Built-in shapes are White, Rounded, Circle, Ring, Play, Pause, Restart, and Arc.

Theme

Create a theme from Assets > Create > CUI > Theme. A UITheme stores the TMP font, palette, outline, padding, and named sprites. Assign it to a screen or leave the field empty to use CUI's default theme.

Put custom sprites in a Unity Sprite Atlas when batching matters. CUI's generated shapes already share one runtime atlas.

Editor preview

• Toggle preview per screen in its inspector.
• Toggle all previews from Tools > CUI > Editor Preview.
• Rebuild from the screen inspector or Tools > CUI > Rebuild All Screens.

Preview() must only update generated UI. It must not save preferences, create persistent managers, or change runtime services. CUI does not register slider callbacks outside Play mode.

Current scope

• Screen Space Overlay canvases only.
• Horizontal sliders only.
• The automatically created EventSystem uses StandaloneInputModule. Projects using only the new Input System should create their preferred EventSystem before enabling a CUI screen.
• Layout is intentionally small and does not attempt to replace every UGUI component.

License

MIT © 2026 Basel Saad.