Health bars

world-space bars over enemies, damage numbers, and a fixed HUD

▶ Run in browser

Tags: ui hud camera tween signals

Enemies wander the world with health bars floating above them; the bars are drawn in world space, so they scroll with a smoothed Camera2D that follows the player. Hits spawn floating damage numbers that rise and fade on a coroutine, and a killed enemy is removed cleanly (its death is a signal the HUD counts). The player’s portrait and health bar are anchored Controls, so they stay glued to the screen while the whole world pans underneath.

What it demonstrates

• World-space draws (enemy bodies + their health bars) following entities under a moving Camera2D, next to screen-anchored Controls that do not scroll.

• Floating damage numbers: a per-node coroutine rises and fades, then destroy().

• A smooth HUD drain: tween() eases the player bar toward the real value.

• Click-to-hit through camera.screen_to_world, clean removal via a died signal.

Controls: WASD / arrows - Move (the camera follows) Left click - Hit the enemy under the pointer SPACE - Melee swing at the nearest enemy in range ESC - Quit

Run: uv run python examples/features/ui/health_bars.py Headless self-check: uv run python examples/features/ui/health_bars.py –test

Source

"""Health bars: world-space bars over enemies, damage numbers, and a fixed HUD

Enemies wander the world with health bars floating above them; the bars are
drawn in world space, so they scroll with a smoothed Camera2D that follows the
player. Hits spawn floating damage numbers that rise and fade on a coroutine,
and a killed enemy is removed cleanly (its death is a signal the HUD counts).
The player's portrait and health bar are anchored Controls, so they stay glued
to the screen while the whole world pans underneath.

# /// simvx
# tags = ["ui", "hud", "camera", "tween", "signals"]
# web = { root = "HealthBarsDemo", width = 960, height = 540, responsive = true }
# ///

## What it demonstrates
- World-space draws (enemy bodies + their health bars) following entities under
  a moving Camera2D, next to screen-anchored Controls that do not scroll.
- Floating damage numbers: a per-node coroutine rises and fades, then destroy().
- A smooth HUD drain: `tween()` eases the player bar toward the real value.
- Click-to-hit through `camera.screen_to_world`, clean removal via a died signal.

Controls:
  WASD / arrows - Move (the camera follows)
  Left click    - Hit the enemy under the pointer
  SPACE         - Melee swing at the nearest enemy in range
  ESC           - Quit

Run: uv run python examples/features/ui/health_bars.py
Headless self-check: uv run python examples/features/ui/health_bars.py --test
"""

import math
import random

from simvx.core import (
    AnchorPreset,
    Camera2D,
    CanvasLayer,
    Colour,
    Input,
    Key,
    Label,
    MouseButton,
    Node2D,
    Panel,
    Signal,
    Vec2,
    easing,
    tween,
    wait,
)
from simvx.graphics import App

WIDTH, HEIGHT = 960, 540
WORLD = 900  # half-size of the walkable world
PAD = 14.0  # HUD gutter from the screen edges
PORTRAIT = 56.0  # portrait panel side, pixels
BAR_W, BAR_H = 200.0, 16.0  # player health bar, pixels
PLAYER_R = 14.0
PLAYER_MAX_HP = 100.0
PLAYER_REGEN = 4.0  # hp per second
CONTACT_DAMAGE = 10
MELEE_RANGE = 150.0
WAVE_SIZE = 5
NUMBER_LIFE = 0.9  # damage number lifetime, seconds
NUMBER_RISE = 46.0  # how far a damage number climbs, world pixels


def _hp_colour(frac: float) -> tuple[float, float, float, float]:
    """Green when healthy, amber when hurt, red when critical."""
    if frac > 0.6:
        return (0.26, 0.77, 0.39, 1.0)
    if frac > 0.3:
        return (0.96, 0.64, 0.38, 1.0)
    return (0.90, 0.22, 0.27, 1.0)


def _pin_bottom_left(ctrl, x: float, y_up: float, w: float, h: float) -> None:
    """Anchor a top-level Control to the bottom-left corner.

    With both anchors collapsed on a corner, the margin pairs define the box:
    ``x``/``y_up`` are the gutters from the left and bottom edges, ``w``/``h``
    the box size. The box then tracks the corner on resize.
    """
    ctrl.set_anchor_preset(AnchorPreset.BOTTOM_LEFT)
    ctrl.margin_left = x
    ctrl.margin_right = x + w
    ctrl.margin_top = -(y_up + h)
    ctrl.margin_bottom = -y_up


class DamageNumber(Node2D):
    """A floating number that rises, fades, and destroys itself."""

    dynamic = True  # position and alpha change every frame

    def __init__(self, text: str, colour: tuple[float, float, float], scale: float = 1.4, **kwargs):
        super().__init__(**kwargs)
        self._text = text
        self._colour = colour
        self._scale = scale
        self._alpha = 1.0

    def on_ready(self):
        self.start_coroutine(self._animate())

    def _animate(self):
        start_y = float(self.position.y)
        t = 0.0
        while t < NUMBER_LIFE:
            dt = yield  # the driver sends per-tick dt
            t += dt
            f = min(t / NUMBER_LIFE, 1.0)
            self.position = Vec2(self.position.x, start_y - NUMBER_RISE * easing.ease_out_cubic(f))
            self._alpha = (1.0 - f) ** 1.5
        self.destroy()

    def on_draw(self, renderer):
        r, g, b = self._colour
        renderer.draw_text(
            self._text,
            (self.position.x, self.position.y),
            colour=(r, g, b, self._alpha),
            scale=self._scale,
            alignment="centre",
            outline=0.08,
        )


class Enemy(Node2D):
    """A wandering enemy with hit points and a world-space health bar."""

    dynamic = True  # wobbles and its bar tracks hp every frame

    died = Signal(object)  # emitted with the enemy just before removal

    def __init__(self, home: Vec2, max_hp: int, colour: tuple[float, float, float, float], **kwargs):
        super().__init__(position=Vec2(home.x, home.y), **kwargs)
        self._home = Vec2(home.x, home.y)
        self.max_hp = max_hp
        self.hp = max_hp
        self.colour = colour
        self.radius = 14.0 + max_hp * 0.1
        self._t = random.uniform(0.0, 10.0)
        self._speed = random.uniform(0.8, 1.4)
        self._flash = 0.0  # white hit flash, seconds left
        self.touch_cd = 0.0  # contact-damage cooldown, seconds left
        self._dead = False

    def on_update(self, dt: float):
        self._t += dt
        self.position = self._home + Vec2(
            math.sin(self._t * self._speed) * 14.0,
            math.sin(self._t * self._speed * 0.7 + 1.7) * 9.0,
        )
        self._flash = max(0.0, self._flash - dt)
        self.touch_cd = max(0.0, self.touch_cd - dt)

    def take_damage(self, amount: int) -> None:
        """Apply damage, spawn a floating number, and die at zero hp."""
        if self._dead:
            return
        self.hp = max(0, self.hp - amount)
        self._flash = 0.12
        killed = self.hp == 0
        p = self.world_position
        self.parent.add_child(
            DamageNumber(
                str(amount),
                (1.0, 0.36, 0.30) if killed else (1.0, 0.85, 0.40),
                scale=1.9 if killed else 1.4,
                position=Vec2(p.x + random.uniform(-8, 8), p.y - self.radius - 22),
            )
        )
        if killed:
            self._dead = True
            self.died.emit(self)
            self.destroy()  # deferred: carried out at end of frame, safe here

    def on_draw(self, renderer):
        p = self.world_position
        body = (1.0, 1.0, 1.0, 1.0) if self._flash > 0 else self.colour
        renderer.draw_circle((p.x, p.y), self.radius, colour=body, filled=True)
        renderer.draw_circle((p.x, p.y), self.radius, colour=(0.10, 0.10, 0.14, 1.0), filled=False)

        # The floating health bar, in WORLD coordinates: it follows this enemy
        # and scrolls with the camera like everything else drawn here.
        frac = self.hp / self.max_hp
        bw, bh = 46.0, 5.0
        top = (p.x - bw / 2, p.y - self.radius - 14)
        renderer.draw_rect(top, (bw, bh), colour=(0.08, 0.08, 0.11, 0.9), filled=True)
        renderer.draw_rect(top, (bw * frac, bh), colour=_hp_colour(frac), filled=True)
        renderer.draw_rect(top, (bw, bh), colour=(0.85, 0.9, 1.0, 0.5), filled=False)


class Player(Node2D):
    """The player avatar; movement only, hp lives on the demo root."""

    dynamic = True
    SPEED = 300.0

    def on_update(self, dt: float):
        v = Input.get_vector("move_left", "move_right", "move_up", "move_down")
        self.position += v * self.SPEED * dt
        self.position.x = max(-WORLD, min(WORLD, self.position.x))
        self.position.y = max(-WORLD, min(WORLD, self.position.y))

    def on_draw(self, renderer):
        p = self.world_position
        renderer.draw_circle((p.x, p.y), PLAYER_R, colour=(0.36, 0.72, 1.0, 1.0), filled=True)
        renderer.draw_circle((p.x, p.y), PLAYER_R * 0.45, colour=(0.9, 0.97, 1.0, 1.0), filled=True)


class Ground(Node2D):
    """Static scroll reference: drawn once, panned by the camera thereafter."""

    def on_draw(self, renderer):
        for gx in range(-WORLD, WORLD + 1, 120):
            for gy in range(-WORLD, WORLD + 1, 120):
                renderer.draw_circle((gx, gy), 2.5, colour=(0.28, 0.29, 0.35, 1.0), filled=True)
        renderer.draw_rect((-WORLD, -WORLD), (WORLD * 2, WORLD * 2), colour=(0.45, 0.48, 0.6, 1.0), filled=False)


class HealthBarsDemo(Node2D):
    """Root: world, camera, combat, and the screen-anchored player HUD."""

    dynamic = True  # draws the melee swing flash

    input_actions = {
        "move_left": [Key.A, Key.LEFT],
        "move_right": [Key.D, Key.RIGHT],
        "move_up": [Key.W, Key.UP],
        "move_down": [Key.S, Key.DOWN],
        "click": [MouseButton.LEFT],
        "attack": [Key.SPACE],
        "quit": [Key.ESCAPE],
    }

    def on_ready(self):
        self._player_hp = PLAYER_MAX_HP
        self._shown_hp = PLAYER_MAX_HP  # what the HUD bar displays; tweens toward the truth
        self._drain = None  # handle of the running HUD tween, if any
        self._kills = 0
        self._swing = 0.0  # melee flash, seconds left
        self._respawning = False
        self._enemies: list[Enemy] = []

        self.add_child(Ground(name="Ground"))
        self._player = self.add_child(Player(name="Player", position=Vec2(0, 0)))
        self._camera = self.add_child(Camera2D(name="Camera"))
        self._camera.target = self._player
        self._camera.smoothing = 5.0

        self._build_hud()
        self._spawn_wave()

    # ------------------------------------------------------------- HUD
    def _build_hud(self):
        # Everything below is a Control anchored to the SCREEN. The CanvasLayer
        # is what makes that literal: a Control parented straight to a Node2D
        # still renders through the world camera and pans with it; a CanvasLayer
        # subtree skips the camera entirely.
        self._hud = self.add_child(CanvasLayer(name="HUD"))
        self._portrait = Panel(name="Portrait")
        _pin_bottom_left(self._portrait, PAD, PAD, PORTRAIT, PORTRAIT)
        self._portrait.bg_colour = Colour.hex("#1B1B22")
        self._hud.add_child(self._portrait)

        # A stylised face inside the frame; its colour tracks the hp band.
        self._face = Panel(name="Face")
        self._face.margin_left = 6
        self._face.margin_top = 6
        self._face.size = Vec2(PORTRAIT - 12, PORTRAIT - 12)
        self._portrait.add_child(self._face)
        for ex in (14.0, 32.0):
            eye = Panel()
            eye.margin_left = ex
            eye.margin_top = 16
            eye.size = Vec2(6, 8)
            eye.bg_colour = Colour.hex("#1B1B22")
            self._face.add_child(eye)
        mouth = Panel()
        mouth.margin_left = 14
        mouth.margin_top = 34
        mouth.size = Vec2(PORTRAIT - 40, 4)
        mouth.bg_colour = Colour.hex("#1B1B22")
        self._face.add_child(mouth)

        self._bar_bg = Panel(name="HealthBarBG")
        _pin_bottom_left(self._bar_bg, PAD + PORTRAIT + 10, PAD + (PORTRAIT - BAR_H) / 2, BAR_W, BAR_H)
        self._bar_bg.bg_colour = Colour.hex("#1B1B22")
        self._hud.add_child(self._bar_bg)

        self._bar_fill = Panel(name="HealthBarFill")
        self._bar_fill.margin_left = 2
        self._bar_fill.margin_top = 2
        self._bar_fill.size = Vec2(BAR_W - 4, BAR_H - 4)
        self._bar_bg.add_child(self._bar_fill)

        self._hp_label = Label("")
        self._hp_label.set_anchor_preset(AnchorPreset.CENTER)
        self._hp_label.margin_left = -BAR_W / 2
        self._hp_label.margin_right = BAR_W / 2
        self._hp_label.margin_top = -BAR_H / 2
        self._hp_label.margin_bottom = BAR_H / 2
        self._hp_label.font_size = 11.0
        self._hp_label.text_colour = Colour.WHITE
        self._hp_label.alignment = "center"
        self._bar_bg.add_child(self._hp_label)

        self._kills_label = Label("Kills: 0")
        self._kills_label.set_anchor_preset(AnchorPreset.TOP_RIGHT)
        self._kills_label.margin_left = -180 - PAD
        self._kills_label.margin_right = -PAD
        self._kills_label.margin_top = PAD
        self._kills_label.margin_bottom = PAD + 24
        self._kills_label.font_size = 16.0
        self._kills_label.text_colour = Colour.hex("#FFD166")
        self._kills_label.alignment = "right"
        self._hud.add_child(self._kills_label)

        hint = Label("WASD/arrows move  |  click an enemy or SPACE to attack  |  ESC quit")
        hint.set_anchor_preset(AnchorPreset.CENTER_BOTTOM)
        hint.margin_left = -260
        hint.margin_right = 260
        hint.margin_top = -30
        hint.margin_bottom = -10
        hint.font_size = 13.0
        hint.text_colour = Colour.LIGHT_GRAY
        hint.alignment = "center"
        self._hud.add_child(hint)

    # ------------------------------------------------------------- waves
    def _spawn_wave(self):
        centre = self._player.world_position
        for i in range(WAVE_SIZE):
            angle = i * (2 * math.pi / WAVE_SIZE) + random.uniform(-0.4, 0.4)
            dist = random.uniform(170, 330)
            home = Vec2(
                max(-WORLD + 50, min(WORLD - 50, centre.x + math.cos(angle) * dist)),
                max(-WORLD + 50, min(WORLD - 50, centre.y + math.sin(angle) * dist)),
            )
            max_hp, colour = random.choice(
                [
                    (40, (0.55, 0.78, 0.42, 1.0)),
                    (60, (0.72, 0.55, 0.90, 1.0)),
                    (80, (0.88, 0.47, 0.36, 1.0)),
                ]
            )
            enemy = Enemy(home, max_hp, colour)
            enemy.died.connect(self._on_enemy_died)
            self._enemies.append(self.add_child(enemy))

    def _on_enemy_died(self, enemy):
        self._enemies.remove(enemy)
        self._kills += 1
        self._kills_label.text = f"Kills: {self._kills}"
        if not self._enemies and not self._respawning:
            self._respawning = True
            self.start_coroutine(self._next_wave())

    def _next_wave(self):
        yield from wait(1.5)
        self._spawn_wave()
        self._respawning = False

    # ------------------------------------------------------------- combat
    def _hurt_player(self, amount: float):
        self._player_hp = max(0.0, self._player_hp - amount)
        self._camera.shake(4.0, 0.25)
        p = self._player.world_position
        self.add_child(
            DamageNumber(str(int(amount)), (1.0, 0.36, 0.30), position=Vec2(p.x, p.y - PLAYER_R - 20))
        )
        # Ease the HUD bar down to the new value rather than snapping it.
        if self._drain is not None:
            self.stop_coroutine(self._drain)
        self._drain = self.start_coroutine(
            tween(self, "_shown_hp", self._player_hp, 0.4, easing=easing.ease_out_cubic, on_complete=self._drain_done)
        )

    def _drain_done(self):
        self._drain = None

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return

        # Click: map the pointer through the camera into world space and hit-test.
        if Input.is_action_just_pressed("click"):
            world = self._camera.screen_to_world(Input.mouse_position, Vec2(*self.tree.screen_size))
            for enemy in list(self._enemies):
                offset = enemy.world_position - world
                if math.hypot(offset.x, offset.y) <= enemy.radius + 6:
                    enemy.take_damage(random.randint(12, 24))
                    break

        # Melee: swing at the nearest enemy within range of the player.
        if Input.is_action_just_pressed("attack"):
            self._swing = 0.18
            pp = self._player.world_position
            in_range = [
                (math.hypot(e.world_position.x - pp.x, e.world_position.y - pp.y), e) for e in self._enemies
            ]
            in_range = [(d, e) for d, e in in_range if d <= MELEE_RANGE]
            if in_range:
                min(in_range, key=lambda pair: pair[0])[1].take_damage(random.randint(15, 25))
        self._swing = max(0.0, self._swing - dt)

        # Contact damage, throttled per enemy.
        pp = self._player.world_position
        for enemy in self._enemies:
            ep = enemy.world_position
            if enemy.touch_cd <= 0 and math.hypot(ep.x - pp.x, ep.y - pp.y) < enemy.radius + PLAYER_R + 4:
                enemy.touch_cd = 1.0
                self._hurt_player(CONTACT_DAMAGE)

        # Slow regeneration; the HUD follows directly whenever no drain tween runs.
        self._player_hp = min(PLAYER_MAX_HP, self._player_hp + PLAYER_REGEN * dt)
        if self._drain is None:
            self._shown_hp = self._player_hp

        # Refresh the screen-anchored HUD from the displayed value.
        frac = self._shown_hp / PLAYER_MAX_HP
        self._bar_fill.size = Vec2((BAR_W - 4) * frac, BAR_H - 4)
        self._bar_fill.bg_colour = Colour(_hp_colour(frac))
        self._face.bg_colour = Colour(_hp_colour(self._player_hp / PLAYER_MAX_HP))
        self._hp_label.text = f"HP {int(round(self._player_hp))} / {int(PLAYER_MAX_HP)}"

    def on_draw(self, renderer):
        if self._swing > 0:
            p = self._player.world_position
            renderer.draw_circle(
                (p.x, p.y), MELEE_RANGE, colour=(0.9, 0.95, 1.0, self._swing * 2.5), filled=False
            )


def _selftest() -> bool:
    """Headless: drive the combat through real input and watch the HUD follow.

    Clicks go through the camera's screen mapping, so the hit-test is the one a
    player uses; damage numbers, removal and the wave respawn are watched on the
    live tree; and the screen-anchored HUD is checked to hold still while the
    world scrolls past it.
    """
    from simvx.core.testing import InputSimulator, SceneRunner

    random.seed(7)
    runner = SceneRunner(screen_size=(WIDTH, HEIGHT))
    scene = HealthBarsDemo(name="HealthBarsDemo")
    runner.load(scene)
    sim = InputSimulator(tree=runner.tree)
    runner.advance_frames(5)
    screen = Vec2(WIDTH, HEIGHT)
    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    def click_at(world_pos) -> None:
        sp = scene._camera.world_to_screen(world_pos, screen)
        sim.press_mouse(MouseButton.LEFT, (sp.x, sp.y))
        runner.advance_frames(1)
        sim.release_mouse()
        runner.advance_frames(1)

    def numbers() -> list[DamageNumber]:
        return [c for c in scene.children if isinstance(c, DamageNumber)]

    check("a wave of enemies spawns", len(scene._enemies) == WAVE_SIZE, f"{len(scene._enemies)} of {WAVE_SIZE}")

    # One click through the camera mapping damages the enemy under the pointer.
    enemy = scene._enemies[0]
    before = enemy.hp
    click_at(enemy.world_position)
    check("clicking an enemy deals damage", enemy.hp < before, f"hp {before} -> {enemy.hp}")
    spawned = numbers()
    check("the hit spawned a damage number", len(spawned) == 1, f"{len(spawned)} numbers in the tree")

    # The number rises and fades on its coroutine, then removes itself.
    number = spawned[0]
    y0, a0 = float(number.position.y), number._alpha
    runner.advance_frames(20)
    risen = float(number.position.y) < y0 and number._alpha < a0
    detail = f"y {y0:.0f} -> {number.position.y:.0f}, alpha {a0:.2f} -> {number._alpha:.2f}"
    check("the number rises and fades", risen, detail)
    runner.advance_frames(int(NUMBER_LIFE * 60) + 20)
    check("and removes itself when spent", not numbers(), f"{len(numbers())} numbers left")

    # Clicking until the enemy dies removes it cleanly and counts the kill.
    for _ in range(40):
        if enemy not in scene._enemies:
            break
        click_at(enemy.world_position)
    check(
        "a killed enemy leaves the tree",
        enemy not in scene._enemies and enemy.parent is None,
        f"in list: {enemy in scene._enemies}, parent: {enemy.parent}",
    )
    check("and the kill is counted", scene._kills == 1 and "1" in scene._kills_label.text, scene._kills_label.text)

    # SPACE swings at the nearest enemy in range.
    target = scene._enemies[0]
    scene._player.position = Vec2(target._home.x + target.radius + PLAYER_R + 40, target._home.y)
    runner.advance_frames(1)
    before = target.hp
    sim.press_key(Key.SPACE)
    runner.advance_frames(1)
    sim.release_key(Key.SPACE)
    runner.advance_frames(1)
    check("SPACE melees the nearest enemy in range", target.hp < before, f"hp {before} -> {target.hp}")

    # Standing on an enemy costs the player health; the HUD bar tweens after it.
    scene._player.position = Vec2(target._home.x, target._home.y)
    runner.advance_frames(2)
    hp_after_hit = scene._player_hp
    lagging = scene._shown_hp > hp_after_hit
    check("contact damage drains the player", hp_after_hit < PLAYER_MAX_HP, f"hp {hp_after_hit:.1f}")
    check("the HUD bar lags behind on a tween", lagging, f"shown {scene._shown_hp:.1f} vs hp {hp_after_hit:.1f}")
    scene._player.position = Vec2(target._home.x + 400, target._home.y)  # step off before the next tick
    runner.advance_frames(40)
    settled = abs(scene._shown_hp - scene._player_hp) < 0.01
    fill_ok = abs(float(scene._bar_fill.size.x) - (BAR_W - 4) * scene._shown_hp / PLAYER_MAX_HP) < 0.01
    detail = f"shown {scene._shown_hp:.1f}, fill {scene._bar_fill.size.x:.1f}px"
    check("then settles on the real value", settled and fill_ok, detail)

    # The HUD is screen-anchored: the world scrolls, the widgets do not.
    bar_rect = scene._bar_bg.get_global_rect()
    portrait_rect = scene._portrait.get_global_rect()
    landmark = scene._enemies[0]._home
    on_screen_before = scene._camera.world_to_screen(landmark, screen)
    scene._player.position = Vec2(scene._player.position.x + 500, scene._player.position.y + 300)
    runner.advance_frames(30)
    on_screen_after = scene._camera.world_to_screen(landmark, screen)
    moved = math.hypot(on_screen_after.x - on_screen_before.x, on_screen_after.y - on_screen_before.y)
    check(
        "the world scrolls under the camera",
        moved > 100,
        f"a fixed landmark moved {moved:.0f}px on screen",
    )
    check(
        "while the HUD holds still",
        scene._bar_bg.get_global_rect() == bar_rect and scene._portrait.get_global_rect() == portrait_rect,
        f"bar at {tuple(round(v) for v in bar_rect)}",
    )

    # Killing the whole wave respawns a fresh one after a pause.
    clicks = 0
    while scene._enemies and clicks < 200:
        click_at(scene._enemies[0].world_position)
        clicks += 1
    check("the whole wave can be cleared", not scene._enemies, f"{clicks} clicks, {len(scene._enemies)} left")
    runner.advance_frames(int(1.5 * 60) + 30)
    fresh = len(scene._enemies) == WAVE_SIZE and all(e.hp == e.max_hp for e in scene._enemies)
    check("and a fresh wave respawns after a pause", fresh, f"{len(scene._enemies)} enemies, all at full hp: {fresh}")

    # Finally, prove the HUD is really composited on SCREEN, in pixels. The
    # layout checks above pass even when the widgets render through the world
    # camera (their rects are layout-space), which is exactly the failure a
    # HUD outside a CanvasLayer produces: correct rects, nothing in the corner.
    from simvx.graphics import App

    class _Panned(HealthBarsDemo):
        def on_ready(self):
            super().on_ready()
            self._player.position = Vec2(self._player.position.x + 900, self._player.position.y + 500)

    frames = App(title="hud pixels", width=WIDTH, height=HEIGHT, visible=False).run_headless(
        _Panned(name="PixelProbe"), frames=12, capture_frames=None
    )
    fill_y = int(HEIGHT - (PAD + PORTRAIT / 2))
    fill_x = int(PAD + PORTRAIT + 10 + 20)
    fill_px = frames[-1][fill_y, fill_x, :3]
    check(
        "and the HUD is really composited on screen",
        int(fill_px[1]) > 100 and int(fill_px[1]) > int(fill_px[0]),
        f"health-bar fill pixel with the camera panned far away: {tuple(int(v) for v in fill_px)}",
    )

    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="SimVX Health Bars", width=WIDTH, height=HEIGHT).run(HealthBarsDemo())