Log inGet started
World

Match Flow Kit: Countdowns, Rounds and Results

README.md

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:

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:

    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:

    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:

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.

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:

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

formatRound ends whenWinnerFields it reads
timedthe clock runs outhighest scoreroundSeconds
firstToScoresomeone reaches the target (or time runs out)first to targetScoretargetScore, roundSeconds
bestOfas firstToScore, per roundmost round wins over up to rounds rounds; a majority ends it earlyrounds, targetScore, roundSeconds
lastStandingone player (or none) is leftthe survivor; earlier knockouts place lowerroundSeconds (0 = no limit)
kingOfTheHillsomeone holds the hill alone for targetScore secondslongest uncontested holdtargetScore, roundSeconds
raceeveryone has finished (or time runs out)finish orderroundSeconds
waveswaves waves cleared (victory), or everyone down, endRound("defeat") or out of time (defeat)the team; the top scorer is shown as MVPwaves, roundSeconds, waveBreakSeconds, firstBreakSeconds
turnBasedevery player has had turns turnshighest scoreturnSeconds, 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 nameCurrent 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 / onRoundEndonStateChanged / 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.

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

hill.component.add(MatchFlow.component("Hill"), { look = "glowRing", spots = "10,0; -10,0; 0,10", moveEvery = 20 })
Look (look)What it is
glowRinga glowing ring on the floor with a soft light column
flagPlatforma low platform with a flag that takes the hill's state colour
scifiPada tech pad with segmented light strips and a holo column
runeCirclea fantasy stone circle of glowing runes
outlinea 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.

hudLayoutWhat it is
classic (default)timer at the top centre with the format line, live scoreboard at the side
cornerTimera compact timer in a corner with your place and score
scoreBuga sports-TV score bug with a LIVE dot
versusBaryou against the best other player across the top, with a tug bar
timerStripa thin timer-only strip, nothing else
rankedSidebarevery player ranked down the side, with gaps to the leader
holdMeterking 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

FieldDefaultWhat it does
format"timed"one of the eight formats above (or a first name)
roundSeconds30round length (0 = no limit; timed treats 0 as 60)
seconds0the round length under its first name; above 0 it wins
targetScore10score to win firstToScore/bestOf, seconds to hold in kingOfTheHill
rounds3maximum rounds in bestOf
waves5waves to clear in waves (0 = endless)
waveBreakSeconds0waves: a break of this many seconds before each wave after the first, cut short by callWave(); 0 = no breaks
firstBreakSeconds-1waves: the break before wave 1; -1 = the same as waveBreakSeconds
joinInProgressfalsesomeone who joins mid-round plays at once (co-op) instead of watching until the next round
turnSeconds / turns10 / 3turn length and turns per player in turnBased
minPlayers2players needed before the lobby counts down
lobbySeconds5lobby countdown once enough players are in
countdownSeconds3the 3-2-1-GO before each round (0 skips it)
resultsSeconds7how long results stay up
breakSeconds5break before the next round
autoStarttruestart by itself at minPlayers; when false, call m:start()
holdfalsewhile 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
showLobbytruefalse hides only the waiting / lobby countdown / next-round panel, for a kit that draws its own lobby; the HUD, countdown and results still show
showHudtruefalse 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
showResultstruefalse hides only the results screen, for a game that draws its own end screen; the lobby, HUD and countdown still show
includePeerstrueeveryone 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
showUitruefalse draws nothing, so you can build your own UI from getState()
sounds / volumetrue / 0.8the 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.

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.

Kindid: tags
formattimed: 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
countdownbold: 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
resultspodium: party, sports, arena · table: minimal, arena, racing, competitive · banner: party, sports, cartoon · recap: sports, arena, competitive
hudLayoutclassic: 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
hillLookglowRing: scifi, arena, arcade · flagPlatform: sports, party, cartoon · scifiPad: scifi, arena · runeCircle: fantasy · outline: minimal
lookminimal: 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.

countdownStyleLookSound
boldbig bold slam-in numbers with a glow streakpunch
trafficLightred → amber → green racing lightsrace beeps
pixel8-bit block digits on a CRT panelchiptune
hologramcyan sci-fi ring, scanlines, "ENGAGE"sci-fi sweep
cartoonbouncy number on a starburst, "GO!"toy boing
minimalthin progress ring, clean typesoft tone
fantasygolden runic circle, "BEGIN"bell
flipClocksplit-flap cards that flip each secondmechanical click
neonbuzzing neon tube signsynth
broadcastsports-TV lower-third with a LIVE tagstadium 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.

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

ScreenChoicesLooks
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 aboveminimal, 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

AssetRole
MatchFlow.componentthe match: the rules, sync, events, UI
Hill.componentthe king-of-the-hill zone, five looks, optionally moving
Countdown.componentstandalone countdown
api.modulethe front door: MatchFlow { ... }, find, component, catalog, VERSION
catalog.moduleevery style with its tags
rules.modulepure state machine for all eight formats (no engine calls, unit tested)
timeline.modulethe shared clock, display delay and host handover (pure, tested with simulated latency)
hill.modulethe hill's pure maths: who is inside, which spot, which state
countdowns.modulethe ten countdown styles as widget-tree renderers
results.module, hud.module, lobby.modulethe screens and HUD layouts
theme.modulethe minimal, sci-fi and cartoon design tokens and helpers, viewport() and solid()
view.moduleturns 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.testSuitethe 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.