Entity UI

Entity UI renders in world space, attached to entities. Used for health bars, damage numbers, and nameplates.

Components

Component	Purpose
`EntityStatUIComponent`	Health bars, stat displays
`CombatTextUIComponent`	Floating damage/heal numbers

Health Bars

Health bars are configured through entity assets, not code. The EntityStatUIComponent displays stats based on entity configuration.

Asset Configuration

In your entity’s JSON asset:

{
  "ui": {
    "statBar": {
      "stat": "health",
      "visible": "damaged",
      "offset": [0, 2.5, 0]
    }
  }
}

Options for visible:

"always" - Always show
"damaged" - Show when not at full health
"never" - Never show

Combat Text

Floating numbers that appear when entities take damage or heal. Combat text is triggered automatically by the damage system - there’s no direct API to spawn it.

Animation Types

Type	Properties
`Scale`	`startScale`, `endScale`
`Position`	`positionOffset` (Vector2f)
`Opacity`	`startOpacity`, `endOpacity`

Timing

Animations use normalized time (0.0 to 1.0):

{
  "startAt": 0.0,
  "endAt": 0.5
}

Asset Configuration

Combat text is configured in damage system assets:

{
  "combatText": {
    "duration": 1.0,
    "animations": [
      {
        "type": "Scale",
        "startScale": 1.5,
        "endScale": 1.0,
        "startAt": 0.0,
        "endAt": 0.3
      },
      {
        "type": "Position",
        "positionOffset": [0, 50],
        "startAt": 0.0,
        "endAt": 1.0
      },
      {
        "type": "Opacity",
        "startOpacity": 1.0,
        "endOpacity": 0.0,
        "startAt": 0.7,
        "endAt": 1.0
      }
    ]
  }
}

Entity UI vs Other Systems

System	Space	Use Case
Entity UI	World	Health bars, damage numbers
HUD	Screen	Persistent player info
Custom Pages	Screen	Menus, dialogs

Entity UI follows the entity in 3D space and scales with distance.

Nameplate Configuration

Nameplates for NPCs and players:

{
  "ui": {
    "nameplate": {
      "visible": "always",
      "offset": [0, 2.2, 0],
      "showHealth": true,
      "showName": true
    }
  }
}

Visibility Conditions

Control when entity UI appears:

Condition	Behavior
`always`	Always visible
`hover`	Visible when looking at entity
`damaged`	Visible when health < max
`never`	Never visible
`targeted`	Visible when targeted