@dcl-regenesislabs/web-editor 0.1.1-37509646646.commit-126b34d → 0.1.1-38415884993.commit-9d6277f

package/prefabs/leaderboard/scripts/pure/board.ts

@@ -12,6 +12,7 @@ export interface BoardRow {
   rank: number
   player: string
   score: number
+  name?: string
 }
 
 const PLAYER_FIELDS = ['player', 'p', 'address', 'wallet', 'name']
@@ -28,6 +29,11 @@ export function shortName(player: string): string {
   return player.startsWith('0x') && player.length > 10 ? `${player.slice(0, 6)}…${player.slice(-4)}` : player
 }
 
+/** The display name the writer stored or the viewer resolved, else the short wallet. */
+export function rowLabel(row: { player: string; name?: string }): string {
+  return row.name?.trim() || shortName(row.player)
+}
+
 /** Whole seconds as m:ss — how an 'asc' board's times want to read. */
 export function formatScore(score: number, sort: BoardSort): string {
   if (sort === 'desc') return `${Math.round(score)}`
@@ -48,13 +54,14 @@ export function clampRows(value: number): number {
  */
 export function boardRows(value: unknown, sort: BoardSort, limit: number): BoardRow[] {
   if (!Array.isArray(value)) return []
-  const rows: { player: string; score: number }[] = []
+  const rows: { player: string; score: number; name?: string }[] = []
   for (const item of value) {
     if (!isRecord(item)) continue
     const playerKey = PLAYER_FIELDS.find((key) => typeof item[key] === 'string' && item[key] !== '')
     const scoreKey = SCORE_FIELDS.find((key) => typeof item[key] === 'number' && Number.isFinite(item[key]))
     if (playerKey === undefined || scoreKey === undefined) continue
-    rows.push({ player: String(item[playerKey]), score: Number(item[scoreKey]) })
+    const name = playerKey !== 'name' && typeof item.name === 'string' && item.name.trim() !== '' ? item.name : undefined
+    rows.push({ player: String(item[playerKey]), score: Number(item[scoreKey]), ...(name === undefined ? {} : { name }) })
   }
   rows.sort((a, b) => (sort === 'desc' ? b.score - a.score : a.score - b.score))
   return rows.slice(0, clampRows(limit)).map((row, index) => ({ rank: index + 1, ...row }))
@@ -66,6 +73,6 @@ export function renderPanel(title: string, rows: BoardRow[], sort: BoardSort, pl
     lines.push(placeholder)
     return lines.join('\n')
   }
-  for (const row of rows) lines.push(`${row.rank}. ${shortName(row.player)}   ${formatScore(row.score, sort)}`)
+  for (const row of rows) lines.push(`${row.rank}. ${rowLabel(row)}   ${formatScore(row.score, sort)}`)
   return lines.join('\n')
 }

package/prefabs/run-progress/ai.md

@@ -0,0 +1,101 @@
+---
+prefab: run-progress
+---
+
+# Run Progress — AI guide
+
+Timed courses with per-player checkpoints, collectibles, best times and a HUD.
+
+## When to use
+
+A race, obstacle course or collection route with start, finish and restart.
+Place Health & Respawn too; read its guide and set its fallback respawnAt and
+dieBelowHeight. Run Progress supplies each player's latest destination.
+The project copy is normally custom/run_progress/; inspect the actual folder.
+
+## API
+
+Configure the placed script, with one distinct courseId per course:
+
+- `courseId`: state namespace, default "course". One course has ONE owner: this
+  placed Run Progress. Never place a second one or call `createRun` with the same
+  id ("needs a unique courseId"); custom scripts read `runOf`/`restartRun` only.
+- `title`: completion screen title.
+- `objective`: short instruction below the status row.
+- `startArea`, `finishArea`: names of existing Trigger Areas.
+- `startMarker`: named entity at a safe feet position before the start area.
+  A missing marker falls back to its area's floor (logged), and with no area
+  either to Health & Respawn's respawnAt.
+- `checkpointAreas`: ordered Trigger Area picker; stored as comma-separated names, or pass an array through setScriptParams.
+- `checkpointMarkers`: one spawn marker per checkpoint, same order; a count mismatch is a problem card.
+- `collectibleAreas`: comma-separated Trigger Area names, each counts once per player.
+- `accentColor`: fallback six-digit hex color. Place UI Theme to style the entire scene together.
+- `collectibleVisuals`: comma-separated names of plain visual entities, matching collectibleAreas in order.
+- `hud`: "Full" (run panel, corner clock, controls), "Big timer" (one large
+  centred clock plus Restart and the results screen) or "Hidden" (draws nothing).
+  The creator's HUD request is THIS setting: "one big timer" = "Big timer". For a
+  custom HUD set "Hidden" and read `runOf()`; never draw a second clock beside it.
+
+An empty checkpointAreas or collectibleAreas disables that goal.
+All area names must be distinct. Place every area with fireWhen "every time" so
+it can trigger on later attempts. Each spawn marker must be above solid ground,
+clear of hazards, and outside its own checkpoint trigger. Names must be unique.
+
+Keep each visible orb/model on a plain entity and list it in collectibleVisuals.
+Attach custom bobbing or glow scripts there. Do not parent custom-script entities
+under a Trigger Area prefab: Update from prefab would remove those children.
+Collecting hides the named visual and its children for that player; restart shows it.
+When collectibleVisuals is empty, older scenes still hide the trigger and its children.
+Put static geometry, markers and areas in the authored scene so they remain editable.
+
+The server validates area entries through the shared game module. It starts the
+timer at startArea, requires ordered checkpoints and all collectibles at finishArea,
+and keeps independent progress per player. Falling retains progress. Restart moves
+only that player to startMarker, resets the run and retains their best time.
+Local entries immediately update the timer, pickups, checkpoints and completion HUD.
+Confirmed state reconciles that presentation; rejected or unconfirmed predictions
+roll back. Only server-confirmed finishes update personal bests. Use this behavior
+instead of adding another pickup request or waiting for server state to show feedback.
+
+Read `src/scripts/runtime/runs.ts` for state and restart functions and
+`src/scripts/runtime/gameHud.tsx` for reusable presentation components. Game state
+at `run:<courseId>` contains each player's phase, checkpoint, collected IDs,
+attempt, startedAt, elapsedMs and bestMs. Do not write it yourself.
+
+Confirmed finishes also publish a persisted top-25 board at
+`run:<courseId>:leaderboard`, with `{ player, score }` rows in seconds, fastest
+first. Place Leaderboard, choose Source "Run best times" and the same Course Id.
+It works without another script; restart and player departure retain the board.
+
+For a moving deck, attach `scripts/moving-platform.ts` from this prefab's actual
+project folder to an authored platform with a MeshCollider. Its `axis` is x/y/z,
+`distance` is the travel amplitude in metres, and `periodSeconds` is one cycle.
+Keep its whole path inside the parcels. Every player uses the same shared clock;
+test riding and jumping from it in the engine before treating it as reachable.
+
+## Do / Don't
+
+- DO use the existing Health & Respawn and Trigger Area guides.
+- DO size trigger areas generously enough for the moving avatar.
+- DO walk toward a safe takeoff edge before longer jumps; target landing centres.
+- DO keep jumps within the existing controller's reach and test the actual route.
+- DON'T add a second timer, checkpoint map, collectible counter or restart handler,
+  and never rewrite the run in your own script to change its look: set `hud`.
+- DON'T use Game Flow merely for individual restarts; reserve it for shared rounds.
+- DON'T claim completion from a build alone. Test falling, an incomplete finish,
+  all pickups/checkpoints, the finish screen and Run again.
+
+## Example
+
+Place areas Start, Finish, Checkpoint 1–3 and Orb 1–5; create safe markers
+Start Spawn and Spawn 1–3. Place Health & Respawn with respawnAt Start Spawn and
+dieBelowHeight below the platforms. Place Run Progress with its default names.
+The HUD and full run loop then work without another scene script.
+
+## Creator workflow
+
+Add and name Trigger Areas, then place Run Progress. In its inspector choose Start Area, Finish Area and
+Start Marker, and use **+ Add** in the checkpoint, spawn-marker and collectible lists; row order is the
+matching order. These are scene entity pickers, so no CSV or generated script is needed; names have no commas.
+Place **UI Theme**, choose one accent color and Dark or Light, and Play. The HUD, result dialog, progress,
+buttons and Announcer use that theme. Keep one UI Theme per scene; its settings override the fallback accent.

package/prefabs/run-progress/composite.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "components": [
+    { "name": "core-schema::Name", "data": { "0": { "json": { "value": "Run Progress" } } } },
+    { "name": "asset-packs::Script", "data": { "0": { "json": { "value": [
+      { "path": "{assetPath}/scripts/run-progress.tsx", "priority": 0, "layout": "{\"params\":{},\"actions\":[]}" }
+    ] } } } }
+  ]
+}

package/prefabs/run-progress/data.json

@@ -0,0 +1,43 @@
+{
+  "id": "8ea22784-81dd-4d60-b0ae-54fef4852fb7",
+  "name": "Run Progress",
+  "description": "Timed runs with per-player checkpoints, collectibles, finish conditions, restart and a configurable HUD.",
+  "category": "custom",
+  "group": "Multiplayer Server",
+  "tags": [
+    "course",
+    "race",
+    "checkpoint",
+    "collectible",
+    "timer",
+    "hud",
+    "restart"
+  ],
+  "requiresSdk": "auth-server",
+  "version": "1.3.1",
+  "changelog": [
+    {
+      "version": "1.3.1",
+      "notes": "Hit points show unless Health & Respawn's Health Bar is turned off, so older Health & Respawn copies keep their bar."
+    },
+    {
+      "version": "1.3.0",
+      "notes": "A missing spawn marker respawns players on its area's floor, not mid-air, and a checkpoint/marker count mismatch shows as a problem."
+    },
+    {
+      "version": "1.2.0",
+      "notes": "HUD setting: Full, one big centred timer, or Hidden for a custom HUD. Health shows only when Health & Respawn turns its bar on."
+    },
+    {
+      "version": "1.1.0",
+      "notes": "A missing spawn marker no longer stops the course: players respawn at the matching area, or at Health & Respawn's point."
+    },
+    {
+      "version": "1.0.0",
+      "notes": "Timed course runs with per-player checkpoints, collectible goals, restart, best times, a persisted leaderboard and a themed HUD."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}

package/prefabs/run-progress/scripts/moving-platform.ts

@@ -0,0 +1,28 @@
+import { Transform, type Entity } from '@dcl/sdk/ecs'
+import { game } from '~runtime/game'
+
+export class MovingPlatform {
+  private origin: { x: number; y: number; z: number } | null = null
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    public axis: 'x' | 'y' | 'z' = 'x',
+    public distance: number = 2,
+    public periodSeconds: number = 6
+  ) {}
+
+  start(): void {
+    const transform = Transform.getOrNull(this.entity)
+    if (transform !== null) this.origin = { ...transform.position }
+  }
+
+  update(): void {
+    if (this.origin === null || !['x', 'y', 'z'].includes(this.axis)) return
+    const transform = Transform.getMutableOrNull(this.entity)
+    if (transform === null) return
+    const period = Number.isFinite(this.periodSeconds) ? Math.max(2, this.periodSeconds) : 6
+    const distance = Number.isFinite(this.distance) ? Math.max(0, Math.min(16, this.distance)) : 0
+    transform.position[this.axis] = this.origin[this.axis] + Math.sin(game.now() / 1000 / period * Math.PI * 2) * distance
+  }
+}

package/prefabs/run-progress/scripts/run-progress.tsx

@@ -0,0 +1,170 @@
+import ReactEcs, { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
+import { engine, PlayerIdentityData, VisibilityComponent, type Entity } from '@dcl/sdk/ecs'
+import { isServer } from '@dcl/sdk/network'
+import { game, reportProblem } from '~runtime/game'
+import { RunHud } from '~runtime/gameHud'
+import { UI_CANVAS } from '~runtime/uiTheme'
+import type { ColorHex, EntityName, EntityNames, ZoneName, ZoneNames } from '~runtime/authoring'
+import { createRun, restartRun, runOf } from '~runtime/runs'
+import { entityWorld, namedEntity } from '~runtime/sceneNames'
+import type { Vec3 } from '~runtime/pure/worldTransform'
+import { elapsedRun, freshRun, type RunAction, type RunState } from '~runtime/pure/runState'
+import { RunPrediction } from '~runtime/pure/runPrediction'
+
+function list(value: string): string[] {
+  return value.split(',').map((name) => name.trim()).filter(Boolean)
+}
+
+function named(name: string | undefined) {
+  const entity = name?.trim() ? namedEntity(name) : null
+  return entity === null ? null : entityWorld(entity)
+}
+
+// A missing marker must not stop the course: respawn on the floor of its area, and
+// with no area either, let Health & Respawn's respawnAt decide.
+function spawnPosition(marker: string | undefined, area: string): Vec3 | undefined {
+  const exact = named(marker)
+  if (exact !== null) return exact.position
+  const zone = named(area)
+  console.log(zone === null
+    ? `[runProgress] no spawn marker "${marker ?? ''}" or area "${area}" — Health & Respawn's respawnAt is used`
+    : `[runProgress] no spawn marker "${marker ?? ''}" — respawning on area "${area}"`)
+  if (zone === null) return undefined
+  return { ...zone.position, y: zone.position.y - Math.abs(zone.scale.y) / 2 }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : {}
+}
+
+export class RunProgress {
+  private items: string[] = []
+  private points: string[] = []
+  private visuals: string[] = []
+  private prediction: RunPrediction | null = null
+  private notice = ''
+  private noticeUntil = 0
+  private pending = false
+  private lastVisual = ''
+
+  constructor(
+    public src: string,
+    public entity: Entity,
+    public courseId: string = 'course',
+    public title: string = 'Sky Lantern Run',
+    public objective: string = 'Collect every orb and reach the finish',
+    public startArea: ZoneName = 'Start',
+    public finishArea: ZoneName = 'Finish',
+    public startMarker: EntityName = 'Start Spawn',
+    public checkpointAreas: ZoneNames = 'Checkpoint 1, Checkpoint 2, Checkpoint 3',
+    public checkpointMarkers: EntityNames = 'Spawn 1, Spawn 2, Spawn 3',
+    public collectibleAreas: ZoneNames = 'Orb 1, Orb 2, Orb 3, Orb 4, Orb 5',
+    public accentColor: ColorHex = '#FFC459',
+    public collectibleVisuals: EntityNames = '',
+    /** "Big timer" shows one large clock at the top; "Hidden" draws nothing, for a custom HUD. */
+    public hud: 'Full' | 'Big timer' | 'Hidden' = 'Full'
+  ) {}
+
+  start(): void {
+    this.items = list(this.collectibleAreas)
+    this.points = list(this.checkpointAreas)
+    this.visuals = list(this.collectibleVisuals)
+    if (this.visuals.length !== 0 && this.visuals.length !== this.items.length) throw new Error('Each collectible area needs a matching visual name.')
+    const markers = list(this.checkpointMarkers)
+    if (isServer() && markers.length !== this.points.length) {
+      reportProblem('Run Progress', `${this.points.length} checkpoint areas but ${markers.length} spawn markers — give each checkpoint one marker, in the same order.`)
+    }
+    if (isServer()) {
+      createRun({
+        id: this.courseId, startArea: this.startArea, finishArea: this.finishArea,
+        startPosition: spawnPosition(this.startMarker, this.startArea),
+        checkpoints: this.points.map((area, index) => ({ area, position: spawnPosition(markers[index], area) })),
+        collectibles: this.items
+      })
+      return
+    }
+    this.prediction = new RunPrediction({ checkpoints: this.points, collectibles: this.items })
+    const watch = (area: string, action: RunAction) => game.onLocalAreaEnter(area, (validation) => {
+      this.current()
+      const predicted = this.prediction!.predict(action, game.now())
+      if (predicted.message) this.say(predicted.message)
+      this.update()
+      void validation.then((accepted) => {
+        this.current()
+        if (!accepted && predicted.id !== null && this.prediction!.reject(predicted.id)) {
+          this.say('Progress could not be confirmed. Try again.')
+          this.update()
+        }
+      })
+    })
+    watch(this.startArea, { type: 'start' })
+    watch(this.finishArea, { type: 'finish' })
+    this.points.forEach((area, index) => watch(area, { type: 'checkpoint', index }))
+    this.items.forEach((id) => watch(id, { type: 'collect', id }))
+    if (this.hud !== 'Hidden') ReactEcsRenderer.addUiRenderer(this.entity, () => this.render(), UI_CANVAS)
+  }
+
+  update(): void {
+    if (isServer()) return
+    const state = this.current()
+    if (state === null) return
+    const signature = `${state.attempt}:${state.collected.join(',')}`
+    if (signature === this.lastVisual) return
+    let complete = true
+    for (const [index, name] of this.items.entries()) {
+      const entity = namedEntity(this.visuals[index] ?? name)
+      if (entity === null) { complete = false; continue }
+      VisibilityComponent.createOrReplace(entity, { visible: !state.collected.includes(name), propagateToChildren: true })
+    }
+    if (complete) this.lastVisual = signature
+  }
+
+  private player(): string {
+    return (PlayerIdentityData.getOrNull(engine.PlayerEntity)?.address ?? '').toLowerCase()
+  }
+
+  private current(): RunState | null {
+    const state = runOf(this.courseId, this.player())
+    this.prediction?.reconcile(state, game.now())
+    return this.prediction?.view(game.now()) ?? state
+  }
+
+  private say(text: string): void {
+    this.notice = text
+    this.noticeUntil = game.now() + 3500
+  }
+
+  private restart(): void {
+    const state = runOf(this.courseId, this.player())
+    if (state === null || this.pending) return
+    this.pending = true
+    this.current()
+    const predicted = this.prediction?.predict({ type: 'restart' }, game.now())
+    this.update()
+    void restartRun(this.courseId, state.attempt).then((result) => {
+      if (record(result).ok !== true) throw new Error('Restart was refused')
+    }).catch((error: unknown) => {
+      if (predicted?.id != null) this.prediction?.reject(predicted.id)
+      this.say('Restart failed. Try again.')
+      console.log(`[runProgress] restart failed: ${String(error)}`)
+    }).finally(() => { this.pending = false })
+  }
+
+  private render(): ReactEcs.JSX.Element {
+    const player = this.player()
+    const state = this.current() ?? freshRun()
+    const health = game.state.healthBar === false ? null : record(game.state.health)[player]
+    const life = record(record(game.state.healthLife)[player])
+    return <RunHud
+      title={this.title} objective={this.objective} phase={state.phase}
+      elapsedMs={elapsedRun(state, game.now())} bestMs={state.bestMs}
+      checkpoint={state.checkpoint} checkpoints={this.points.length}
+      collected={state.collected.length} collectibles={this.items.length}
+      health={typeof health === 'number' ? health : null}
+      maxHealth={typeof game.state.healthMax === 'number' ? game.state.healthMax : 100}
+      respawnSeconds={life.dead === true && typeof life.respawnAt === 'number' ? Math.max(0, life.respawnAt - game.now()) / 1000 : 0}
+      notice={game.now() < this.noticeUntil ? this.notice : ''}
+      accentColor={this.accentColor} restart={() => this.restart()} hud={this.hud === 'Big timer' ? 'Big timer' : 'Full'}
+    />
+  }
+}

package/prefabs/server-clock/ai.md

@@ -13,9 +13,10 @@ second copy is custom/server_clock_2/.
 
 ## When to use
 
-Any shared deadline or shared elapsed time: a round timer, a countdown, a daily
-event, a scoreboard's "started at". Also just to show the time. Needs an
-scene with a Multiplayer Server (data.json requiresSdk: auth-server).
+Show the current server time, or reuse its synchronization module for a custom
+shared deadline. For a ready-made round countdown use Game Flow with display
+"2D UI". For a player's elapsed course time use Run Progress. This prefab shows
+clock time; it does not start or end rounds. Needs a Multiplayer Server scene.
 
 ## API
 
@@ -39,6 +40,9 @@ Params of the prefab's script — set them in the placePrefab request:
 - position: where the 2D overlay sits — 'top' (default), 'top left', 'top right'
   or 'bottom'. Ignored for '3D text'.
 
+The overlay uses UI Theme. Multiple placed clocks keep their own label, time and
+position; choose different corners so they remain visible.
+
 ## Shared deadlines
 
 Express a deadline as an absolute server timestamp, share THAT, and derive the
@@ -61,7 +65,6 @@ countdown locally every frame:
 
 ## Example
 
-"Show a 60-second round timer everyone sees the same": place Server Clock (or
-call initTimeSync() in a script of your own), store endsAt as a server timestamp
-when the round starts, and render Math.ceil((endsAt - getServerTime()) / 1000)
-in update() while isTimeSyncReady().
+"Show a 60-second round timer everyone sees the same": place Game Flow with
+roundSeconds 60, countdownSeconds 3 and display "2D UI". Place UI Theme to choose
+its palette. Use Server Clock separately if the scene also needs the time of day.

package/prefabs/server-clock/data.json

@@ -11,11 +11,15 @@
     "time"
   ],
   "requiresSdk": "auth-server",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "changelog": [
     {
       "version": "1.0.0",
       "notes": "Initial release: the Multiplayer Server's NTP-synced time, identical for every player, shown as 3D text at the item or as a 2D overlay on the player's client."
+    },
+    {
+      "version": "1.1.0",
+      "notes": "Shared UI theme and independent clocks when multiple items use the overlay."
     }
   ],
   "origin": {

package/prefabs/server-clock/scripts/server-clock.ts

@@ -1,7 +1,7 @@
-import { Entity, TextShape } from '@dcl/sdk/ecs'
+import { Entity, TextShape, VisibilityComponent } from '@dcl/sdk/ecs'
 import { isServer } from '@dcl/sdk/network'
 import { initTimeSync, getServerTime, isTimeSyncReady } from '~runtime/timeSync'
-import { mountClockHud, setClockHudText } from './clock-hud'
+import { mountStatusHud } from '~runtime/statusHud'
 
 // Displays the Multiplayer Server's clock, NTP-synced, identical for every
 // player — as floating 3D text, or as a 2D overlay on the player's client. Both
@@ -14,6 +14,7 @@ function pad(n: number): string {
 
 export class ServerClock {
   private accum = 0
+  private time = '--:--:--'
 
   constructor(
     public src: string,
@@ -21,7 +22,7 @@ export class ServerClock {
     /** Label above the time */ public label: string = 'SERVER TIME',
     /** Show in UTC instead of each viewer's timezone */ public utc: boolean = true,
     /** How the clock is shown */ public display: '3D text' | '2D UI' = '3D text',
-    /** Where the 2D UI sits in the player's view */ public position: 'top' | 'top left' | 'top right' | 'bottom' = 'top'
+    /** For "2D UI": where the clock sits on screen. */ public position: 'top' | 'top left' | 'top right' | 'bottom' = 'top'
   ) {}
 
   private get onScreen(): boolean {
@@ -32,9 +33,9 @@ export class ServerClock {
     initTimeSync()
     if (isServer()) return
     if (this.onScreen) {
-      // the 3D text becomes the overlay — remove the placed shape
+      VisibilityComponent.createOrReplace(this.entity, { visible: false })
       TextShape.deleteFrom(this.entity)
-      mountClockHud(this.entity, this.position)
+      mountStatusHud(this.entity, this.position, () => ({ label: this.label, value: this.time }))
     }
     this.render('--:--:--')
   }
@@ -57,7 +58,7 @@ export class ServerClock {
 
   private render(time: string): void {
     if (this.onScreen) {
-      setClockHudText(this.label, time)
+      this.time = time
       return
     }
     TextShape.createOrReplace(this.entity, {

package/prefabs/trigger-zone/ai.md

@@ -4,9 +4,8 @@ prefab: trigger-zone
 
 # Trigger Area — AI guide
 
-An invisible named volume that knows who is standing in it. Other scripts react
-to it BY NAME through the bus module in the project's shared runtime — nothing is
-wired, and a reacting script pasted into another scene keeps working.
+An invisible named volume. Scripts react to its name through the shared runtime
+bus; the same reaction works in another scene.
 
 ## When to use
 
@@ -97,10 +96,12 @@ reactions. Decide by what the reaction acts on:
   working for everybody. The prefab owns those callbacks; you consume the bus.
 - DON'T hand-roll proximity (distance loops against the player). The prefab
   exists so you never do.
-- The volume IS the entity's Transform scale in metres, so the scale gizmo is the
-  resize tool. Neither you nor the editor can measure a model's bounding box —
-  place the area NEAR the object at a sensible size and say in one line to drag
-  the scale handles to fit. Never claim you fitted it.
+- The volume IS the entity's Transform scale in metres. For a model, use
+  `asset_request inspect_model` and account for its scale, rotation and pivot.
+  Fit the area to the interaction space and verify entry/exit in play. Bounds
+  exclude animation; leave clearance for moving models and avatar height.
+- Keep the whole volume and its movement range inside the active parcels.
+  Resize with sceneSettings first and wait for its successful preview result.
 - Detection is client-side only: the headless server has no avatar colliders, so
   an area never fires there. Fine for doors, lights, sound, ambience. When an area
   gates something valuable (a reward, a score, a paid area) put the decision in a
@@ -110,6 +111,11 @@ reactions. Decide by what the reaction acts on:
 
 ## Example
 
+For a course, read the Run Progress and Health & Respawn guides too. Use Run
+Progress's start/checkpoint/finish references and its local feedback. Do not add
+a second score or checkpoint owner to the areas. Use the inspector's message
+action for a local notice; the server still validates progression and rewards.
+
 "Make the door open when someone walks up": placePrefab trigger-zone named
 "Front Door Area" (4×3×4 at the doorway, who: 'any player'), then a script on
 the Door entity whose update() runs the isInZone snippet above.

package/prefabs/trigger-zone/data.json

@@ -14,8 +14,9 @@
     "code": "onZone('Front Door', 'enter', (event) => { /* what happens */ })",
     "next": "Use the Add a reaction button below and the new Script arrives already listening to this area."
   },
-  "version": "1.1.0",
+  "version": "1.1.1",
   "changelog": [
+    { "version": "1.1.1", "notes": "Guide covers model bounds, active parcels and course prefab integration." },
     {
       "version": "1.0.0",
       "notes": "Initial release: an invisible named area that publishes who is standing in it, so a Script anywhere in the scene reacts to it by name with nothing wired."

package/prefabs/ui-theme/ai.md

@@ -0,0 +1,30 @@
+---
+prefab: ui-theme
+---
+
+# UI Theme — AI guide
+
+## When to use
+
+Place one UI Theme from the library. Pick Accent Color and Dark or Light in its inspector, then Play. Run Progress, Announcer, and the 2D UI modes of Game Flow, Server Clock and Leaderboard share the palette. A single color change restyles their buttons, timers, scores, progress indicators and results together; text contrast is derived automatically. Keep one theme per scene.
+
+## API
+
+- `accentColor`: six-digit hex color, edited with a color picker.
+- `appearance`: Dark or Light.
+
+For custom UI, import `sceneUiTheme` and `UI_CANVAS` from `~runtime/uiTheme`, and `UiPanel`, `UiText`, `UiButton`, `ProgressPips`, `UiNotice` from `~runtime/uiComponents`. Register with `ReactEcsRenderer.addUiRenderer(entity, render, UI_CANVAS)`. Keep viewport roots pointer-transparent and handlers on actual buttons. Labels and stacks need explicit dimensions. Inspect a screenshot in the real preview, including completion and a smaller viewport.
+
+`ColorHex`, `EntityName`, `EntityNames`, `ZoneName` and `ZoneNames` from `~runtime/authoring` are string aliases that give constructor parameters color or entity pickers. Plural references are ordered comma-separated names; creators pick and reorder them in the inspector. Names must be unique and contain no commas. The assistant can provide arrays to the plural parameters.
+
+## Do / Don't
+
+- Use one theme per scene, readable text and small non-blocking HUDs.
+- Do not write a separate palette for each prefab or use default pink SDK buttons.
+- Verify running and finished states in a real preview screenshot.
+
+## Example
+
+Place UI Theme with accentColor "#59E0AC" and appearance "Dark", then place Run Progress and Announcer.
+Their buttons, progress indicators, result panel and messages all share mint accents on dark surfaces.
+Choose a new accent in the inspector to change them together. No scene script is needed.

package/prefabs/ui-theme/composite.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "components": [
+    {
+      "name": "core-schema::Name",
+      "data": {
+        "0": {
+          "json": {
+            "value": "UI Theme"
+          }
+        }
+      }
+    },
+    {
+      "name": "asset-packs::Script",
+      "data": {
+        "0": {
+          "json": {
+            "value": [
+              {
+                "path": "{assetPath}/scripts/ui-theme.ts",
+                "priority": 0,
+                "layout": "{\"params\":{},\"actions\":[]}"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/prefabs/ui-theme/data.json

@@ -0,0 +1,24 @@
+{
+  "id": "41939776-72b2-45f1-b40a-097fa66c9790",
+  "name": "UI Theme",
+  "description": "One accent color and appearance for game HUDs, timers, leaderboards, buttons, results and announcements.",
+  "category": "custom",
+  "group": "Scene UI",
+  "tags": [
+    "ui",
+    "theme",
+    "color",
+    "hud",
+    "design"
+  ],
+  "version": "1.0.0",
+  "changelog": [
+    {
+      "version": "1.0.0",
+      "notes": "One accent color and dark or light appearance shared by the scene's game HUDs, buttons, timers, leaderboards and results."
+    }
+  ],
+  "origin": {
+    "source": "builtin"
+  }
+}