UI overlay

/** * The DOM half of the overlay: the HUD panel `app.ui.layer("hud")` carries, and the safe-area * override the "Simulate a notch" toggle writes. * * @remarks * **This is not the kit reaching into the document.** `04-examples-platform.md` §4 says the kit is * the only place an example touches the DOM, and `@ignifx/ui` is the one exception the rule was * written around: game UI in ignifx *is* HTML, and `app.ui.layer(name).element` is the engine * handing a game the `<div>` it is meant to build into. Everything below goes through that element. * * Two things are worth reading before copying it. * * `ignifx-ui-interactive` is what turns pointer events back on. The overlay root and its layers are * `pointer-events: none` so a click reaches the canvas; a HUD that wants a button says so with that * class, and `UI_CLASS_NAMES` is where the name comes from rather than a string literal. * * The four safe-area insets are published by the host as CSS custom properties on the overlay root * — `env(safe-area-inset-*)` with a `0px` fallback — so game CSS reads a notch with * `var(--ignifx-safe-top)` and never measures anything. A desktop browser reports zero for all * four, which is why this example can set them on its own subtree: the same declarations, the same * cascade, and a laptop can see what a phone would do. */import { UI_CLASS_NAMES, UI_CSS_VARIABLES } from "ignifx";import type { UiHost, UiLayout } from "ignifx";/** The inset a simulated notch reports on the top and bottom edges. */const NOTCH_BLOCK = "34px";/** The inset a simulated notch reports on the left and right edges. */const NOTCH_INLINE = "18px";/** The HUD, mounted, with the two things `main.ts` drives from the panel. */export interface Hud {  /** The outermost element, so a caller can read it in a test. */  readonly element: HTMLElement;  /**   * Writes the live figures. Called every frame, and a no-op on a frame where nothing changed.   *   * @param layout - What `app.ui.layout` currently says.   */  readonly update: (layout: UiLayout) => void;  /**   * Overrides the four safe-area insets on this subtree, or gives them back to the host.   *   * @param on - `true` to report a notch, `false` to inherit the device's own insets.   */  readonly setNotch: (on: boolean) => void;  /** Removes the HUD. */  readonly dispose: () => void;}/** * Builds one labelled figure. * * @param label - The label text. * @returns The row, and the cell {@link Hud.update} rewrites. */function buildRow(label: string): { row: HTMLElement; value: HTMLElement } {  const row = document.createElement("div");  row.className = "hud-row";  const name = document.createElement("span");  name.textContent = label;  const value = document.createElement("span");  value.className = "hud-value";  row.append(name, value);  return { row, value };}/** * Mounts the HUD into the overlay's `hud` layer. * * @remarks * Returns `null` on an app with no DOM overlay — a headless app — so the caller needs no branch. * The layer is created for you: `layer(name)` is get-or-create. * * @param ui - The overlay host, normally `app.ui`. * @returns The HUD, or `null` when there is no overlay to mount into. * * @example * ```ts * const hud = createHud(app.ui); * hud?.update(app.ui.layout); * ``` */export function createHud(ui: UiHost): Hud | null {  const host = ui.layer("hud").element;  if (host === null) {    return null;  }  const element = document.createElement("section");  // Interactive because the HUD carries a button; a HUD that only reads would leave the class off  // and let every click through to the game.  element.className = `${UI_CLASS_NAMES.interactive} hud`;  element.setAttribute("aria-label", "Heads-up display");  const title = document.createElement("h2");  title.className = "hud-title";  title.textContent = "app.ui";  element.append(title);  const mode = buildRow("scaling");  const unit = buildRow("one UI unit");  const size = buildRow("root, UI units");  const scale = buildRow("root scale");  const inset = buildRow("safe area, top");  element.append(mode.row, unit.row, size.row, scale.row, inset.row);  const note = document.createElement("p");  note.className = "hud-note";  note.textContent = "Plain DOM in app.ui.layer(“hud”). The score above it is HudText, drawn by the GPU.";  element.append(note);  host.append(element);  const words: Readonly<Record<UiLayout["mode"], string>> = {    css: "one CSS pixel",    fit: "one reference pixel",    dpi: "one backing-store pixel",  };  /**   * Reads the resolved top inset back out of the cascade.   *   * @remarks   * Called when the notch toggle moves and once at mount, never per frame: `getComputedStyle`   * forces a style recalculation, and a HUD that did it every frame would be the most expensive   * thing on the page. It is read back rather than remembered so the figure is what the cascade   * resolved — `env(safe-area-inset-top, 0px)` on a desktop, the override when one is set.   *   * @returns The inset as CSS wrote it, e.g. `"0px"`.   */  const readInset = (): string => getComputedStyle(element).getPropertyValue(UI_CSS_VARIABLES.safeTop).trim() || "0px";  // The last layout written, so a per-frame refresh with nothing to say touches no DOM at all.  let written = "";  inset.value.textContent = readInset();  return {    element,    update(layout: UiLayout): void {      const key = `${layout.mode}|${String(layout.width)}|${String(layout.height)}|${String(layout.scale)}`;      if (key === written) {        return;      }      written = key;      mode.value.textContent = layout.mode;      unit.value.textContent = words[layout.mode];      size.value.textContent = `${String(Math.round(layout.width))} × ${String(Math.round(layout.height))}`;      scale.value.textContent = layout.scale.toFixed(3);    },    setNotch(on: boolean): void {      const style = element.style;      for (const [name, value] of [        [UI_CSS_VARIABLES.safeTop, NOTCH_BLOCK],        [UI_CSS_VARIABLES.safeBottom, NOTCH_BLOCK],        [UI_CSS_VARIABLES.safeLeft, NOTCH_INLINE],        [UI_CSS_VARIABLES.safeRight, NOTCH_INLINE],      ] as const) {        if (on) {          style.setProperty(name, value);        } else {          style.removeProperty(name);        }      }      inset.value.textContent = readInset();    },    dispose(): void {      element.remove();    },  };}

/** * The scene behind the overlay: three shapes turning on the grid, so the overlay has something to * sit in front of and the point of an overlay is visible. * * @remarks * A separate file for the reason `pbr-model/shot.ts` is: none of it is a lesson about UI. */import { createMaterialAsset, f32, MeshAsset, MeshRenderer, pbrMaterialDefinition, Script } from "ignifx";import type { App, ScriptCallbacks } from "ignifx";/** Spins its entity about Y, in degrees per second. */export class Spinner  extends Script.define({ speed: f32(30, { tooltip: "Degrees per second about Y." }) })  implements ScriptCallbacks{  /** The namespaced registration id. */  static typeId = "ui-overlay/Spinner";  /** Reused so the per-frame path allocates nothing (coding standards §7). */  readonly #step = { x: 0, y: 0, z: 0 };  /**   * Advances the rotation.   *   * @param dt - Seconds since the previous frame, scaled — so `?static=1` holds the pose and a   * capture of this example is the same frame every time.   */  update(dt: number): void {    this.#step.y = this.speed * dt;    this.transform.rotate(this.#step);  }}/** * Builds the three props. * * @remarks * `app.registerComponents([Spinner])` is the caller's job, because a game registers every component * it uses in one place. * * @param app - The app the entities and the assets belong to. * * @example * ```ts * app.registerComponents([Spinner]); * createProps(app); * ``` */export function createProps(app: App): void {  const material = createMaterialAsset(    app,    pbrMaterialDefinition({      name: "ui-overlay/prop",      baseColor: { r: 0.55, g: 0.36, b: 0.22, a: 1 },      metallic: 0.35,      roughness: 0.4,    }),    [],  );  const meshes = [    MeshAsset.box(app, { size: 0.62 }),    MeshAsset.torus(app, { diameter: 0.8, thickness: 0.22, tessellation: 24 }),    MeshAsset.capsule(app, { height: 0.9, radius: 0.22, tessellation: 16 }),  ];  for (const [index, mesh] of meshes.entries()) {    const prop = app.world.createEntity(`Prop ${String(index + 1)}`);    prop.transform.localPosition.set((index - 1) * 1.15, index === 1 ? 0.24 : 0.45, 0);    prop.transform.localEulerAngles = { x: 0, y: 25 * index, z: index === 1 ? 90 : 0 };    prop.addComponent(MeshRenderer, { mesh, materials: [material], castShadows: true });    prop.addComponent(Spinner, { speed: 18 + index * 14 });  }}

/*
 * The HUD panel's own styling, in the site's tokens (`02-design-system.md` §2.3), transcribed for
 * the same reason `_kit/kit.css` transcribes them: a frame is a separate document and the site's
 * stylesheet is emitted with a content hash this build cannot know.
 *
 * One deviation from `08-execution.md` §4.2, which asks that every `<slug>/index.html` be identical
 * in shape: this example links a second stylesheet. It is the one example whose subject is DOM UI,
 * and the alternative — thirty `element.style.setProperty` calls in `hud.ts` — would bury the
 * lesson under styling. The frames' CSP allows `style-src 'self'`, so a linked stylesheet needs no
 * relaxation.
 *
 * The four `--ignifx-safe-*` custom properties are published by `@ignifx/ui` on the overlay root
 * from `env(safe-area-inset-*)`. Reading them here, rather than reading `env()` directly, is what
 * lets the panel's "Simulate a notch" toggle show a laptop what a phone would do.
 */

.hud {
  position: absolute;
  top: calc(88px + var(--ignifx-safe-top, 0px));
  left: calc(20px + var(--ignifx-safe-left, 0px));
  box-sizing: border-box;
  width: 19rem;
  max-width: calc(100% - 40px);
  padding: 12px 14px;
  border: 1px solid #262d38;
  border-radius: 6px;
  background: rgb(20 24 31 / 88%);
  color: #e7eaf0;
  font:
    13px/1.5 ui-monospace,
    sfmono-regular,
    "SF Mono",
    menlo,
    consolas,
    monospace;
}

@media (prefers-color-scheme: light) {
  .hud {
    border-color: #d2d8e2;
    background: rgb(250 251 252 / 92%);
    color: #14181f;
  }
}

.hud-title {
  margin: 0 0 8px;
  color: #ff9e4a;
  font-size: 0.8125rem;
  font-weight: 600;
  letter-spacing: 0.06em;
  text-transform: uppercase;
}

@media (prefers-color-scheme: light) {
  .hud-title {
    color: #a63d07;
  }
}

.hud-row {
  display: flex;
  align-items: baseline;
  justify-content: space-between;
  gap: 12px;
  padding: 1px 0;
}

.hud-value {
  color: #5ad1c8;
  font-variant-numeric: tabular-nums;
  text-align: right;
}

@media (prefers-color-scheme: light) {
  .hud-value {
    color: #0b6a78;
  }
}

.hud-note {
  margin: 10px 0 0;
  color: #98a2b3;
  font-size: 0.75rem;
  line-height: 1.45;
}

@media (prefers-color-scheme: light) {
  .hud-note {
    color: #4b5464;
  }
}