Skip to main content
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; 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:
2. Add a bar. A type:"bar" element with a fill in [0, 1] — a health or progress bar:
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:
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:

​
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

​
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.

UI & HUD endpoints

HUD text, bar, list, and clear endpoints, with request and response schemas.