HUD Layer

The HUD layer is a screen-space overlay. HudLayer is a renderer layer whose compose method calls target.drawHud(screen). Hs2dHud is the helper used by Hs2dLevelScene for cached bitmap text and loading-screen text fallback.

The renderer does not reorder HUD layers specially. A HUD is final only when it is appended last. Hs2dWorldBuilder does that automatically when its hud option is provided; manual worlds should call world.addHud(...) after all world layers.

HUD code should draw bounded overlay elements only. Gameplay sprites, particles, tiles, and backgrounds belong in layers, pools, and cached surfaces, not in drawHud.

When To Use

Use a HUD layer for:

Use	Preferred API
Score, health, ammo, timer, status labels	`drawCachedText` with stable cache keys.
Pause/menu overlays already built as UI controls	UI scene/menu systems or a measured HUD callback.
Loading text before a world text renderer exists	`Hs2dHud.drawText` or `drawTextCentered`.
Debug counters	Direct text is acceptable when bounded and diagnostic-only.

Use Hs2dFloatingTextSystem for world-space score or damage labels. Do not draw dozens of world labels from the HUD callback.

Construction Pattern

Manual, after adding all world layers:

world.addHud(this);

Builder:

const built = Hs2dWorldBuilder.fromLevel({
  level,
  assets,
  viewportWidth: screenWidth,
  viewportHeight: screenHeight,
  hud: this,
});

In an Hs2dLevelScene, update attaches the world's text renderer to this.hud when the world becomes ready. That lets drawCachedText use cached bitmap text instead of raw DrawText.

Update, Render, And Compose Behavior

Phase	Behavior
Update	No camera or world update.
Render	No intermediate render step.
Compose	Calls `drawHud(screen)` at its insertion point. It follows all non-HUD layers only when added last.
Text helper	`Hs2dHud.drawCachedText` uses the attached `Hs2dTextRenderer`; before attachment it falls back to raw `DrawText`.

HUD coordinates are screen pixels, not world pixels.

Performance Notes

Use cached text for stable HUD labels.
Keep cache keys stable, for example score, hp, wave, and timer.
Prewarm common text when many variants are known.
Update status strings on a stats cadence when possible.
Avoid using HUD text as placeholder gameplay art.
Do not run collision, tile, entity, or map scans from drawHud.
In manual worlds, add the HUD last so later layers cannot cover it.

Code Sample

override drawHud(screen: GameScreen): void {
  this.drawCachedText(
    screen,
    'score',
    'SCORE ' + String(this.score),
    this.screenWidth - 270,
    28,
    0xfef08aff,
    this.titleFont,
  );

  this.drawCachedText(
    screen,
    'hp',
    'HP ' + String(this.shipHealth),
    this.screenWidth - 170,
    58,
    0xa7f3d0ff,
    this.hudFont,
  );
}

Source References

Source	Why it matters
`../games/hosanna-ui/src/hosanna-game/scene/GameSceneRenderer.ts`	`HudLayer`, `isHudLayer`, render-frame compose order, and layer contract.
`../games/hosanna-ui/src/hosanna-game/hosanna2d/game/Hs2dHud.ts`	Cached HUD text helper and raw text fallback.
`../games/hosanna-ui/src/hosanna-game/hosanna2d/game/Hs2dLevelScene.ts`	HUD text renderer attachment, `drawCachedText`, and `drawHud` callback shape.
`../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dWorld.ts`	`addHud` world API.
`../hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterLevelScene.ts`	Cached HUD labels, direct live score example, and throttled status text.

When To Use​

Construction Pattern​

Update, Render, And Compose Behavior​

Performance Notes​

Code Sample​

Source References​