# hud The in-play readout, in seven layouts and three looks (`minimal`, `scifi`, `cartoon`). Every layout draws the same match from the same data, honours the last-five-seconds pulse (`urgent`), the clock label, the format/info line, players who are out or left (dimmed), long names (trimmed to fit), and 0, 1 or 8+ players. Each has a real phone layout (`narrow`) that fits a 248 pt sliver. MatchFlow calls it during the countdown and play with `layout = hudLayout`. ```lua local Hud = require("MatchFlow.hud") local node = Hud.render(look, data, { w = 1280, h = 702, k = 1, t = os.clock(), narrow = false, layout = "versusBar" }) ``` `opts`: `w`, `h` (the canvas in points, default 1280x702), `k` (scale, default fits 1280x702), `t` (a clock in seconds for pulses and blinks), `narrow` (a phone held upright; default `w < 640`), `layout` (default and fallback for unknown ids: `classic`), `id`, `position`/`left`/`top` for the root. Classic only: `board = false` hides the scoreboard. The node is run through `T.solid`, so no size ends up read as a fraction of its parent. ## Layouts (`Hud.LAYOUTS`, in order) | id | label | what it shows | | --- | --- | --- | | `classic` | Top Timer + Scoreboard | Timer at the top centre with the format chip under it, standings top right. On a phone the board moves under the timer and keeps four rows, always including you. Exactly the original HUD. | | `cornerTimer` | Corner Timer | Compact timer top left, the clock label and info beside it, a progress line, and your own place and score (or the leader's when you are watching). | | `scoreBug` | TV Score Bug | Broadcast bar top left: blinking LIVE, three-letter tags and scores of the leaders (you always included, highlighted), the clock cell (red when urgent), and a strip with the format and round pips for best-of matches. Shows as many players as fit. | | `versusBar` | Versus Bar | You (or the leader when you are not playing) on the left against the best other player on the right, scores facing each other, the clock between them, a tug bar of the score share and the format chip. One player shows "No rival yet", none "No players". | | `timerStrip` | Timer Strip | Only the clock: a thin strip across the top with the format left, info right, a progress line along its edge and the clock in a tab hanging from the middle. No scoreboard. | | `rankedSidebar` | Ranked Sidebar | Clock panel and a full ranked list down the right side: medals for 1st-3rd, avatars, gap to the leader ("-3 pts", "+1.20" in a race), out/left players struck through, your row lit. When rows run out of room the list keeps the top and you, with "+N more". | | `holdMeter` | Hold Meter | King of the hill: who holds the hill (crown), a meter per player filling toward the hold target with a dot on whoever is on the hill, a pulsing CONTESTED state, and the clock. Without `data.hold` it draws each score toward `data.target`, or against the leader's score when there is no target. | `Hud.layoutId(id)` returns the id when it is one of these, else nil. `Hud.sample(layout, t?)` returns realistic data for a gallery: five players (you second, one with a long name, one who left), a best-of match, and for `holdMeter` a king-of-the-hill match with its hold table. With `t` the clock runs down a 90 s round, scores grow, and the hill changes hands every 4 s (Nova holds, contested, Rook holds). ## Data (`MatchFlow.view.hud(...)`) | field | meaning | | --- | --- | | `clock`, `clockFrac`, `clockLabel`, `urgent` | "0:24", 0..1 of the round left, "Time left"/"Elapsed"/"Turn", true in the last seconds. No `clock` hides the timer. | | `format`, `formatId`, `info`, `valueLabel` | "King Of The Hill", "kingOfTheHill", "Round 2 of 3", "PTS"/"SEC"/"KOs"/"TIME". | | `rows` | Best first: `{ id, place, name, value, detail, isLocal, out }`. `value` may be a string (race times, "DNF"). | | `round`, `rounds`, `target` | Current round; rounds in a best-of; target score (firstToScore, bestOf, kingOfTheHill). | | `hold` | King of the hill only: `{ target, holderId, holderName, contested, count, rows = { { id, name, place, value, frac, isLocal, holding, out } } }`. | Any field may be missing.

# audio Plays a countdown style's tick (3, 2, 1) and GO sounds from the ten sound sets in `sounds/`: punch, race, chip, scifi, toy, soft, bell, click, synth and horn. `play(styleId, "tick" | "go", volume?, n?)` plays through one Audio source on the active camera, created on first use. `n` is the number the tick belongs to: `pitchFor(kind, n)` raises 2 and 1 a step each, so the count sounds more urgent near GO. `clip(kind, set)` returns the soundClip. MatchFlow, Countdown and the gallery call it.

# api MatchFlow's front door. `local MatchFlow = require("MatchFlow.api")`, then `MatchFlow { format = "timed", seconds = 30 }` inside a scene's `content()` spawns the synced `Match` entity with a MatchFlow component and returns the component. A scene that already has a match by that name has its fields updated instead. | Call | Does | |---|---| | `MatchFlow { ...fields, name? }` / `MatchFlow.start(opts)` | the match, as above | | `MatchFlow.find(name?)` | the MatchFlow component on the entity named `name` (default `Match`), or nil | | `MatchFlow.component(short)` | `MatchFlow`, `Countdown` or `Hill` as a component type, wherever the package is installed | | `MatchFlow.catalog` | the tagged style catalog (`MatchFlow.catalog` module) | | `MatchFlow.VERSION` | `"1.1.0"` |

# rules The match state machine for all eight formats, as pure Luau with no engine calls. MatchFlow runs it on the machine in charge, and the test suite drives it directly. - `config(t)` fills defaults and clamps; `newState()` returns an empty match. - `step(state, cfg, dt)` moves through waiting → lobby → countdown → playing → results → intermission and returns events (`phase`, `roundEnd`, `matchEnd`, `turn`, `wave`). - Reports: `score`, `setScore`, `knockOut`, `finish`, `clearWave`, `endTurn` and `setOnHill`. Roster: `addPlayer` and `removePlayer`. Control: `forceStart` and `reset`. - `standings(state, cfg)` returns rows ordered by the format's ranking, with shared places for ties. - `advanceClock` moves only the clock, for machines between snapshots. `formatClock(seconds)` gives `m:ss`. - `cfg.grace` (default 0) keeps a timed round open that many seconds after 0:00. `inPlayAt(state, at)` says whether a report made `at` seconds into the round falls between GO and 0:00. `finish(state, cfg, id, at?)` records the finish time as `at` when it is given. MatchFlow uses all three to judge reports by the time on the reporter's screen. Use it directly to run a match in your own component, or to simulate one in a test.

# hill The pure rules behind the `Hill` zone (king of the hill), with no engine calls, so they can be unit tested. `Hill.component` calls them every frame. A game or a test can use them directly. - `LOOKS`: the five looks in gallery order, each `{ id, label, description }` (`glowRing`, `flagPlatform`, `scifiPad`, `runeCircle`, `outline`). `lookId(id)` returns the canonical id, or nil. It ignores case and accepts a label, so `"Sci-Fi Pad"` gives `"scifiPad"`. - `parseSpots(str)` reads `"x,z; x,y,z; EntityName"` into `{ {x, z, y?, name?} }`. These are the extra spots: spot 1 is always the hill's own place. - `inside(px,py,pz, cx,cy,cz, radius, height)` tests the capture cylinder: within `radius` across the floor, from 0.5 below the centre up to `height` above it. - `spotIndex(info, moveEvery, nSpots)` gives the 1-based spot from `match:hillInfo()`. While playing it is `floor(elapsed / moveEvery) % nSpots + 1`; otherwise it is 1. `untilMove(...)` gives the seconds to the next move, or `math.huge`. - `stateOf(info, localInsideIds)` returns `"idle" | "held" | "contested"` and the holder (0 for none). It uses the match while a kingOfTheHill round is playing, and the local ids otherwise. - `COLORS`, `stateColor(state, mine, t, idle?)` (contested pulses red to orange), `flash(left, warnSeconds, t)` (the blink before a move, getting faster) and `parseColor("#rrggbb")`.

# theme The three looks every MatchFlow screen comes in (`minimal`, `scifi` and `cartoon`) as design tokens: colours, fonts, panels, medals and avatar colours. It also holds the small widget helpers the screen modules share (`label`, `box`, `row`, `abs`, `svg`, `text`, `panel`, `ease`). The results, HUD and lobby modules call it; to add a look, add a token set here. - `viewport()` returns `{ w, h, narrow, short }`: the safe area in UI points, with `narrow` for a phone held upright (under 640 wide) and `short` for one held sideways (under 480 tall). - `solid(node)` snaps every size or position strictly between -1 and 1 to whole points, because the UI reads such a number as a fraction of the parent. Every kit panel's render runs it; run it on your own panels too.

# view Turns a match state (from `MatchFlow.rules`) into the plain data each screen draws: `hud(state, cfg, localId)`, `lobby(...)` and `results(...)`. `formatSummary(cfg)` gives text such as "Timed round · 30s". `sample()` returns the fixed standings the gallery and tests render. Keeping this out of the renderers means a game with `showUi = false` can still use these tables for its own UI.

# lobby The "Waiting for players 1 / 2", "Starting in 5" and "Next round in 5" panel, with a countdown ring, player chips and the match format, in `minimal`, `scifi` and `cartoon`. `render(look, data, { w, h, k, t })`; `data.mode` is `waiting`, `lobby` or `intermission`, and is built by `MatchFlow.view.lobby(...)`. The title shrinks only as far as it must to fit `w`, so the panel works down to a phone's width. MatchFlow shows it in every phase outside the round.

# catalog Every MatchFlow style, tagged, so a game can list or filter them: the 8 formats, 10 countdowns, 4 results screens, 7 HUD layouts, 5 hill looks and 3 looks. ```lua local Catalog = 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.get("results", "winnerBanner").id -- "banner": older names resolve Catalog.tags() -- every tag in use, sorted ``` `filter` takes `kind`, `tag` (one tag), `tags` (all of them) and `anyTag` (at least one). Every tag comes from `Catalog.VOCABULARY`: retro, scifi, sports, fantasy, cartoon, minimal, party, arena, racing, arcade, broadcast, competitive, coop, casual, strategy, versus, team. `field` names where the id goes (`MatchFlow.countdownStyle`, `Hill.look`, ...). Results return copies.

# countdowns The ten countdown styles as widget-tree renderers: `bold`, `trafficLight`, `pixel`, `hologram`, `cartoon`, `minimal`, `fantasy`, `flipClock`, `neon` and `broadcast`. MatchFlow, the Countdown component and the style gallery all call it. - `render(styleId, secondsLeft, { w, h, goText, caption })` returns a node for that moment, animated from the fractional seconds. A negative `secondsLeft` is the time since GO. It returns nil once GO has finished showing. - `STYLES` lists `{ id, label, sound }`; `byId` indexes it. `frame(secondsLeft)` returns `(number, progress, isGo)`. Every element is sized from `w` and `h` (default 420×320), so a style can be drawn as a small tile or full screen.

# timeline What keeps every machine's screen on the same moment of the match, as pure Luau with no engine calls. MatchFlow uses it on every machine, the one in charge included, and the test suite drives it with simulated latency. - `newClock()` / `ownClock()`, `addSample(clock, t0, theirs, t1)`, `guess` and `slew` match this machine's clock to the match clock of the machine in charge from ping round trips. The quickest recent trip sets the offset, and the first one replaces the initial guess outright. Later corrections run the shown clock at most 5% fast or slow (`SLEW_RATE`), so it never jumps. `clock.rttMax`, the slowest recent trip, is what a machine reports so that the delay can be sized. - `delayFor(rtts, lates?)` picks how far every screen trails the machine in charge: the worst snapshot lateness any player reports plus 0.05 s (`LATE_MARGIN`), or half the slowest round trip plus 0.1 s (`MARGIN`: one sync tick, a frame either side and a little clock error) if that is longer, from 0.15 to 0.6 s. `graceFor(delay, rtts)` gives how long a timed round stays open after 0:00, so late-arriving reports made before the end still count. - `newLate()`, `noteLate(track, late, now)` and `lateOf(track, now)` keep how late snapshots reach this machine, worst of the last `LATE_WINDOW` (20) seconds. A follower reports it with each ping. - `delayAt(ramp, now)` and `retarget(ramp, to, now)` handle a published delay `{ from, to, at }`. A new delay starts `RAMP_LEAD` (0.5 s) after it is published and slides at `RAMP_RATE` (0.2 s per second), so every machine's delay moves at the same instant and rate. A plain number is read as a fixed delay. - `new()`, `push(tl, snapshot)` and `pick(tl, t)` hold the recent snapshots and pick the one standing at a shared time. A snapshot carries `ev`, how far into its phase the latest change was made, so one that arrives a sync tick late is still shown from the moment of its change. - `show(view, snapshot, t)` turns a snapshot into the state to draw at time `t`. The clocks run on from the snapshot, and the clock never runs backwards within a phase. - `decode(snap)` reads a snapshot off the synced property, keeping a published delay ramp as a ramp; nil for anything that is not a snapshot. - `newRival()`, `noteRival(r, snap, me, now)` and `rivalOf(r, now, present)` catch a machine whose engine wrongly says it owns the match (one coming back into play can): fresh snapshots from another machine that is still present mean that machine is really in charge, for `RIVAL_HOLD` (1.5 s) after the last one.

# results The end-of-round screens. Each of the four kinds comes in all three looks: - `podium`: the top three on steps, with the rest listed below. - `table`: full standings with place, score and rounds won. - `banner`: one big winner card. - `recap`: a round-by-round grid with each round's winner. `render(kind, look, data, { w, h, t, narrow })` returns a node. `t` is the seconds since the screen opened, which drives the entrance animation. `narrow` picks the portrait phone layout (4th place on listed under the podium, detail folded into each table row, runners-up stacked under the banner, the recap turned to a row per player); it defaults to on when the panel is taller than it is wide. `data` comes from `MatchFlow.view.results(...)`, or `view.sample()` for previews. MatchFlow and the style gallery call it.

# 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`: ```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. ## 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 or out of time (defeat) | the team; the top scorer is shown as MVP | `waves`, `roundSeconds` | | `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` | | `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()` | | `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. - **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 | | `clearWave()`, `endTurn(who?)` | waves and turns | | `addPlayer(id, name)`, `removePlayer(id)` | add bots or hand-picked players (any id that is not a peer id) | | `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}`. 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 | 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) | 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.

# MatchFlow Runs a whole multiplayer match from one component: the lobby, a 3-2-1-GO countdown, the round with its timer, results, a break, then the next round. Put it on a **synced** entity (`entity.spawnSynced("Match")`); it needs no sibling components. - `format` picks one of eight match types: `timed`, `firstToScore`, `bestOf`, `lastStanding`, `kingOfTheHill`, `race`, `waves`, `turnBased`. Each reads a couple of fields (`roundSeconds`, `targetScore`, `rounds`, `waves`, `turnSeconds`, `turns`). - `countdownStyle`, `resultsScreen`, `resultsLook`, `hudLook` and `lobbyLook` restyle the screens. Set `showUi = false` to draw your own. - The entity's owner is in charge. It runs `MatchFlow.rules` and publishes the match in the synced `snapshot` field. Everyone else follows that snapshot and forwards their reports. If the owner leaves, the lowest remaining peer id takes over from the last snapshot and the match carries on. - Game code reports `addScore`, `setScore`, `knockOut`, `finish`, `clearWave`, `endTurn` and `setOnHill`, and listens to `onStateChanged`, `onCountdown`, `onRoundEnded`, `onMatchEnded`, `onTurn` and `onWave`. ```lua local match = entity.spawnSynced("Match") local m = match.component.add("MatchFlow", { format = "timed", roundSeconds = 30 }) m.events.onRoundEnded:connect(function(e) print(e.winnerName, "wins round", e.round) end) ``` The package README has every format, style, field and the full multiplayer behaviour.

# Hill A king-of-the-hill zone you drop into any level. It lights up idle, held or contested. In a MatchFlow `kingOfTheHill` match it tells the match who is standing on it, so hold time counts with no game code. It can also hop between spots during a round. Put it on any plain entity: its position is the centre of the hill's floor. It needs no sibling components and finds the match by name. ## How it works - **Every machine** checks which players stand inside the capture cylinder: within `radius` of the centre across the floor, and from 0.5 m below the floor up to `height` above it. It draws the hill from that, and fires `onEnter` / `onExit` locally. - **Only the machine in charge of the match** (`match:isAuthority()`) reports `setOnHill(player, true/false)`, and only while the match format is `kingOfTheHill`. It reports each change as it happens. It also re-sends the full list once a second and whenever the phase, round or format changes, and straight away on a machine that has just been put in charge, so a host taking over mid-round gets the truth. - **While a kingOfTheHill round is playing**, the hill shows what `match:hillInfo()` says, since that is the same on every screen. Otherwise it shows what this machine sees. With no match at all it still works, from local detection. - Use **one Hill per match**: when a player leaves a hill, that hill reports them off it. - **Visuals** are temporary, unsynced child entities, rebuilt whenever `look`, `radius`, `height` or `label` changes. They show in edit mode too, and are never written into the scene. There are no colliders, so players walk straight on. The flag platform is 0.14 m high, so feet sink into it slightly. ## Fields | Field | Default | What it does | |---|---|---| | `look` | `glowRing` | `glowRing` (glowing floor ring, soft light column that rises while held), `flagPlatform` (low platform with a lit rim and a flag that climbs while held), `scifiPad` (hex tech pad, light strips, holo pillars, scan rings, floating core), `runeCircle` (standing stones with glowing runes, floor sigil, drifting motes), `outline` (a thin ring only). | | `radius` | 3 | Radius of the hill in metres. | | `height` | 3 | Height of the capture volume in metres. | | `match` | `"Match"` | Name of the entity carrying MatchFlow. Empty: any MatchFlow in the scene. | | `spots` | `""` | Extra spots, separated by `;`: an offset `x,z` (or `x,y,z`) in metres from this entity, or an entity name. The entity's own place is spot 1. | | `moveEvery` | 0 | Seconds between moves during a round (0 = never moves). | | `warnSeconds` | 3 | Before a move the floor lights blink faster and faster and the label counts down `MOVING IN 3`. | | `preview` | `live` | `live` shows and reports the real hill. `idle`, `held` and `contested` pin a state (for screenshots), and `cycle` loops all three (for a style gallery). Anything but `live` never reports. | | `label` | `"HILL"` | Floating word while nobody holds the hill. It changes to the holder's name, `YOU HOLD THE HILL` (on the holder's own screen), `CONTESTED` or `MOVING IN n`. Empty: no floating text. | | `idleColor` | `""` | Idle colour as `#rrggbb`. Empty keeps the cool blue. | Colours: idle is cool blue, held is gold, held by you is green, and contested is red with a red/orange pulsing light. ## Events - `onEnter { player }`: a player stepped onto the hill (seen on this machine). - `onExit { player }`: a player stepped off, or was left behind when the hill moved. - `onMoved { spot }`: the hill moved to another spot (1 = the entity's own place). ## Methods - `getState()` returns `{ state, holder, holderName, mine, spot, spots, nextMoveIn, occupants }`. `state` is `idle`, `held` or `contested`, `mine` is true when this machine's player holds the hill, and `nextMoveIn` is -1 when the hill doesn't move. - `getOccupants()` returns the ids of the players inside, lowest first. - `isInside(who)` takes a player id or any entity. - `getSpot()` returns the current spot index. `getCentre()` returns `{ x, y, z }` of the current spot. ## Drop one into a level (build.luau) ```lua local match = entity.spawnSynced("Match") match.component.add("MatchFlow", { format = "kingOfTheHill", roundSeconds = 90, targetScore = 30, hudLayout = "holdMeter" }) local hill = entity.spawn("Hill") hill.component.add("Hill", { look = "scifiPad", radius = 3 }) hill.localPosition = { 0, 0, 0 } ``` ## A moving hill ```lua -- Three spots: the entity itself, 10 m east, and wherever the "NorthLedge" entity stands. -- It hops every 20 s of the round, blinking for the last 3 s before each move. local hill = entity.spawn("Hill") hill.component.add("Hill", { look = "runeCircle", radius = 2.5, spots = "10,0; NorthLedge", moveEvery = 20 }) ``` Every machine works out the spot from the round's clock (`floor(elapsed / moveEvery) % spots + 1` while playing, spot 1 otherwise), so all screens agree without any extra network traffic. ## Reacting in game code ```lua local hill = entity.find("Hill").component.get("Hill") hill.events.onEnter:connect(function(e) print(e.player, "stepped on") end) if hill:getState().mine then -- this player holds it end ```