@origingame/engine 0.1.1 → 0.2.0

package/schema/api.schema.json

@@ -16,6 +16,7 @@
     "ratio": "a fraction between 0 and 1",
     "bytes": "bytes",
     "kg": "kilograms",
+    "newton": "newtons: the force that gives a kilogram one metre per second squared",
     "mps": "metres per second",
     "mps2": "metres per second squared",
     "radps": "radians per second",
@@ -133,6 +134,7 @@
         "Entity",
         "SpawnDesc",
         "RestoreDesc",
+        "WorldRestored",
         "QueryDesc"
       ],
       "consts": [],
@@ -479,7 +481,7 @@
             },
             {
               "name": "restore",
-              "doc": "Replace the world with a save that world.snapshot wrote: entities, components, names, resources, events and the modules' state, so the restored world hashes as the saved one did, on either host. The session stays: input (og.Input, og.Pointers, og.Gamepad), the player's bus volumes (og.Audio), the UI's focus and hover, and what lives outside the world (the platform's calls and clock, the language, the loaded assets, the command channel's scheduled steps, which keep their remaining delays though og.Time takes the saved tick). Called in a system or a command it applies when the tick ends, after the last system; elsewhere (GameDesc.start, between ticks) at once. A save a system took mid-tick restores to that moment of its tick (og.Time reads its tick): the next step completes it (the systems after the saver, then the engine's), so the ticks after it are the saved run's. The meshes and height fields its colliders name must be loaded or registered first (a save naming one that is not is refused). A save holds only the world: progress kept in module variables is not in it, so keep it in components and resources.",
+              "doc": "Replace the world with a save that world.snapshot wrote: entities, components, names, resources, events and the modules' state, so the restored world hashes as the saved one did, on either host. The session stays: input (og.Input, og.Pointers, og.Gamepad), the player's bus volumes (og.Audio), the UI's focus and hover, and what lives outside the world (the platform's calls and clock, the language, the loaded assets, the command channel's scheduled steps, which keep their remaining delays though og.Time takes the saved tick, so an `og run --commands` script goes on to its last step or `quit` whether the save is of a later tick or an earlier one). Called in a system or a command it applies when the tick ends, after the last system; elsewhere (GameDesc.start, between ticks) at once. Either way the tick after it delivers og.WorldRestored, for the systems that reset what lives in the session. A save a system took mid-tick restores to that moment of its tick (og.Time reads its tick): the next step completes it (the systems after the saver, then the engine's), so the ticks after it are the saved run's. The meshes and height fields its colliders name must be loaded or registered first (a save naming one that is not is refused). A save holds only the world: progress kept in module variables is not in it, so keep it in components and resources.",
               "params": [
                 {
                   "name": "save",
@@ -1234,6 +1236,12 @@
         "Shader"
       ],
       "consts": [
+        {
+          "name": "PARTICLES_ARMED",
+          "type": "u32",
+          "value": 4294967295,
+          "doc": "ParticleSystem.startTick's default: never written. A looping emitter emits as if started at tick 0; a one-shot (`looping false`) emits nothing until its startTick is written, so a burst spawned in `start` waits for its first use. Write it back to re-arm a one-shot without firing it."
+        },
         {
           "name": "MAX_LIGHTS",
           "type": "u32",
@@ -8030,6 +8038,33 @@
       },
       "additionalProperties": false
     },
+    "WorldRestored": {
+      "x-og-kind": "event",
+      "x-og-module": "world",
+      "description": "A world.restore applied: the tick after it (the first whole tick after a save taken mid-tick, whose next step completes the saved tick) delivers this, read through world.events like any event. Everything in the world came back as saved, request numbers and resources the session filled included; the session did not (og-game §17), so a system that reads this resets what belongs to the session: it forgets requests answered long ago, asks the store again for the settings and progress, and closes a menu the player had open. Sent as that tick starts, not when the restore applies, so the world between the two hashes as the save did.",
+      "type": "object",
+      "properties": {
+        "from": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The tick the world was at when the restore applied.",
+          "x-og-unit": "ticks"
+        },
+        "tick": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The saved tick: og.Time's tick right after the restore.",
+          "x-og-unit": "ticks"
+        }
+      },
+      "required": [
+        "from",
+        "tick"
+      ],
+      "additionalProperties": false
+    },
     "QueryDesc": {
       "x-og-kind": "desc",
       "x-og-module": "world",
@@ -12645,8 +12680,8 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 4294967295,
-          "description": "The tick emission started: write og.world tick when spawning a one-shot burst.",
-          "default": 0
+          "description": "The tick emission started: write the tick (`time.tick`, `world.tick`) to fire a one-shot burst, or to restart one. Its default, PARTICLES_ARMED, is never written: a looping emitter emits as if started at tick 0, while a one-shot (`looping false`) stays armed and emits nothing until a tick is written, so effects spawned ahead of their first use wait.",
+          "default": 4294967295
         },
         "stopTick": {
           "type": "integer",
@@ -14880,7 +14915,7 @@
     "CharacterController": {
       "x-og-kind": "component",
       "x-og-module": "physics",
-      "description": "A kinematic character (3D, or top-down 2D): the entity's capsule (or any og.Collider) moved by `move` each tick, sliding along walls, climbing slopes up to `maxSlope` and steps up to `stepHeight`, snapped to the ground, carried by the moving platform it stands on and falling by gravity. It keeps `skin` off every surface, standing that far over the ground; a step is climbed when the ground beyond it is at most `stepHeight` over the ground it stands on. What blocks it is every solid collider its og.Collider's `layers` and `mask` interact with (each one's layers meeting the other's mask), as for bodies. The entity needs an og.Transform and an og.Collider; the step makes it a kinematic body and pushes dynamic bodies it walks into.",
+      "description": "A kinematic character (3D, or top-down 2D): the entity's capsule (or any og.Collider) moved by `move` each tick, sliding along walls, climbing slopes up to `maxSlope` and steps up to `stepHeight`, snapped to the ground, carried by the moving platform it stands on and falling by gravity. It keeps `skin` off every surface, standing that far over the ground; a step is climbed when the ground beyond it is at most `stepHeight` over the ground it stands on. What blocks it is every solid collider its og.Collider's `layers` and `mask` interact with (each one's layers meeting the other's mask), as for bodies. The entity needs an og.Transform and an og.Collider; the step makes it a kinematic body and pushes the dynamic bodies it walks into (`pushBodies`) with at most `pushStrength`, so a light one is shoved and a heavy one holds.",
       "type": "object",
       "properties": {
         "move": {
@@ -14964,9 +14999,17 @@
         },
         "pushBodies": {
           "type": "boolean",
-          "description": "Push dynamic bodies it walks into.",
+          "description": "Push dynamic bodies it walks into, with at most `pushStrength`.",
           "default": true
         },
+        "pushStrength": {
+          "type": "number",
+          "description": "The most force it pushes with: each tick the bodies it walks into share an impulse of at most this times the tick's length (mass times the speed it asks of them, capped), so a body of a few kilograms is shoved at its speed while one whose friction holds more (a tonne on the ground) does not move. 0 leaves every body where it is, as `pushBodies` false does.",
+          "default": 1000,
+          "minimum": 0,
+          "x-og-unit": "newton",
+          "x-og-tunable": true
+        },
         "grounded": {
           "type": "boolean",
           "description": "Written: standing on walkable ground after the step.",
@@ -15024,7 +15067,7 @@
     "PlatformerController": {
       "x-og-kind": "component",
       "x-og-module": "physics",
-      "description": "A 2D platformer character (the 2D profile): run, jump and fall with designer units (jump height and time to apex, not gravity), coyote time, jump buffering, variable jump height (releasing jump while rising cuts the jump), apex hang, air jumps, wall slide and wall jump, one-way platforms (colliders on `oneWayLayers` are solid from above only; hold `down` to drop through), moving platforms (it rides what it stands on) and corner correction (a jump that clips a ceiling corner by less than `cornerCorrection` slides past it). It keeps `skin` off every surface; what blocks it is every solid collider its og.Collider's `layers` and `mask` interact with (each one's layers meeting the other's mask), as for bodies. The entity needs an og.Transform and an og.Collider (a box or capsule); it becomes a kinematic body.",
+      "description": "A 2D platformer character (the 2D profile): run, jump and fall with designer units (jump height and time to apex, not gravity), coyote time, jump buffering, variable jump height (releasing jump while rising cuts the jump), apex hang, air jumps, wall slide and wall jump, one-way platforms (colliders on `oneWayLayers` are solid from above only; hold `down` to drop through), moving platforms (it rides what it stands on) and corner correction (a jump that clips a ceiling corner by less than `cornerCorrection` slides past it). It keeps `skin` off every surface; what blocks it is every solid collider its og.Collider's `layers` and `mask` interact with (each one's layers meeting the other's mask), as for bodies. The entity needs an og.Transform and an og.Collider (a box or capsule); it becomes a kinematic body and pushes the dynamic bodies it runs into (`pushBodies`) with at most `pushStrength`, so a crate's mass tells: a light one is shoved at the run speed, a heavy one holds (set its og.RigidBody `mass`).",
       "type": "object",
       "properties": {
         "moveX": {
@@ -15242,6 +15285,19 @@
           "minimum": 0.001,
           "x-og-unit": "m"
         },
+        "pushBodies": {
+          "type": "boolean",
+          "description": "Push dynamic bodies it runs into, with at most `pushStrength`.",
+          "default": true
+        },
+        "pushStrength": {
+          "type": "number",
+          "description": "The most force it pushes with: each tick the bodies it runs into share an impulse of at most this times the tick's length (mass times the speed it asks of them, capped), so a body of a few kilograms is shoved at its speed while one whose friction holds more (a tonne on the ground) does not move. 0 leaves every body where it is, as `pushBodies` false does.",
+          "default": 1000,
+          "minimum": 0,
+          "x-og-unit": "newton",
+          "x-og-tunable": true
+        },
         "grounded": {
           "type": "boolean",
           "description": "Written: standing on ground after the step.",
@@ -15335,7 +15391,7 @@
     "CharacterEvent": {
       "x-og-kind": "event",
       "x-og-module": "physics",
-      "description": "Something a CharacterController or PlatformerController did this step: the hooks for dust, squash, sounds and camera kicks. Read the next tick.",
+      "description": "Something a CharacterController or PlatformerController did this step: the hooks for dust, squash, sounds and camera kicks. Read the next tick: the controllers move in the physics step, after the game's systems, so a jump pressed in tick T moves the character in T and its CHARACTER_JUMPED is read in T + 1 (og-feel §12 has the same-tick alternative).",
       "type": "object",
       "properties": {
         "entity": {
@@ -18900,7 +18956,7 @@
           "type": "integer",
           "minimum": 0,
           "maximum": 4294967295,
-          "description": "The collision layers of those colliders, as bits (Collider.layers).",
+          "description": "The collision layers of those colliders, as bits (Collider.layers), for every collision layer of the map that names none of its own (a map layer's `colliderLayers`, with its `colliderMask`, puts a layer of grates on a one-way layer while the walls stay here).",
           "default": 1
         },
         "friction": {
@@ -18943,6 +18999,18 @@
           "type": "boolean",
           "description": "Its solid tiles collide."
         },
+        "colliderLayers": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The collision layers (og.Collider.layers bits) of its colliders, from its `colliderLayers` line or Tiled int property; 0 (unset) takes Tilemap.colliderLayers."
+        },
+        "colliderMask": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "The layers its colliders collide with (og.Collider.mask bits), from its `colliderMask` line or Tiled int property; 0 (unset) is every layer."
+        },
         "terrain": {
           "type": "string",
           "description": "The auto-tiling terrain of a terrain layer (its cells are 1 filled or 0 empty); empty for a tile layer."
@@ -18962,6 +19030,8 @@
         "z",
         "parallax",
         "collision",
+        "colliderLayers",
+        "colliderMask",
         "terrain",
         "visible",
         "lit"
@@ -21193,7 +21263,7 @@
         },
         "time": {
           "type": "number",
-          "description": "The host's clock when it answered, UTC milliseconds since 1970 (PlatformInfo.clock says whose); 0 when the host gave none.",
+          "description": "The host's clock when it answered, UTC milliseconds since 1970 (PlatformInfo.clock says whose); 0 when the host gave none. A slot call (saveSlot, loadSlot) answers the time of the store answer that ended it.",
           "x-og-unit": "ms"
         }
       },
@@ -25805,6 +25875,16 @@
           "type": "boolean",
           "description": "Show touch controls (a d-pad and Jump) on phones and tablets.",
           "default": false
+        },
+        "jumpLabel": {
+          "type": "string",
+          "description": "The touch Jump button. Every word of the HUD is a field with its English default: a localised game passes its string table's (og.i18n.t).",
+          "default": "Jump"
+        },
+        "pauseLabel": {
+          "type": "string",
+          "description": "The pause button's name (what a screen reader says; the button shows its icon).",
+          "default": "Pause"
         }
       },
       "additionalProperties": false
@@ -25943,6 +26023,21 @@
           "type": "boolean",
           "description": "Show touch controls (a stick and Fire) on phones and tablets.",
           "default": false
+        },
+        "killsLabel": {
+          "type": "string",
+          "description": "The word after the kill count. Every word of the HUD is a field with its English default: a localised game passes its string table's (og.i18n.t).",
+          "default": "kills"
+        },
+        "fireLabel": {
+          "type": "string",
+          "description": "The touch Fire button.",
+          "default": "Fire"
+        },
+        "pauseLabel": {
+          "type": "string",
+          "description": "The pause button's name (what a screen reader says; the button shows its icon).",
+          "default": "Pause"
         }
       },
       "additionalProperties": false
@@ -26007,6 +26102,21 @@
           ],
           "description": "Seconds left; null hides it.",
           "default": null
+        },
+        "movesLabel": {
+          "type": "string",
+          "description": "The caption under the moves left. Every word of the HUD is a field with its English default: a localised game passes its string table's (og.i18n.t).",
+          "default": "moves left"
+        },
+        "targetLabel": {
+          "type": "string",
+          "description": "The line beside the stars; `{target}` is replaced by the target, formatted (1,000). A localised game passes its string table's, with `{target}` in it.",
+          "default": "Target {target}"
+        },
+        "pauseLabel": {
+          "type": "string",
+          "description": "The pause button's name (what a screen reader says; the button shows its icon).",
+          "default": "Pause"
         }
       },
       "additionalProperties": false
@@ -26118,6 +26228,21 @@
           "type": "string",
           "description": "The tap target's label; empty hides it.",
           "default": "Tap"
+        },
+        "levelLabel": {
+          "type": "string",
+          "description": "A generator's level badge; `{level}` is replaced by its level. Every word of the HUD is a field with its English default: a localised game passes its string table's (og.i18n.t), with `{level}` in it.",
+          "default": "Lv {level}"
+        },
+        "rateLabel": {
+          "type": "string",
+          "description": "A currency's rate; `{rate}` is replaced by its per-second amount, formatted (+12/s is `+{rate}/s`). A localised game passes its string table's, with `{rate}` in it.",
+          "default": "+{rate}/s"
+        },
+        "pauseLabel": {
+          "type": "string",
+          "description": "The pause button's name (what a screen reader says; the button shows its icon).",
+          "default": "Pause"
         }
       },
       "additionalProperties": false

package/src/index.ts

@@ -100,6 +100,7 @@ export const MAX_POINTERS: typeof Api.MAX_POINTERS = 5;
 export const MAX_GAMEPADS: typeof Api.MAX_GAMEPADS = 4;
 export const MAX_LIGHTS: typeof Api.MAX_LIGHTS = 256;
 export const MAX_CLUSTER_LIGHTS: typeof Api.MAX_CLUSTER_LIGHTS = 64;
+export const PARTICLES_ARMED: typeof Api.PARTICLES_ARMED = 4294967295;
 export const UI_LAYER: typeof Api.UI_LAYER = 1000;
 export const BODY_DYNAMIC: typeof Api.BODY_DYNAMIC = 0;
 export const BODY_STATIC: typeof Api.BODY_STATIC = 1;

package/src/node/polish.ts

@@ -223,7 +223,8 @@ async function runOne(file: string, entry: string, root: string, out: string): P
       quit = true;
       break;
     }
-    if ((answer.tick ?? 0) > report!.untilTick) break;
+    // Its last step has run (a restore may have moved og.Time, and the steps with it).
+    if ((answer.pending ?? ((answer.tick ?? 0) > report!.untilTick ? 0 : 1)) === 0) break;
   }
   drain();
   const wav = join(out, "audio.wav");

package/src/node/run.ts

@@ -304,7 +304,11 @@ if (!probing) {
       break;
     }
     if (ticks !== undefined && tick >= ticks) break;
-    if (ticks === undefined && commands !== undefined && listening === undefined && !watchFile && tick > untilTick) break;
+    // The script ends once its last step has run: a restore moving og.Time
+    // forward or back moves the steps with it (they keep their delays), so
+    // the tick its last step was scheduled for is no end (brasswick #13).
+    const left = answer.pending ?? (tick > untilTick ? 0 : 1);
+    if (ticks === undefined && commands !== undefined && listening === undefined && !watchFile && left === 0) break;
     if (realtime || listening !== undefined || watchFile) await sleep(Math.max(0, tickMs - (performance.now() - last)));
   }
 }

package/src/runtime.ts

@@ -1179,6 +1179,8 @@ export class Engine {
     /** Wall milliseconds a tick took (this frame's mean, or the last frame's that ticked) and the last render took. */
     stepMs?: number;
     renderMs?: number;
+    /** The command channel's steps still to run (scheduled, or a screenshot waiting for its frame): a script has ended at 0, however a restore moved og.Time. */
+    pending?: number;
     reason?: string;
     /** The UI's focused text control (web/text-input.ts's TextTarget), or null. */
     text?: { path: string; rect: [number, number, number, number]; multiline: boolean; selection: string; composing: boolean } | null;

package/src/ui-kit/huds.ts

@@ -2,7 +2,9 @@
 // set of anchored groups over the game in the safe area, plus the touch
 // controls they show on phones and tablets. HUDs turn keyboard and gamepad
 // navigation off (the keys move the player); Back still answers `paused`,
-// except under an open dialog, which keeps it (og.ui.back).
+// except under an open dialog, which keeps it (og.ui.back). Every word a HUD
+// draws or names is a field of its desc with the English default (og-i18n
+// §2), so a game in another language has none of the kit's English left.
 
 import type * as Api from "@origingame/engine";
 import { kit } from "./bind.ts";
@@ -15,7 +17,8 @@ function hud(): Hud {
   return { paused: kit.back(), action: null, moveX: 0, moveY: 0, held: [] };
 }
 
-function pauseButton(out: Hud, label = "Pause"): void {
+/** The pause button: its icon, named by the desc's `pauseLabel` (what a screen reader says). */
+function pauseButton(out: Hud, label: string): void {
   const r = kit.actionButton("Pause", label, { size: 44, icon: "pause" });
   if (r.clicked) out.paused = true;
 }
@@ -85,9 +88,9 @@ export function platformerHud(id: string, desc: Api.PlatformerHudDesc = {}): Api
       });
     }
     if (score !== null) capsule("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
-  if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: "Jump", primary: true }] });
+  if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: desc.jumpLabel ?? "Jump", primary: true }] });
   return out;
 }
 
@@ -120,9 +123,9 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
   kit.anchor(`${id}.top`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     capsule("Kills", () => {
       kit.label("Count", fmt(desc.kills ?? 0), { font: "mono", nowrap: true });
-      kit.label("Unit", "kills", { step: "meta", color: token("fgMuted"), nowrap: true });
+      kit.label("Unit", desc.killsLabel ?? "kills", { step: "meta", color: token("fgMuted"), nowrap: true });
     });
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
  kit.anchor(`${id}.ammo`, { anchor: showTouch ? "topRight" : "bottomRight", offsetY: showTouch ? 56 : 0, direction: "column", cross: "end", gap: t.xs }, () => {
     const mag = desc.magazine ?? 0;
@@ -144,7 +147,7 @@ export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudRe
     });
   }
   if (desc.crosshair ?? true) crosshair();
-  if (showTouch) touchControls(out, { buttons: [{ id: "fire", label: "Fire", primary: true }] });
+  if (showTouch) touchControls(out, { buttons: [{ id: "fire", label: desc.fireLabel ?? "Fire", primary: true }] });
   return out;
 }
 
@@ -156,21 +159,21 @@ export function puzzleHud(id: string, desc: Api.PuzzleHudDesc = {}): Api.HudResu
   const marks = desc.stars && desc.stars.length > 0 ? desc.stars : [Math.round(target / 3), Math.round((2 * target) / 3), target];
   kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.xs }, () => {
     if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
-    if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, "moves left", "xl3");
+    if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, desc.movesLabel ?? "moves left", "xl3");
   });
   kit.anchor(`${id}.score`, { anchor: "top", direction: "column", cross: "center", gap: t.xs, width: px(260) }, () => {
     kit.label("Score", fmt(score), { step: "displaySm", font: "display", align: "center", width: grow() });
     kit.meter("Progress", score, target, { kind: "accent", width: grow(), segments: 3 });
     kit.row("Stars", { gap: t.sm, cross: "center" }, () => {
       marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "accent" : "fillStrong")));
-      kit.label("Target", `Target ${fmt(target)}`, { step: "meta", color: token("fgMuted"), nowrap: true });
+      kit.label("Target", (desc.targetLabel ?? "Target {target}").replaceAll("{target}", fmt(target)), { step: "meta", color: token("fgMuted"), nowrap: true });
     });
   });
   kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
     if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
       capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "fg"), nowrap: true }));
     }
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
   return out;
 }
@@ -185,10 +188,10 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
       capsule(c.id ?? kit.idi("Currency", i), () => {
         if (c.icon) iconOr("Icon", c.icon, 20, token("accent"));
         kit.label("Amount", fmt(c.amount ?? 0), { step: i === 0 ? "lg" : "body", font: "mono", nowrap: true });
-        if ((c.perSecond ?? 0) !== 0) kit.label("Rate", `+${fmt(c.perSecond ?? 0)}/s`, { step: "meta", color: token("success"), nowrap: true });
+        if ((c.perSecond ?? 0) !== 0) kit.label("Rate", (desc.rateLabel ?? "+{rate}/s").replaceAll("{rate}", fmt(c.perSecond ?? 0)), { step: "meta", color: token("success"), nowrap: true });
       }, { height: i === 0 ? t.controlLg : t.controlMd });
     });
-    pauseButton(out);
+    pauseButton(out, desc.pauseLabel ?? "Pause");
   });
   if (desc.tapLabel !== "") {
     kit.anchor(`${id}.tap`, { anchor: phone ? "top" : "center", offsetY: phone ? 96 : 0, offsetX: phone ? 0 : -150 }, () => {
@@ -205,7 +208,7 @@ export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
         kit.column("Text", { width: grow(), gap: t.xxs }, () => {
           kit.row("Head", { gap: t.sm, cross: "center", width: grow() }, () => {
             kit.label("Name", g.name ?? g.id ?? "", { step: "lg", nowrap: true, width: grow() });
-            kit.badge("Level", `Lv ${g.level ?? 0}`, "neutral");
+            kit.badge("Level", (desc.levelLabel ?? "Lv {level}").replaceAll("{level}", `${g.level ?? 0}`), "neutral");
           });
           kit.meter("Cycle", g.progress ?? 0, 1, { kind: "accent", height: 4, width: grow() });
         });
@@ -254,7 +257,8 @@ export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResu
     const delta = desc.delta ?? null;
     if (delta !== null) kit.label("Delta", deltaText(delta), { step: "lg", font: "mono", color: deltaInk(delta), nowrap: true });
     if (desc.best !== null && desc.best !== undefined) {
-      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", clock(desc.best, true)), { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+      // A finished lap: m:ss.mmm as lapTime cuts it (30.717 s is 0:30.717, where the running clock's floor reads 0:30.716).
+      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", lapTime(desc.best)), { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
     }
     const splits = desc.splits ?? [];
     if (splits.length > 0) {