> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/the-editor/game-ui-kit-widget-reference.md).

# Game UI Kit widget reference

Ready-made HUD and menu widgets with a consistent style. Use the kit for health, ammo, inventories, menus, and on-screen messages. Write custom HTML only when no widget here covers the job.

Ask the agent for a real widget by name, for example: add an `ENGINE.AmmoCounter`.

## How to use any widget

Every widget is constructed the same way. Pass the world's UI manager, then `initialize()`. Widgets extend `ENGINE.BaseUIComponent` and attach to `world.gameContainer` on their own. Do not append UI to the document root.

```typescript
const bar = new ENGINE.ProgressBar(world.uiManager, { /* options */ });
await bar.initialize();
```

{% hint style="danger" %}
*WARNING: Safe UI — player names, chat, scores, and any other network text must go through text setters (`setLabel`, `setMessage`, `setTitle`) or `element.textContent`. Never `innerHTML`, `setHTML`, `iconHtml`, or `imageHtml`. Those APIs are for developer-authored markup only. This is an XSS security rule.*
{% endhint %}

## HUD

| Widget                 | What it does                                                       |
| ---------------------- | ------------------------------------------------------------------ |
| `ENGINE.ProgressBar`   | Themed progress bar with label and percentage (health and similar) |
| `ENGINE.StatBar`       | Shield, mana, stamina, or energy HUD bar                           |
| `ENGINE.AmmoCounter`   | Current and max ammo with a low-ammo warning                       |
| `ENGINE.WeaponCard`    | Weapon name and ammo HUD card                                      |
| `ENGINE.Crosshair`     | Configurable center reticle                                        |
| `ENGINE.AbilityIcon`   | Ability slot with hotkey and cooldown radial                       |
| `ENGINE.CenterMessage` | Full-screen hero banner (victory or defeat)                        |
| `ENGINE.Message`       | Compact single-line chat or system message                         |

## Inventory

| Widget                 | What it does                                 |
| ---------------------- | -------------------------------------------- |
| `ENGINE.InventoryBar`  | Horizontal hotbar with add, remove, and find |
| `ENGINE.InventoryGrid` | Full-screen drag-and-drop grid inventory     |
| `ENGINE.ItemCard`      | Item card with rarity, quantity, and price   |

## Feedback

| Widget                     | What it does                                 |
| -------------------------- | -------------------------------------------- |
| `ENGINE.Achievement`       | Toast notification with rarity border        |
| `ENGINE.NotificationBadge` | Unread count or dot overlay                  |
| `ENGINE.ReloadIndicator`   | Circular reload or cooldown progress overlay |
| `ENGINE.Tooltip`           | Floating anchored hint panel                 |

## Navigation and menus

| Widget                 | What it does                                       |
| ---------------------- | -------------------------------------------------- |
| `ENGINE.Compass`       | HUD compass driven by camera rotation              |
| `ENGINE.Minimap`       | Radar-style player and target tracking             |
| `ENGINE.NavItem`       | Sidebar nav row with icon, label, and active state |
| `ENGINE.ControlsPanel` | Keyboard and mouse bindings help panel             |

## Data display

| Widget                 | What it does                                           |
| ---------------------- | ------------------------------------------------------ |
| `ENGINE.Avatar`        | Round profile picture with initials and status dot     |
| `ENGINE.Badge`         | Pill status or category label (8 colors, 3 sizes)      |
| `ENGINE.Card`          | Surface container (default, glass, elevated)           |
| `ENGINE.ChatMessage`   | Chat row with avatar, name, timestamp, and body        |
| `ENGINE.Keystroke`     | Keyboard key chip for keybind hints                    |
| `ENGINE.NumberDisplay` | Stats card with animated value and trend chip          |
| `ENGINE.PlayerCard`    | Player avatar, name or handle, optional badge or score |
| `ENGINE.StatCard`      | Metric card with icon, value, trend, and subtitle      |

## Controls and input

| Widget          | What it does                                                     |
| --------------- | ---------------------------------------------------------------- |
| `ENGINE.Button` | Interactive button: variants, sizes, disabled and loading states |
| `ENGINE.Toggle` | Pill on/off switch                                               |
| `ENGINE.Input`  | Text field with label, helper or error, optional icons           |

*Last verified against engine 14.x on 16 Aug 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/the-editor/game-ui-kit-widget-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.