Skip to content

Developing a HUDyML Interface

HUDyML is a renderer-agnostic semantic HUD format.

A HUDyML producer emits:

  • concepts,
  • semantic types,
  • priorities,
  • layout hints,
  • and runtime values.

A HUDyML host decides how to present them.

A single HUDyML surface may be rendered as:

  • HTML,
  • a terminal HUD,
  • a game overlay,
  • OSC messages,
  • subtitles,
  • cockpit instrumentation,
  • haptics,
  • speech,
  • or accessibility tooling.

HUDyML intentionally separates:

  • semantic meaning from
  • visual presentation.

Then immediately clarify what HUDyML is NOT.

This is very important because people will otherwise misuse it.

HUDyML Is Not

HUDyML is not:

  • a CSS framework,
  • a scene graph,
  • a widget toolkit,
  • a React replacement,
  • or a game engine UI system.

HUDyML does not define:

  • pixel layout,
  • animation systems,
  • rendering technology,
  • fonts,
  • or host behavior.

It defines:

  • semantic concepts,
  • concept relationships,
  • update cadence,
  • and presentation hints.

The host remains responsible for rendering.

Then do the smallest possible example.

Again: tiny. Not “jazz session.”

Maybe:

```json id="9mt3yq" { "concepts": [ { "id": "reactor_temp", "type": "resource", "class": "temperature", "data": { "value": 74 } } ], "widgets": { "resource": { "temperature": { "type": "label", "prefix": "TEMP" } } } }


Then show:

- console rendering,
- HTML rendering,
- and hypothetical speech rendering.

Like:

```text id="2c7efv"
TEMP 74

```html id="jlwmr9"

TEMP 74

Speech:

> “Reactor temperature seventy four.”

That instantly teaches the abstraction boundary.

Then explain the pipeline.

---

# The HUDyML Pipeline

A typical HUDyML flow looks like this:

```text id="r1f1by"
runtime state
  -> semantic concepts
  -> HUDyML config
  -> transport
  -> host renderer
  -> visible/audible/tactile surface

The producer owns:

  • meaning,
  • values,
  • cadence,
  • and semantic grouping.

The host owns:

  • rendering,
  • styling,
  • accessibility,
  • and interaction.

Then introduce the concept model carefully.

Not just schema. Motivation.

Concepts

A concept is a semantic observation.

Examples:

  • temperature,
  • fuel,
  • leadership,
  • tension,
  • pressure,
  • objective state,
  • signal quality,
  • or mission progress.

Concepts should describe: what exists, not how it should look.

Good concept:

```json id="4ykmbu" { "id": "fuel", "type": "resource", "data": { "value": 0.62 } }


Bad concept:

```json id="s1zqvu"
{
  "id": "red_blinking_fuel_bar"
}

Rendering decisions belong to the host.

That distinction is absolutely essential.

Then later:

  • widgets,
  • layout hints,
  • source binding,
  • updates,
  • incremental patches,
  • synchronization,
  • and host integration.

And THEN: Walker integration.

Not earlier.

Something like:

Walker Integration

Walker includes a reference HUDyML host implementation.

Walker can:

  • resolve concepts,
  • bind runtime values,
  • sort layouts,
  • and render semantic surfaces.

However: HUDyML is intentionally host-independent.

A HUDyML producer should not assume:

  • Walker,
  • DOM rendering,
  • CSS,
  • browser APIs,
  • or even visual output.

If your surface depends on Walker-specific behavior, that behavior belongs in Walker integration code, not in the HUDyML surface definition itself.

That’s the philosophical guardrail you absolutely need.

Because otherwise people will start embedding:

  • CSS assumptions,
  • DOM assumptions,
  • and HTML metaphors into the semantic layer.

Which eventually destroys portability.

I would also strongly recommend an entire section called:

Designing Portable Concepts

And explain:

  • avoid visual naming,
  • avoid implementation naming,
  • avoid transport naming,
  • prefer semantic stability,
  • tolerate partial updates,
  • design for late joiners,
  • and support degraded hosts.

That section will save you enormous pain later.

And finally, lightly reference the future semantics doc:

Metrics and Semantic Meaning

HUDyML intentionally does not standardize metric semantics.

For example:

  • “tension,”
  • “leadership,”
  • “threat,”
  • or “stability”

may have radically different meanings across domains.

This document focuses on:

  • transport,
  • projection,
  • concepts,
  • and rendering boundaries.

For guidance on designing stable semantic metrics and avoiding accidental gamification, see: PLAN-METRICS-AND-SEMANTICS.md