unity_agent/knowledge/entries/unity_ui.md

Unity UI

Unity ships two UI systems:

1. uGUI (UnityEngine.UI) -- the Canvas-based system that has been standard since Unity 4.6. Used by the generated UIManager.cs.
2. UI Toolkit -- the new web-style (UXML/USS) system. Not used here.

Canvas

The Canvas is the root of every UI hierarchy. There are three render modes:

Mode	Use case
ScreenSpaceOverlay	UI drawn on top of everything (default, cheapest)
ScreenSpaceCamera	UI positioned in front of a specific camera
WorldSpace	UI lives in the 3D world (health bars, dialogue bubbles)

Set the Canvas Scaler to Scale With Screen Size with a reference resolution of 1920x1080 for desktop games.

Common components

• Image -- a sprite or solid color rectangle.
• Text (uGUI) / TMP_Text (TextMeshPro) -- text. TMP produces sharper glyphs and is preferred; the UIManager.cs generator uses TMP_Text.
• Button -- a clickable button with onClick events.
• Slider -- a draggable value selector.
• Toggle -- a checkbox.
• ScrollRect -- a scrolling viewport.
• InputField / TMP_InputField -- text entry.

Layout

• VerticalLayoutGroup / HorizontalLayoutGroup / GridLayoutGroup -- auto-arrange children.
• LayoutElement -- override min/preferred sizes.
• ContentSizeFitter -- resize a container to fit its children.

Anchoring

Anchors determine how a UI element scales with its parent. Use the anchor presets in the inspector to pin an element to a corner, edge, or center.

• Top-left HUD elements: anchor top-left.
• Health bars that grow left-to-right: anchor top-left, pivot (0, 0.5).
• Centered messages: anchor middle-center.

Health bar recipe

public Image healthBarFill;

private void Update()
{
    healthBarFill.fillAmount = Mathf.Clamp01(currentHealth / maxHealth);
}

• Use an Image with Image Type = Filled, Fill Method = Horizontal to get a depleting bar.
• Place a darker Image behind it as the background.
• For a world-space health bar, parent a Canvas to the enemy with Render Mode = World Space and use a LookAtCamera script to keep it facing the camera.

HUD wiring pattern

The generated UIManager.cs is a singleton that other systems call:

UIManager.Instance.SetScore(PickupSystem.Instance.score);
UIManager.Instance.SetHealth(health.Current, health.Max);
UIManager.Instance.SetMessage("Level Complete!");

The HUD GameObjects (TMP_Text, Image) are assigned in the inspector. The GameManager bootstrapper in the example game wires these up at runtime if they are missing.

Buttons and events

[SerializeField] private Button restartButton;

private void OnEnable()  => restartButton.onClick.AddListener(Restart);
private void OnDisable() => restartButton.onClick.RemoveListener(Restart);

private void Restart() => SceneManager.LoadScene(SceneManager.GetActiveScene().buildIndex);

• Always unsubscribe from events in OnDisable to avoid leaks.
• UnityEvent fields (e.g. Button.onClick) let designers wire callbacks in the inspector without code changes.

TMP essentials

• Use TMP_Text instead of Text for any text the player reads -- the rendering quality is dramatically better.
• Generate a TMP Font Asset via Window > TextMeshPro > Font Asset Creator.
• TMP_Dropdown, TMP_InputField, and TMP_Text are drop-in replacements for the uGUI equivalents.

Performance

• Mark static UI elements as Static in the Canvas to batch them.
• Split a complex UI into multiple Canvases so a single text change does not rebuild the entire hierarchy.
• Avoid LayoutGroup chains deeper than 3 levels on mobile -- they are expensive to rebuild.
• Pool item tooltips, inventory slots and damage popups instead of instantiating/destroying them every frame.