An event-driven on-screen score HUD — a roster of named, color-tinted rows that repaint whenever scores change.
What it does
ScoreboardSystem holds a fixed roster of players (id, label, tint) and a live score map. It subscribes to two public events: score.updated, whose allScores map it copies into the core, and score.reset, which clears every row back to zero. After each update it rebuilds the row snapshot — { title, fontSize, position, rows[] } — and emits scoreboard.updated carrying that snapshot and the source entity id. The HUD pixels are painted by the Solid panel in Scoreboard.panel.tsx, which reads the snapshot; the System never touches the 3D layer, so it does no per-frame work and runs identically wherever the events come from. It is decoupled from any specific point source: anything that emits score.updated with an allScores map drives it, which is the same shape Score rebroadcasts on score.changed.
Use it in a scene
A scene is just data — a list of entities, each with its components. At startup the SceneLoader turns this JSON into a live world; edit the file and reload to rebuild it.
Fastest path
bjs download scene Scoreboard
Pulls this exact scene into your project and runs it — no copy-paste. Add --all to grab the components and assets it needs too.
Or build it from scratch with the bjs CLI:
1Scaffold a project
npm create @babylonjsmarket/arcade@latest my-game
World, renderer, and dev server — ready to run.
2Install dependencies
cd my-game && npm install
3Add Scoreboard
bjs download Scoreboard
Copies its source into src/ so the scene resolves.
First time? Run bjs login once.
4Paste the scene into src/scenes/arcade-room.ts and run
npm run dev
SceneLoader builds the world from the JSON; reload to rebuild.
title (string, default "SCORE") — overlay heading shown above the rows.
fontSize (number, default 18) — base font size in CSS pixels.
position ("top-left" | "top-right" | "bottom-left" | "bottom-right", default "top-left") — which canvas corner the overlay anchors to.
players ({ entityId, name, color }[], default []) — the row roster. entityId must match the key used in score.updated's allScores map; color is RGB in [0,1], rendered as an rgb(...) swatch. A player with no score entry shows 0.
Events
Emits scoreboard.updated (ScoreboardEvents.UPDATED) after every rebuild — { entityId, snapshot }, where snapshot is { title, fontSize, position, rows } and each row is { entityId, name, colorCss, color, scoreText, score }.
Listens for score.updated (ScoreboardInputEvents.SCORE_CHANGED) — { ownerEntity?, score?, allScores? }. Only allScores is read; the snapshot is rebuilt from the whole map.
Listens for score.reset (ScoreboardInputEvents.SCORE_RESET) — { allScores? }. With an allScores map it sets those totals; without one it drops every row to 0.
Notes
The roster is fixed by players — only listed entityIds get a row. Scores in allScores for ids not in the roster are ignored, and roster ids absent from the map render as 0.
An update repaints every Scoreboard entity in the scene, so multiple boards (different corner, different title) stay in sync off the same events.
The roster's row order is the display order — it does not re-sort by score. Order players the way you want the rows stacked.
The component's input constant for the change event is score.updated. The bundled Score system rebroadcasts on score.changed with the same { allScores } payload, so bridge the two names (re-emit, or align the constant) when wiring Score directly into Scoreboard. The score.reset event matches on both sides as-is.
The core owns two pieces of state: the list of players being displayed (id, display name, tint color) and the live score map (entityId → score). Every frame the System feeds new score totals in; the core renders a row snapshot that the panel/overlay paints to the screen.
Keeping the rendering data pure means the scoreboard reads identically under BabylonJS, Three.js, or a headless test — the only thing that changes is whoever consumes the snapshot. No @babylonjs, no three, no solid-js, no DOM.
Public surface: createScoreboard(params, players?) — factory instance.setScores(map) — push fresh scores from the Score system instance.resetScores() — drop all scores back to 0 instance.setPlayers(players) — replace the row definitions instance.getPlayers() — current row definitions instance.getSnapshot() — { title, rows[] } ready for the overlay instance.setParams(partial) — live tuning from the panel instance.getParams() — current params instance.reset() — restore defaults (params + empty scores)
Scoreboard.core.ts
importtype { Color } from'@babylonjsmarket/ecs/renderer-types';exporttypeScoreboardPosition = | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';exportinterfaceScoreboardPlayer {/** Matches the `ownerEntity` key used in `score.updated` payloads. */entityId: string;/** Human-facing label for the row. */name: string;/** RGB in [0,1]. Rendered as an `rgb(...)` swatch next to the name. */color: Color;}exportinterfaceScoreboardParams {/** Overlay title. "SCORE" by default. */title: string;/** Base font size in CSS pixels. */fontSize: number;/** Which corner of the canvas container the overlay anchors to. */position: ScoreboardPosition;}exportconstDEFAULT_SCOREBOARD_PARAMS: ScoreboardParams = {title: 'SCORE',fontSize: 18,position: 'top-left',};exportinterfaceScoreboardRow {entityId: string;name: string;/** "rgb(r, g, b)" formatted on 0-255 ints, ready for CSS. */colorCss: string;/** Raw RGB in [0,1] for renderers that prefer tuples. */color: Color;/** The current score as a string — always "0" for players with no entry. */scoreText: string;score: number;}exportinterfaceScoreboardSnapshot {title: string;fontSize: number;position: ScoreboardPosition;rows: ScoreboardRow[];}exportinterfaceScoreboardInstance {setScores(scores: Readonly<Record<string, number>>): void;resetScores(): void;setPlayers(players: ReadonlyArray<ScoreboardPlayer>): void;getPlayers(): ReadonlyArray<ScoreboardPlayer>;getSnapshot(): ScoreboardSnapshot;setParams(partial: Partial<ScoreboardParams>): void;getParams(): Readonly<ScoreboardParams>;reset(): void;}functiontoRgbCss(color: Color): string {const r = Math.max(0, Math.min(255, Math.round(color[0] * 255)));const g = Math.max(0, Math.min(255, Math.round(color[1] * 255)));const b = Math.max(0, Math.min(255, Math.round(color[2] * 255)));return`rgb(${r}, ${g}, ${b})`;}exportfunctioncreateScoreboard(params: Partial<ScoreboardParams> = {},players: ReadonlyArray<ScoreboardPlayer> = [],): ScoreboardInstance {constactive: ScoreboardParams = { ...DEFAULT_SCOREBOARD_PARAMS, ...params };letroster: ScoreboardPlayer[] = players.map((p) => ({entityId: p.entityId,name: p.name,color: [p.color[0], p.color[1], p.color[2]], }));letscores: Record<string, number> = {};const buildRows = (): ScoreboardRow[] => roster.map((p) => {const score = scores[p.entityId] ?? 0;return {entityId: p.entityId,name: p.name,colorCss: toRgbCss(p.color),color: [p.color[0], p.color[1], p.color[2]],scoreText: String(score), score, }; });return {setScores(map) { scores = { ...map }; },resetScores() { scores = {}; },setPlayers(players) { roster = players.map((p) => ({entityId: p.entityId,name: p.name,color: [p.color[0], p.color[1], p.color[2]], })); },getPlayers() {return roster; },getSnapshot() {return {title: active.title,fontSize: active.fontSize,position: active.position,rows: buildRows(), }; },setParams(partial) {Object.assign(active, partial); },getParams() {return active; },reset() {Object.assign(active, DEFAULT_SCOREBOARD_PARAMS); scores = {}; }, };}
Scoreboard.defs.ts
Scoreboard — definitions.
Holds the ScoreboardComponent class, its event dictionary and the shapes its data and events travel in. No System lives here, which is the point: another component can name Scoreboard in a query, or type an event it listens for, without pulling Scoreboard's behaviour into its own bundle. Import from here, not from Scoreboard.ts.
Renderer-free Solid panel for the Scoreboard core. Binds directly to the live core instance and polls its snapshot so the overlay preview ticks along with the game clock. Zero imports from @babylonjs or three (including type-only).
The preview block inside this panel IS the scoreboard — the same markup would render in a standalone overlay. Keeping it here means the panel doubles as the live HUD when pinned open, which is exactly what the ref Scoreboard does (its "UI" was an absolute-positioned HTML div).
The core (Scoreboard.core.ts) owns the roster, the score map, and the formatted row output. This System is the thin driver: it subscribes to the public score events (score.changed, score.reset) and feeds them into the core, then broadcasts a scoreboard.updated event carrying the fresh snapshot so the overlay (panel viz) can repaint.
No adapter calls — Scoreboard is a pure on-screen HUD. Its pixels are painted by the renderer-free Solid panel that lives in Scoreboard.panel.tsx and is mounted by the Scoreboard.viz.tsx ECS wrapper. The same System works under both Babylon and Three because it never touches the 3D layer.
Re-exported from the shared dictionary rather than redeclared. The local copy had drifted to score.updated while Score emits score.changed, so the HUD silently never updated — which is exactly the failure the no-cross-component-event-import rule and the single dictionary exist to stop.
Scoreboard.ts
export { ScoreboardInputEvents };
System — listens to Score events, rebuilds snapshot
The definitions live in Scoreboard.defs.ts; re-exported so existing importers keep working. New code should import them from './Scoreboard.defs' directly.
Scoreboard.viz.tsx — ECS wrapper that registers the renderer-free Panel with vizStore. Mirrors Health.viz.tsx. The Panel itself is in Scoreboard.panel.tsx and works against either the Babylon or the Three.js demo unchanged — it only binds to the pure core.
