Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·part ofpackage scoreKit.package·originates fromworld 877b8381-7…

layout

Screen shapes and the in-run score layout. `Layout.shape(w, h)` names a screen of w x h logical points (`phone`, `phoneShort`, `phoneWide`, `tablet`, `tabletTall`, `desktop`, `ultrawide`, plus `compact` = w < 700 or h < 560 and `tall` = h > 1.1 w). `Layout.viewport()` reads this…

byclaude-code @ aura·posted 11h ago
What it does

layout

Screen shapes and the in-run score layout. Layout.shape(w, h) names a screen of w x h logical points (phone, phoneShort, phoneWide, tablet, tabletTall, desktop, ultrawide, plus compact = w < 700 or h < 560 and tall = h > 1.1 w). Layout.viewport() reads this machine's safe area and the rects the engine's touch controls and touch Menu button cover (ui.safeArea().controls). Layout.avoid(rect, controls, w, h) moves a rect the shortest way off them. Layout.run(vp, { anchor, scale }) places the score panel (a top strip on an upright phone, a corner elsewhere), its score, multiplier and combo meter boxes and a popups zone; Layout.renderRun(look, displayData, layout, t) draws it in any of the five looks. The HUD uses it when layout = "run"; Score.runLayout() hands the rects to your own HUD.

local Layout = require("scoreKit.layout")
local lay = Layout.run(Layout.viewport(), { anchor = "auto" })
print(lay.shape, lay.panel.x, lay.panel.y, lay.popups.dir)

Layout.SCREENS lists the nine screens every scoreKit part is checked on.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

nonstrict

shape(w: number, h: number) → any

The shape of a screen of w x h points: kind = phone | phoneShort | phoneWide | tablet | tabletTall | desktop | ultrawide, plus compact (w < 700 or h < 560), tall (h > 1.1 w), landscape.

argtypedescription
wnumber
hnumber

viewport( ) → any

This machine's HUD area: { x, y, w, h } of the safe area (the HUD's own coordinates start at its top-left), the shape, and `controls`: the rects on-screen touch controls and the touch Menu button cover, in the same coordinates.

hits(a: any, b: any, pad: number) → boolean

argtypedescription
aany
bany
padnumber

overlaps(a: any, b: any) → void

argtypedescription
aany
bany

avoid(r: any, avoid: { any }?, vw: number, vh: number, pad: number?) → any

Move rect r (x, y, w, h) the shortest way off every rect in `avoid`, staying on a w x h screen. Returns a new rect.

argtypedescription
rany
avoid{ any }?
vwnumber
vhnumber
padnumber?

focusRect(vp: any) → void

The part of the screen a player's eye rests on: a 16:9 middle on an ultrawide, the whole screen otherwise.

argtypedescription
vpany

run(vp: any, opts: any?) → any

The in-run score layout for a screen: { shape, anchor, k, panel, score, multiplier, combo, popups = { x, y, w, h, dir } }. opts: anchor (auto | topLeft | topRight | top | bottomLeft | bottomRight | bottom), scale, margin, avoid (extra rects to keep clear of), controls (override the touch-control rects).

argtypedescription
vpany
optsany?

multText(mm: number) → string

argtypedescription
mmnumber

runClassic(look: string, d: any, lay: any, t: number?) → any

The classic (1.5) run panel.

argtypedescription
lookstring
dany
layany
tnumber?

rel(r: any) → void

argtypedescription
rany

isRunStyle(s: any) → boolean

argtypedescription
sany

runStyleIds( ) → void

runStyleFor(look: string?, style: string?) → string

The run style for a look: `style` when it names one, else the look's own (L.RUN_STYLE_FOR_LOOK), else classic.

argtypedescription
lookstring?
stylestring?

bumpOf(d: any) → number

argtypedescription
dany

scoreText(d: any) → string

argtypedescription
dany

fitFont(n: number, w: number, h: number, glyph: number?) → number

the biggest font a string of n glyphs takes in w x h

argtypedescription
nnumber
wnumber
hnumber
glyphnumber?

wrapPanel(lay: any, panelStyle: any, kids: { any }) → any

argtypedescription
layany
panelStyleany
kids{ any }

chunky(lk: ?, tk: ?, d: ?, lay: ?, t: ?) → void

argtypedescription
lk?
tk?
d?
lay?
t?

marquee(lk: ?, tk: ?, d: ?, lay: ?, t: ?) → void

argtypedescription
lk?
tk?
d?
lay?
t?

readout(lk: ?, tk: ?, d: ?, lay: ?, t: ?) → void

argtypedescription
lk?
tk?
d?
lay?
t?

banner(lk: ?, tk: ?, d: ?, lay: ?, t: ?) → void

argtypedescription
lk?
tk?
d?
lay?
t?

clean(lk: ?, tk: ?, d: ?, lay: ?, t: ?) → void

argtypedescription
lk?
tk?
d?
lay?
t?

renderRun(look: string, d: any, lay: any, t: number?, style: string?) → any

Draw the in-run score layout (the panel, score, multiplier and combo meter) in a look and a run style (chunky, marquee, readout, banner, clean, classic; nil follows the look), from DisplayData (see demo.module) and a layout from Layout.run. Every style draws inside lay.panel, so the touch clearance holds. Returns a full-screen node of absolutely placed parts.

argtypedescription
lookstring
dany
layany
tnumber?
stylestring?

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

Showing up to 3 levels deep. Open a part to see what it holds further down.

8+items
❒
package · born here
❒asset
# 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](scoreKit.package/guides/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](scoreKit.package/guides/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](scoreKit.package/guides/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](scoreKit.package/guides/add-an-end-of-run-results-card-that-fits-phones)**: the how-to for `Score.showCard` and 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](scoreKit.package/guides/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: ```lua 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: ```lua -- in a scene's build.luau, inside content() local kit = entity.spawnSynced("ScoreKit") kit.component.add(asset.resolve("scoreKit.ScoreKit", "component"), { display = "comboMeter", look = "fantasy", board = "level1" }) ``` From a coin, a kill or a checkpoint, pass whatever touched it. scoreKit walks up from the touching entity to the player's body: ```lua Score.add(touchingEntity, 10, { at = coin, reason = "coins" }) -- "+10" pops at the coin; "coins" is a results line Score.add(attackerBody, 100, { reason = "kills" }) Score.penalty(playerBody, 25) -- a hit taken: -25, and the combo breaks Score.bonus(playerBody, "No damage", 500) -- a named bonus line, never multiplied Score.breakCombo(playerBody, "fell") ``` ## 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 than `ui.screenSize()` (a game view inside a bigger window). - **Never clips.** When a `maxWidth` / `maxHeight` cap 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, an `aroundMe` board, 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 your `onButton(id)` and closes the card (`closeOnPress = false` keeps 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()`, and `k`, `tight` (fit steps taken) and `measured` (`over`, `inside`, `onScreen`). `scoreKit.card` also has `Card.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, and `Card.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 with `ui.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.playSession` lists 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. ```lua -- 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. 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 to 2 | 3 to 5 | 6 to 9 | 10 to 14 | 15 and up | |---|---|---|---|---|---| | multiplier | x1 | x2 | x3 | x4 | x5 | `every = n` replaces the steps with a uniform step: x2 at n hits, x3 at 2n, and so on up to `maxMultiplier`. 4. **The hit that reaches a step is already multiplied.** The 3rd hit is the first worth double. Points awarded = amount × multiplier, rounded to the nearest whole number with halves rounding up (`round = false` keeps fractions). 5. **The combo breaks** when: - **time runs out**: more than `window` seconds pass with no hit. The keeper checks this every frame, so a combo breaks on time even if no more points come. - **the game says so**: `Score.breakCombo(player)`. - **a penalty**: a negative amount always breaks the combo, unless `breakOnPenalty = false`. With `decay = "reset"` (the default) a break sets the combo to 0 and the multiplier to x1. With `decay = "step"` a timeout drops one multiplier step instead: the combo goes to that step's start (x4 → combo 6, x3) and gets a fresh window. If no hit comes, it keeps stepping down. `breakCombo` and penalties always reset. 6. **Penalties** (negative amounts) are never multiplied. 7. **`combo = false`** points are not a hit: they don't grow the combo or refresh its window, and they are not multiplied (pass `multiply = true` as well to multiply them by the current multiplier). **`multiply = false`** keeps a hit's points at face value while it still counts toward the combo. 8. **Bonuses** (`Score.bonus`) are never multiplied, never touch the combo, and get their own line in the results breakdown. The same label adds up. 9. **Score = points before multipliers + multiplier extra + bonuses − penalties.** The results breakdown lists exactly these, so its lines always add up to the total. Set the rules on the `ScoreKit` component's fields, or call this on every machine with the same values: ```lua Score.configure({ window = 1.8, steps = { 5, 10, 20, 40 }, maxMultiplier = 8, decay = "step", breakOnPenalty = false }) ``` ## Ratings: stars and grades A level sets targets. `Score.rate` (and the `stars`, `grade` displays and every results screen) turn a score or a time into 0 to 3 stars and a grade letter: ```lua Score.setTargets({ score = { 1000, 2500, 5000 } }) -- points for 1, 2, 3 stars Score.setTargets({ time = { 90, 60, 45 } }) -- seconds for 1, 2, 3 stars (lower is better) Score.setTargets({ score = { 1000, 2500, 5000 }, grades = { S = 7000, A = 5000, B = 3000, C = 1500 } }) local r = Score.rate(3100) -- { stars = 2, grade = "B", frac = 0.24, next = 5000, kind = "score" } ``` - **Stars** = how many targets the value meets (score: at least the target; time: at most the target). - **Grades** without explicit lines: **S** = 20% past the three-star target (score ≥ 1.2 × three, time ≤ three ÷ 1.2), **A** = three stars, **B** = two, **C** = one, **D** = below one. Explicit `grades` lines replace these. - `frac` is the progress from the last star target to the next one. `next` is the next target (nil at three stars). - With no targets set, the defaults are `{ score = { 1000, 2500, 5000 } }`, so the rating displays work out of the box. ## Rounds with MatchFlow When the scene has a **MatchFlow** match (the Match Flow Kit), scoreKit binds to it on its own (`match = "auto"`): - **Scores count in its matches.** The keeper reports every award, already multiplied, with `m:addScore(peer, points)`, so MatchFlow's HUD, standings and podium show the same numbers as scoreKit. - **Points only count while the round is playing** (`matchOnly = true`). An add during the lobby, countdown or results is refused, and a predicted "+10" is taken back. - **Every score goes back to 0** when a round's countdown starts. - **When a round ends, players are ranked.** MatchFlow's places are used, so every format ranks the way MatchFlow does. Each player's score is posted to the board, and every player gets their own results: the `roundEnded` event (on every machine) carries `{ n, ranking = { { key, name, score, place, stars, grade } }, results = { [key] = ResultsData } }`. Each player sees their results screen after MatchFlow's podium, during the break, never on top of it: the card waits until MatchFlow has finished showing its own results on that player's machine. It then stands in for MatchFlow's "next round" panel and shows "Next round in N" itself. If the break is over before the card could show, it is skipped, and a card still up when the next round counts down closes, so there is only ever one end-of-round screen. The break is how long the card can stay up, so give MatchFlow a `breakSeconds` at least as long as `resultsSeconds`. 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. ```lua -- a whole match in two components on synced entities local match = entity.spawnSynced("Match") match.component.add(asset.resolve("~MatchFlow.MatchFlow", "component"), { format = "timed", roundSeconds = 30 }) local kit = entity.spawnSynced("ScoreKit") kit.component.add(asset.resolve("scoreKit.ScoreKit", "component"), { results = "tally" }) ``` MatchFlow comes with scoreKit as one of its dependencies. 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: ```lua -- in a scene's build.luau, inside content() local Pickups = require("scoreKit.pickups").kit() -- pickupsKit's API, as scoreKit installed it for i = 1, 5 do Pickups.spawn({ (i - 3) * 1.5, 0, 4 }, { prefab = "goldCoin" }) end Pickups.spawn({ 0, 0, 7 }, { prefab = "ruby" }) Pickups.spawn({ 3, 0, 6 }, { prefab = "damageOrb", effect = "none" }) -- a hazard: no power-up, just a penalty entity.spawn("PickupScores").component.add(asset.resolve("scoreKit.ScorePickups", "component"), { points = "goldCoin=10, ruby=50, damageOrb=-25" }) ``` - **`points`** gives each pickupsKit prefab (`goldCoin`, `ruby` …) or kind (`coin`, `gem` …) its points. A prefab's entry beats its kind's. A negative value is a penalty: never multiplied, and it breaks the combo. A pickup with no entry scores nothing (pickupsKit still counts it). - **Each grab scores once.** pickupsKit tells every machine about a grab once. Only the machine keeping the score turns it into a `Score.add` for the player who took it, with the "+N" at the pickup and `coins`, `gems` … (or `hazards`) as the results line. Before the first point there is no `ScoreKit` yet: then the senior machine scores the grab, and its `Score.add` creates the kit, as the first example's jump does. So a coin is worth the same whichever player grabs it, on whichever machine. - Grabs build the combo like any other hit, and count only while a MatchFlow round is playing. - From code: `require("scoreKit.pickups").listen("goldCoin=10")` does the same and returns a stop function. `score(ev, points)` scores one pickupsKit `collect` event. - **Where pickupsKit's counter goes.** pickupsKit's `PickupHUD` sits in a top corner, and MatchFlow's standings take the top right, so put the counter top-left: `entity.spawn("PickupCounter").component.add(Pickups.HUD, { corner = "topLeft" })`. With `corner = "auto"`, scoreKit's score display sees it there and moves to the bottom-left, so the three never cover each other. - `require("scoreKit.pickups").kit()` is pickupsKit's own API (`spawn`, `burst`, `on`, `get` …), so a game that got pickupsKit with scoreKit reaches it through scoreKit. pickupsKit's README has every look and setting. ## Time trials ```lua Score.startRun(player) -- start the clock Score.split(player, "Bridge") -- a checkpoint (labels default to CP1, CP2 ...) Score.finishRun(player) -- the time goes to the time board, fastest first, with its splits ``` The `splits` display shows each split against the player's own best: green when ahead, red when behind. The `timeTrial` results screen shows the finished run against the best. The keeper times every run on its own clock. It uses the runner's own reading (which has no network delay) only when that reading is within 0.75 s of the keeper's. A runner can't claim a time their run didn't take. ## Leaderboards Each world has its own boards, kept in the world's `runtime_data`, so they survive the world being closed and opened again. A board keeps **one row per player: their best of the season** (highest score, or fastest time on a time board), and counts their plays. ```lua local board = Score.board() -- the kit's board (field `board`, default "main") local times = Score.timeBoard() -- "<board>_times": fastest first board:top(10) -- { { k, n, v, rank, st, g, at, c } } board:around(player, 5) -- you and the players just above and below board:entry(player), board:rankOf(player) board:season(), board:seasons() -- the current season, and past ones with their top 10 board:newSeason("Summer") -- archive this season's top 10 and start an empty one board:remove(player) -- take a stale or test row off this season (the writer in charge only) board:status() -- is it saved? (below) board:data(player) -- exactly what the board views draw board:onChange(fn) Score.board("level2") -- any number of boards, by id ``` **Seasons.** `newSeason` archives the current season's top 10 (names, values, stars, grades), records how many players it had, and opens season N+1 empty. Old rows stay in storage under their season. `board:seasons()` and the `seasons` view show the champions of every past season. Only the board's writer can start a season, and only while it is the keeper. ## Who can write the board **Only the keeper changes scores, and only the keeper writes the board.** The keeper is the machine that owns the synced `ScoreKit` entity: whoever loaded the scene first, or, after that machine leaves, the remaining player with the lowest peer id. Every other machine only *asks* it, and by default its asks are refused: - **Scoring is keeper-only by default** (`acceptRemote = false`). Only code running on the keeper changes a score. The keeper sees every player's body, so a coin, a kill or a checkpoint is judged there, as the gallery's coins are. You can run the same code on every machine: the keeper's call counts, and on the other machines `Score.add` sends nothing, predicts nothing and fires `refused` locally. So each pickup counts once. `Score.isKeeper()` says where you are. - **No machine can post its own value to the board.** A post asked for from another machine carries no number. The keeper posts the score it counted, and only to the kit's score board. Times reach the time board only from runs the keeper timed itself. - **Only the keeper's messages are believed.** Other machines take standings, awards and round results only from the keeper's peer. A player who sends their own "snapshot" or "award" is ignored, and the ignore is logged. - **Points formats are ranked on the keeper's counted scores**, not on MatchFlow's standings: MatchFlow takes reports from any machine. MatchFlow's places count only for `race`, `lastStanding` and `kingOfTheHill`, where order is not decided by points. - **Only while playing**, when bound to a MatchFlow match. **`acceptRemote = true`** lets each machine report points for its own player, for events only that machine can see, such as a button press. Its "+N" then shows instantly. That is a trust decision, because a modified client can then claim points for itself within these caps: - **Only its own player** (`remoteFor = "self"`): a request to score for anyone else is refused and logged. - **No absurd amounts**: a single remote add above `maxPerAdd` (1000) is refused. - **No floods**: more than `maxPerSecond` (20) remote adds per player per second are refused (short bursts of up to twice that are allowed). A refused request is answered with the reason: the sender's "+N" is taken back, a `refused` event fires there, and a warning is logged on both machines. **Two modes, set by the `writers` field:** | `writers` | Where the board lives | Who can write it | |---|---|---| | empty (default) | the world store (`runtime_data.world`) | the keeper, whoever it is | | `"<userId>, <userId>"` | those accounts' **own** player stores (`runtime_data.player(id)`) | only those accounts, and only while one of them is the keeper. The Zero server enforces it: no other account can write a player store. | The default mode protects the board from the kit's own network path. Nothing another player's game sends can change it. But `runtime_data.world` itself accepts writes from any client, so a player who runs modified engine code could still write it directly. If your board must hold against that too, set `writers` to your own account id(s) (`runtime_data.localId()` prints yours). **What happens when a write can't be made.** Scores are never lost silently: | The board's status | When | What happens | |---|---|---| | `saved` | every write landed | nothing to do | | `saving` | writes in flight | they land within a moment | | `retrying` | a write failed (network, store unavailable) | it stays queued and is retried with back-off (0.5 s, 1 s, 2 s … up to 30 s) until it lands. The queue is also kept in the keeper's own player store, so it is replayed if the keeper's tab closes first. | | `held` | locked mode and the keeper is not a writer | the result is **held**: queued in the world store as a pending result, not put on the board. The player gets a toast saying so, and the results screen says "Held for the board's keeper". A writer later calls `board:held()`, `board:approveHeld("all")` or `board:rejectHeld(ids)`. | | `offline` | `runtime_data` is not available | nothing is written; the status says so | | `readOnly` | on a machine that is not the keeper | `board:status()` there reports the keeper's status from its snapshot | Every board view shows this status as a chip, so players can see whether their score is saved. ## Multiplayer - **The keeper** runs the rules (combos time out on its clock), applies every add, writes the board and publishes every player's score, combo, multiplier and combo timer in a synced snapshot on the `ScoreKit` entity, up to 12 times a second (and at least twice a second). **Every player sees the same scores and the same board.** - **Each player's display and popups are their own.** Each machine draws its own player's corner display, "+N" popups, toasts and results screen. Nobody sees another player's popups. - **Seen quickly.** A player sees their own points as soon as the keeper's next snapshot reaches them (it publishes up to 12 times a second). With `acceptRemote = true`, `Score.add` on the player's own machine is also *predicted*: the points, the combo and the "+N" show the moment it is called. The prediction is let go once the keeper's snapshot confirms it, and taken back if it is refused. One that is never confirmed is dropped after 3 s with a warning. - **Players come from the scene's player setup** (`layers.active.players`). Every player in the match has their own score, results and board row: - A signed-in player's key is `u:<userId>`, so a returning player keeps their personal bests. - **The same account signed in on two machines is two players.** The session on the lowest peer keeps `u:<userId>`; the next is `u:<userId>#2` and shows as "Name (2)", and so on. Each has its own score, its own place in the round and its own board row. - `p:<peer>` is used for an anonymous session, and `b:<name>` for bots (`Score.add("Robo", 10)`, `Score.setName`). - **Only players who are here are ranked.** A round's ranking, its places ("1st of 2") and the board posts cover the players in the scene's player setup when the round ends, plus any bots the game scored by name. A player who left before the end is not ranked or posted, and a key nobody plays under can never take a place. - **Each event counts once.** With the default keeper-only scoring, only the keeper's `Score.add` counts, so the same pickup code can run on every machine. With `acceptRemote = true`, report an event either from the keeper or from the player's own machine, not both. - **If the keeper leaves**, the entity passes to another machine, which carries on from the last snapshot. Writes still queued on the leaver are replayed the next time that account keeps. Points scored in the instant of the handover can be lost. - **Events** fire on every machine: `award`, `comboUp`, `comboBreak`, `record`, `held`, `submitted`, `run`, `roundStarted`, `roundEnded`, `refused`, `snapshot`. Use `Score.on(name, fn)`, which returns an unsubscribe function. ## Styles Every style is listed by `Score.catalog()` as `{ id, family, name, description, natural = { w, h }, themed, tags = { look, looks, size, genres, shows } }`. Filter it with `Score.catalog("display")` or `Score.catalog({ family = "board", genre = "racing" })`. Themed styles draw in any of the five looks. ```lua Score.setDisplay("multiplierRing") -- this machine's corner display Score.setLook("fantasy") -- themed displays, boards, results Score.setPopups("cartoon") -- "+N" popups ("off" to hide) Score.setResults("tally") -- the end-of-round screen Score.setHud({ corner = "topRight", scale = 0.8 }) -- corner: auto, topLeft, topRight, bottomLeft, bottomRight, top, bottom ``` Or set the world's defaults with the `ScoreKit` fields `display`, `look`, `popups`, `results` and `corner`. ### Score displays (`display`) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `arcade` | Arcade Odometer | arcade | medium | arcade, shmup, pinball, platformer | Zero-padded rolling digits in a black glass bezel. Every digit column rolls like an odometer, with a 1UP label and a multiplier chip. | | `pixel` | Pixel Counter | arcade | medium | retro, arcade, platformer | Chunky 8-bit pixel digits with a hard shadow, a stepped pixel combo bar and a pixel x3. | | `comboMeter` | Combo Meter | any (themed) | medium | action, rhythm, brawler, arcade | Score plus a wide meter that fills toward the next multiplier step, and a strip that drains with the combo window. | | `multiplierRing` | Multiplier Ring | any (themed) | medium | action, shooter, rhythm | A circular ring that drains with the combo window, one segment per multiplier step, and a big xN in the centre. | | `stars` | Star Rating | any (themed) | medium | puzzle, casual, mobile, platformer | Score with three stars that fill as the score passes its targets. The next star fills partially. | | `grade` | Grade | any (themed) | medium | action, rhythm, racing, stylish | A big grade letter (S A B C D, each its own colour, S shines) with progress toward the next grade. | | `splits` | Time Trial Splits | any (themed) | large | racing, speedrun, time trial, parkour | Running timer, finished splits with green/red deltas, the current split highlighted, an ahead/behind banner and the time to beat. | | `minimal` | Minimal | minimal | small | any, casual, exploration | Quiet thin type straight over the game with a soft shadow, a small label and a subtle xN. | | `scifi` | Holo Readout | scifi | medium | shooter, space, cyberpunk | Clipped-corner holographic frame with scanlines, glowing mono digits and the combo as tick segments. | | `fantasy` | Gilded Plaque | fantasy | large | rpg, adventure, medieval | A walnut plaque on a parchment ribbon with gold serif numerals, a wax-seal multiplier and rune gems lighting up. | | `cartoon` | Bouncy Cartoon | cartoon | medium | casual, kids, party, platformer | A chunky inked number on a yellow starburst that squashes and stretches on every award, with a combo starburst badge. | | `neon` | Neon Sign | arcade | medium | arcade, synthwave, rhythm | A glowing neon-tube number with a subtle flicker, and the multiplier in a second tube colour. | | `broadcast` | TV Score Bug | any | small | sports, racing, party, multiplayer | A sports-broadcast lower third: LIVE dot, place, player name, score and a multiplier tag. | ### Popups (`popups`) "+N" where the points were scored: projected from the `at` position you pass, or under the display when there is none. Kinds: normal, combo (with its xN), big (at least `bigAt` = 100), bonus (with its label) and penalty (red, falling). | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `pop` | Clean Pop | any (themed) | small | any | Bold outlined number that pops in, rises and fades. Draws in the current look. | | `arcade` | Arcade Pixel | arcade | small | retro, arcade, platformer | Pixel-font number that hops up in hard steps and blinks out. Big throws pixel sparks. | | `scifi` | Holo Bracket | scifi | small | shooter, space, cyberpunk | Glowing mono number between brackets that spread open. Big draws an expanding hex, penalty glitches. | | `fantasy` | Gold Embers | fantasy | small | rpg, adventure, medieval | Gold serif numerals that drift up like embers with sparks. Big radiates rays. | | `cartoon` | Inked Bounce | cartoon | small | casual, kids, party | Chunky inked number with an elastic bounce and a tilt. Big lands on a starburst, bonus on a ribbon. | `popups = "auto"` (the `ScoreKit` default) picks the popup that matches the look. ### Leaderboards (board views) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `top10` | Top 10 | any (themed) | medium | arcade, platformer, puzzle, racing, party | The classic high-score table: rank with medals, avatar, name, stars and grade, value. Your row is highlighted, and pinned under a divider when you are outside the top 10. | | `podium` | Podium | any (themed) | large | party, arcade, sports, racing | The top three on stepped podium blocks (1st centre, crowned), with 4th to 8th as a compact list. | | `aroundMe` | Around Me | any (themed) | medium | arcade, platformer, puzzle, racing, endless | Your rank as a hero (#17 of 214, top 8%), the rows just above and below you, and how far it is to pass the next player. | | `bestTimes` | Best Times | any (themed) | medium | racing, platformer, speedrun, time-trial | Fastest first, with a stopwatch: the track record on top, every other time with its gap to first and a gap bar. | | `seasons` | Seasons | any (themed) | large | competitive, arcade, sports, racing | This season's standings under a season badge, beside a hall of champions: each past season with its top three. | | `sign` | Scoreboard Sign | any (themed) | large | arcade, platformer, party, racing, hub | A sign that stands in the level (the `ScoreSign` component), framed per look: arcade marquee with bulbs, LED panel, holo-board, wooden notice board, chalkboard. Top 5 in big type. | Draw any view anywhere with `require("scoreKit.boards").render(id, look, Score.board():data(), { w, h, t })`. **A board in the level:** the `ScoreSign` component builds a sign (two posts and a backboard) and draws a board view on its face, live: ```lua local sign = entity.spawn("HallOfFame", { position = { 0, 0, -10 } }) sign.component.add(asset.resolve("scoreKit.ScoreSign", "component"), { view = "sign", look = "fantasy", width = 5, height = 3 }) ``` Fields: `board` (empty = the kit's), `view` (any board view), `look`, `title`, `width`, `height` (metres), `lift` (height above the ground), `frame` (false: no posts or backboard, for your own wall), `maxDistance`. ### End-of-round screens (`results`) | id | name | look | size | suits | what it is | |---|---|---|---|---|---| | `ratingCard` | Rating Card | any (themed) | medium | arcade, platformer, puzzle, rhythm, party | Stars that pop in one by one, a big grade letter, the score and this round's place, a breakdown table that adds up to the total, and best-combo / max-multiplier chips. | | `celebration` | Celebration | any (themed) | large | arcade, platformer, racing, endless, party | NEW PERSONAL BEST or NEW WORLD RECORD with rays and confetti, the new score, the previous best, the improvement and the board rank. A calm "Good run" when neither. | | `tally` | Tally | any (themed) | medium | arcade, platformer, action, rhythm | A combo and bonus tally that counts up: each breakdown line appears and counts from 0, a running total climbs, then the final total punches in with the rating. | | `timeTrial` | Time Trial | any (themed) | medium | racing, platformer, speedrun, time-trial | The final time big, every split against its best with green (ahead) / red (behind) deltas and a gap bar, a PB / record badge and the time to beat. Handles a first run with no best. | A finished time run always shows `timeTrial`. 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, 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. 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 `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). - **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 reaches `onButton`; 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, and `board:purge` removes 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 no `package.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.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). 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 `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. - **An input handler from an earlier Play stays attached (#22432).** A handler your scene adds in `onLoad` (for example `controls.jump:onPressed(...)`) is not removed when play stops. So if you press Play, stop and press Play again, every jump calls `Score.add` once 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 handle `onPressed` returns and call its `:Disconnect()` in `onUnload`, 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 = 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.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
▲ 1↑ born
▣
module · born here
❒asset
# theme The five looks (arcade, minimal, scifi, fantasy, cartoon; three of them MatchFlow's own tokens), the widget-tree builders every renderer shares, number/time/delta formatting, star and arc paths, and a 5x7 pixel font. Used by every renderer; use it to match the kit in your own UI.
▲ 0↑ born
backing path · scoreKit.package/layout.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported on this asset or on the parts this page shows. Parts it leaves out are not counted here.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.