@dcl-regenesislabs/web-editor 0.1.1-37517974772.commit-b9847a1 → 0.1.1-38415884993.commit-9d6277f

package/prefabs/game-flow/data.json

@@ -1,7 +1,7 @@
 {
   "id": "44374100-12fb-481f-90ce-2a4d81949084",
   "name": "Game Flow",
-  "description": "Lobby, countdown, rounds, winners — runs your game from start to end. Works with: Leaderboard, Announcer.",
+  "description": "Lobby, countdown, rounds, winners \u2014 runs your game from start to end. Works with: Leaderboard, Announcer.",
   "category": "custom",
   "group": "Multiplayer Server",
   "tags": [
@@ -14,11 +14,15 @@
     "winners"
   ],
   "requiresSdk": "auth-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "changelog": [
     {
       "version": "1.0.0",
-      "notes": "Initial release: lobby → round → winners on game.round, a countdown every client derives from one shared deadline, a winners line read from the board key a Leaderboard shows, and a \"script\" mode where your own game.newRound() ends the round and the round length is only a ceiling."
+      "notes": "Initial release: lobby \u2192 round \u2192 winners on game.round, a countdown every client derives from one shared deadline, a winners line read from the board key a Leaderboard shows, and a \"script\" mode where your own game.newRound() ends the round and the round length is only a ceiling."
+    },
+    {
+      "version": "1.1.0",
+      "notes": "Optional themed round timer and lobby countdown, configured in the inspector."
     }
   ],
   "origin": {

package/prefabs/game-flow/scripts/game-flow.ts

@@ -11,9 +11,10 @@
 // rather than fighting it, and in that mode the round length is only a ceiling —
 // when the ceiling fires it goes out through game.newRound() too, so a round
 // never ends down two different paths. See ai.md in this folder.
-import { TextShape, type Entity } from '@dcl/sdk/ecs'
+import { TextShape, VisibilityComponent, type Entity } from '@dcl/sdk/ecs'
 import { isServer } from '@dcl/sdk/network'
 import { game } from '~runtime/game'
+import { mountStatusHud } from '~runtime/statusHud'
 import {
   advanceFlow,
   asFlowFact,
@@ -61,7 +62,10 @@ export class GameFlow {
     /** Who ends a round: this clock, or your own script calling game.newRound(). */
     public endsWhen: 'timer' | 'script' = 'timer',
     /** The game.state key the winners come from — the key a Leaderboard shows. */
-    public boardKey: string = 'leaderboard'
+    public boardKey: string = 'leaderboard',
+    public display: '3D text' | '2D UI' = '3D text',
+    /** For "2D UI": where the round timer sits on screen. */
+    public position: 'top' | 'top left' | 'top right' | 'bottom' = 'top'
   ) {}
 
   private get config(): FlowConfig {
@@ -97,11 +101,20 @@ export class GameFlow {
         this.publish()
       })
       game.every(TICK_S, () => this.tick())
+      return
+    }
+    if (this.display === '2D UI') {
+      VisibilityComponent.createOrReplace(this.entity, { visible: false })
+      TextShape.deleteFrom(this.entity)
+      mountStatusHud(this.entity, this.position, () => {
+        const [label, value = '', detail] = this.text().split('\n')
+        return { label, value, detail }
+      })
     }
   }
 
   update(dt: number): void {
-    if (isServer()) { return }
+    if (isServer() || this.display === '2D UI') { return }
     this.accum += dt
     if (this.accum < PAINT_S) return
     this.accum = 0
@@ -152,9 +165,13 @@ export class GameFlow {
     game.setState({ [FLOW_KEY]: fact })
   }
 
-  private paint(): void {
+  private text(): string {
     const fact = asFlowFact(game.state[FLOW_KEY])
-    const text = panelText(fact, game.now(), this.endsWhen === 'timer', this.config.minPlayers)
+    return panelText(fact, game.now(), this.endsWhen === 'timer', this.config.minPlayers)
+  }
+
+  private paint(): void {
+    const text = this.text()
     if (text === this.painted) return
     this.painted = text
     TextShape.createOrReplace(this.entity, {

package/prefabs/health-respawn/ai.md

@@ -26,9 +26,13 @@ owns all three, and health a client can edit is health nobody can trust.
 - `damage(player, amount)` — WHICH SIDE: the SERVER, inside the `if (isServer())`
   branch, from a `game.onRequest`, `game.onEnterArea`, `game.every` or
   `game.onRoundStart` handler. Takes the player to a minimum of 0; at 0 this
-  prefab respawns them within half a second and refills them. A player who is not
-  in the scene is ignored.
+  prefab refills them and respawns them after respawnDelay, checked every half
+  second. A player who is not in the scene is ignored.
 - `healthOf(player)` — reads hit points on either side, the client included.
+- `heal(player, amount)` and `kill(player)` — SERVER helpers from the same health.ts.
+  Healing caps at maxHealth and cannot revive a dead player. kill forces health to zero.
+- `lifeOf(player)` — reads life number, death count, dead status, respawnAt and
+  protectedUntil, or null before the player joins. Times use game.now().
 - `game.state.health` — the whole `{ wallet: points }` map, readable on every
   client and by late joiners. Read it to draw bars or count who is alive; never
   write it.
@@ -43,6 +47,25 @@ Params of the prefab's script — set them in the placePrefab request:
 - `dieBelowHeight`: players below this height die (default 0 = off). This is the
   death plane for a climbing or platforming scene; set it under the lowest floor
   a player is allowed to stand on.
+- `respawnDelay`: seconds to remain dead before returning (default 0).
+- `protectionSeconds`: damage/fall protection after returning (default 1).
+- `healthBar`: show hit points on Run Progress's HUD (default on). Set it to
+  false when nothing calls `damage()` (falling alone needs no bar) unless the
+  creator asks for one. Published as `game.state.healthBar`.
+
+Checkpoint destinations and an explicit restart move use the shared
+`src/scripts/runtime/respawn.ts` module; read its header. Health & Respawn must
+be placed to receive the move. Each player's destination overrides respawnAt;
+leaving clears it. The course owns resetting destinations at a new round or
+personal restart; Run Progress does both before requesting the move.
+The owner also publishes game.state.healthLife and game.state.healthMax for HUDs.
+
+For a course, read Run Progress and Trigger Area too. Place the start and checkpoint
+markers inside the active parcels, above a collidable landing. Enable
+`ALLOW_TO_MOVE_PLAYER_INSIDE_SCENE` through sceneSettings. Test falling, returning
+to each checkpoint, and Restart run through playtest before finishing the turn.
+If the preview still has the old parcels, retry sceneSettings and wait for success;
+an outside respawn destination is a broken game, not a task to leave to the creator.
 
 ## Hazards
 

package/prefabs/health-respawn/data.json

@@ -21,8 +21,15 @@
     "code": "game.onEnterArea('Spikes', (player) => damage(player, 25))",
     "next": "Press New script below, write that inside the isServer() block it comes with, and import damage from the health.ts beside this item's own script."
   },
-  "version": "1.1.0",
+  "version": "1.3.1",
   "changelog": [
+    { "version": "1.3.1", "notes": "The health bar is on by default again; turn Health Bar off for a game that never deals damage." },
+    { "version": "1.3.0", "notes": "Health bar setting, off by default: a course that never deals damage shows no hit points." },
+    { "version": "1.2.1", "notes": "Guide covers in-bounds respawn destinations, permissions and course playtesting." },
+    {
+      "version": "1.2.0",
+      "notes": "Per-player checkpoint destinations, healing, forced death, death counts, optional respawn delay and protection after respawning."
+    },
     {
       "version": "1.0.0",
       "notes": "Initial release: hit points the server owns in game.state.health, a respawn point picked in the inspector, a \"die below height\" death plane, and a damage() other server code calls."

package/prefabs/health-respawn/scripts/health-respawn.ts

@@ -10,10 +10,12 @@ import { Transform, type Entity } from '@dcl/sdk/ecs'
 import { isServer } from '@dcl/sdk/network'
 import { movePlayerTo } from '~system/RestrictedActions'
 import { game, type Player } from '~runtime/game'
+import { clearRespawnPoint, onLocalRespawn, onPlayerRespawn, respawnPlayer } from '~runtime/respawn'
+import type { Vec3 } from '~runtime/pure/worldTransform'
 import { asHealthMap, clampMax, deadPlayers } from './pure/health'
-import { HEALTH_KEY } from './health'
+import { advanceLives, freshLife, readLives, type LifeMap } from './pure/life'
+import { HEALTH_KEY, LIFE_KEY } from './health'
 
-const RESPAWN = 'respawn'
 const SWEEP_S = 0.5
 const NO_POINT = "Players won't respawn anywhere until you pick a respawn point."
 
@@ -32,7 +34,13 @@ export class HealthRespawn {
     /** Hit points a player starts every life with. */
     public maxHealth: number = 100,
     /** Players who fall below this height die. Leave at 0 to switch it off. */
-    public dieBelowHeight: number = 0
+    public dieBelowHeight: number = 0,
+    /** Seconds to remain dead before returning to the latest checkpoint. */
+    public respawnDelay: number = 0,
+    /** Seconds of protection after a respawn. */
+    public protectionSeconds: number = 1,
+    /** Show hit points on Run Progress's HUD. Turn off when nothing in the game deals damage. */
+    public healthBar: boolean = true
   ) {}
 
   start(): void {
@@ -46,35 +54,40 @@ export class HealthRespawn {
     }
     if (this.respawnAt === (0 as Entity)) console.log(`[healthRespawn] ${NO_POINT}`)
     if (isServer()) {
-      game.onReady(() => game.setState({ [HEALTH_KEY]: {} }))
+      onPlayerRespawn((player) => this.restore(player))
+      game.onReady(() => game.setState({ [HEALTH_KEY]: {}, [LIFE_KEY]: {}, healthMax: clampMax(this.maxHealth), healthBar: this.healthBar !== false }))
       game.onPlayerJoin((player) => this.revive(player))
       game.onPlayerLeave((player) => {
         const map = { ...asHealthMap(game.state[HEALTH_KEY]) }
+        const lives = { ...readLives(game.state[LIFE_KEY]) }
         delete map[player]
-        game.setState({ [HEALTH_KEY]: map })
+        delete lives[player]
+        clearRespawnPoint(player)
+        game.setState({ [HEALTH_KEY]: map, [LIFE_KEY]: lives })
       })
       game.onRoundStart(() => {
         const map = asHealthMap(game.state[HEALTH_KEY])
         const full: Record<string, number> = {}
-        for (const player of Object.keys(map)) full[player] = clampMax(this.maxHealth)
-        game.setState({ [HEALTH_KEY]: full })
+        const lives: LifeMap = {}
+        for (const player of Object.keys(map)) {
+          full[player] = clampMax(this.maxHealth)
+          lives[player] = freshLife()
+        }
+        game.setState({ [HEALTH_KEY]: full, [LIFE_KEY]: lives })
       })
       game.every(SWEEP_S, () => this.sweep())
       return
     }
-    game.onBroadcast(RESPAWN, () => this.goHome())
+    onLocalRespawn((position) => this.goHome(position))
   }
 
   private sweep(): void {
     const map = asHealthMap(game.state[HEALTH_KEY])
-    const dead = deadPlayers(map, (player) => game.positionOf(player), this.deathPlane)
-    if (dead.length === 0) return
-    const next = { ...map }
-    for (const player of dead) {
-      next[player] = clampMax(this.maxHealth)
-      game.broadcast(RESPAWN, {}, player)
-    }
-    game.setState({ [HEALTH_KEY]: next })
+    const fallen = new Set(deadPlayers(map, (player) => game.positionOf(player), this.deathPlane))
+    const next = advanceLives(map, readLives(game.state[LIFE_KEY]), fallen, game.now(), this.maxHealth, this.respawnDelay, this.protectionSeconds)
+    if (!next.changed) return
+    game.setState({ [HEALTH_KEY]: next.health, [LIFE_KEY]: next.lives })
+    for (const player of next.respawn) respawnPlayer(player)
   }
 
   private get deathPlane(): number {
@@ -83,16 +96,35 @@ export class HealthRespawn {
 
   private revive(player: Player): void {
     game.setState({
-      [HEALTH_KEY]: { ...asHealthMap(game.state[HEALTH_KEY]), [player]: clampMax(this.maxHealth) }
+      [HEALTH_KEY]: { ...asHealthMap(game.state[HEALTH_KEY]), [player]: clampMax(this.maxHealth) },
+      [LIFE_KEY]: { ...readLives(game.state[LIFE_KEY]), [player]: freshLife() }
+    })
+  }
+
+  private restore(player: Player): void {
+    const health = asHealthMap(game.state[HEALTH_KEY])
+    if (health[player] === undefined) return
+    const lives = readLives(game.state[LIFE_KEY])
+    const life = lives[player] ?? freshLife()
+    const protection = Number.isFinite(this.protectionSeconds) ? Math.max(0, Math.min(30, this.protectionSeconds)) : 1
+    game.setState({
+      [HEALTH_KEY]: { ...health, [player]: clampMax(this.maxHealth) },
+      [LIFE_KEY]: { ...lives, [player]: {
+        ...life, life: life.life + (life.dead ? 1 : 0), dead: false, respawnAt: 0,
+        protectedUntil: game.now() + protection * 1000
+      } }
     })
   }
 
-  private goHome(): void {
+  private goHome(requested: Vec3 | null): void {
     const point = this.respawnAt === (0 as Entity) ? null : Transform.getOrNull(this.respawnAt)
-    if (point === null) {
+    const position = requested ?? point?.position
+    if (position === undefined) {
       console.log(`[healthRespawn] ${NO_POINT}`)
       return
     }
-    void movePlayerTo({ newRelativePosition: { ...point.position } })
+    void movePlayerTo({ newRelativePosition: { ...position } }).catch((error: unknown) => {
+      console.log(`[healthRespawn] could not move the player: ${String(error)}`)
+    })
   }
 }

package/prefabs/health-respawn/scripts/health.ts

@@ -4,8 +4,14 @@
 // export, so a helper sitting next to the class could be built instead of it.
 import { game, type Player } from '~runtime/game'
 import { afterDamage, asHealthMap } from './pure/health'
+import { readLives, type LifeState } from './pure/life'
 
 export const HEALTH_KEY = 'health'
+export const LIFE_KEY = 'healthLife'
+
+export function lifeOf(player: Player): LifeState | null {
+  return readLives(game.state[LIFE_KEY])[player] ?? null
+}
 
 /** Hit points a player has right now. 0 means they are on their way back. */
 export function healthOf(player: Player): number {
@@ -18,5 +24,20 @@ export function healthOf(player: Player): number {
  * point on their next sweep.
  */
 export function damage(player: Player, amount: number): void {
+  const life = lifeOf(player)
+  if (life?.dead || (life !== null && game.now() < life.protectedUntil)) return
   game.setState({ [HEALTH_KEY]: afterDamage(asHealthMap(game.state[HEALTH_KEY]), player, amount) })
 }
+
+export function heal(player: Player, amount: number): void {
+  const map = asHealthMap(game.state[HEALTH_KEY])
+  if (map[player] === undefined || map[player] <= 0 || lifeOf(player)?.dead || !Number.isFinite(amount)) return
+  const max = typeof game.state.healthMax === 'number' ? game.state.healthMax : 100
+  game.setState({ [HEALTH_KEY]: { ...map, [player]: Math.min(max, map[player] + Math.max(0, Math.round(amount))) } })
+}
+
+export function kill(player: Player): void {
+  const map = asHealthMap(game.state[HEALTH_KEY])
+  if (map[player] === undefined || lifeOf(player)?.dead) return
+  game.setState({ [HEALTH_KEY]: { ...map, [player]: 0 } })
+}

package/prefabs/health-respawn/scripts/pure/life.ts

@@ -0,0 +1,59 @@
+import { clampMax, type HealthMap } from './health'
+
+export interface LifeState {
+  life: number
+  deaths: number
+  dead: boolean
+  respawnAt: number
+  protectedUntil: number
+}
+
+export type LifeMap = Record<string, LifeState>
+
+export function freshLife(): LifeState {
+  return { life: 1, deaths: 0, dead: false, respawnAt: 0, protectedUntil: 0 }
+}
+
+export function readLives(value: unknown): LifeMap {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {}
+  const result: LifeMap = {}
+  for (const [player, entry] of Object.entries(value)) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const row = entry as Record<string, unknown>
+    if (typeof row.dead !== 'boolean' || ![row.life, row.deaths, row.respawnAt, row.protectedUntil]
+      .every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0)) continue
+    result[player] = {
+      life: row.life as number, deaths: row.deaths as number, dead: row.dead,
+      respawnAt: row.respawnAt as number, protectedUntil: row.protectedUntil as number
+    }
+  }
+  return result
+}
+
+export function advanceLives(
+  health: HealthMap, lives: LifeMap, fallen: ReadonlySet<string>, now: number,
+  maxHealth: number, delaySeconds: number, protectionSeconds: number
+): { health: HealthMap; lives: LifeMap; respawn: string[]; changed: boolean } {
+  const nextHealth = { ...health }
+  const nextLives = { ...lives }
+  const respawn: string[] = []
+  const delay = Number.isFinite(delaySeconds) ? Math.max(0, Math.min(60, delaySeconds)) * 1000 : 0
+  const protection = Number.isFinite(protectionSeconds) ? Math.max(0, Math.min(30, protectionSeconds)) * 1000 : 1000
+  let changed = false
+  for (const [player, hp] of Object.entries(health)) {
+    let life = lives[player] ?? freshLife()
+    if (!life.dead && (hp <= 0 || (fallen.has(player) && now >= life.protectedUntil))) {
+      life = { ...life, dead: true, deaths: life.deaths + 1, respawnAt: now + delay }
+      nextHealth[player] = 0
+      changed = true
+    }
+    if (life.dead && now >= life.respawnAt) {
+      life = { ...life, life: life.life + 1, dead: false, respawnAt: 0, protectedUntil: now + protection }
+      nextHealth[player] = clampMax(maxHealth)
+      respawn.push(player)
+      changed = true
+    }
+    nextLives[player] = life
+  }
+  return { health: nextHealth, lives: nextLives, respawn, changed }
+}

package/prefabs/leaderboard/ai.md

@@ -4,19 +4,25 @@ prefab: leaderboard
 
 # Leaderboard — AI guide
 
-A panel that shows one board: it reads a `game.state` key and paints the places.
-It never decides or stores a score.
+A panel or screen overlay that shows game scores or persisted course best times.
+The server validates and stores scores; this prefab displays them.
 
 The project copy is normally custom/leaderboard/ — check what is on disk, a
 second copy is custom/leaderboard_2/.
 
 ## When to use
 
-Whenever a game already keeps a ranked list and wants it on a wall. Place one per
-board: round scores and all-time bests are two keys, so two panels.
+For a course, place Run Progress and choose Source "Run best times" on this prefab.
+Use the same Course Id (default "course"). Confirmed finishes automatically fill
+the board, fastest first, and survive player departures and server restarts. No
+custom score code is needed. One course has one top-25 board.
 
-Place NOTHING if no server code writes rows — the panel would just show its empty
-line. Write the rows first, then place the board on that key.
+The 3D panel is solid and reads from its -z side: at identity rotation players
+stand at -z looking toward +z. Turn the board by rotating its root; never move or
+flip the text child.
+
+For other scoring systems choose Source "State key" and provide server-owned rows
+as below. Place one panel per board; use 2D UI when the scores belong on screen.
 
 ## API
 
@@ -37,12 +43,19 @@ There is nothing to import. The contract is the state key:
 
 Params of the prefab's script — set them in the placePrefab request:
 
+- `source`: `State key` (default) or `Run best times`.
+- `courseId`: matches Run Progress when source is `Run best times`.
+- `display`: `3D panel` (default) or `2D UI`. The overlay uses UI Theme.
+- `position`: `left` or `right` for the overlay.
 - `title`: the heading on the panel (default "Leaderboard").
 - `boardKey`: the `game.state` key to read (default `'leaderboard'`). Game Flow
   reads the same key for its winners line — point both at one key.
 - `sort`: `'desc'` (highest wins — points) or `'asc'` (lowest wins — best times,
   which also renders the score as m:ss).
-- `rows`: how many places the panel lists (default 8, max 25).
+- `rows`: how many places to list (default 8; max 25 in 3D, 10 on screen).
+
+For Run best times, Board Key and Sort are hidden: the course supplies the key,
+scores in seconds and ascending order. The shared key is `run:<courseId>:leaderboard`.
 
 ## The all-time board idiom
 
@@ -62,11 +75,16 @@ Then place a second Leaderboard with `boardKey: 'bestTimes'`.
   number a client reports is a claim.
 - DON'T write more than the visible places into the key. Fold to the top ten in
   server code — every extra row rides the wire on every change.
-- DO expect wallet addresses. There is no name lookup for a player who is not
-  connected, so offline players show as a shortened address.
+- Rows show display names: a player in the scene is named live; Run best times
+  stores the finisher's name when the server can see it. Give your own rows a
+  `name` beside `player` to keep it for offline players; else a short wallet shows.
 
 ## Example
 
+Without code: place Leaderboard, choose Source "Run best times", leave Course Id
+"course" to match Run Progress, and choose Display "2D UI". Finish the course;
+the server-validated time appears. Restarting or leaving does not erase the board.
+
 "Show the fastest climbers": in a handler inside the server branch keep the list,
 and place a board on that key.
 

package/prefabs/leaderboard/composite.json

@@ -28,7 +28,7 @@
         },
         "513": {
           "json": {
-            "position": { "x": 0, "y": 0.45, "z": 0.02 },
+            "position": { "x": 0, "y": 0.45, "z": -0.02 },
             "rotation": { "x": 0, "y": 0, "z": 0, "w": 1 },
             "scale": { "x": 1, "y": 1, "z": 1 },
             "parent": 512
@@ -42,7 +42,7 @@
         "512": {
           "json": {
             "src": "{assetPath}/board-panel.glb",
-            "visibleMeshesCollisionMask": 0,
+            "visibleMeshesCollisionMask": 2,
             "invisibleMeshesCollisionMask": 0
           }
         }

package/prefabs/leaderboard/data.json

@@ -1,7 +1,7 @@
 {
   "id": "493daede-2afd-4c10-9c0d-6aefb25629a8",
   "name": "Leaderboard",
-  "description": "Shows one of your game's boards — point it at the game.state key your game writes the rows to. Works with: Game Flow.",
+  "description": "Show game scores or automatic Run Progress best times on a 3D panel or themed screen overlay.",
   "category": "custom",
   "group": "Multiplayer Server",
   "tags": [
@@ -13,13 +13,16 @@
     "board"
   ],
   "requiresSdk": "auth-server",
-  "drivenBy": {
-    "rule": "This panel only paints what it reads — the server writes the rows into the synced state key named in Board Key, and every client draws them in order.",
-    "code": "game.setState({ leaderboard: [{ player, score }] })",
-    "next": "Press New script below and write that line inside the isServer() block it comes with, using the same key you set in Board Key above."
-  },
-  "version": "1.1.0",
+  "version": "1.4.0",
   "changelog": [
+    {
+      "version": "1.4.0",
+      "notes": "The 3D panel's text is readable from its front, and players can no longer walk through the board. A board placed before this keeps its old text position and no collider: delete it and place it again."
+    },
+    {
+      "version": "1.3.0",
+      "notes": "Rows show the display name of players in the scene, or a name the row carries; others show a short address."
+    },
     {
       "version": "1.0.0",
       "notes": "Initial release: a panel that reads the game.state key you name in boardKey and paints its top rows, so the board a Script keeps is the board every player sees and a late joiner gets it from the snapshot."
@@ -27,6 +30,10 @@
     {
       "version": "1.1.0",
       "notes": "The placed panel's Script card now shows the setState line that writes the rows it paints, under its own settings."
+    },
+    {
+      "version": "1.2.0",
+      "notes": "Themed screen overlay and automatic persisted best times from Run Progress."
     }
   ],
   "origin": {

package/prefabs/leaderboard/scripts/leaderboard-hud.tsx

@@ -0,0 +1,28 @@
+import ReactEcs, { ReactEcsRenderer, UiEntity } from '@dcl/sdk/react-ecs'
+import type { Entity } from '@dcl/sdk/ecs'
+import { UI_CANVAS, sceneUiTheme } from '~runtime/uiTheme'
+import { UiPanel, UiText } from '~runtime/uiComponents'
+import { formatScore, rowLabel, type BoardRow, type BoardSort } from './pure/board'
+
+export function mountLeaderboardHud(entity: Entity, position: 'left' | 'right', read: () => {
+  title: string; rows: BoardRow[]; sort: BoardSort; empty: string
+}): void {
+  ReactEcsRenderer.addUiRenderer(entity, () => {
+    const theme = sceneUiTheme()
+    const board = read()
+    const rows = board.rows.slice(0, 10)
+    return <UiEntity uiTransform={{ positionType: 'absolute', width: '100%', height: '100%', padding: 28,
+      justifyContent: position === 'left' ? 'flex-start' : 'flex-end', alignItems: 'center', pointerFilter: 'none' }}>
+      <UiPanel theme={theme} uiTransform={{ width: 420, height: 116 + Math.max(1, rows.length) * 40 }}>
+        <UiText value={board.title} color={theme.text} size={26} height={40} />
+        <UiText value={board.sort === 'asc' ? 'FASTEST TIMES' : 'HIGH SCORES'} color={theme.muted} size={14} height={24} />
+        {rows.length === 0 && <UiText value={board.empty} color={theme.muted} size={16} height={40} />}
+        {rows.map((row) => <UiEntity key={row.player} uiTransform={{ width: '100%', height: 40, pointerFilter: 'none' }}>
+          <UiText value={String(row.rank).padStart(2, '0')} color={theme.accentText} size={17} mono uiTransform={{ width: 42 }} height={40} />
+          <UiText value={rowLabel(row)} color={theme.text} size={18} uiTransform={{ width: 212 }} height={40} />
+          <UiText value={formatScore(row.score, board.sort)} color={theme.text} size={18} mono align="middle-right" uiTransform={{ width: 116 }} height={40} />
+        </UiEntity>)}
+      </UiPanel>
+    </UiEntity>
+  }, UI_CANVAS)
+}

package/prefabs/leaderboard/scripts/leaderboard.ts

@@ -7,10 +7,17 @@
 // The panel is ordinary scene content: swap board-panel.glb for your own model
 // and keep (or restyle) the text child — the script writes only its `text`, so
 // font, size and colour stay exactly as authored.
-import { TextShape, Transform, engine, type Entity } from '@dcl/sdk/ecs'
+// The text sits on the panel's -z face, where players read it (a TextShape reads
+// from -z); a replacement model must face the same way.
+import { TextShape, Transform, VisibilityComponent, engine, type Entity } from '@dcl/sdk/ecs'
 import { isServer } from '@dcl/sdk/network'
 import { game } from '~runtime/game'
 import { boardRows, clampRows, renderPanel } from './pure/board'
+import { runBoardKey } from '~runtime/pure/runBoard'
+import { playerName } from '~runtime/playerPositions'
+import { mountLeaderboardHud } from './leaderboard-hud'
+
+const NAME_REFRESH_S = 1
 
 const EMPTY = 'Nothing to show yet — set the board key the server writes to.'
 
@@ -23,27 +30,56 @@ export class Leaderboard {
     public entity: Entity,
     /** The panel's title. */
     public title: string = 'Leaderboard',
-    /** The game.state key this board shows. The server writes the rows there. */
+    /** For "State key": the game.state key containing the server's scores. */
     public boardKey: string = 'leaderboard',
-    /** Which score wins: highest keeps points, lowest keeps best times. */
+    /** For "State key": highest keeps points, lowest keeps best times. */
     public sort: 'desc' | 'asc' = 'desc',
     /** How many places the panel lists. */
-    public rows: number = 8
+    public rows: number = 8,
+    public source: 'State key' | 'Run best times' = 'State key',
+    /** For "Run best times": match the Course Id on Run Progress. */
+    public courseId: string = 'course',
+    public display: '3D panel' | '2D UI' = '3D panel',
+    /** For "2D UI": the side of the screen. */
+    public position: 'left' | 'right' = 'right'
   ) {}
 
   start(): void {
     if (isServer()) { return }
+    if (this.display === '2D UI') {
+      VisibilityComponent.createOrReplace(this.entity, { visible: false, propagateToChildren: true })
+      mountLeaderboardHud(this.entity, this.position, () => this.content())
+      return
+    }
     this.panel = this.findPanel()
     game.onStateChange(() => this.repaint())
+    // Avatar names arrive after the rows do, and with no state change to repaint on.
+    let wait = 0
+    engine.addSystem((dt) => {
+      wait += dt
+      if (wait < NAME_REFRESH_S) return
+      wait = 0
+      this.repaint()
+    })
     this.repaint()
   }
 
   private repaint(): void {
+    const content = this.content()
     this.paint(
-      renderPanel(this.title, boardRows(game.state[this.boardKey], this.sort, clampRows(this.rows)), this.sort, EMPTY)
+      renderPanel(content.title, content.rows, content.sort, content.empty)
     )
   }
 
+  private content() {
+    const runs = this.source === 'Run best times'
+    const sort: 'asc' | 'desc' = runs ? 'asc' : this.sort
+    const rows = boardRows(game.state[runs ? runBoardKey(this.courseId) : this.boardKey], sort, clampRows(this.rows))
+      .map((row) => ({ ...row, name: playerName(row.player) ?? row.name }))
+    return { title: this.title, sort, rows,
+      empty: runs ? 'Complete a run to set the first time.' : EMPTY }
+  }
+
   // The text lives on a child so the model can be replaced without touching it.
   private findPanel(): Entity {
     for (const [entity, transform] of engine.getEntitiesWith(Transform)) {