logo

Babylon.js Market

HealthBar

ui

HealthBar

Free

Install with the CLI:

bjs download HealthBar

HealthBar

A 3D billboarded HP bar that floats over any entity with Health.

What it does

HealthBar is data-only: it holds a bar width, height, a vertical offsetY, a fill color, a backgroundColor, and two flags — hideAtFullHp and fillFromLeft. Attach it to an entity that already has Health and MeshPrimitive. On the first tick HealthBarSystem builds two thin box meshes — a darker background and a colored fill — and billboards both (setMeshBillboardMode(handle, 'all')) so they always face the active camera. Each frame it reads the parent mesh's position, lifts the bar by offsetY, and scales the fill's X to hp / maxHp. At full HP the whole bar collapses to zero scale when hideAtFullHp is on. The bar emits no events — it just reads Health and draws.

Use it in a scene

A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.

Build it from scratch with the bjs CLI:

  1. 1Scaffold a project
    npm create @babylonjsmarket/arcade@latest my-game

    World, renderer, and dev server — ready to run.

  2. 2Install dependencies
    cd my-game && npm install
  3. 3Add HealthBar
    bjs download HealthBar

    Copies its source into src/ so the scene resolves.

    First time? Run bjs login once.

  4. 4Paste the scene into src/scenes/arcade-room.ts and run
    npm run dev

    SceneLoader builds the world from the JSON; reload to rebuild.

JSON
{
  "Enemy": {
    "components": {
      "MeshPrimitive": { "primitive": "capsule", "position": [0, 1, 0] },
      "Health": { "hp": 6, "maxHp": 10 },
      "HealthBar": {
        "width": 1.2,
        "offsetY": 1.4,
        "color": [0.35, 0.95, 0.45],
        "hideAtFullHp": false
      }
    }
  }
}

Props

  • width (number, default 1.2) — world-space width of the bar at full HP.
  • height (number, default 0.14) — world-space height (the thin axis); the mesh depth is derived as height * 0.4.
  • offsetY (number, default 1.0) — vertical lift above the parent mesh's origin.
  • color ([r,g,b], default [0.35, 0.95, 0.45]) — fill color (0..1); also used as the fill's emissive so it reads even in dim light.
  • backgroundColor ([r,g,b], default [0.12, 0.06, 0.08]) — empty/background color; its emissive is a dimmed 40% of this.
  • hideAtFullHp (boolean, default true) — collapse the whole bar to zero scale while the ratio is >= 0.9999, revealing it only once the entity takes damage.
  • fillFromLeft (boolean, default true) — when true the fill anchors to the left and drains right→left; false anchors it to the right.

Events

None. HealthBarSystem neither emits nor listens on the EventBus — it reads Health.hp / Health.maxHp directly each frame and drives the renderer. To react to damage, subscribe to Health's own events (health.damaged, health.died).

Dependencies

  • Health — supplies hp / maxHp; the fill ratio is hp / maxHp (a maxHp of 0 is treated as an empty bar, no divide-by-zero).
  • MeshPrimitive — supplies the parent position the bar hovers over. Both must be siblings on the same entity or the System's query skips it.

Notes

  • Billboarding rotates the meshes to face the camera but doesn't move their local origin, so the fill's left/right anchoring assumes a locked camera angle. A free-orbiting camera would need the shrink projected through the camera right-vector — out of scope here.
  • Runtime state (the two MeshHandles and the initialized one-shot flag) lives in a per-Component WeakMap on the System, keeping the Component a pure data class.
  • When an entity is deactivated (parked/pooled) the bar meshes are hidden via setMeshVisible(false) rather than disposed, and re-shown on reactivation; a full removeEntity disposes them.
  • Hiding uses a [0, 0, 1] scale on the hidden path instead of enable/disable, keeping the per-frame layout branch cheap.

More like this

Health
MeshPrimitive
CardFan
PokerHUD
PokerTableCards
Score
Scoreboard
SpaceShooterHealth
SpaceShooterScore
Waypoint

Was this page helpful?

We read every note — tell us what's working and what isn't.

↑↓ NavigateEnter SelectEsc CloseCtrl+K Open Search