# MatchFlow 1.4.3
**The match loop every multiplayer game needs, as one component.** One call puts a match in your scene, and the world runs:
```
waiting for players → lobby countdown → 3-2-1-GO → round with timer → results → break → next round
```
One machine is in charge, so every player sees the same countdown, clock, round end and results at the same moment, and when that machine's player quits, the match carries on for everyone else on the same clock and scores. Eight match formats sit behind one field. Ten countdown styles with their own 3-2-1-GO sounds, four results screens, seven in-round HUD layouts, a lobby panel and a king-of-the-hill zone with five looks are each one field away, and every style carries tags so a game can list and filter them.
**matchFlowKit is this package.** matchFlowKit is the name it was first asked for. It ships as **MatchFlow** and keeps that name because other kits already install it and reach it by that name: scoreKit, spawnerKit, SecondWind, pickupsKit and others load `~MatchFlow.*`, and renaming the package would break every one of them. One package, one name; searching ZeroMind for either "MatchFlow" or "matchFlowKit" finds it.
## Guides
Two guides ship inside this package, in `MatchFlow.package/guides/`, and install with it:
- **[How to add rounds, a countdown and a scoreboard to my game](MatchFlow.package/guides/how-to-add-rounds-a-countdown-and-a-scoreboard-to-my-game)**: the how-to. Starting a match, rounds and win conditions in each format, scoring and teams, the hill zone, picking a HUD layout, countdown and results styles, and what players see when the host leaves.
- **[A best-of-three arena match with a countdown, live scores and a results screen](MatchFlow.package/guides/best-of-three-arena-match-with-countdown-live-scores-and-results-screen)**: the example. A brand-new world becomes a best-of-three match with a countdown before each round, live scores, score bars from barsKit, and a results screen and Victory or Game Over screen from menusKit. MatchFlow needs neither kit; the example adds them.
Open one with the `guides` tool by the path in its link (`MatchFlow.package/guides/<name>`). In the editor's Docs panel they are listed under MatchFlow and open by their full name, `MatchFlow.guides.<name>`.
## First example
Install the package from ZeroMind (search "MatchFlow match flow kit"). It lands at `/source/MatchFlow.package`. A brand-new world already has a scene with a ground and a player: open `scenes/main.scene/build.luau` and add these two lines at the end of its `content()` function, just before its final `end`:
```lua
local MatchFlow = require("MatchFlow.api")
MatchFlow { format = "timed", seconds = 30, minPlayers = 1 }
```
Press **Play**. A five-second "Starting in" lobby counts down, then a bold 3-2-1-GO with sound, a 30-second round timer with the scoreboard, a podium, a five-second break, and the next round. Every score is 0 until your game reports some (see "Hooking your game in"). Leave out `minPlayers = 1` and the match waits for two players, which is the default.
`MatchFlow { ... }` spawns the synced `Match` entity with a MatchFlow component set from the table, and returns the component. Every field below can go in the table, and `name` names the entity (default `Match`). From inside another package, require it as `"~MatchFlow.api"`.
**Edit it freely.** Change `30` to `45` (or any field) and save: the scene rebuilds and the match updates, on every machine, and a machine that opens the world later loads the new numbers too. Inside a scene's `content()`, `MatchFlow { ... }` always makes the match itself, so the scene's build owns it and keeps it, under the same id, from one rebuild to the next. Called from an ordinary script instead (outside a build), it finds a match already in the scene by that name and updates its fields rather than adding a second one.
To switch the match type, change one field: `format = "firstToScore"`, `"bestOf"`, `"lastStanding"`, and so on. The screens are restyled the same way:
```lua
MatchFlow {
format = "bestOf", rounds = 3, targetScore = 5,
countdownStyle = "trafficLight", resultsScreen = "recap", hudLayout = "scoreBug",
resultsLook = "cartoon", hudLook = "cartoon", lobbyLook = "cartoon",
}
```
The component works without the front door too: `entity.spawnSynced("Match").component.add("MatchFlow", { format = "timed", roundSeconds = 30 })`.
## Hooking your game in
Get the component from any script, report what happens, and listen for what changes:
```lua
local m = require("MatchFlow.api").find() -- the MatchFlow on the entity named "Match"
-- report (call from any machine; non-authority calls are forwarded to the one in charge)
m:addScore(avatar, 1) -- who = peer id, an entity (its owner is the player) or nil for "me"
m:knockOut(victimAvatar) -- lastStanding, or a player going down in waves
m:finish(avatar) -- race: crossing the line
m:clearWave() -- waves: the team cleared a wave
m:endTurn() -- turnBased: the local player ends their turn early
m:setOnHill(avatar, true) -- kingOfTheHill: only needed without a Hill zone (see below)
-- listen
m.events.onStateChanged:connect(function(e) print(e.previous, "->", e.phase) end)
m.events.onRoundEnded:connect(function(e) print("round", e.round, "won by", e.winnerName, e.outcome) end)
m.events.onMatchEnded:connect(function(e) print("match won by", e.winnerName) end)
m.events.onCountdown:connect(function(e) if e.n == 0 then unfreezePlayers() end end)
```
A typical game spawns its pickups, enemies or checkpoints only while `m:getPhase() == "playing"`, and only on the machine where `m:isAuthority()` is true. The example `game/OrbRush.component` in this kit's world does exactly that in about 100 lines: synced orbs, and `m:addScore(body, 1)` on pickup.
A score reported outside `playing`, or for a player who is out or watching, is ignored. You don't need to guard your calls.
## Holding the match (a ready check)
`m:setHold(true)` keeps the match in the waiting room however many players are in. `m:setHold(false)` lets it go: the lobby counts down `lobbySeconds` and the round begins as usual. Holding again while that countdown runs stops it and goes back to waiting, which is how a ready check works: hold while anyone is not ready.
```lua
local m = require("MatchFlow.api").find()
m:setHold(true, "Waiting for everyone to be ready") -- any machine; the one in charge applies it
-- ... later, when everyone pressed Ready:
m:setHold(false)
```
A hold never interrupts a round being played. A match that has ended and is held waits at the end of its break and goes back to waiting with fresh scores instead of starting the next match. `start()` starts regardless of a hold. A kit that draws its own lobby sets `showLobby = false` (and `showHud = false` if it draws its own scoreboard), so MatchFlow's waiting panel steps aside while its HUD, countdown and results still show. lobbyKit's ready check is built this way.
## Waves with breaks (a tower defense, a horde survival)
A `waves` match can pace its waves itself: give it `waveBreakSeconds` and every wave after the first is preceded by a break of that many seconds (build time), and `firstBreakSeconds` sets the break before wave 1 (`-1`, the default, uses `waveBreakSeconds`). The break counts down on every screen on the shared clock. Your game listens for the wave starting and sends its enemies, and reports the wave cleared:
```lua
local m = require("MatchFlow.api").find()
m.events.onWaveStarted:connect(function(e)
if m:isAuthority() then sendWave(e.wave) end -- e.early, e.left: called early, with this many seconds to spare
end)
-- when the last enemy of the wave is gone (report once, on one machine):
m:clearWave() -- the next break begins, or the last wave wins
m:callWave() -- a "send it now" button: cuts the break short
m:endRound("defeat") -- the base fell: the team loses together
local w = m:waveInfo() -- { state = "break" | "wave", wave, waves, left, ... }
```
- `waves = 0` is endless: clearing waves never wins, only a defeat (or `roundSeconds`) ends the round.
- `endRound(outcome)` ends the round now in any format; in `waves` it is how a game loses when its own rule says so (lives at zero) without knocking every player out.
- `joinInProgress = true` lets someone who joins mid-round play at once, which a co-op match wants; without it they watch until the next round.
- `showResults = false` hides only the results screen, for a game that draws its own victory and defeat screens. With `hold = true` a finished match then waits in the waiting room, and `start()` is "Play again".
- With breaks, a `clearWave()` that arrives during a break is ignored, so a wave reported twice counts once. Without `waveBreakSeconds` a waves match runs exactly as before.
- towerDefenseKit runs its whole match this way: build time, waves, the call-early bonus, a defeat when the lives run out, and Play again.
## Formats
| `format` | Round ends when | Winner | Fields it reads |
|---|---|---|---|
| `timed` | the clock runs out | highest score | `roundSeconds` |
| `firstToScore` | someone reaches the target (or time runs out) | first to `targetScore` | `targetScore`, `roundSeconds` |
| `bestOf` | as `firstToScore`, per round | most round wins over up to `rounds` rounds; a majority ends it early | `rounds`, `targetScore`, `roundSeconds` |
| `lastStanding` | one player (or none) is left | the survivor; earlier knockouts place lower | `roundSeconds` (0 = no limit) |
| `kingOfTheHill` | someone holds the hill alone for `targetScore` seconds | longest uncontested hold | `targetScore`, `roundSeconds` |
| `race` | everyone has finished (or time runs out) | finish order | `roundSeconds` |
| `waves` | `waves` waves cleared (victory), or everyone down, `endRound("defeat")` or out of time (defeat) | the team; the top scorer is shown as MVP | `waves`, `roundSeconds`, `waveBreakSeconds`, `firstBreakSeconds` |
| `turnBased` | every player has had `turns` turns | highest score | `turnSeconds`, `turns` |
A round with no time limit (`roundSeconds = 0`) shows elapsed time. A turn-based round shows the current turn's clock.
### The names first asked for
Every one of these works and stays working beside the current name. MatchFlow reads them as the current one, and the machine in charge writes the current name back into `format` and the length into `roundSeconds`, so other kits reading those fields see the usual values.
| First name | Current name |
|---|---|
| `seconds` (field) | `roundSeconds`: above 0, `seconds` wins; 0 leaves `roundSeconds` in charge |
| `format = "scoreLimit"` / `"bestOfRounds"` / `"lastOneStanding"` / `"raceToFinish"` / `"surviveWaves"` | `firstToScore` / `bestOf` / `lastStanding` / `race` / `waves` |
| `countdownStyle = "bigDigits"` / `"scifiHologram"` / `"cartoonPop"` | `bold` / `hologram` / `cartoon` (also for the `Countdown` component's `style`) |
| `resultsScreen = "winnerBanner"` / `"roundRecap"` | `banner` / `recap` |
| event `onState` / `onRoundEnd` | `onStateChanged` / `onRoundEnded`: both fire, with the same fields |
## King of the hill: the Hill zone
Drop a `Hill` on any entity in a level. A player standing in it alone is holding it, two or more is contested, and the match counts the hold time with no code of yours: the machine in charge tells the match who is on the hill.
```lua
-- in a scene's build.luau, inside content()
local MatchFlow = require("MatchFlow.api")
MatchFlow { format = "kingOfTheHill", targetScore = 20, seconds = 90, hudLayout = "holdMeter" }
local hill = entity.spawn("Hill", { position = { 0, 0, 8 } })
hill.component.add(MatchFlow.component("Hill"), { look = "scifiPad", radius = 3 })
```
**A hill that moves:** give it `spots` and `moveEvery`. During a round it hops to the next spot every `moveEvery` seconds, flashing for `warnSeconds` before it goes. Every machine works out the spot from the match clock, so they all agree with nothing extra sent.
```lua
hill.component.add(MatchFlow.component("Hill"), { look = "glowRing", spots = "10,0; -10,0; 0,10", moveEvery = 20 })
```
| Look (`look`) | What it is |
|---|---|
| `glowRing` | a glowing ring on the floor with a soft light column |
| `flagPlatform` | a low platform with a flag that takes the hill's state colour |
| `scifiPad` | a tech pad with segmented light strips and a holo column |
| `runeCircle` | a fantasy stone circle of glowing runes |
| `outline` | a plain thin outline, nothing else |
Each look shows three states readable from across a level: idle, held, and contested (pulsing red). The fields, events and methods are in `Hill.component/README.md`. A hill also works with no match in the scene, lighting up from who stands in it.
## In-round HUD layouts
`hudLayout` picks how the round is shown. Every layout draws the same match, in the `minimal`, `scifi` and `cartoon` looks (`hudLook`), and has its own phone layout.
| `hudLayout` | What it is |
|---|---|
| `classic` (default) | timer at the top centre with the format line, live scoreboard at the side |
| `cornerTimer` | a compact timer in a corner with your place and score |
| `scoreBug` | a sports-TV score bug with a LIVE dot |
| `versusBar` | you against the best other player across the top, with a tug bar |
| `timerStrip` | a thin timer-only strip, nothing else |
| `rankedSidebar` | every player ranked down the side, with gaps to the leader |
| `holdMeter` | king of the hill: who holds it, each player's hold time against the target, CONTESTED |
Draw one yourself with `require("MatchFlow.hud").render(look, data, { w, h, layout, narrow, t })`; `data` comes from `MatchFlow.view.hud(...)`, and `Hud.sample(layout)` gives sample data.
## Every field and its default
| Field | Default | What it does |
|---|---|---|
| `format` | `"timed"` | one of the eight formats above (or a first name) |
| `roundSeconds` | `30` | round length (0 = no limit; `timed` treats 0 as 60) |
| `seconds` | `0` | the round length under its first name; above 0 it wins |
| `targetScore` | `10` | score to win `firstToScore`/`bestOf`, seconds to hold in `kingOfTheHill` |
| `rounds` | `3` | maximum rounds in `bestOf` |
| `waves` | `5` | waves to clear in `waves` (0 = endless) |
| `waveBreakSeconds` | `0` | `waves`: a break of this many seconds before each wave after the first, cut short by `callWave()`; 0 = no breaks |
| `firstBreakSeconds` | `-1` | `waves`: the break before wave 1; -1 = the same as `waveBreakSeconds` |
| `joinInProgress` | `false` | someone who joins mid-round plays at once (co-op) instead of watching until the next round |
| `turnSeconds` / `turns` | `10` / `3` | turn length and turns per player in `turnBased` |
| `minPlayers` | `2` | players needed before the lobby counts down |
| `lobbySeconds` | `5` | lobby countdown once enough players are in |
| `countdownSeconds` | `3` | the 3-2-1-GO before each round (0 skips it) |
| `resultsSeconds` | `7` | how long results stay up |
| `breakSeconds` | `5` | break before the next round |
| `autoStart` | `true` | start by itself at `minPlayers`; when false, call `m:start()` |
| `hold` | `false` | while true no match starts: the waiting room stays up, a lobby countdown stops, a finished match waits instead of starting the next (see Holding the match) |
| `holdText` | `"Waiting for everyone to be ready"` | what the waiting panel says while held |
| `showLobby` | `true` | false hides only the waiting / lobby countdown / next-round panel, for a kit that draws its own lobby; the HUD, countdown and results still show |
| `showHud` | `true` | false hides only the in-round HUD (timer and scoreboard), for a kit that draws its own scoreboard; the 3-2-1-GO and the results still show |
| `showResults` | `true` | false hides only the results screen, for a game that draws its own end screen; the lobby, HUD and countdown still show |
| `includePeers` | `true` | everyone in the world is a player; when false, call `m:addPlayer(id, name)` yourself |
| `countdownStyle` | `"bold"` | one of the ten countdown styles |
| `resultsScreen` | `"podium"` | `podium`, `table`, `banner` or `recap` |
| `hudLayout` | `"classic"` | one of the seven HUD layouts |
| `resultsLook` / `hudLook` / `lobbyLook` | `"scifi"` | `minimal`, `scifi` or `cartoon` |
| `showUi` | `true` | false draws nothing, so you can build your own UI from `getState()` |
| `sounds` / `volume` | `true` / `0.8` | the countdown's tick and GO sounds |
## Styles and tags
Every style in the kit is in one tagged catalog: the 8 formats, 10 countdowns, 4 results screens, 7 HUD layouts, 5 hill looks and 3 looks.
```lua
local Catalog = require("MatchFlow.api").catalog -- or require("MatchFlow.catalog")
Catalog.list("countdown") -- { { kind, id, name, description, tags, aliases, field } }
Catalog.filter({ tag = "retro" }) -- every retro style, of any kind
Catalog.filter({ kind = "hudLayout", anyTag = { "sports", "racing" } })
Catalog.filter({ kind = "countdown", tags = { "sports", "racing" } }) -- all of the tags
Catalog.get("results", "winnerBanner").id -- "banner": first names resolve
Catalog.tags() -- every tag in use, sorted
```
Kinds: `format`, `countdown`, `results`, `hudLayout`, `hillLook`, `look`. Tags come from a fixed vocabulary: retro, scifi, sports, fantasy, cartoon, minimal, party, arena, racing, arcade, broadcast, competitive, coop, casual, strategy, versus, team.
| Kind | id: tags |
|---|---|
| format | `timed`: arena, party, arcade, competitive · `firstToScore`: arena, sports, party, competitive · `bestOf`: sports, arena, competitive, versus · `lastStanding`: arena, party, competitive · `kingOfTheHill`: arena, party, competitive · `race`: racing, sports, competitive · `waves`: arena, coop, team, scifi · `turnBased`: party, strategy, casual |
| countdown | `bold`: arena, sports, party, arcade · `trafficLight`: racing, sports · `pixel`: retro, arcade · `hologram`: scifi, arena · `cartoon`: cartoon, party, casual · `minimal`: minimal, casual · `fantasy`: fantasy · `flipClock`: retro, minimal · `neon`: retro, arcade, scifi · `broadcast`: sports, broadcast, racing |
| results | `podium`: party, sports, arena · `table`: minimal, arena, racing, competitive · `banner`: party, sports, cartoon · `recap`: sports, arena, competitive |
| hudLayout | `classic`: arena, party · `cornerTimer`: minimal, racing, casual · `scoreBug`: sports, broadcast, racing · `versusBar`: versus, arena, sports, competitive · `timerStrip`: minimal, casual · `rankedSidebar`: arena, party, racing, competitive · `holdMeter`: arena, party, competitive |
| hillLook | `glowRing`: scifi, arena, arcade · `flagPlatform`: sports, party, cartoon · `scifiPad`: scifi, arena · `runeCircle`: fantasy · `outline`: minimal |
| look | `minimal`: minimal, casual · `scifi`: scifi, arena · `cartoon`: cartoon, party, casual |
## Countdown styles
Every style has its own tick (3, 2, 1) and GO sound. The ticks climb a little in pitch as the count nears GO, so the last second sounds urgent. In a match the sounds play on every machine, at the moment each number appears on its screen.
| `countdownStyle` | Look | Sound |
|---|---|---|
| `bold` | big bold slam-in numbers with a glow streak | punch |
| `trafficLight` | red → amber → green racing lights | race beeps |
| `pixel` | 8-bit block digits on a CRT panel | chiptune |
| `hologram` | cyan sci-fi ring, scanlines, "ENGAGE" | sci-fi sweep |
| `cartoon` | bouncy number on a starburst, "GO!" | toy boing |
| `minimal` | thin progress ring, clean type | soft tone |
| `fantasy` | golden runic circle, "BEGIN" | bell |
| `flipClock` | split-flap cards that flip each second | mechanical click |
| `neon` | buzzing neon tube sign | synth |
| `broadcast` | sports-TV lower-third with a LIVE tag | stadium beeps and an air horn |
### A countdown on its own
`Countdown` is the same visuals and sounds as a standalone component, for any other timer in your game: a respawn, a bomb or a door. It is local to each machine.
```lua
local MatchFlow = require("MatchFlow.api")
local cd = entity.spawn("RespawnTimer").component.add(MatchFlow.component("Countdown"), { style = "neon", seconds = 5, autoStart = false, anchor = "top" })
cd.events.onFinished:connect(respawn)
cd:start() -- or cd:start(10)
```
Fields: `style`, `seconds` (3), `autoStart` (true), `loop` / `loopDelay`, `goText` and `caption` (override the words), `sounds`, `volume`, `showUi`, `anchor` (`center`/`top`/`bottom`), `scale`, `layer`. Events: `onTick{n}`, `onFinished`. Methods: `start(seconds?)`, `stop()`, `isRunning()`, `timeLeft()`.
To draw one inside your own UI, call `require("MatchFlow.countdowns").render(style, secondsLeft, { w = 420, h = 320 })`, which returns a widget node.
## Screens
| Screen | Choices | Looks |
|---|---|---|
| Results (`resultsScreen`) | `podium` (top three on steps, then the rest), `table` (full standings with places, score and rounds won), `banner` (one big winner card), `recap` (round-by-round grid with each round's winner) | `minimal`, `scifi`, `cartoon` |
| In-round HUD (`hudLayout`) | the seven layouts above | `minimal`, `scifi`, `cartoon` |
| Lobby / break panel | "Waiting for players 1 / 2" with player chips, "Starting in 5", "Next round in 5" | `minimal`, `scifi`, `cartoon` |
All of them are plain functions over data (`results.render(kind, look, data)`, `hud.render`, `lobby.render`), so you can draw them yourself with `showUi = false`.
### Small screens
- **Every panel sizes itself from the screen.** MatchFlow reads the safe area (the part no notch or system bar covers) each frame through `require("MatchFlow.theme").viewport()`, which returns `{ w, h, narrow, short }` in UI points. `narrow` is a phone held upright (under 640 wide), `short` is one held sideways (under 480 tall).
- **Phones get compact layouts, not smaller text.** Each HUD layout has its own phone arrangement. The podium lists 4th place onwards under the steps, the standings table folds its detail column into each row, the banner stacks the runners-up, and the round-by-round recap turns on its side. Pass `narrow = true` or `false` in the opts of `results.render` and `hud.render` to choose for yourself.
- **Checked** in the engine at a 412 × 892 pt phone, a 248 pt sliver and a 1280 × 702 desktop; a test renders every screen and every HUD layout at phone and desktop sizes. It has not been run on a real phone, and this release has not been checked in a web browser.
- **Touch buttons stay uncovered.** On a touch screen every HUD layout reads where the on-screen buttons sit (the engine's touch overlay, including its Menu button, and buttons kits such as controlsKit draw themselves) and moves any top panel a button would cover down below the buttons. Pass `touch = false` to `hud.render` to turn it off.
- **Fonts** are engine-bundled families (Anton, Archivo Black, Arimo, Bricolage Grotesque, Comic Neue, EB Garamond, JetBrains Mono).
- **Sound** in a browser plays once the page has had a click or tap: browsers keep audio locked until then.
- **Drawing your own panels?** The UI reads a plain number strictly between 0 and 1 in `width`, `height`, `left`, `top` (and their min/max/right/bottom/flexBasis cousins) as a fraction of the parent. Wrap your tree in `require("MatchFlow.theme").solid(node)`, as every kit panel does, to snap those to whole points.
## Methods
| Method | |
|---|---|
| `addScore(who?, amount?)`, `setScore(who?, value)` | add to or set a player's score |
| `knockOut(who?)`, `finish(who?)`, `setOnHill(who?, on)` | knockouts, race finishes, hill presence |
| `setStatus(who?, text)` | what happened to a player this round, in a few words ("Caught by the storm", "Fell"): shown beside them in the standings and results instead of Racing/Out, until the next round starts |
| `clearWave()`, `callWave()`, `waveInfo()`, `endTurn(who?)` | waves (cleared, called early, the break as shown) and turns |
| `endRound(outcome?)` | end the round now, e.g. `"defeat"` when a waves game's base falls |
| `addPlayer(id, name)`, `removePlayer(id)` | add bots or hand-picked players (any id that is not a peer id) |
| `setHold(on, text?)`, `isHeld()` | hold the match in the waiting room (a ready check) or let it go, from any machine |
| `start()`, `reset()` | start now regardless of head-count; throw the match away and wait again |
| `getState()`, `getStandings()`, `getPhase()`, `timeLeft()` | read the match as it is on screen (see How multiplayer works) |
| `hillInfo()` | the hill as shown: phase, elapsed, holder, holderName, contested, count, target; cheap enough for every frame |
| `syncInfo()` | clock offset, round trip, display delay and grace on this machine, for checking a multiplayer setup |
| `isAuthority()`, `localPlayer()` | whether this machine is in charge; the local player's id |
Events: `onStateChanged{phase, previous}` (also as `onState`), `onCountdown{n}` (3, 2, 1, then 0 = GO), `onRoundEnded{round, winner, winnerName, outcome}` (also as `onRoundEnd`), `onMatchEnded{winner, winnerName, outcome}`, `onTurn{player, name}`, `onWave{wave}`, `onWaveBreak{wave, seconds}`, `onWaveStarted{wave, early, left}`. Events fire on every machine. `outcome` is one of `time`, `target`, `lastStanding`, `allFinished`, `victory`, `defeat`, `turns` or `empty`.
The front door, `require("MatchFlow.api")`: call it (`MatchFlow { ... }`) or `start(opts)` to spawn or update the match, `find(name?)` for the MatchFlow component on the entity named `Match`, `component("MatchFlow" | "Countdown" | "Hill")` for the component types wherever the package is installed, `catalog`, and `VERSION`.
## How multiplayer works
- **One machine is in charge:** the owner of the synced `Match` entity, normally whoever created it. Only it runs the rules. It keeps a match clock and publishes the whole match (phase, clock, players, scores, history) in a synced snapshot stamped with that clock. It publishes whenever something changes, and at least four times a second.
- **Every screen shows the same moment.** Each machine matches its clock to the match clock by pinging the machine in charge; the quickest of the last eight round trips sets it. It keeps the last few snapshots and shows the match as it stood a short **display delay** ago. The machine in charge shows it that way too. Every snapshot has landed before its moment comes up, so the countdown numbers, the timer, the round end and the results change on every screen at the same instant.
- **The display delay** is long enough for the slowest player's snapshots to have landed: the worst lateness other machines measured in the last 20 s plus 0.05 s, or half the slowest round trip plus 0.1 s if that is longer, kept between 0.15 and 0.6 s. On a live two-machine test with a 60 to 70 ms round trip it sat at 0.18 to 0.21 s. When it changes, the new value is published half a second ahead and slides in the same way on every machine.
- **Reads trail by the same delay.** `getState()`, `getStandings()`, `getPhase()`, `timeLeft()`, `hillInfo()` and every event describe the match as it is on screen.
- **The 0:00 hold.** A timed round stays open for a short grace after 0:00 (about 0.2 to 0.3 s) so reports made just before it still count. The timer sits at 0:00 on every screen for that moment, then the results appear everywhere at once.
- **Reports** (`addScore` and the rest) are sent to the machine in charge, stamped with the time on the reporter's screen. A score, knockout, finish or cleared wave counts if it was made on screen after GO and before 0:00. Calling a report on every machine for the same event would count it more than once, so report each event from one place, typically the authority as OrbRush does. A Hill zone reports from the machine in charge only.
- **Players** are the peers in the room the `Match` entity lives in. Someone who joins mid-round sees "Watching · you join next round" and plays from the next round. Someone who leaves mid-round is counted out of that round, and drops off the board when the match ends.
- **Checking a setup:** `m:syncInfo()` returns whether this machine is in charge, its clock offset and round trip, the display delay and grace, the newest snapshot's age, and the player count.
### If the host quits mid-round
The match carries on for everyone else, on the same clock and with the same scores. Nothing restarts. It is not instant: expect a pause of about 10 seconds first (see Known limits, #9546). And in some cases the match can disappear for a player who stays instead of carrying on (see Known limits, #19490).
1. **The wait.** When the host's game closes, the engine takes about 10 seconds to notice the player has left. Until it does, the relay still counts the host as the `Match` entity's owner, and no other machine may take the match over. For that time the match does not move on: the round does not end, phase changes wait and nothing new is counted. Every machine keeps the last snapshot the host published, at most a quarter of a second old.
2. **The takeover.** Once the engine reports the host gone, the relay hands the `Match` entity to a player who stays, and that machine takes charge at once. It continues from the host's last snapshot on the same match clock, with the same phase, round and scores. It does not wait on the quit host's last snapshot. If the relay does not hand the entity on, the remaining player with the lowest peer id claims it about half a second after the host drops off the room, and anyone else after 4 s.
3. **After it.** The other machines keep the clock they already matched and start pinging the new machine. The player who quit is counted out of the round. A phase change that fell due in the gap (the clock reaching zero, say) happens on every screen at once. A report made between the host quitting and the takeover is lost. A Hill zone re-reports who is on it from the new machine within a second, so hold time keeps counting.
Tested on two real machines with 1.1.0: the machine running the match was quit in the middle of a round. The other machine took over about 10 seconds later; the clock carried on, the scores were kept and the round ended normally. The tests also check the handover from the host's last snapshot: the new machine's clock matches what the other screens showed, scores carry over, a long gap is carried over whole, and the round ends on the same clock.
If everyone leaves, the round ends with outcome `empty`, and the match waits for players again.
## Using it offline or in single-player
With nobody else connected, the local machine is in charge. Set `minPlayers = 1` to play solo, or add bots with `m:addPlayer(1001, "Bot")` and drive their scores yourself.
## What's inside
| Asset | Role |
|---|---|
| `MatchFlow.component` | the match: the rules, sync, events, UI |
| `Hill.component` | the king-of-the-hill zone, five looks, optionally moving |
| `Countdown.component` | standalone countdown |
| `api.module` | the front door: `MatchFlow { ... }`, `find`, `component`, `catalog`, `VERSION` |
| `catalog.module` | every style with its tags |
| `rules.module` | pure state machine for all eight formats (no engine calls, unit tested) |
| `timeline.module` | the shared clock, display delay and host handover (pure, tested with simulated latency) |
| `hill.module` | the hill's pure maths: who is inside, which spot, which state |
| `countdowns.module` | the ten countdown styles as widget-tree renderers |
| `results.module`, `hud.module`, `lobby.module` | the screens and HUD layouts |
| `theme.module` | the minimal, sci-fi and cartoon design tokens and helpers, `viewport()` and `solid()` |
| `view.module` | turns match state into the data each screen draws |
| `audio.module` + `sounds/` | 20 short tick and GO clips, two for each of the ten sound sets |
| `matchflow.testSuite` | the tests (see below) |
| `guides/` | the how-to guide and the best-of-three example guide (see Guides) |
Run the tests with `tools.use("tests", "run", { suite = "matchflow" })` in edit mode. They cover every format, the roster rules, every renderer and HUD layout at desktop and phone sizes, the sound sets, two simulated machines over a jittery network, the host handover, the hill's maths, every first name, the catalog and its tags, and this README's version.
## Known limits
Only open issues are listed here, each by its number: engine issues as `#number`, ZeroMind issues as `ZeroMind#number`.
- **When the host stops mid-round, the match can disappear for a player who stays (#19490).** Sometimes, not every time (it happened in one of two live tries), the match a scene builds, as the first example builds it, vanishes on the remaining player's machine when the host stops in the middle of a round. That player then has no match: no timer, no scoreboard and no results, and the round does not carry on for them. MatchFlow cannot keep the match alive when the engine removes it.
- **When the host quits, the match waits about 10 seconds before another machine takes over (#9546).** The engine takes that long to notice that a player whose game closed has left, and until it does no other machine may take the match over. Nothing moves on during the wait; then the takeover carries on with the same clock and scores (see "If the host quits mid-round"). A host who only leaves play, without closing the game, was noticed within about a second in the 1.0.0 live test.
- **Two players can't be tested inside one engine (#18688, #19114).** The suite tests multiplayer through simulated machines; two-machine behaviour was last checked by hand on two real machines for 1.1.0.
- **The guides inside this package don't show up in ZeroMind search yet (ZeroMind#3099).** A ZeroMind search worded like a guide's title (for example "how to add a pause menu to my game" for menusKit's guide) finds the package, not the guide inside it. Once MatchFlow is installed, the `guides` tool and the Docs panel find them; see Guides.
- **A guide does not open by its short name (#22286).** In the Docs panel, `how-to-add-rounds-a-countdown-and-a-scoreboard-to-my-game` alone opens nothing. Use the full name, `MatchFlow.guides.<name>`, there, and the path, `MatchFlow.package/guides/<name>`, with the `guides` tool. The guides link to each other by path.
## Changelog
### 1.4.3
- Both guides open by naming the package and the version they describe (1.4.3), with its ZeroMind install line. Behaviour is unchanged.
### 1.4.2
- **A race that ends with runners still out says so, and why.** Once a race round is over (results, intermission) an unfinished runner reads `Did not finish` and `DNF` instead of `Racing` and `-`. New `match:setStatus(who, text)` puts a game's own words beside a player (up to 40 characters, any machine, any phase; cleared when the next round starts): Skyhook marks runners the storm swallowed the finish ahead of as "Caught by the storm". Rows from `getStandings()` carry `status`. Found by Skyhook, where a runner still flying looked like they were "Racing" on the results table.
- One new test (96).
### 1.4.1
- **A player who leaves and rejoins resumes their own row.** A rejoin arrives with a new peer id, so a race used to show that player twice: the old row as Left/DNF and a new empty one. Now a player added under the name of a row that left (not a bot) takes that row over: the id moves to the new one, score, finish and time stay, `left` clears, and whether they play on at once follows `joinInProgress` as for any late joiner. Found by Skyhook.
- **The HUD keeps clear of on-screen touch buttons.** On a touch screen at tablet or desktop size the engine's touch Menu button and controlsKit's corner Controls button sat on top of the classic layout's scoreboard. Every HUD layout now reads `Zin.touchControls.layout()` (safely; nothing changes where it can't be read or the overlay is off screen) and moves any top panel a button covers down below the buttons, with whatever is stacked under it. `hud.render` takes `touch = false` to turn it off, or a list of `{ x, y, r }` circles of your own.
- Six new tests (95).
### 1.4.0
- **Waves with breaks**, asked for by towerDefenseKit: `waveBreakSeconds` and `firstBreakSeconds` put a counted-down break (build time) before each wave, `callWave()` cuts it short (`onWaveStarted` says it was early and how many seconds were left, for a bonus), `waveInfo()` reads the break as shown, and `onWaveBreak` / `onWaveStarted` fire on every machine. The HUD's wave line shows "Wave 3 of 10 in 12s" during a break.
- **`endRound(outcome)`**: end the round now, so a waves game loses when its base falls without knocking every player out.
- **Endless waves**: `waves = 0` never wins by count (it was raised to 1 before).
- **`joinInProgress`**: a late joiner plays at once in a co-op match instead of watching until the next round.
- **`showResults = false`** hides only the results screen, for a game with its own end screens.
- Eight new tests (89). Without the new fields every format behaves exactly as in 1.3.2.
### 1.3.2
- Its tests find the package's own files wherever it is installed (at /source, or under /source/deps when another package installs it). In a world where platformer3dKit installed it, 10 of its tests failed because they read README.md, package.yaml and source files from a fixed /source/MatchFlow.package path.
### 1.3.1
- `MatchFlow.component("MatchFlow")` looks the component up by `~MatchFlow.MatchFlow` first again, as 1.2.1 did, so MatchFlow is found wherever it was installed, including as another kit's dependency. The merge that brought 1.3.0 had turned that first lookup into a second copy of the bare-name one.
### 1.3.0
- **Hold the match for a ready check.** New `hold` and `holdText` fields and `setHold(on, text?)` / `isHeld()` methods: while held no match starts, a lobby countdown stops and goes back to waiting, and a finished match waits at its break instead of starting the next. A round being played is never interrupted. Asked for by lobbyKit's ready check.
- **`showLobby = false`** hides only the waiting, lobby countdown and next-round panel, so another kit can draw the lobby while MatchFlow's HUD, countdown and results still show.
- **`showHud = false`** hides only the in-round HUD, so another kit can draw the scoreboard (lobbyKit's team scoreboards) while the 3-2-1-GO countdown and the results still show.
- Five new tests for the hold (81 tests).
### 1.2.1
- **No long dashes left in any file of the kit, code included.** A comment in `Countdown.component` now uses a colon. The placeholder the HUD and results screens draw for an empty score, an empty versus side or a missing round value is now a plain hyphen (`-`). A new test fails if a long dash ever comes back into any text file of the package (76 tests).
- **The store listing names the two guides.** The world's description and page text now say the kit ships with the how-to guide and the best-of-three example guide, and what each one teaches (see Guides).
### 1.2.0
- **Two guides ship in the package**, in `guides/`: *How to add rounds, a countdown and a scoreboard to my game* (the how-to: starting a match, every format's win condition, scoring and teams, the hill zone, HUD layouts, countdown and results styles, what players see when the host leaves) and *A best-of-three arena match with a countdown, live scores and a results screen* (an example from a brand-new world, using menusKit for the end screens and barsKit for score bars). They link to each other, and the README's new Guides section points to both. The example was followed from start to finish in a fresh world.
- **Checked on today's engine**: MatchFlow installed alone in a brand-new world runs the first example as written (lobby, countdown, round, podium, break, next round, and editing 30 to 45 takes effect), and the tests pass. No code changes.
- **Known limits**: the bare-name lookup for a copy that came as another kit's dependency (#19199) is fixed in the engine and comes out; added that package guides don't show up in ZeroMind search yet (ZeroMind#3099) and that a guide doesn't open by its short name (#22286).
### 1.1.0
- **Hill zone** (`Hill` component): drop it in a level and king of the hill counts hold time on its own. Five looks (`glowRing`, `flagPlatform`, `scifiPad`, `runeCircle`, `outline`), idle / held / contested states, and an optional hill that moves between spots during a round.
- **Seven HUD layouts** behind `hudLayout`: `classic`, `cornerTimer`, `scoreBug`, `versusBar`, `timerStrip`, `rankedSidebar`, `holdMeter`, each in all three looks and on a phone. `classic` is unchanged and still the default.
- **Tags on every style** and `MatchFlow.catalog` to list and filter them.
- **The names first asked for work**: `seconds`, `scoreLimit`, `bestOfRounds`, `lastOneStanding`, `raceToFinish`, `surviveWaves`, `bigDigits`, `scifiHologram`, `cartoonPop`, `winnerBanner`, `roundRecap`, `onState`, `onRoundEnd`. Nothing was renamed.
- **The front door**: `MatchFlow { format = "timed", seconds = 30 }` from `require("MatchFlow.api")`. Inside a scene's `content()` it always makes the match itself, so editing the numbers and saving rebuilds the scene and updates the match on every machine and on a fresh load. (Before this fix, a second build found the match the first build had saved and tried to change it, which the engine refuses: the rebuild failed, and on a machine loading the world everything the build placed after the match, such as a Hill, was missing.)
- **Known limits** now names the ~10 second wait before another machine takes over when the host's game is closed (#9546), and that the match can disappear for a player who stays when the host stops mid-round (#19490).
- **Host quitting mid-round**: the machine the match is handed to no longer defers to the quit host's last snapshot, and a gap of any length is carried over (it was capped at 5 s, which could pull the clock back on every screen).
- **Gallery**: the world opens on it, one page with no tabs, readable from the spawn. Each of the ten countdowns stands beside a results screen, a live card shows the five hill looks with each one labelled under its hill, and the seven HUD layouts sit in one row. "Walk around" puts you next to a live hill to step into. Orb Rush is the second scene.
- **matchFlowKit** is named in this README as this package; the package keeps its name, MatchFlow.
### 1.0.0
- First release: one component for lobby, countdown, round, results and break; eight formats; ten countdowns with sounds; four results screens; HUD and lobby in three looks; shared match clock and host migration.