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

```csharp
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:

```csharp
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

```csharp
[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.