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:

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:

-- 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:

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:

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:

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.

-- 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:

-- 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

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.

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:

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:

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.

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)

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).

popups = "auto" (the ScoreKit default) picks the popup that matches the look.

Leaderboards (board views)

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:

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)

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

minimal, scifi and cartoon use MatchFlow's own design tokens, so a world running both kits looks like one game.

The ScoreKit component

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").

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

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.