> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eucaengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UI & HUD

> Build a HUD: add text and bars to a canvas, read the element list back, and clear it — the data model behind the on-screen overlay, on a local server.

A HUD in Euca is a list of **elements on a canvas** — each a tagged `text`, `bar`, or `rect` with a
screen position and style. You add them, list them, and clear them over HTTP; a render host draws the
canvas every frame. The element *model* is fully headless; only turning those elements into pixels
needs a GPU. The catch this page makes explicit: the canvas itself is a world resource the host owns,
and the minimal server doesn't register one — so adds return `ok:true` but the list stays empty. Every
command is real and runnable against a [local server](/quickstart); output is captured from one.

## Build a HUD

**1. Add a text element.** The body is a tagged `HudElement` — `type:"text"` plus a position, size,
and color name:

```bash theme={null}
curl -s -X POST http://localhost:3917/ui/text -H 'Content-Type: application/json' \
  -d '{"type":"text","text":"Score: 3","x":20,"y":20,"size":24,"color":"white"}'
# {"ok":true}
```

**2. Add a bar.** A `type:"bar"` element with a `fill` in `[0, 1]` — a health or progress bar:

```bash theme={null}
curl -s -X POST http://localhost:3917/ui/bar -H 'Content-Type: application/json' \
  -d '{"type":"bar","x":20,"y":60,"width":0.3,"height":0.04,"fill":0.75,"color":"green"}'
# {"ok":true}
```

**3. List the canvas — and see the host gate.** On the minimal server the list comes back *empty*,
because no `HudCanvas` resource is registered to receive the adds:

```bash theme={null}
curl -s http://localhost:3917/ui/list
# {"count":0,"elements":[]}
```

On a host that **registers a `HudCanvas`** (the editor and game hosts do), the same two adds populate
it, and `/ui/list` returns each element as a tagged value — e.g.
`{"elements":[{"type":"text","text":"Score: 3","x":20.0,"y":20.0,"size":24.0,"color":"white"}],
"count":1}`.

**4. Clear the HUD.** Removes all elements; this one reports a message regardless:

```bash theme={null}
curl -s -X POST http://localhost:3917/ui/clear
# {"ok":true,"message":"HUD cleared"}
```

## Behavior and gotchas

The things you only find out by running it:

* **`ok:true` from `/ui/text` and `/ui/bar` does not mean added.** Like templates, these only push onto
  the canvas **if a `HudCanvas` resource exists** (`if let Some(canvas) = …`). On the bare server the
  add is silently dropped and still returns `ok:true`. Trust `/ui/list`, not the add response.
* **`/ui/clear` always reports a message** (`{"ok":true,"message":"HUD cleared"}`) even with no canvas —
  it's the one HUD endpoint that returns a message, but it clears only the canvas the host owns.
* **The element body is a tagged enum.** `type` is required and selects the variant: `text`
  (`text`, `x`, `y`, `size`, `color`), `bar` (`x`, `y`, `width`, `height`, `fill`, `color`), or `rect`
  (`x`, `y`, `width`, `height`, `color`). Color is a name string (`"white"`, `"green"`), not an array.
* **No `/step` needed.** Adding, listing, and clearing are immediate; the HUD canvas is mutated on the
  call, not on a tick.
* **Layout and draw live above this surface.** The richer `euca-ui` flex layout, button hit-testing, and
  world-space projection resolve in the engine, but the HTTP surface here is the flat HUD element list;
  drawing it (fonts, quads) is the render host's job.

## Endpoints

| Method | Path        | Description                                                                |
| ------ | ----------- | -------------------------------------------------------------------------- |
| `POST` | `/ui/text`  | Append a `text` element to the HUD canvas                                  |
| `POST` | `/ui/bar`   | Append a `bar` element (`fill` in `[0, 1]`) to the HUD canvas              |
| `GET`  | `/ui/list`  | The current HUD elements (each tagged `text`/`bar`/`rect`) and their count |
| `POST` | `/ui/clear` | Remove all HUD elements                                                    |

## Status

* **Shipped & headless** — the HUD element model (`text`/`bar`/`rect`), the add/list/clear logic, and
  the canvas resource type. The full `euca-ui` flex layout and input routing run headless too.
* **Host-dependent** — the `HudCanvas` resource itself. The minimal example server doesn't register one,
  so adds no-op and `/ui/list` is empty; a host that registers a `HudCanvas` makes the
  add→list→clear loop work. Drawing the canvas to the screen needs a render host.

<Card title="UI & HUD endpoints" icon="window-maximize" href="/api-reference/introduction" horizontal>
  HUD text, bar, list, and clear endpoints, with request and response schemas.
</Card>