Create UI

​

Code Rules

• ALWAYS use a coroutine when creating hierarchies
• ALWAYS add a “yield return null” after adding a component, obtain a reference to that component after the yield statement
• ALWAYS use textmeshproUGUI not Text
• ALWAYS use a callback to return new gameObjects created in coroutines
• ALWAYS create a prefab for groups of objects that are repeated, Add them to the “Prefab/GeneratedUI” folder
• ALWAYS use prefabs for objects that can be considered to be a separated section of the UI
• ALWAYS re-use a created prefab for repeated objects
• ALWAYS separate the creation of a prefab from the UI creation, create the prefab first and re-use it
• NEVER add readme code
• NEVER add code to implement the feature just the code to create the UI
• If a for, foreach or while loop is used create a prefab
• ONLY use layout groups when the number of child objects is likely to change
• Use the slider component for progress bars

​

Tool Rules

• ALWAYS provide a window for the asset hierarchy creation process
• Make this window available from a menu item inside Tools>UIBuilder>Name
• Include the ability to assign font assets where appropriate
• Include the ability to assign sprite assets where appropriate
• Ignore UI elements that could be considered decorations

​

General Rules

• Search the current scene for a canvas object to place the new UI
• Ensure that you use Unity.EditorCoroutineUtility

​

Essential UI Toolkit Guide for Unity 6.1

​

Panel Settings Asset

• Reference Resolution (e.g., 1920x1080)
• Scale Mode (Constant Pixel Size, Constant Physical Size, Scale With Screen Size)
• Screen Match Mode for aspect ratio handling
• Sort Order for layering multiple UIs

​

UXML Documents

​

USS StyleSheets

​

UI Document Component

• Panel Settings: Assign Panel Settings asset
• Source Asset: Assign UXML document
• Sort Order: Set rendering order

​

Asset Requirements

​

Fonts

• Formats: TrueType (.ttf), OpenType (.otf)
• Applied via USS -unity-font property or inline styles
• Import by dragging into Assets folder

​

Sprites and Textures

• Formats: PNG, JPG, TGA, PSD, SVG (with Vector Graphics package)
• Recommended sizes: Power-of-two (256x256, 512x512, 1024x1024)
• Icon sizes: 16x16, 24x24, 32x32, 64x64 pixels
• Use sprite atlases for batching
• 9-slice support for scalable elements

​

Core Workflow

1. Create Panel Settings → Configure rendering
2. Create UXML Document → Define structure
3. Create USS StyleSheet → Define styles
4. Link USS to UXML → Apply visual appearance
5. Create UI Document in Scene → Display at runtime
6. Use UI Builder → Visual design and iteration
7. Test in Play Mode → Verify functionality

​

Built-in UI Elements

​

Input Controls

• Button - Clickable actions
• TextField - Single-line text input
• Toggle - Boolean checkbox
• Slider, SliderInt - Numeric input with drag handle
• MinMaxSlider - Dual-handle range selector
• DropdownField - Selection from list
• EnumField - Dropdown for enums

​

Numeric Fields

• IntegerField, LongField - Integer inputs
• FloatField, DoubleField - Floating-point inputs
• Vector2Field, Vector3Field, Vector4Field - Vector inputs
• BoundsField, BoundsIntField - 3D bounds

​

Display Elements

• Label - Non-interactive text
• Image - Textures, sprites, vector images
• HelpBox - Informational messages

​

Containers

• VisualElement - Base container for grouping
• Box - Container with border styling
• GroupBox - Container with header
• Foldout - Collapsible container
• ScrollView - Scrollable content
• ListView - Virtualized list for collections
• TreeView - Hierarchical tree structure
• MultiColumnListView, MultiColumnTreeView - Tabular data displays

​

Editor-Specific

• ObjectField - Unity Object references
• ColorField - Color picker
• CurveField - Animation curve editor
• GradientField - Gradient editor

​

Best Practices

​

Web-Inspired Architecture

• UXML - Structure (like HTML)
• USS - Style (like CSS)
• C# - Behavior and logic

​

UI Builder Workflow

• Primary tool for visual authoring
• Drag-and-drop interface for rapid prototyping
• Extract inline styles to reusable USS classes
• Preview different screen sizes in viewport
• Use UI Debugger (Window → UI Toolkit → Debugger) for troubleshooting

​

Flexbox Layout

• Flex Direction: Row or column flow
• Justify Content: Main axis alignment (start, center, end, space-between)
• Align Items: Cross axis alignment (stretch, start, center, end)
• Flex Grow/Shrink: How elements expand or contract
• Use percentage-based sizes for responsive design

​

Retained Mode Architecture

• UI structure persists in memory as visual tree
• Elements created once, updated only when data changes
• Framework handles rendering optimization
• Better performance than immediate mode

​

Data Binding Pattern

• Automatically synchronize UI with data sources
• Two-way binding (UI updates data, data updates UI)
• Reduces boilerplate synchronization code
• Similar to modern web frameworks

​

Design Patterns

• MVP (Model-View-Presenter): Separate data, presentation, and logic
• State Pattern: Manage UI screens and navigation flows
• Custom Controls: Extend VisualElement for reusable components

​

Styling

​

USS Structure

• Type Selectors: Target by C# class name (e.g., Button)
• Name Selectors: Target by unique name (e.g., #playButton)
• Class Selectors: Target by USS class (e.g., .primary-button)
• Complex Selectors: Descendant selector1 selector2), child selector1 > selector2)
• Pseudo-classes: State-based :hover, :active, :focus, :disabled, :checked)

​

Style Application Methods

1. USS Files: Define reusable styles (recommended)
2. Inline Styles: Direct properties on elements (prototyping only)
3. UI Builder: Visual style modification
4. C# Scripts: Programmatic styling at runtime

​

Theme Style Sheets (TSS)

• Use @import to compose multiple stylesheets
• Switch themes at runtime for dark/light modes
• Support platform-specific or localization-based themes
• Assign to Panel Settings as default theme

​

Managing Styles at Runtime

• Add class: element.AddToClassList("className")
• Remove class: element.RemoveFromClassList("className")
• Toggle class: element.ToggleInClassList("className")
• Direct property: element.style.backgroundColor = Color.red;

​

Interactivity

​

Event System

• Default event system created automatically in Play mode
• Supports Input Manager (legacy) and Input System (new) packages
• Configure in Project Settings → Player → Active Input Handling

​

Event Types

• Pointer Events: Mouse/touch PointerDownEvent, PointerUpEvent, PointerMoveEvent)
• Click Events: Click interactions ClickEvent)
• Change Events: Value changes ChangeEvent<T>)
• Keyboard Events: Key presses KeyDownEvent, KeyUpEvent)
• Navigation Events: UI navigation NavigationMoveEvent, NavigationSubmitEvent)
• Focus Events: Focus changes FocusInEvent, FocusOutEvent)

​

Event Propagation

1. Trickle-Down: Root to target
2. Target: At the target element
3. Bubble-Up: Target back to root

​

Callback Registration

​

Focus and Navigation

• Mark elements focusable = true for keyboard focus
• Tab key navigates between focusable elements
• Arrow keys for UI navigation
• :focus pseudo-class for visual feedback

​

Manipulators

• Clickable - Click detection
• ContextualMenuManipulator - Right-click menus
• Custom manipulators for drag-drop, gestures, long-press

​

App UI Package (com.unity.dt.app-ui)

​

Key Components

• Popover - Content next to target element with arrow
• Modal - Blocking dialog centered on screen
• Tray - Bottom-anchored popup (mobile-style)
• Toast - Auto-dismiss notification at screen edge
• Tooltip - Hover information popup

​

Architecture Support

• MVVM: Model-View-ViewModel pattern
• Observables: Data binding infrastructure
• Dependency Injection: Constructor injection with lifetimes
• Navigation: Stack-based page navigation
• Context Management: Hierarchical context propagation

​

Resources

• Icon library with Phosphor Icons integration
• Typography system
• Pre-built theme TSS files (dark/light, various sizes)

​

Performance Optimization

​

Draw Call Batching

• UI Toolkit auto-batches compatible elements
• Same material/texture batch together
• Monitor in Unity Profiler

​

Dynamic Atlasing

• Automatically combines textures at runtime
• Configure in Project Settings
• Reduces draw calls for multiple images

​

Hierarchy Optimization

• Flatten visual tree where possible
• Minimize nesting depth
• Remove unnecessary containers

​

Memory Management

• Unregister callbacks when elements destroyed
• Pool and reuse elements for lists
• Release unused asset references

​

Quick Tips

• Use UI Builder for visual authoring, code for behavior only
• Prefer USS classes over inline styles for maintainability
• Design at reference resolution, use scaling modes for adaptation
• Test multiple resolutions and aspect ratios thoroughly
• Profile with Unity Profiler for performance bottlenecks
• Use data binding to reduce manual UI updates and synchronization
• Implement MVP pattern for complex UIs and better separation of concerns
• Create reusable custom controls to avoid duplication
• Use flexbox for responsive layouts that adapt to screen sizes
• Debug with UI Debugger tool for style and hierarchy inspectionSteps to create a custom tool