Hall of Fame: Scores, Combos and Leaderboards Kit
- ..
- .metadata283 B
- README.md88.1 KB
- ScoreGallery.component
- ScoreKit.component
- ScorePickups.component
- ScoreSign.component
- basetheme.module
- board.module
- boards.module
- card.module
- catalog.module
- core.module
- demo.module
- displays.module
- geom.module
- guides
- hud.module
- layout.module
- package.yaml1.2 KB
- pickups.module
- popups.module
- preview.module
- results.module
- rules.module
- score.module
- scoreKit.testSuite
- stack.module
- store.module
- theme.module
README.md
scoreKit 1.6.0
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.
- New in 1.5.0: parts that fit every screen. Score popups that stay readable during a 20-hit combo (they stack into free rows and merge), an end of run results card a game hands its numbers to (tallies with hints, count-up, NEW badges, a leaderboard beside or below, touch-size buttons with gamepad focus, shrunk to fit by measuring), an in-run score layout (score, combo meter, multiplier and a popups zone, placed per screen and clear of touch buttons), and leaderboards that only ever hold real players' runs (agent-driven and test sessions never post). See "Readable popups, results card, in-run layout, real players only".
- 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.
Guides
Five guides ship inside this package, in scoreKit.package/guides/, and install with it:
- How to add a score and combo system to my game: the how-to. What the kit is and what to do first, adding points and "+N" popups, how combos and multipliers build and break, penalties and bonuses, star ratings and grades, leaderboards that survive a restart (top scores, best times, personal bests, seasons), swapping every style with one setting, and how scores work per player in multiplayer.
- Make an arcade game with a score, combos and a leaderboard: the example. A brand-new world becomes a two-player coin round with scoreKit, MatchFlow and menusKit: quick pickups build a combo, the round ends with stars and a grade, the result goes onto a top-10 leaderboard that is still there after a restart, and there is a title screen and a pause menu.
- Make score popups readable during combos: the how-to for
popupStack: why popups pile up in a burst, the six modes (stack, column, merge, fan, fade, free), the cap and merging, where popups with no world position go, and checking it with a 20-hit burst. - Add an end of run results card that fits phones: the how-to for
Score.showCardand the in-run layout: tallies with hints, the leaderboard on the card, buttons for touch and gamepad, how it arranges itself per screen and fits the whole card (every button measured), a card style and an in-run style per look, and keeping the score panel clear of touch buttons. It also covers keeping test runs off your leaderboard (realSessionsOnly,Score.markTestSession,board:purge). - Build a small game with scoreKit: Bounce Run: the example. A one-scene game from a new world: points and combos while you run, the in-run layout, stacked popups, an end of run card with tallies and a depth board, and a board that only real players reach.
Open one with the guides tool by the path in its link (scoreKit.package/guides/<name>), or in the editor's Docs panel under scoreKit.
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, juiceKit and controlsKit 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 already has one: scenes/main.scene, with a ground, lights and the default player, and an entrypoint.luau that holds only comments. (A world that has no scene yet gets the same one from tools.use("scene", "create", "main", "player", { startup = true }).) Replace everything in scenes/main.scene/entrypoint.luau with this:
local Score = require("scoreKit.score")
local jump -- the jump handler, kept so it can be removed when play stops
function onLoad()
local controls = asset.resolve("@builtin::inputMaps.default", "inputMap"):activate()
jump = controls.jump:onPressed(function()
Score.add(nil, 10) -- nil = the player on this machine
end)
end
function onUnload()
-- remove the handler when play stops: the engine keeps it otherwise (#22432)
if jump then jump:Disconnect() end
jump = nil
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.
Stop and press Play again and the score starts from 0: every play session starts a fresh score, combo and round, and only the boards keep scores between sessions. Each jump still counts once, because onUnload removes the jump handler when play stops. Leave onUnload out and the engine keeps the old handler attached (#22432, see Known limits): from the second Play on, each jump counts twice, then three times in the third Play, and so on.
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")
Readable popups, results card, in-run layout, real players only (new in 1.5.0)
Four reusable parts, each drawn in all five looks and laid out for every screen: an upright phone (390x844), a small phone (360x640), a sideways phone (844x390 and 667x375), a tablet both ways (768x1024 and 1024x768), a laptop at 150% (1280x720 points), 1080p and an ultrawide. Sizes are logical points, the space ui.screenSize() reports.
Score popups that stay readable during combos (popupStack)
A burst of hits used to pile its "+N" popups on top of each other. Now each new popup takes a free row (stacking upward from where it was scored, or into a column), older ones shrink and leave sooner when it is crowded, and past a cap small hits merge into one popup such as "+150 x5". Every popup on screen can be read, even at a 20-hit combo inside one second.
popupStack | What it does |
|---|---|
stack (default) | each popup takes the next free row above the spot it was scored at (below it near the top of the screen) |
column | every popup goes into the popups zone beside the score as a list, newest first |
merge | like stack, and small hits merge sooner (from 2 on screen instead of 3) |
fan (new in 1.6.0) | each popup takes a seat on an arc around the spot it was scored at (or hanging under the score panel), the first in the middle and the next ones alternating right and left; the arc grows until no two overlap, keeps clear of the score panel, and each popup keeps its seat while it lives |
fade (new in 1.6.0) | popups take turns: each fades in a short stagger (0.16 s) after the one before, holds readable, and fades out after 0.75 s, in a slot of its own; when more than 3 are waiting, small hits merge into the last one waiting, so a burst never builds a long queue |
free | the behaviour before 1.5.0: each popup where it was scored, free to overlap |
Set it on the ScoreKit component (popupStack), or from code: Score.setHud({ popupStack = "fan", popupCap = 5 }). popupCap (default 6) is the most popups one spot shows; more merge. Works with every popup style. Stacked popups keep their pop and fade but drift only a few points, so a row never reaches the next one. For your own UI, scoreKit.stack lays out any list: Stack.add(list, popup, now, opts) and Stack.place(list, now, sizeOf, opts) (opts: mode, zone, screen, avoid = rects popups keep off, and for fade stagger, dwell, fadeQueue). Every mode except free is checked with a 20-hit burst inside one second, in every look, on every screen, at eight moments: no two popups overlap, none leaves the screen, none covers the score panel.
End of run results card that fits phones (Score.showCard)
Hand the kit your numbers and it builds the card: a title and headline, a list of tallies (each with a label, a value, an optional hint line under it that says what the number means, a NEW badge, and a count-up from 0), an optional highlight banner (a record or something new), a leaderboard, and buttons.
- Laid out for the screen: one column for a few tallies, a two-column grid on an upright phone, a 3x3 grid on a short upright phone, three columns on an upright tablet with the board under them, and the leaderboard beside the tallies on any landscape screen, sideways phones included.
- Fits the whole card, measured. The card estimates a scale, draws, then reads what it drew with
ui.getLayoutInfo: the content's natural height (nothing in it may shrink) and the rectangle of every button, against the inside of the card. It corrects until all of it is inside, every frame the screen changes. The screen is the size the card's full-screen root was really laid out at, which can be smaller thanui.screenSize()(a game view inside a bigger window). - Never clips. When a
maxWidth/maxHeightcap or the screen is too small, it shrinks the type down to its floors, then takes the fit steps in order (Card.FIT_STEPS): drop the hint lines, add columns, pack the buttons up to 4 to a row, show the board as one line ("Your place: 3rd of 20"). Measured with Tumblestep's card (10 or 11 tallies with hints, a highlight, anaroundMeboard, 7 buttons,maxWidth = 1040,maxHeight = 640) on 390x844, 360x640, 844x390, 667x375, 768x1024, 1024x768, 1280x720, 1920x1080, 2560x1440 and 3440x1440, with and without the caps, in every look: every button inside the card and the screen. - Buttons for thumbs and pads. Every button is at least 48 points tall. When they do not fit one row, they wrap: on an upright phone the primary has its own full-width row and the rest go 3 or 2 to a row; on a wide card up to 4 to a row. The primary button takes gamepad and keyboard focus when the card opens; the d-pad moves between buttons and
south(or Enter) presses. A press calls youronButton(id)and closes the card (closeOnPress = falsekeeps it). - Tallies come first. Values never get smaller than 16 points and labels than 11. An empty board is one line, and a board under the tallies takes at most 35% of the card on a phone.
- The NEW badge never covers text. It sits inline after the value ("507 NEW"); in a tally too narrow for both it gets its own line under the value. Measured in every style: the badge is inside its tally and clear of the label, the value and the hint.
Score.showCard(spec)returns a handle with:close(),:update(spec)and:isOpen(), andk,tight(fit steps taken) andmeasured(over,inside,onScreen).scoreKit.cardalso hasCard.render(look, spec, { vw, vh, t, style })to draw the same card inside your own UI,Card.measure(idPrefix, spec, info, sw, sh)to measure one you drew, andCard.fromResults(results, extra)to turn a scoreKit round's results into a card spec.
Card styles (new in 1.6.0)
Each look has its own card, not a recolour: a different shape, ornament, tally layout, buttons and entrance. The default follows the look; spec.style picks any style in any look (it takes that look's colours and type), and Score.setHud({ cardStyle = "scroll" }) sets a default for every card.
| Look | Style (style) | What it looks like | Tallies | Entrance |
|---|---|---|---|---|
| cartoon | sticker | a chunky sticker: thick ink outline, hard shadow, tape on the corners, the title on a tilted ribbon | coloured stickers with a tinted top edge and shadow | pops in with a wobble, each sticker pops in turn |
| arcade | scoreboard | a neon cabinet scoreboard: chasing marquee lights top and bottom, * TITLE *, a blinking HI-SCORE | striped rows with dotted leaders and glowing mono digits | switches on like a CRT, rows slide in |
| scifi | terminal | a holo terminal: corner brackets, > TITLE_ typed on with a blinking cursor, a scanline sweep | readouts with an accent bar down the left edge | flickers on and rises |
| fantasy | scroll | a parchment scroll between two wooden rods with gold caps, a serif title over an ornament rule | a ledger with dotted leaders | unrolls from the middle, lines rise in |
| minimal | clean | a quiet sheet: left-aligned small caps title and a big headline, an accent tick | a table with hairline rules | fades up |
| any | classic | the 1.5 card: tally cells in a grid on the look's panel | cells | scales in |
Gallery captures of each style: gallery/captures/card-style-<style>.jpg.
The spec:
| Field | What it is |
|---|---|
title, headline, subtitle | the card's heading lines |
tallies | { { label, value, hint?, unit?, format? = "time", isNew?, countUp? = true } }; a number counts up, a string shows as written |
highlight | { text, kind = "record" or "new" }, a banner under the heading |
board | { id, view = "top10" (any board view), title? }: a scoreKit board drawn in the card |
buttons | { { id, label, primary? } } |
onButton | function(id) called on a press |
look, seconds | the look (default arcade) and an optional auto-close |
In-run score layout (layout = "run")
The score, a combo meter (progress to the next multiplier, with the combo window draining under it) and the multiplier, as one panel placed for the screen shape, plus a popups zone where "+N" popups with no world position stack:
- Desktop, tablet, sideways phone: a panel in a corner (top-left by default). On an ultrawide the corner of the middle 16:9, where the eye is.
- Upright phone: a strip across the top.
- Clear of touch controls. It reads
ui.safeArea().controls(the engine's touch buttons and its touch Menu button in the top-right corner, plus any rect a world declares withui.setControlRegions) and moves off them; the phone strip ends before the Menu button. anchor:auto,topLeft,topRight,top,bottomLeft,bottomRight,bottom.
Turn it on with the ScoreKit fields layout = "run" and anchor, or Score.setHud({ layout = "run", anchor = "auto" }). Score.runLayout({ anchor }) returns the rectangles (panel, score, multiplier, combo, popups zone) for your own HUD, and scoreKit.layout has Layout.shape(w, h) (phone, phoneShort, phoneWide, tablet, tabletTall, desktop, ultrawide) and Layout.avoid(rect, controls, w, h).
Run layout styles (new in 1.6.0)
Each look draws the in-run panel its own way: the same panel rectangle (so the touch clearance and the popups zone hold for every style), a different shape, arrangement, ornament and motion inside it. The default follows the look; Score.setHud({ runStyle = "banner" }) (or the ScoreKit field runStyle) picks any style in any look, independently of the card style. Layout.renderRun(look, data, layout, t, style) draws one for your own UI.
| Look | Run style (runStyle) | What it looks like | Motion |
|---|---|---|---|
| cartoon | chunky | a sticker panel with an ink outline and hard shadow, the score big under a tilted "Score" tab, the multiplier as a round badge, the combo as 8 chunky pill segments | the badge bounces and turns on every award, the number pops |
| arcade | marquee | a cabinet readout: a blinking 1UP, the score as zero-padded glowing mono digits, the multiplier in a magenta box, the combo as 12 LED blocks (the last three magenta) | 1UP blinks at 2 Hz, the box glows harder on an award |
| scifi | readout | corner brackets on dark glass, SCORE // and MULT x4 across the top, the score right-aligned in mono, the combo as a thin line with 11 tick marks | a sweep runs along the line on an award |
| fantasy | banner | a parchment banner: the score centred in serif between ornament rules, the multiplier as a wax seal, the combo as a gilded bar with diamond end caps | the seal swells on an award |
| minimal | clean | a light glass card: a small caps label, a bold number, the multiplier as a quiet pill, the combo as a hairline that fills | the number brightens on an award |
| any | classic | the 1.5 panel: score, multiplier chip and combo meter | bump on award |
Gallery capture of all six side by side: gallery/captures/run-styles-all.jpg. The new popup modes: gallery/captures/popups-fan-cartoon.jpg and gallery/captures/popups-fade-arcade.jpg.
Keep test runs off your leaderboard (realSessionsOnly)
A public board holds real players' runs only. With realSessionsOnly on (the default) nothing is posted from:
- a play session an agent takes part in:
engine.playSessionlists the agents in it (it is nil for a published game and for a person's own Play press); - edit mode, where test suites and editor tools run;
- a session marked as a test:
Score.markTestSession("why")(Score.markTestSession(false)clears it). Call it from any harness that drives input for a test.
The keeper also refuses rows for a player whose machine says it is not a real session (that machine tells the keeper on its own), so one agent in a room cannot put rows on the board through another machine. A refused post is not lost silently: the submitted event carries test = true and the reason ("Not posted: an agent is driving this play session (...)"), and the log says it once. Score.isRealSession() answers true, or false and why.
Cleaning a board. On the keeper, the board's writer can take rows off: board:remove(player) for one, board:purge(function(row) ... end) for every row the function answers true for (row has k (key), n (name), v (value), st, g, at, c). It returns how many went.
-- take every bot and every stand-in test row off the "depth" board (run on the keeper)
local removed = Score.board("depth"):purge(function(row)
return string.sub(row.k, 1, 2) == "b:" or string.find(row.n or "", "Test", 1, true) ~= nil
end)
print("removed", removed)
Combo rules
These are the exact rules, with the defaults. They are written so that you can balance a game around them.
-
A hit is any
Score.addwith a positive amount, unless it is passedcombo = false. -
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 exactlywindowstill counts. -
The multiplier is 1 plus the number of
stepsthe combo has reached, and never abovemaxMultiplier. With the defaultsteps = { 3, 6, 10, 15 }andmaxMultiplier = 5:combo 1 to 2 3 to 5 6 to 9 10 to 14 15 and up multiplier x1 x2 x3 x4 x5 every = nreplaces the steps with a uniform step: x2 at n hits, x3 at 2n, and so on up tomaxMultiplier. -
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 = falsekeeps fractions). -
The combo breaks when:
- time runs out: more than
windowseconds 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. Withdecay = "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.breakComboand penalties always reset. - time runs out: more than
-
Penalties (negative amounts) are never multiplied.
-
combo = falsepoints are not a hit: they don't grow the combo or refresh its window, and they are not multiplied (passmultiply = trueas well to multiply them by the current multiplier).multiply = falsekeeps a hit's points at face value while it still counts toward the combo. -
Bonuses (
Score.bonus) are never multiplied, never touch the combo, and get their own line in the results breakdown. The same label adds up. -
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 to 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
gradeslines replace these. fracis the progress from the last star target to the next one.nextis 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
roundEndedevent (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. The break is how long the card can stay up, so give MatchFlow abreakSecondsat least as long asresultsSeconds. A new personal best or record is shown on the rating card itself ("New personal best" beside the place): in a MatchFlow break there is time for one card, not a 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. Your own scripts find it by name, MatchFlow.MatchFlow or ~MatchFlow.MatchFlow (the form to use from inside another package), wherever the install put it.
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" })
pointsgives 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.addfor the player who took it, with the "+N" at the pickup andcoins,gems… (orhazards) as the results line. Before the first point there is noScoreKityet: then the senior machine scores the grab, and itsScore.addcreates 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 pickupsKitcollectevent. - Where pickupsKit's counter goes. pickupsKit's
PickupHUDsits 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" }). Withcorner = "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 machinesScore.addsends nothing, predicts nothing and firesrefusedlocally. 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,lastStandingandkingOfTheHill, 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
ScoreKitentity, 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.addon 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 isu:<userId>#2and 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, andb:<name>for bots (Score.add("Robo", 10),Score.setName).
- A signed-in player's key is
- 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.addcounts, so the same pickup code can run on every machine. WithacceptRemote = 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. UseScore.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)
| 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:
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. Without MatchFlow, a round that brings a personal best or record shows celebration before a ratingCard; in a MatchFlow round the ratingCard shows alone and says "New personal best" or "New world record" beside the place. 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) |
popupStack | stack | how popups share the screen: stack, column, merge, fan, fade, free (see Readable popups) |
layout / anchor | corner / auto | run: the in-run layout (score, combo meter, multiplier, popups zone) placed for the screen and clear of touch buttons; anchor places it |
runStyle | auto | how the in-run layout is drawn: auto follows the look (chunky, marquee, readout, banner, clean), or any of them, or classic |
realSessionsOnly | true | only real players' runs reach a board: never from a session an agent drives, edit mode or a marked test |
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 |
Score.showCard(spec) | the end of run results card (see Readable popups, results card ...); spec.style picks its style; returns a handle with close, update, isOpen, k, tight, measured |
Score.setHud({ cardStyle, runStyle, popupStack }) | the default card style (sticker, scoreboard, terminal, scroll, clean, classic, auto), the run layout style, the popup mode; an unknown name is an error |
Score.runLayout({ anchor }) | the in-run layout's rectangles for this screen |
Score.isRealSession(), Score.markTestSession(reason or false) | is this a real player's session (true, or false and why); mark a test run |
board:purge(fn), board:remove(player) | take rows off a board (the writer, on the keeper) |
require("scoreKit.pickups"): listen(points, { reason }?), score(ev, points, { reason }?), 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, andScore.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'stheme.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 takenarrow) 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. Each release is checked in the desktop editor: an agent working inside the engine cannot open the web build to check it there (#20946).
- 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.3.1 | Match Flow Kit | rounds: addScore, getPhase, getStandings, onStateChanged, onRoundEnded. Its theme tokens are the base of three looks. |
| navUiKit 1.2.1 | Wayfinder Studio | toasts (Nav.toast, achievement / minimal / banner variants), and its camera projection (navUiKit.geom) for popups and signs |
| pickupsKit 2.3.14 | 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
ScoreKitandScoreGallerycomponents. - 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
ScorePickupscomponent. - 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
~Nameis found under/source/deps/ - toasts run on the HUD scoreKit makes itself
- every require and asset name in the package resolves wherever an install puts scoreKit and its dependencies (package-relative
- This README: its version against
package.yaml,Score.versionand the changelog, its rules and style tables, and its first example run against a stand-in jump button (three quick jumps make 40). - 1.5.0 parts: a 20-hit burst inside one second in every look, every stacking mode and every screen never overlaps, stays on screen and off the score panel; merging keeps every point; the results card arranges itself per screen, draws in every look with its hints and 48 point buttons, counts up, and fits every screen measured on screen with
ui.getLayoutInfo; a button press reachesonButton; the in-run layout is a strip on upright phones and a corner elsewhere and never covers a touch button or the Menu button, for every anchor; edit mode, an agent's play session and a marked test never post, the keeper refuses a test peer's rows, andboard:purgeremoves only matching rows and only for the writer in charge. - 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. It passes in a world just loaded, right after a play session, and with other engines in the room.
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 some of scoreKit's modules (#10762). A fresh install puts scoreKit in
/source/scoreKit.package, and can put copies of a few of its modules (theme,basetheme,displays,popups,boards,results) beside it under/source/deps/877b8381-7a16-4946-9242-f1140f46092a/scoreKit.package/. The engine records which version of each module a file requires against that file's bytes, and an install fetches every recorded version the package does not ship as a lone copy. The copy has nopackage.yaml, so it is not a second scoreKit:scoreKit.*and~scoreKit.*still name the real one. Up to 1.3.1 the copies held older code, and the shipped modules loaded it (the 1.3.1 pixel-font fix did not reach installs). 1.4.0 gives every file new bytes, so each one records the versions it ships with, and a fresh install loads the code it ships. Fresh installs of 1.4.0, 1.4.1 and 1.4.2 wrote no copy at all. - 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.worlddirectly and forge rows. Usewritersfor 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:gotgrab announcements). So two real machines are played by hand for each release instead. For 1.4.2, two editors on the relay, signed in to one account, played the gallery's coin round together, one of them hosting. The other machine's player took the seven coins and the ruby: that machine showed its own score as 290 and the host's live count for that player was 290, both showed the same standings, and both showed the same Hall of Fame board (1060 and 150, Saved) before, during and after the round. MatchFlow ended the round on both together, with the player 1st at 290, 1 star, C. The board kept that player's season best of 1060 and counted the play. The machine with the lower peer id kept the account's own key and the host showed as "(2)". - The sign's face is UI drawn where the sign is on screen (#19284). Zero's 3D
UiPanelturns 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 beyondmaxDistance, but a wall between you and the sign does not hide it. - An input handler from an earlier Play stays attached (#22432). A handler your scene adds in
onLoad(for examplecontrols.jump:onPressed(...)) is not removed when play stops. So if you press Play, stop and press Play again, every jump callsScore.addonce for each Play so far: twice in the second Play, three times in the third, four times in the fourth. The score really does start from 0 each time, it just climbs two, three or four times too fast. To avoid it, keep the handleonPressedreturns and call its:Disconnect()inonUnload, as the first example does. Closing and reopening the world also clears the old handlers. - ZeroMind's description can lag a release (#19258). For a while after a release, scoreKit's description on ZeroMind can still show the previous README. The README inside an install is always the one for the version installed.
By design:
acceptRemote = truetrusts each machine with its own player's points, withinmaxPerAddandmaxPerSecond. 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,lastStandingandkingOfTheHillit 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.6.0
Found and asked for by Tumblestep's owner; every game gets it.
- The results card fits whole, never clipped. On a big desktop window Tumblestep's second row of buttons was cut off at the bottom of the card. The 1.5 fit read only the content box, which the layout can squash, and trusted
ui.screenSize()for the room. Now nothing in the card may shrink, the fit (Card.measure) reads the content's natural height and the rectangle of every button against the inside of the card, and the screen is the size the card's root was really laid out at. When a cap or the screen is too small it shrinks the type to its floors (values 16, labels 11, hints 10 points), then drops hints, adds columns, packs buttons up to 4 to a row, and shows the board as one line (Card.FIT_STEPS). Measured with Tumblestep's spec (10 or 11 tallies with hints, a highlight, anaroundMeboard with few or no rows, 7 buttons,maxWidth = 1040,maxHeight = 640) on 390x844, 360x640, 844x390, 667x375, 768x1024, 1024x768, 1280x720, 1920x1080, 2560x1440 and 3440x1440, with and without the caps, in every look and style: every button inside the card and the screen. At 1920x1080 in cartoon the card is 1040x640 at (440, 220) and its two button rows sit at y 725 and 780 (48 points tall), ending 15 points above the card's padding. - The NEW badge never covers text. It sits inline after the value, or on its own line under the value in a narrow tally, measured clear of the label, value and hint.
- A card style per look, not a recolour:
sticker(cartoon),scoreboard(arcade),terminal(scifi),scroll(fantasy),clean(minimal), plusclassic(the 1.5 card). Each has its own shape, ornament, tally layout (cells or ledger rows), buttons and entrance.spec.stylepicks any style in any look;Score.setHud({ cardStyle })sets the default. - A run layout style per look:
chunky,marquee,readout,banner,clean, plusclassic, chosen independently withScore.setHud({ runStyle })or theScoreKitfieldrunStyle. Every style draws inside the same panel rectangle, so the touch-control clearance holds. - Two popup modes for long combos:
fan(seats on an arc around the spot, growing until none overlap, clear of the score panel, each popup keeping its seat) andfade(one after another with a 0.16 s stagger, each held readable for 0.75 s in a slot of its own; a long queue merges into the last one waiting).stack,column,mergeandfreeare unchanged.Stack.placetakesavoidrects. Card.show(spec, { viewport = { w, h } })lays a live card out for a given screen size (tests, previews).Score.setHudrefuses unknown style and mode names.- Guides updated (popups, results card, Bounce Run example); gallery captures of each card style, each run style and the new popup modes.
- Tests: 148 (was 138): the whole-card fit matrix, the live fit at four desktop sizes, the NEW badge, styles per look, fan and fade bursts.
1.5.3
- A game can cap the results card's size.
Score.showCard{ ..., maxWidth = 980, maxHeight = 600 }keeps the card smaller than the room it has, so the game's world stays in view around it on a big screen; the card still shrinks below the cap to fit a phone. Without the fields nothing changes. Asked for by Tumblestep, whose card covered the whole 1280x720 screen. - Tests:
Card.arrangehonours the caps. 138 tests.
1.5.2
- The HUD costs far less per frame. The score HUD rebuilds its tree only when what it shows changes (score as the roll-up shows it, multiplier, combo, the combo bar in 1/40 steps, settings, screen and safe area, results and toasts). While something on it moves (popups, the award bump, a roll-up, an animated display, the results card) it rebuilds at most 30 times a second.
ui.showScreenruns only when the screen was hidden. The screen size is read every frame; the safe area, touch-control rects, the in-run layout and the roster are read again when the size changes and every 0.5 s. Popups keep their measured size between frames, the pixel font keeps its markup, andT.soliddoes not walk a part twice. On this world's test machine the idle HUD went from about 0.75 to 1.0 ms a frame to about 0.33 to 0.45 ms with no rebuilds at all; during combos and bursts it now rebuilds every other frame at 60 fps instead of every frame. - The results card fits a busy run on a phone. Buttons wrap: on an upright phone the primary gets its own full-width row and the rest go 3 or 2 to a row (labels shrink to 13 points before a row wraps further); on a wide card up to 4 to a row, primary first. Every button stays at least 48 points tall with its label unclipped. Tally type never goes below 16 points for values and 11 for labels; when the card still does not fit, hint lines go first, then a third column. An empty board draws as one line ("No scores yet. Be the first!") and a board under the tallies takes at most 35% of the card on a phone.
Card.planandCard.buttonRowssay how a card will be laid out. - Tests: the HUD makes no
ui.updateScreencall on frames where nothing changed, a frame's parts (cached viewports, roster and layout, the key, the results step, the build), and a card with 10 tallies, 7 buttons and an empty board measured on 390x844, 360x640, 844x390, 667x375, 768x1024 and 1280x720. 138 tests.
1.5.1
- The package description names the 1.5 parts (readable score popups, the results card, the in-run layout, real players only) and the five guides, so a search for them finds the kit. No code change.
1.5.0
- Popups stay readable during combos.
popupStack(defaultstack): each "+N" takes a free row, older ones shrink and leave sooner when crowded, and pastpopupCap(6) small hits merge into one "+N x5". Alsocolumn,mergeandfree(the old behaviour). Checked with a 20-hit burst inside one second in every look and on every screen. - The results card (
Score.showCard,scoreKit.card): a game's own tallies with hint lines, count-up, NEW badges, a highlight banner, a leaderboard and buttons, laid out for the screen (one column, two columns, 3x3 on a short upright phone, the board beside on landscape) and shrunk to fit by measuring what it drew. Buttons are at least 48 points tall and take gamepad focus. - The in-run layout (
layout = "run",anchor,Score.runLayout,scoreKit.layout): score, combo meter, multiplier and a popups zone, a corner on desktop and a top strip on upright phones, kept off the engine's touch buttons and its Menu button. - Real players only (
realSessionsOnly, default on): a play session an agent takes part in, edit mode and a session marked withScore.markTestSessionnever post to a board, and the keeper refuses rows from a machine that says it is one.Score.isRealSession(). Newboard:purge(fn)besideboard:remove. scoreKit.previewdraws any of the parts on all nine screens at once; the Hall of Fame world'sgallery/holds those captures for every look.- Three new guides: make score popups readable during combos, add an end of run results card that fits phones (with keeping test runs off the leaderboard), and an example small game.
- Built and tested on pickupsKit 2.3.14 (the Hall of Fame world was on 2.3.8, so the dependency test failed there). Everything else is backwards compatible: existing settings and calls behave as before, except that popups now stack by default (
popupStack = "free"brings the old behaviour back) and a test or agent session no longer posts (realSessionsOnly = falsebrings that back).
1.4.10
- Every player's pickups score, whoever's machine they were grabbed on. The keeper found the player behind a grab by the collector entity pickupsKit named, an entity id another machine's player body may not have on the keeper, so grabs made on other machines could score nothing. It now falls back to the player pickupsKit names by key (
p<peer>).listen(points, { reason })andscore(ev, points, { reason })name the results line the points go to (Skyhook's starfruit read "starfruit", not "stars"). Built and tested on pickupsKit 2.3.14.
1.4.8
- Built and tested on pickupsKit 2.3.8, the version a new install of scoreKit brings. Earlier releases named 2.3.0, so a fresh install ran against a newer pickupsKit than the README said, and the dependency test failed there. Nothing in scoreKit's code changed: pickupsKit 2.3.1 to 2.3.8 added guides and fixed how it loads when installed under
deps/, with the samecollectevent.
1.4.7
- The test suite passes with the gallery open. Two pickups tests grab a gold coin and a ruby through pickupsKit, which every listener hears, and the gallery's own
ScorePickups(listening in edit mode too) scored those same grabs, so the tests read 20 for 10 and 100 for 50. They now use pickup names no scene scores. - The test file is back to the kit's own references. 1.4.6 came from a contribution whose test file named the kit the way its own install did (
~scoreKit.ScoreKitand~.score), and one of those, a file read by asset name, broke the catalog test. They read as before 1.4.6 again. The 1.4.6 fix itself is unchanged.
1.4.6
- Fixed: the run clock shows from the start of a run. A run started before the player had scored (
Score.startRunon a fresh player) had no timer on thesplitsdisplay, which read "SCORE 0" until the first point: the view packs the run from the keeper's player record, and starting a run did not make one. Starting a run now makes the record. Found while following Trapline's Trap Run example, which starts the clock on Play. A test inapicovers it.
1.4.5
- Fixed: from the third Play on, sometimes nothing scored or showed. A flag that stops two kits being made at once was cleared by a task one second later. When play stopped within that second, the task was dropped with the session and the flag stayed set, so no later session ever made a
ScoreKit: scores waited for a keeper that never came and the score display stayed off. The hold is now a time that runs out by itself, and every new session clears it. - The first example removes its jump handler in
onUnload. The engine keeps an input handler from an earlier Play attached (#22432), so the old example counted each jump twice in the second Play, three times in the third, and so on. WithonUnloadeach jump counts once in every Play. Known limits describes the engine issue in plain words, and the how-to guide's copy of the example does the same.
1.4.4
- Every play session starts from zero. The score, combos, runs and rounds lived on in the kit's module between play sessions, so pressing Play again went on from the last session's score (40, then 150 …), and that score stayed on screen in edit mode. Now each switch between edit and play starts a fresh session (
C.newSession) and takes the HUD down until the next session draws it. Boards and settings are untouched. Found in a fresh world running the first example. - A readable end-of-round card in MatchFlow rounds. The card shows in MatchFlow's break and closes at the next countdown. On a first score or a new best, the
celebrationscreen used to take the first 4 seconds of that break, leaving the rating card a second or so. In a MatchFlow round the rating card now shows alone for the whole break and says "New personal best" or "New world record" beside the place. Without MatchFlow the celebration still comes first. The README and the how-to guide say to give MatchFlow a break at least as long asresultsSeconds. - The example guide builds a 60 second round with a 4 second podium and a 10 second break, keeps its rubies away from the spawn point (one sat right where players arrive), and installs scoreKit first so a world gets one MatchFlow package (see the guide for what installing MatchFlow first does).
- Changelog: older entries say what the engine changed instead of citing issues that are now closed.
1.4.3
- Played on two real machines again. Two editors on one account played the Hall of Fame world's coin round together, and both showed the same scores, standings and board before, during and after the round. Known limits describes it in place of the 1.3.0 test.
- The Hall of Fame world's opening scene has a proper description, and a leftover scene from an earlier install check is gone. No code change.
1.4.2
- A steadier test. The test that checks scoreKit sees pickupsKit's counter took one look 1.1 s after adding a stand-in counter. On a slow editor (frames of 250 ms and more) the counter's component sometimes attached too late for that look, and the test failed in about 2 runs of 7 in a freshly installed world. It now waits up to 3 s for the answer. scoreKit's own check (once a second) is unchanged.
1.4.1
- The test suite passes right after a play session. Two tests read what a play session (or a second engine in the room) leaves on a machine. The refused-prediction test sent its refusal from a made-up machine, which a kit that has a keeper rightly ignores; it now comes from the keeper. The toast test found the toast HUD scoreKit had made before a local player existed.
- Fixed: toasts follow this machine's player. scoreKit's navUiKit toast HUD kept the player key it was made with. When the local player arrived later (the HUD was made before the player spawned, or in edit mode before Play), it stayed keyed to no one. It is now made again for the player who is here.
- Fixed: MatchFlow in the Hall of Fame world, and in what 1.4.0 installed. Eight MatchFlow files in this world had been brought to MatchFlow's current release by hand after an update left them behind. Their recorded references still named older MatchFlow modules, so MatchFlow stopped every frame with "attempt to call a nil value" (
MatchFlow.component:255), and 1.4.0 carried those eight files to the worlds that installed it. MatchFlow is now a clean install of its release (2bd2d5f), and every scoreKit file records it.
1.4.0
- Two guides ship in the package (see Guides): How to add a score and combo system to my game, the how-to, and Make an arcade game with a score, combos and a leaderboard, an example that builds a two-player coin round with scoreKit, MatchFlow and menusKit from a brand-new world. The example was followed step by step in a throwaway world before release.
- Installs now run the code they install. A file's record of which version of each module it requires is kept against that file's bytes. Files whose bytes had not changed since 1.3.0 kept pointing at older versions of
theme,displays,boards,popupsandresults, so an install fetched those older copies intodeps/and loaded them: the 1.3.1 pixel-font fix never reached an installed kit. Every file in 1.4.0 has new bytes, so each one records the versions it ships with. The test suite failed 2 of 113 in a fresh 1.3.1 install and catches this. - README checked on today's engine, in a brand-new world with only scoreKit installed. A new world now comes with
scenes/main.scene, so the first example no longer asks you to create it (that step failed with "'main' already exists"). The engine now finds a kit that came as a dependency by its bare name (MatchFlow.MatchFlow), and finds a moved kit at its new place without an editor restart, so the two Known limits about those are gone. Installing scoreKit no longer leavesversions/folders (other kits can still leave their own). - Built and tested against MatchFlow 1.3.1 and navUiKit 1.2.1, the versions a scoreKit install brings, in the Hall of Fame world too.
- On-screen text drops its dashes: "Held, will retry", "No scores yet. Be the first!", "You're on top. Hold the line!", "First run: this is the time to beat".
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.penaltyandScore.bonusreturn 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 withacceptRemote = true. See "WhatScore.addreturns".- The gallery's coin round is built on pickupsKit 2.3.8, 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 byScorePickups. The world's own one-off coin script is gone. ScorePickupsandscoreKit.pickups: pickups that score. Every pickupsKit grab becomes oneScore.addon the machine keeping the score, for the player who took it, from a points table such as"goldCoin=10, ruby=50, damageOrb=-25". Before anyScoreKitexists, the senior machine scores the grab and itsScore.addcreates 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 engine now sends a table with an
xfield, and an entity inside a table, between machines intact, so the notes about working around them are gone. Added #10762 (the partial copy an install writes), #19284 (the sign's face) and #18688 / #19114 (two players in one engine), plus two limits the engine has fixed since (a kit that came as a dependency was not found by its bare name, and a moved kit needed an editor restart). - 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.toastreached 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), and say what the engine changed for the ones it has fixed since: positions sent between machines now arrive as tables, an entity inside a sent table now arrives on the other machine, and keys with prefixes are carried intact.
- Fixed: two writes to the same board row are sent in order. A
board:removemade 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 (
acceptRemotenow defaults tofalse). Another machine'sScore.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 = truerestores 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/nakmessages 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,lastStandingandkingOfTheHillonly. - 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.addwith combos and multipliers, ratings (stars and S to 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 theScoreSign, 4 results screens, 5 looks, theScoreGallery, and thescoreKittest suite.