# board The pure leaderboard logic over plain tables: `submit` (keeps each player's best, reports personal best / world record / rank), `ranked`, `rankOf`, `around`, `top`, `merge` (best row per player across stores), `validRow` (corrupt rows are skipped) and `newSeason` (archives the top rows). Used by the store and the tests.

# store Keeps a board in runtime_data so it survives the world closing, and decides who may write it. Host mode: rows in the world store, written only by the keeper. Locked mode (`writers`): rows in those accounts' own player stores, server-enforced; a keeper that is not a writer holds results for approval. Every write is queued, retried with back-off and mirrored to the keeper's own outbox; `status()` reports saved, saving, retrying, held, offline or readOnly.

# ScoreKit The one component behind scoreKit. Put it on a **synced** entity (`entity.spawnSynced`), or let the first `Score.add` create one. The machine that owns the entity is the keeper: it runs the combo rules, writes the board, talks to MatchFlow and publishes every player's score in a synced snapshot. Every machine draws its own player's display, popups and results from it. Its fields are the world's defaults (display, look, popups, corner, results, the combo rules, the board id, writers, the MatchFlow binding and the remote-score checks). See the package README.

# rules The pure maths behind every score: the combo and multiplier rules (`config`, `add`, `tick`, `bonus`, `breakCombo`, `multiplierFor`, `stepProgress`), star and grade ratings (`rate`), ranking with shared places (`rank`) and the token bucket that limits scores sent by other machines (`checkRemote`). No engine calls; the package README's Combo rules section is this file in words.

# scoreKit 1.3.1 Scores, combos, multipliers, star ratings, grade letters and leaderboards for any Zero game, in one package. A game writes one line, `Score.add(player, 10)`, and the player sees it straight away: the number rolls up, a "+10" pops where it was scored, quick points build a combo, the multiplier climbs to x5, and the end of the round brings a rating card and a place on a leaderboard that is still there tomorrow. - **13 score displays, 5 popup styles, 6 leaderboard views, 4 end-of-round screens, 5 looks.** Every style works off the same data. Changing one setting swaps one for another, and nothing else in your code changes. - **Multiplayer by design.** One machine (the *keeper*) runs the rules and writes the board. Every player sees the same scores and the same board, and each player gets their own display, popups and results. - **Builds on MatchFlow, navUiKit and pickupsKit.** Rounds are MatchFlow matches: scores count in them and players are ranked when a round ends. Notifications ("x4 COMBO", "New personal best!") are navUiKit toasts. pickupsKit's coins, gems and hazards score through `ScorePickups`, once per grab. ## Install One install: search ZeroMind for "scoreKit" and install it from the ZeroMind panel, or ask your agent to run `zeromind_install` with `guid = a1e6c665-2332-4886-954e-06c028e86b19`. Your world gets `/source/scoreKit.package`, and the kits it builds on come with it under `/source/deps/`: MatchFlow (rounds), navUiKit (toasts) and pickupsKit (pickups that score, with the SecondWind, Lifeline and juiceKit it uses). There is nothing else to set up. While the files land, the log can show passing "waiting for content it requires" lines. ## First example Your world needs a scene with a player. A brand-new world has none yet: make one with `tools.use("scene", "create", "main", "player", { startup = true })` (ask the agent panel, or run it in an `execute` call). That writes `scenes/main.scene`, with a ground, lights and the default player. Then replace everything in `scenes/main.scene/entrypoint.luau` with this: ```lua local Score = require("scoreKit.score") local controls function onLoad() controls = asset.resolve("@builtin::inputMaps.default", "inputMap"):activate() controls.jump:onPressed(function() Score.add(nil, 10) -- nil = the player on this machine end) end ``` Press **Play** and jump (Space, or the jump button on a phone or a gamepad). The arcade counter appears top-left and rolls up by 10, and a "+10" pops under it. Jump three times quickly and the third jump is worth 20 (x2). Keep it going and you reach x3 at 6 jumps, x4 at 10 and x5 at 15, with an "x3 COMBO" toast along the way. Wait more than 2.5 s and the combo breaks. That's everything you need on one machine. With two or more players, scoring is keeper-only by default, so a jump on another player's machine is not counted. Score from code on the keeper (a coin it sees taken), or set `acceptRemote = true` to let each machine report its own player's points (see "Who can write the board"). The first `Score.add` creates the synced `ScoreKit` entity that keeps the score. You can also place it yourself to set its options: ```lua -- in a scene's build.luau, inside content() local kit = entity.spawnSynced("ScoreKit") kit.component.add(asset.resolve("scoreKit.ScoreKit", "component"), { display = "comboMeter", look = "fantasy", board = "level1" }) ``` From a coin, a kill or a checkpoint, pass whatever touched it. scoreKit walks up from the touching entity to the player's body: ```lua Score.add(touchingEntity, 10, { at = coin, reason = "coins" }) -- "+10" pops at the coin; "coins" is a results line Score.add(attackerBody, 100, { reason = "kills" }) Score.penalty(playerBody, 25) -- a hit taken: -25, and the combo breaks Score.bonus(playerBody, "No damage", 500) -- a named bonus line, never multiplied Score.breakCombo(playerBody, "fell") ``` ## Combo rules These are the exact rules, with the defaults. They are written so that you can balance a game around them. 1. **A hit is any `Score.add` with a positive amount**, unless it is passed `combo = false`. 2. **The combo** counts hits in a row. A hit that comes at most **2.5 s** (`window`) after the previous hit adds 1 to the combo. A hit that comes later, or after the combo broke, starts it again at 1. A gap of exactly `window` still counts. 3. **The multiplier** is 1 plus the number of `steps` the combo has reached, and never above `maxMultiplier`. With the default `steps = { 3, 6, 10, 15 }` and `maxMultiplier = 5`: | combo | 1–2 | 3–5 | 6–9 | 10–14 | 15 and up | |---|---|---|---|---|---| | multiplier | x1 | x2 | x3 | x4 | x5 | `every = n` replaces the steps with a uniform step: x2 at n hits, x3 at 2n, and so on up to `maxMultiplier`. 4. **The hit that reaches a step is already multiplied.** The 3rd hit is the first worth double. Points awarded = amount × multiplier, rounded to the nearest whole number with halves rounding up (`round = false` keeps fractions). 5. **The combo breaks** when: - **time runs out**: more than `window` seconds pass with no hit. The keeper checks this every frame, so a combo breaks on time even if no more points come. - **the game says so**: `Score.breakCombo(player)`. - **a penalty**: a negative amount always breaks the combo, unless `breakOnPenalty = false`. With `decay = "reset"` (the default) a break sets the combo to 0 and the multiplier to x1. With `decay = "step"` a timeout drops one multiplier step instead: the combo goes to that step's start (x4 → combo 6, x3) and gets a fresh window. If no hit comes, it keeps stepping down. `breakCombo` and penalties always reset. 6. **Penalties** (negative amounts) are never multiplied. 7. **`combo = false`** points are not a hit: they don't grow the combo or refresh its window, and they are not multiplied (pass `multiply = true` as well to multiply them by the current multiplier). **`multiply = false`** keeps a hit's points at face value while it still counts toward the combo. 8. **Bonuses** (`Score.bonus`) are never multiplied, never touch the combo, and get their own line in the results breakdown. The same label adds up. 9. **Score = points before multipliers + multiplier extra + bonuses − penalties.** The results breakdown lists exactly these, so its lines always add up to the total. Set the rules on the `ScoreKit` component's fields, or call this on every machine with the same values: ```lua Score.configure({ window = 1.8, steps = { 5, 10, 20, 40 }, maxMultiplier = 8, decay = "step", breakOnPenalty = false }) ``` ## Ratings: stars and grades A level sets targets. `Score.rate` (and the `stars`, `grade` displays and every results screen) turn a score or a time into 0–3 stars and a grade letter: ```lua Score.setTargets({ score = { 1000, 2500, 5000 } }) -- points for 1, 2, 3 stars Score.setTargets({ time = { 90, 60, 45 } }) -- seconds for 1, 2, 3 stars (lower is better) Score.setTargets({ score = { 1000, 2500, 5000 }, grades = { S = 7000, A = 5000, B = 3000, C = 1500 } }) local r = Score.rate(3100) -- { stars = 2, grade = "B", frac = 0.24, next = 5000, kind = "score" } ``` - **Stars** = how many targets the value meets (score: at least the target; time: at most the target). - **Grades** without explicit lines: **S** = 20% past the three-star target (score ≥ 1.2 × three, time ≤ three ÷ 1.2), **A** = three stars, **B** = two, **C** = one, **D** = below one. Explicit `grades` lines replace these. - `frac` is the progress from the last star target to the next one. `next` is the next target (nil at three stars). - With no targets set, the defaults are `{ score = { 1000, 2500, 5000 } }`, so the rating displays work out of the box. ## Rounds with MatchFlow When the scene has a **MatchFlow** match (the Match Flow Kit), scoreKit binds to it on its own (`match = "auto"`): - **Scores count in its matches.** The keeper reports every award, already multiplied, with `m:addScore(peer, points)`, so MatchFlow's HUD, standings and podium show the same numbers as scoreKit. - **Points only count while the round is playing** (`matchOnly = true`). An add during the lobby, countdown or results is refused, and a predicted "+10" is taken back. - **Every score goes back to 0** when a round's countdown starts. - **When a round ends, players are ranked.** MatchFlow's places are used, so every format ranks the way MatchFlow does. Each player's score is posted to the board, and every player gets their own results: the `roundEnded` event (on every machine) carries `{ n, ranking = { { key, name, score, place, stars, grade } }, results = { [key] = ResultsData } }`. Each player sees their results screen after MatchFlow's podium, during the break, never on top of it: the card waits until MatchFlow has finished showing its own results on that player's machine. It then stands in for MatchFlow's "next round" panel and shows "Next round in N" itself. If the break is over before the card could show, it is skipped, and a card still up when the next round counts down closes, so there is only ever one end-of-round screen. A new personal best or record shows its celebration first. Without MatchFlow, call `Score.endRound()` yourself to rank, post and show results, and `Score.resetRound()` to start over. `Score.submit(player)` posts a score to the board at any moment, for example at the end of a level. ```lua -- a whole match in two components on synced entities local match = entity.spawnSynced("Match") match.component.add(asset.resolve("~MatchFlow.MatchFlow", "component"), { format = "timed", roundSeconds = 30 }) local kit = entity.spawnSynced("ScoreKit") kit.component.add(asset.resolve("scoreKit.ScoreKit", "component"), { results = "tally" }) ``` MatchFlow comes with scoreKit as one of its dependencies, so name it with a `~` (`~MatchFlow.MatchFlow`): a kit that arrived as another kit's dependency is not found by its bare name from your own scripts (#19199). ## Pickups that score (pickupsKit) scoreKit comes with **pickupsKit**: coins, gems, hearts, keys and power-ups in 47 looks, where pickupsKit decides who took each one, even when two players grab at once. The `ScorePickups` component turns every grab into points for the player who took it: ```lua -- in a scene's build.luau, inside content() local Pickups = require("scoreKit.pickups").kit() -- pickupsKit's API, as scoreKit installed it for i = 1, 5 do Pickups.spawn({ (i - 3) * 1.5, 0, 4 }, { prefab = "goldCoin" }) end Pickups.spawn({ 0, 0, 7 }, { prefab = "ruby" }) Pickups.spawn({ 3, 0, 6 }, { prefab = "damageOrb", effect = "none" }) -- a hazard: no power-up, just a penalty entity.spawn("PickupScores").component.add(asset.resolve("scoreKit.ScorePickups", "component"), { points = "goldCoin=10, ruby=50, damageOrb=-25" }) ``` - **`points`** gives each pickupsKit prefab (`goldCoin`, `ruby` …) or kind (`coin`, `gem` …) its points. A prefab's entry beats its kind's. A negative value is a penalty: never multiplied, and it breaks the combo. A pickup with no entry scores nothing (pickupsKit still counts it). - **Each grab scores once.** pickupsKit tells every machine about a grab once. Only the machine keeping the score turns it into a `Score.add` for the player who took it, with the "+N" at the pickup and `coins`, `gems` … (or `hazards`) as the results line. Before the first point there is no `ScoreKit` yet: then the senior machine scores the grab, and its `Score.add` creates the kit, as the first example's jump does. So a coin is worth the same whichever player grabs it, on whichever machine. - Grabs build the combo like any other hit, and count only while a MatchFlow round is playing. - From code: `require("scoreKit.pickups").listen("goldCoin=10")` does the same and returns a stop function. `score(ev, points)` scores one pickupsKit `collect` event. - **Where pickupsKit's counter goes.** pickupsKit's `PickupHUD` sits in a top corner, and MatchFlow's standings take the top right, so put the counter top-left: `entity.spawn("PickupCounter").component.add(Pickups.HUD, { corner = "topLeft" })`. With `corner = "auto"`, scoreKit's score display sees it there and moves to the bottom-left, so the three never cover each other. - `require("scoreKit.pickups").kit()` is pickupsKit's own API (`spawn`, `burst`, `on`, `get` …), so a game that got pickupsKit with scoreKit reaches it through scoreKit. pickupsKit's README has every look and setting. ## Time trials ```lua Score.startRun(player) -- start the clock Score.split(player, "Bridge") -- a checkpoint (labels default to CP1, CP2 ...) Score.finishRun(player) -- the time goes to the time board, fastest first, with its splits ``` The `splits` display shows each split against the player's own best: green when ahead, red when behind. The `timeTrial` results screen shows the finished run against the best. The keeper times every run on its own clock. It uses the runner's own reading (which has no network delay) only when that reading is within 0.75 s of the keeper's. A runner can't claim a time their run didn't take. ## Leaderboards Each world has its own boards, kept in the world's `runtime_data`, so they survive the world being closed and opened again. A board keeps **one row per player: their best of the season** (highest score, or fastest time on a time board), and counts their plays. ```lua local board = Score.board() -- the kit's board (field `board`, default "main") local times = Score.timeBoard() -- "<board>_times": fastest first board:top(10) -- { { k, n, v, rank, st, g, at, c } } board:around(player, 5) -- you and the players just above and below board:entry(player), board:rankOf(player) board:season(), board:seasons() -- the current season, and past ones with their top 10 board:newSeason("Summer") -- archive this season's top 10 and start an empty one board:remove(player) -- take a stale or test row off this season (the writer in charge only) board:status() -- is it saved? (below) board:data(player) -- exactly what the board views draw board:onChange(fn) Score.board("level2") -- any number of boards, by id ``` **Seasons.** `newSeason` archives the current season's top 10 (names, values, stars, grades), records how many players it had, and opens season N+1 empty. Old rows stay in storage under their season. `board:seasons()` and the `seasons` view show the champions of every past season. Only the board's writer can start a season, and only while it is the keeper. ## Who can write the board **Only the keeper changes scores, and only the keeper writes the board.** The keeper is the machine that owns the synced `ScoreKit` entity: whoever loaded the scene first, or, after that machine leaves, the remaining player with the lowest peer id. Every other machine only *asks* it, and by default its asks are refused: - **Scoring is keeper-only by default** (`acceptRemote = false`). Only code running on the keeper changes a score. The keeper sees every player's body, so a coin, a kill or a checkpoint is judged there, as the gallery's coins are. You can run the same code on every machine: the keeper's call counts, and on the other machines `Score.add` sends nothing, predicts nothing and fires `refused` locally. So each pickup counts once. `Score.isKeeper()` says where you are. - **No machine can post its own value to the board.** A post asked for from another machine carries no number. The keeper posts the score it counted, and only to the kit's score board. Times reach the time board only from runs the keeper timed itself. - **Only the keeper's messages are believed.** Other machines take standings, awards and round results only from the keeper's peer. A player who sends their own "snapshot" or "award" is ignored, and the ignore is logged. - **Points formats are ranked on the keeper's counted scores**, not on MatchFlow's standings: MatchFlow takes reports from any machine. MatchFlow's places count only for `race`, `lastStanding` and `kingOfTheHill`, where order is not decided by points. - **Only while playing**, when bound to a MatchFlow match. **`acceptRemote = true`** lets each machine report points for its own player, for events only that machine can see, such as a button press. Its "+N" then shows instantly. That is a trust decision, because a modified client can then claim points for itself within these caps: - **Only its own player** (`remoteFor = "self"`): a request to score for anyone else is refused and logged. - **No absurd amounts**: a single remote add above `maxPerAdd` (1000) is refused. - **No floods**: more than `maxPerSecond` (20) remote adds per player per second are refused (short bursts of up to twice that are allowed). A refused request is answered with the reason: the sender's "+N" is taken back, a `refused` event fires there, and a warning is logged on both machines. **Two modes, set by the `writers` field:** | `writers` | Where the board lives | Who can write it | |---|---|---| | empty (default) | the world store (`runtime_data.world`) | the keeper, whoever it is | | `"<userId>, <userId>"` | those accounts' **own** player stores (`runtime_data.player(id)`) | only those accounts, and only while one of them is the keeper. The Zero server enforces it: no other account can write a player store. | The default mode protects the board from the kit's own network path. Nothing another player's game sends can change it. But `runtime_data.world` itself accepts writes from any client, so a player who runs modified engine code could still write it directly. If your board must hold against that too, set `writers` to your own account id(s) (`runtime_data.localId()` prints yours). **What happens when a write can't be made.** Scores are never lost silently: | The board's status | When | What happens | |---|---|---| | `saved` | every write landed | nothing to do | | `saving` | writes in flight | they land within a moment | | `retrying` | a write failed (network, store unavailable) | it stays queued and is retried with back-off (0.5 s, 1 s, 2 s … up to 30 s) until it lands. The queue is also kept in the keeper's own player store, so it is replayed if the keeper's tab closes first. | | `held` | locked mode and the keeper is not a writer | the result is **held**: queued in the world store as a pending result, not put on the board. The player gets a toast saying so, and the results screen says "Held for the board's keeper". A writer later calls `board:held()`, `board:approveHeld("all")` or `board:rejectHeld(ids)`. | | `offline` | `runtime_data` is not available | nothing is written; the status says so | | `readOnly` | on a machine that is not the keeper | `board:status()` there reports the keeper's status from its snapshot | Every board view shows this status as a chip, so players can see whether their score is saved. ## Multiplayer - **The keeper** runs the rules (combos time out on its clock), applies every add, writes the board and publishes every player's score, combo, multiplier and combo timer in a synced snapshot on the `ScoreKit` entity, up to 12 times a second (and at least twice a second). **Every player sees the same scores and the same board.** - **Each player's display and popups are their own.** Each machine draws its own player's corner display, "+N" popups, toasts and results screen. Nobody sees another player's popups. - **Seen quickly.** A player sees their own points as soon as the keeper's next snapshot reaches them (it publishes up to 12 times a second). With `acceptRemote = true`, `Score.add` on the player's own machine is also *predicted*: the points, the combo and the "+N" show the moment it is called. The prediction is let go once the keeper's snapshot confirms it, and taken back if it is refused. One that is never confirmed is dropped after 3 s with a warning. - **Players come from the scene's player setup** (`layers.active.players`). Every player in the match has their own score, results and board row: - A signed-in player's key is `u:<userId>`, so a returning player keeps their personal bests. - **The same account signed in on two machines is two players.** The session on the lowest peer keeps `u:<userId>`; the next is `u:<userId>#2` and shows as "Name (2)", and so on. Each has its own score, its own place in the round and its own board row. - `p:<peer>` is used for an anonymous session, and `b:<name>` for bots (`Score.add("Robo", 10)`, `Score.setName`). - **Only players who are here are ranked.** A round's ranking, its places ("1st of 2") and the board posts cover the players in the scene's player setup when the round ends, plus any bots the game scored by name. A player who left before the end is not ranked or posted, and a key nobody plays under can never take a place. - **Each event counts once.** With the default keeper-only scoring, only the keeper's `Score.add` counts, so the same pickup code can run on every machine. With `acceptRemote = true`, report an event either from the keeper or from the player's own machine, not both. - **If the keeper leaves**, the entity passes to another machine, which carries on from the last snapshot. Writes still queued on the leaver are replayed the next time that account keeps. Points scored in the instant of the handover can be lost. - **Events** fire on every machine: `award`, `comboUp`, `comboBreak`, `record`, `held`, `submitted`, `run`, `roundStarted`, `roundEnded`, `refused`, `snapshot`. Use `Score.on(name, fn)`, which returns an unsubscribe function. ## Styles Every style is listed by `Score.catalog()` as `{ id, family, name, description, natural = { w, h }, themed, tags = { look, looks, size, genres, shows } }`. Filter it with `Score.catalog("display")` or `Score.catalog({ family = "board", genre = "racing" })`. Themed styles draw in any of the five looks. ```lua Score.setDisplay("multiplierRing") -- this machine's corner display Score.setLook("fantasy") -- themed displays, boards, results Score.setPopups("cartoon") -- "+N" popups ("off" to hide) Score.setResults("tally") -- the end-of-round screen Score.setHud({ corner = "topRight", scale = 0.8 }) -- corner: auto, topLeft, topRight, bottomLeft, bottomRight, top, bottom ``` Or set the world's defaults with the `ScoreKit` fields `display`, `look`, `popups`, `results` and `corner`. ### Score displays (`display`) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `arcade` | Arcade Odometer | arcade | medium | arcade, shmup, pinball, platformer | Zero-padded rolling digits in a black glass bezel. Every digit column rolls like an odometer, with a 1UP label and a multiplier chip. | | `pixel` | Pixel Counter | arcade | medium | retro, arcade, platformer | Chunky 8-bit pixel digits with a hard shadow, a stepped pixel combo bar and a pixel x3. | | `comboMeter` | Combo Meter | any (themed) | medium | action, rhythm, brawler, arcade | Score plus a wide meter that fills toward the next multiplier step, and a strip that drains with the combo window. | | `multiplierRing` | Multiplier Ring | any (themed) | medium | action, shooter, rhythm | A circular ring that drains with the combo window, one segment per multiplier step, and a big xN in the centre. | | `stars` | Star Rating | any (themed) | medium | puzzle, casual, mobile, platformer | Score with three stars that fill as the score passes its targets. The next star fills partially. | | `grade` | Grade | any (themed) | medium | action, rhythm, racing, stylish | A big grade letter (S A B C D, each its own colour, S shines) with progress toward the next grade. | | `splits` | Time Trial Splits | any (themed) | large | racing, speedrun, time trial, parkour | Running timer, finished splits with green/red deltas, the current split highlighted, an ahead/behind banner and the time to beat. | | `minimal` | Minimal | minimal | small | any, casual, exploration | Quiet thin type straight over the game with a soft shadow, a small label and a subtle xN. | | `scifi` | Holo Readout | scifi | medium | shooter, space, cyberpunk | Clipped-corner holographic frame with scanlines, glowing mono digits and the combo as tick segments. | | `fantasy` | Gilded Plaque | fantasy | large | rpg, adventure, medieval | A walnut plaque on a parchment ribbon with gold serif numerals, a wax-seal multiplier and rune gems lighting up. | | `cartoon` | Bouncy Cartoon | cartoon | medium | casual, kids, party, platformer | A chunky inked number on a yellow starburst that squashes and stretches on every award, with a combo starburst badge. | | `neon` | Neon Sign | arcade | medium | arcade, synthwave, rhythm | A glowing neon-tube number with a subtle flicker, and the multiplier in a second tube colour. | | `broadcast` | TV Score Bug | any | small | sports, racing, party, multiplayer | A sports-broadcast lower third: LIVE dot, place, player name, score and a multiplier tag. | ### Popups (`popups`) "+N" where the points were scored: projected from the `at` position you pass, or under the display when there is none. Kinds: normal, combo (with its xN), big (at least `bigAt` = 100), bonus (with its label) and penalty (red, falling). | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `pop` | Clean Pop | any (themed) | small | any | Bold outlined number that pops in, rises and fades. Draws in the current look. | | `arcade` | Arcade Pixel | arcade | small | retro, arcade, platformer | Pixel-font number that hops up in hard steps and blinks out. Big throws pixel sparks. | | `scifi` | Holo Bracket | scifi | small | shooter, space, cyberpunk | Glowing mono number between brackets that spread open. Big draws an expanding hex, penalty glitches. | | `fantasy` | Gold Embers | fantasy | small | rpg, adventure, medieval | Gold serif numerals that drift up like embers with sparks. Big radiates rays. | | `cartoon` | Inked Bounce | cartoon | small | casual, kids, party | Chunky inked number with an elastic bounce and a tilt. Big lands on a starburst, bonus on a ribbon. | `popups = "auto"` (the `ScoreKit` default) picks the popup that matches the look. ### Leaderboards (board views) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `top10` | Top 10 | any (themed) | medium | arcade, platformer, puzzle, racing, party | The classic high-score table: rank with medals, avatar, name, stars and grade, value. Your row is highlighted, and pinned under a divider when you are outside the top 10. | | `podium` | Podium | any (themed) | large | party, arcade, sports, racing | The top three on stepped podium blocks (1st centre, crowned), with 4th to 8th as a compact list. | | `aroundMe` | Around Me | any (themed) | medium | arcade, platformer, puzzle, racing, endless | Your rank as a hero (#17 of 214, top 8%), the rows just above and below you, and how far it is to pass the next player. | | `bestTimes` | Best Times | any (themed) | medium | racing, platformer, speedrun, time-trial | Fastest first, with a stopwatch: the track record on top, every other time with its gap to first and a gap bar. | | `seasons` | Seasons | any (themed) | large | competitive, arcade, sports, racing | This season's standings under a season badge, beside a hall of champions: each past season with its top three. | | `sign` | Scoreboard Sign | any (themed) | large | arcade, platformer, party, racing, hub | A sign that stands in the level (the `ScoreSign` component), framed per look: arcade marquee with bulbs, LED panel, holo-board, wooden notice board, chalkboard. Top 5 in big type. | Draw any view anywhere with `require("scoreKit.boards").render(id, look, Score.board():data(), { w, h, t })`. **A board in the level:** the `ScoreSign` component builds a sign (two posts and a backboard) and draws a board view on its face, live: ```lua local sign = entity.spawn("HallOfFame", { position = { 0, 0, -10 } }) sign.component.add(asset.resolve("scoreKit.ScoreSign", "component"), { view = "sign", look = "fantasy", width = 5, height = 3 }) ``` Fields: `board` (empty = the kit's), `view` (any board view), `look`, `title`, `width`, `height` (metres), `lift` (height above the ground), `frame` (false: no posts or backboard, for your own wall), `maxDistance`. ### End-of-round screens (`results`) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `ratingCard` | Rating Card | any (themed) | medium | arcade, platformer, puzzle, rhythm, party | Stars that pop in one by one, a big grade letter, the score and this round's place, a breakdown table that adds up to the total, and best-combo / max-multiplier chips. | | `celebration` | Celebration | any (themed) | large | arcade, platformer, racing, endless, party | NEW PERSONAL BEST or NEW WORLD RECORD with rays and confetti, the new score, the previous best, the improvement and the board rank. A calm "Good run" when neither. | | `tally` | Tally | any (themed) | medium | arcade, platformer, action, rhythm | A combo and bonus tally that counts up: each breakdown line appears and counts from 0, a running total climbs, then the final total punches in with the rating. | | `timeTrial` | Time Trial | any (themed) | medium | racing, platformer, speedrun, time-trial | The final time big, every split against its best with green (ahead) / red (behind) deltas and a gap bar, a PB / record badge and the time to beat. Handles a first run with no best. | A finished time run always shows `timeTrial`. A round that brings a personal best or record shows `celebration` before a `ratingCard`. The screen closes on its own after `resultsSeconds`, or on a click or tap. ### Looks | id | name | what it is | |---|---|---| | `arcade` | Arcade | Black glass, neon yellow and magenta, chunky monospace digits. | | `minimal` | Minimal | White cards, quiet blue accent, clean sans type (MatchFlow's minimal). | | `scifi` | Sci-Fi | Dark navy glass, cyan and pink glow, clipped corners (MatchFlow's sci-fi). | | `fantasy` | Fantasy | Parchment and walnut, gilded gold, serif type. | | `cartoon` | Cartoon | Cream panels, thick ink outlines, hard drop shadows (MatchFlow's cartoon). | `minimal`, `scifi` and `cartoon` use MatchFlow's own design tokens, so a world running both kits looks like one game. ## The ScoreKit component | Field | Default | What it does | |---|---|---| | `display` | `arcade` | the corner score display | | `look` | `arcade` | the look for themed displays, boards and results | | `popups` | `auto` | "+N" popup style (`auto` follows the look, `off` hides them) | | `corner` | `auto` | `auto` (top-left; bottom-left when pickupsKit's counter is in the top-left or a MatchFlow timer would overlap; the bottom on a phone), `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `top`, `bottom` | | `showHud` | `true` | off: draw nothing, and build your own HUD from `Score.state()` | | `results` / `resultsSeconds` | `ratingCard` / `7` | the end-of-round screen (`none` for none) and how long it stays | | `toasts` / `toastComboFrom` | `true` / `3` | navUiKit toasts; a combo toast when the multiplier reaches this (0 = never) | | `window`, `steps`, `maxMultiplier`, `decay`, `breakOnPenalty` | `2.5`, `"3,6,10,15"`, `5`, `reset`, `true` | the combo rules | | `board` / `boardTitle` | `main` / "" | the board's id and title (time board: `<board>_times`) | | `writers` | "" | user ids that may write the board (empty: the keeper) | | `match` | `auto` | bind to the scene's MatchFlow (`off`, or the Match entity's name) | | `acceptRemote`, `maxPerAdd`, `maxPerSecond` | `false`, `1000`, `20` | off: only the keeper scores. On: other machines may report their own player's points, capped by the other two | `Score.configure` also takes `matchOnly`, `remoteFor`, `round`, `bigAt`, `every`, `targets`, `comboToast` and `recordToast` (navUiKit toast variants, default `minimal` and `achievement`), and `resultsAt` (`auto` waits for MatchFlow's results to finish). ## API `local Score = require("scoreKit.score")`. From inside another package, use `require("~scoreKit.score")`. | Call | Does | |---|---| | `Score.add(player, amount, { at, reason, combo, multiply })` | add points; returns the points awarded, as a number (see below) | | `Score.penalty(player, amount, opts)` / `Score.bonus(player, label, amount)` / `Score.breakCombo(player, reason)` | take points away / a named bonus / break the combo. `penalty` and `bonus` return the points awarded too. | | `Score.get(player)` / `Score.state(player)` / `Score.players()` | a score / everything live about a player / everyone this round, ranked | | `Score.configure(opts)` / `Score.rules()` / `Score.setTargets(t)` / `Score.rate(v, t)` | rules and settings / the rules in force / a level's targets / a rating | | `Score.setDisplay`, `setLook`, `setPopups`, `setResults`, `setHud`, `start`, `stop` | this machine's HUD | | `Score.catalog(filter)` | every style with its tags | | `Score.endRound(opts)`, `Score.resetRound()`, `Score.submit(player, value, { board })`, `Score.lastRound()`, `Score.match()` | rounds and posting | | `Score.startRun`, `split`, `finishRun`, `cancelRun` | time trials | | `Score.board(id)`, `Score.timeBoard()` | board handles (see Leaderboards) | | `Score.on(event, fn)`, `Score.isKeeper()`, `Score.keyOf(player)`, `Score.setName(player, name)` | events and identity | | `require("scoreKit.pickups")`: `listen(points)`, `score(ev, points)`, `scoresHere()`, `parse`, `pointsFor`, `reasonFor`, `kit()` | pickupsKit grabs as points (see Pickups that score) | **What `Score.add` returns.** Always a number: the points that call put on the score. - **On the keeper** (a solo game, or the host): the points awarded after the combo multiplier, at once. Three quick `Score.add(player, 10)` calls return 10, 10, then 20 (x2). `Score.penalty(player, 25)` returns -25, and `Score.bonus(player, "No damage", 500)` returns 500. - **0 when nothing was awarded:** outside a playing MatchFlow round, or when the call was refused. - **On another machine with keeper-only scoring** (`acceptRemote = false`, the default): 0. That machine's call awards nothing; the keeper's own call for the same event is the one that counts. - **On another machine with `acceptRemote = true`:** the points it predicts, shown at once. The keeper confirms them within a round trip, or takes them back if it refuses. The renderers are plain functions over data, for drawing a style inside your own UI. Each data shape is written down, with a moving sample generator, in `scoreKit.demo`: - `scoreKit.displays.render(id, data, { w, h, look, t })` - `scoreKit.popups.render(id, popup, { k, look })` - `scoreKit.boards.render(id, look, data, { w, h, t, narrow })` - `scoreKit.results.render(id, look, data, { w, h, t, narrow })` ## The gallery `ScoreGallery` is the style browser the Hall of Fame world opens with. Its **Everything** tab puts every score display, every leaderboard and every end-of-round screen on one page, side by side and labelled with their tags. Further tabs show each family larger, plus the popups. Every card draws from **one feed** at the same moment: in a round it is your own live score, combo and multiplier, the world's real boards and your last round's results (the card is marked LIVE). Before there is anything live, all cards play the same demo run in lockstep (marked DEMO). A look switcher redraws every themed card, and a "Use" button on a card puts that style on your own HUD. The **Live round** tab shows the world's real round and board. Add it to any scene: `entity.spawn("Gallery").component.add(asset.resolve("scoreKit.ScoreGallery", "component"), {})`. **The coin round is scoreKit with pickupsKit.** The arena's seven gold coins, the ruby and the damage orb are real pickupsKit pickups, placed in the scene's `build.luau` exactly as in "Pickups that score". pickupsKit decides who took each one, pops it, counts it on its own counter (top left, so MatchFlow's standings keep the top right) and brings it back. The score display then sits bottom-left on its own (`corner = "auto"`). A `ScorePickups` with `points = "goldCoin=10, ruby=50, damageOrb=-25"` scores each grab. The world has no coin code of its own. ## Phones and the browser - Every screen is sized from the safe area (`ui.safeArea()`, through MatchFlow's `theme.viewport()`). On a phone held upright (under 640 points wide), the corner display takes at most 62% of the width. Results screens and the gallery switch to single-column layouts (boards and results take `narrow`) instead of shrinking their text. - Everything is UI-tree drawing (boxes, SVG, engine-bundled fonts: Anton, Archivo Black, Arimo, Comic Neue, EB Garamond, PT Serif, JetBrains Mono), with no textures or shaders to load, so the web build draws the same thing on its first frame. - Results screens close on a tap. The gallery's buttons are full-size touch targets. ## What it builds on | Package | World | Used for | |---|---|---| | **MatchFlow** 1.0.0 | Match Flow Kit | rounds: `addScore`, `getPhase`, `getStandings`, `onStateChanged`, `onRoundEnded`. Its theme tokens are the base of three looks. | | **navUiKit** 1.0.1 | Wayfinder Studio | toasts (`Nav.toast`, achievement / minimal / banner variants), and its camera projection (`navUiKit.geom`) for popups and signs | | **pickupsKit** 2.3.0 | Treasure Trove | pickups that score: `ScorePickups` and `scoreKit.pickups` listen to its `collect` event (see Pickups that score). It brings SecondWind, Lifeline and juiceKit with it, and the same MatchFlow. | They come with scoreKit: its code names them (`~MatchFlow.theme`, `~navUiKit.nav`, `~navUiKit.hud`, `~navUiKit.geom`, `~pickupsKit.api`), and an install brings what the published package references. scoreKit finds them by package name, so they work wherever the install puts them (`/source` or `/source/deps/<guid>/`). Keep one copy of each: a second MatchFlow, navUiKit or pickupsKit makes its name ambiguous. If the log shows `module '~navUiKit.nav' not found`, `'~MatchFlow.theme' not found` or `'~pickupsKit.api' not found`, install the missing kit from ZeroMind ("navUiKit", "MatchFlow", "pickupsKit"). Only the part that uses it stops working: without navUiKit scoreKit draws its own toasts, without MatchFlow it uses its embedded looks, and without pickupsKit only `ScorePickups` fails to load. scoreKit carries its toasts on a navUiKit HUD it makes itself through navUiKit's `hud` module. It shows only the toasts (no minimap, compass or objectives, and the map key is unbound), and needs no navUiKit component in your scene. If your world runs navUiKit's own HUD (`Nav.start()` or a NavHud), scoreKit's toasts appear on that one instead. ## Tests The `scoreKit` test suite runs in edit mode with `tools.use("tests", "run", { suite = "scoreKit" })`. It covers: - **Rules:** the combo rules against the numbers in this README, ratings and ranking. - **Board:** bests, records, time boards, corrupt rows, merging, around-me, seasons. - **Persistence through `runtime_data`:** write and read back, a new session seeing it, a non-keeper refusing, held results in locked mode with their approval and rejection, retrying and the outbox replay. - **Keeper:** its checks on remote scores, prediction and refusal, adopting the keeper's rules on another machine, MatchFlow binding with a stand-in match, round ends whose breakdown adds up, time runs and their validation. - **API:** every public call (HUD settings, reading, configuring, scoring, rounds, runs, every board-handle method), the events they fire, and the `ScoreKit` and `ScoreGallery` components. - **Pickups:** the points table, the keeper scoring each pickupsKit grab once (combo, penalty, unlisted pickups), a machine that is not the keeper scoring nothing, only the senior machine scoring before any ScoreKit exists, grabs announced through pickupsKit's own network handler, and the `ScorePickups` component. - **Styles:** the catalog, and every renderer in every look at desktop and phone sizes. Also the HUD, every gallery tab (and that all its cards are handed the same data in the same frame) and the sign. - **Install layout:** - every require and asset name in the package resolves wherever an install puts scoreKit and its dependencies (package-relative `~.x`, packages by name `~Name.x`, or `@builtin::`) - a package named `~Name` is found under `/source/deps/` - toasts run on the HUD scoreKit makes itself - **This README:** its version against `package.yaml`, `Score.version` and the changelog, its rules and style tables, and its first example run against a stand-in jump button (three quick jumps make 40). - **Coverage:** a check that every public function of every module is called by the suite. The suite removes everything it writes to the world's store. ## Known limits Engine issues that still affect scoreKit, each with the GitHub issue that tracks it: - **An install also writes a partial second copy of scoreKit's own modules (#10762).** A fresh install puts scoreKit in `/source/scoreKit.package`, and beside it seven of its modules again (`theme`, `basetheme`, `rules`, `displays`, `popups`, `boards`, `results`) under `/source/deps/877b8381-7a16-4946-9242-f1140f46092a/scoreKit.package/`. The engine pins each file to the versions of the modules it requires, and an install fetches every pinned version the package does not ship as a lone copy. The copy has no `package.yaml`, so it is not a second scoreKit: `scoreKit.*` and `~scoreKit.*` still resolve to the real one, and nothing in a fresh world loaded from it. It is safe to delete. Saving and committing scoreKit again does not refresh those pins, so the kit cannot avoid it: the install splits part of the package's own tree into `deps/`. MatchFlow and navUiKit leave the same kind of `versions/` folders under their own `deps/` folders, and those old copies can log `no root to resolve against` while the world opens. - **A kit that came with scoreKit is not found by its bare name from your own scripts (#19199).** MatchFlow, navUiKit and pickupsKit arrive as scoreKit's dependencies. In your own code `asset.resolve("MatchFlow.MatchFlow", "component")` answers "not found", while `asset.resolve("~MatchFlow.MatchFlow", "component")` works. For pickupsKit, use `require("scoreKit.pickups").kit()`. - **The world store is open to modified clients** in the default mode (see Who can write the board). The engine has no store that only the world's authority can write (#19283), so the kit's own network path cannot change the board, but a player running modified engine code can still write `runtime_data.world` directly and forge rows. Use `writers` for a board that must hold against that too. - **One account on two machines presents one player in the engine (#14448).** scoreKit works around it by giving each session its own key (`u:<id>`, `u:<id>#2` …). "Nova (2)" is whichever of that account's machines joined the room second, so that board row belongs to the account's second seat rather than to one particular computer. - **The test suite can't be two players in one engine (#18688, #19114).** The loopback test mode doesn't echo messages, and an agent in the engine can't bring in a second player. So the suite delivers the other machine's messages through the real network handlers: scoreKit's own (refusals, rate limits, predictions, forged snapshots) and pickupsKit's (`pk:got` grab announcements). Two real machines were played by hand for 1.3.0 instead. Two editors on the relay, signed in to one account, played the gallery's coin round together, with one machine hosting. Every coin, ruby and damage orb the other machine's player grabbed was announced once and scored once, during the round only, under that player's own key ("claude-code @ aura", with the host as "(2)"). Their own score display showed the keeper's total (95), and pickupsKit's counter agreed (8 coins, 1 gem). - **Moving an installed MatchFlow, navUiKit or pickupsKit needs an editor restart (#19314).** After a package is moved or reinstalled somewhere else, the engine's name lookup keeps its old location: `~MatchFlow` then reads as "not found" (or "ambiguous", if a copy was left behind) until the editor restarts. Reproduced on 2026-10-18. A fresh install, or a world opened fresh, is not affected. - **The sign's face is UI drawn where the sign is on screen (#19284).** Zero's 3D `UiPanel` turns widget trees into plain rich text, so the styled board is drawn as UI fitted to the backboard's projected size, squashed to the viewing angle. It is hidden when its back faces you or beyond `maxDistance`, but a wall between you and the sign does not hide it. By design: - **`acceptRemote = true` trusts each machine with its own player's points**, within `maxPerAdd` and `maxPerSecond`. A modified client can then award itself points up to those caps. Keep the default for anything competitive. - **MatchFlow takes reports from any machine.** scoreKit ranks points rounds on its own counted scores. But in `race`, `lastStanding` and `kingOfTheHill` it uses MatchFlow's places, and those trust MatchFlow's own reports (`finish`, `knockOut`, `setOnHill`). - **Points scored in the instant the keeper leaves can be lost.** The next keeper carries on from the last published snapshot. - **A player who leaves before the round ends is not ranked or posted.** Their points that round don't reach the board. ## Changelog ### 1.3.1 - **One end-of-round screen at a time.** With MatchFlow, the results card waits until MatchFlow has finished its own results on that machine and moved on to the break. Before, it only waited while that machine already read "results": on a machine that wasn't hosting, the round's results arrive a moment before its MatchFlow switches over, so the card and MatchFlow's podium were drawn on top of each other. A card the break has passed by is skipped, and one still up when the next round counts down closes. - **pickupsKit's counter and MatchFlow's standings no longer overlap.** With `corner = "auto"`, the score display moves to the bottom-left when pickupsKit's counter is in the top-left (`H.pickupHudCorners()`). The gallery puts the counter top-left, so MatchFlow's standings keep the top right. - **Clean text in the pixel font.** The arcade look's pixel text read text byte by byte, so "·" and "…" (and any accented letter) drew as one "?" per byte, and "@" had no glyph. It now reads characters, draws "·", "…", "@", brackets, quotes and other punctuation, and draws accented letters as their plain letter (`T.pixelGlyphs`). A test renders every display, board and results screen in every look with awkward names and fails on any "?". - **Gallery:** its board is now "Hall of Fame" (id `hallOfFame`), with both players' rows carried over, and the demo boards are titled "Gem Dash". A stray empty entity left in the gallery scene is gone. ### 1.3.0 - **`Score.add`, `Score.penalty` and `Score.bonus` return the points awarded.** On the keeper they returned nothing; they now return the amount after the combo multiplier (10, 10, 20 for three quick 10s), negative for a penalty, 0 when nothing was awarded. Off the keeper they return 0 with keeper-only scoring, or the predicted amount with `acceptRemote = true`. See "What `Score.add` returns". - **The gallery's coin round is built on pickupsKit 2.3.0**, installed in the Hall of Fame world under `/source/deps/` like MatchFlow and navUiKit. Its coins, ruby and damage orb are pickupsKit pickups placed in the scene, scored by `ScorePickups`. The world's own one-off coin script is gone. - **`ScorePickups` and `scoreKit.pickups`: pickups that score.** Every pickupsKit grab becomes one `Score.add` on the machine keeping the score, for the player who took it, from a points table such as `"goldCoin=10, ruby=50, damageOrb=-25"`. Before any `ScoreKit` exists, the senior machine scores the grab and its `Score.add` creates the kit. pickupsKit is now a dependency of scoreKit, next to MatchFlow and navUiKit. - **README checked in a brand-new world with nothing but scoreKit installed.** The first example now says how to make the scene it goes in (a new world has none), and the MatchFlow example names MatchFlow as `~MatchFlow.MatchFlow`, the form that resolves when MatchFlow came with scoreKit. - **Known limits name only open issues.** The notes on #19298, #19299 and #19268 are gone: the engine now carries a table with an `x` field and an entity inside a table intact, so scoreKit no longer works around them. Added #10762 (the partial copy an install writes), #19199 (dependencies by bare name), #19314 (moving an installed kit), #19284 (the sign's face) and #18688 / #19114 (two players in one engine). - **Played on two real machines.** The coin round with two editors on the relay: every grab on the machine that wasn't hosting scored exactly once, for its own player. - **Fixed:** navUiKit's HUD modules pin different copies of navUiKit's core, so toasts sent through `Nav.toast` reached a core the HUD never read. scoreKit hands toasts straight to its HUD (or to the world's own navUiKit HUD), and its HUD shows only the toast band. ### 1.2.1 - MatchFlow and navUiKit are installed as dependencies under `/source/deps/<origin world>/` in the Hall of Fame world, next to controlsKit, the layout an install of scoreKit gives you. No code change: scoreKit already reaches them by package name. - Known limits now cite the engine issues behind them (#19283, #14448, #19298, #19299, and #19268, now fixed). - **Fixed:** two writes to the same board row are sent in order. A `board:remove` made while that row's save was still on its way used to be folded into the save already sent and lost, so the row came back. - **Fixed:** navUiKit is looked up when toasts first need it, and again (at most once a second) until it is found. Right after an install or an editor start the first lookup can fail, and that used to leave toasts off for the whole session. `H.navModules()` returns the navUiKit modules in use. ### 1.2.0 - **One account signed in on two machines is two players.** Each session gets its own key (`u:<id>`, `u:<id>#2` …) and name ("Nova", "Nova (2)"), so the round ranking, the results and the board show both with their own points. Before, both sessions shared one key: one machine's points were credited to the other, and the board listed one row. - **Only players who are here are ranked, placed and posted.** Absent player keys are dropped at the next round's start and never count toward "1st of N". - **`board:remove(player)`**: the writer in charge can take a stale or test row off the current season. A queued delete hides the row at once. - Removed a leftover test player ("Player Two") from the gallery's board. ### 1.1.0 - **Keeper-only scoring by default** (`acceptRemote` now defaults to `false`). Another machine's `Score.add`, `bonus`, runs and board posts are refused at the keeper, and not sent or predicted at all once a keeper is known. The same code can run on every machine and count once. `acceptRemote = true` restores self-reported points within the caps. - **A board post from another machine never carries its own value.** The keeper posts the score it counted, to the kit's board only. Time boards take only runs the keeper timed. - **Only the keeper's standings, awards and round results are believed**: forged `snap`/`ev`/`nak` messages from other peers are ignored. - **Points rounds are ranked on scoreKit's counted scores**, not on MatchFlow's standings. MatchFlow's places are used for `race`, `lastStanding` and `kingOfTheHill` only. - **Fixed:** after leaving play and pressing Play again (or any rebuild that replaces the MatchFlow component on the same entity), scoreKit kept the old, frozen match. It refused every point as "not playing" and never saw the round end. It now follows the live component. - Gallery: an **Everything** tab with every display, leaderboard and results screen on one page, all drawn from one shared feed (live scores when there are any). ### 1.0.0 - First release: `Score.add` with combos and multipliers, ratings (stars and S–D grades), rounds through MatchFlow, toasts through navUiKit, persistent boards (top scores, best times, personal bests, seasons, locked writers, held results), 13 displays, 5 popup styles, 6 board views with the `ScoreSign`, 4 results screens, 5 looks, the `ScoreGallery`, and the `scoreKit` test suite.