MatchFlow 1.1.0

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.

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.

Formats

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.

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

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.

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

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.

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.

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

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

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}. 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–70 ms round trip it sat at 0.18–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–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

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 engine issues with an open GitHub issue are listed here, each by its number. All five were open on 2026-10-18.

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

• A kit that arrived as another kit's dependency is not found by its bare name (#19199). When MatchFlow came with another kit it sits under /source/deps/, and require("MatchFlow.api") or component.add("MatchFlow", ...) answer "not found" from your own scripts. Use require("~MatchFlow.api") and MatchFlow.component("MatchFlow").

• 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 with two real editors for 1.0.0.

Changelog

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.