# Lifeline.api The one module scripts talk to: `damage`, `heal`, `kill`, `revive`, `fire` (projectiles), `on` (events on every peer), `get`/`all`/`isAlive`, `setDamageFilter` (owner-side validation), `setSpawnPicker`, `setStyle`. It routes requests to the owning peer over `multiplayer.send`.

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

# Lifeline — health, damage & respawn kit Drop-in health for anything that can get hurt (players, enemies, breakable props), with damage zones, heal zones, projectiles, respawning, events for your own scripts, and a large wardrobe of looks: **13 health bar styles, 7 damage-number styles (4 presets) and 5 mix-and-match hit effects**, all switched by changing one field. Multiplayer-safe: only the peer that owns an entity decides what happens to its health.  ## Installing it into your world The package is called **Lifeline** — asset `Lifeline.package`, guid `7b85ce05-3903-4374-b654-2d4ffea295a5`, MIT licensed. (Its showcase world is *Lifeline — Health, Damage & Respawn Kit*.) One install, any of these ways: - **From the ZeroMind library in the editor** — search for `health` or `Lifeline` and install the **Lifeline** package. - **By guid, from the engine shell:** ``` zero zeromind installAsset 7b85ce05-3903-4374-b654-2d4ffea295a5 ``` - **From Luau:** ```lua tools.use("zeromind", "preview", "7b85ce05-3903-4374-b654-2d4ffea295a5") -- what it would write tools.use("zeromind", "installAsset", "7b85ce05-3903-4374-b654-2d4ffea295a5") -- do it ``` - **From an agent:** `zeromind.install { guid = "7b85ce05-3903-4374-b654-2d4ffea295a5" }`. It lands in your `/source` as `Lifeline.package/`, so after installing, every piece resolves by that name: `Lifeline.Health`, `Lifeline.LifelineHUD`, `Lifeline.DamageZone`, `Lifeline.HealZone`, `Lifeline.Projectile`, `Lifeline.ProjectileLauncher`, `Lifeline.SpawnPoint`, and `require("Lifeline.api")` / `require("Lifeline.bars")`. Nothing in it is world-specific — you bring the entities. Run `zeromind.update` later to pull new versions. ## Five-minute start **1. Give things health.** Add `Lifeline.Health` to the player body on your scene's PlayerPrototype, and to any enemy or prop. Put enemies and props on **synced** entities (`entity.spawnSynced`) so every player sees the same health. ```lua body.component.add("Lifeline.Health", { maxHealth = 100, regenRate = 5, maxShield = 25 }) crate.component.add("Lifeline.Health", { maxHealth = 40, onDeath = "remove" }) ``` **2. Show it.** Add `Lifeline.LifelineHUD` to one plain (non-synced) entity in the scene. Every peer runs its own copy. ```lua entity.spawn("HUD").component.add("Lifeline.LifelineHUD", { playerBar = "hearts", worldBar = "overhead" }) ``` **3. Hurt and heal.** Add a zone to any entity. It's a box of `sizeX × sizeY × sizeZ` around the entity and moves with it. ```lua lava.component.add("Lifeline.DamageZone", { sizeX = 4, sizeZ = 4, kind = "fire", amount = 5, mode = "perSecond" }) spikes.component.add("Lifeline.DamageZone", { kind = "spikes", amount = 25, mode = "onEnter" }) pad.component.add("Lifeline.HealZone", { amount = 10, interval = 0.5 }) ``` **4. From code.** ```lua local Lifeline = require("Lifeline.api") Lifeline.damage(target, 20, { kind = "fire", source = attacker, crit = false }) Lifeline.heal(target, 15) Lifeline.fire { origin = muzzlePos, direction = aim, damage = 15, source = shooter } -- projectile Lifeline.on("died", function(e) print(e.target, "died to", e.kind) end) ``` **5. Respawn.** Dead players come back after `respawnDelay` seconds at a random free `Lifeline.SpawnPoint` (or at the scene's `PlayerSpawn` if you haven't placed any), with full health and a moment of spawn protection. That's it. The `scenes.main` showcase in this world uses every piece. ## What happens on death (`onDeath`, per entity) | value | effect | |---|---| | `auto` (default) | `respawn` for players, `reset` for everything else | | `respawn` | back at a spawn point after `respawnDelay`, full health | | `reset` | back where it started after `respawnDelay`, full health | | `remove` | disappears after `removeDelay` | | `stay` | stays dead until `Lifeline.revive(target)` | ## Health fields (most useful) `maxHealth`, `health`, `maxShield`/`shield` (soaks damage first), `regenRate` + `regenDelay`, `shieldRegenRate` + `shieldRegenDelay`, `invulnerabilityTime` (i-frames after a hit; damage-over-time ticks ignore it), `invulnerable` (god mode → "IMMUNE"), `armor` (flat reduction → "BLOCKED"), `respawnDelay`, `spawnProtection`, `displayName`, `team`, `barStyle` (bar drawn over this entity, `none` hides it), `bossBar` (show the big boss bar when near), `bodyHeight`/`bodyRadius` (bar placement and hit volume), `killBelowY`. Read-only: `isDead`, `deaths`. ## Events `Lifeline.on(name, fn)` fires on **every** peer for `damaged`, `healed`, `blocked`, `died`, `respawned`, or `"*"` for all. The payload is `{ event, target, amount, shieldAmount, kind, source, crit, health, shield, maxHealth, reason, origin, pos, isPlayer, name }`. It returns a connection with `:Disconnect()`. Each Health component also exposes typed events: `entity.component.get("Lifeline.Health").events.died:connect(fn)`. ## Styles: change one field On `LifelineHUD` (or at runtime per player with `Lifeline.setStyle { bar = …, worldBar = …, number = …, feedback = … }`): - **Bars** (`playerBar`, `worldBar`, Health's `barStyle`): `classic` (lost chunk drains away), `segmented`, `ring`, `hearts` (half hearts, shield hearts, heartbeat at low HP), `boss`, `overhead`, `minimal`, `stacked` (shield on health), `scifi`, `fantasy`, `cartoon`, `pixel`, `orb`. - **Numbers** (`numberStyle`): `classic` (pop / shaky crit / green heal / IMMUNE-BLOCKED), `combo` (hits on one target add up into a running total), `comic`, `minimal`. - **Feedback** (`feedback`, any mix): `flash shake vignette heartbeat direction`, or `all` / `none`. ## Multiplayer & anti-cheat Health fields are `Sync`. Only the entity's owner mutates them, and the relay refuses writes from anyone else — so one player cannot set another player's health from their own machine. - **Hit something you own** (your avatar, or a prop your peer took) — it changes on your machine and the new value goes on the wire. Every other peer draws exactly that number: health bars, numbers and death screens all read the same synced field. - **Hit something another player owns** — `Lifeline.damage` doesn't decide anything. It sends a request to that entity's owner over `multiplayer.send`, and the owner validates it before applying. `Lifeline.setDamageFilter(function(comp, amount, info, fromPeer) ... end)` is where that validation goes: return the amount to allow (clamped if you like), or 0 to refuse. `fromPeer` is set only when the hit arrived from another peer's request. - **Zones** run on every peer but act only on entities that peer owns, so a player in a fire zone is burned exactly once, by their own machine. A player's damage events are broadcast by the owner, so remote players see the same flash, numbers and score hooks. - **Events** (`Lifeline.on`) fire on every peer — same channel the kit uses for its own visuals. **The honest limit:** the engine's model is that the owning peer is the authority for its own entities. That is what stops *other* players from touching your health, and it is what this kit is built on. It does not, by itself, stop a modified client from lying about *its own* health (a hacked client could ignore a fire zone). If your game needs damage that a cheating client can't dodge, run the damage on a peer you control and funnel it through `setDamageFilter` — the filter runs on the owner, so it's the place to require proof, rate-limit, or refuse anything that doesn't match your own simulation. ## Other hooks `Lifeline.kill`, `Lifeline.revive`, `Lifeline.get(target)`, `Lifeline.all()`, `Lifeline.isAlive`, `Lifeline.setSpawnPicker(fn(comp, points) -> entity)`, `Lifeline.kinds` (damage kinds → colour/label, add your own). ## Contents `Health`, `DamageZone`, `HealZone`, `Projectile`, `ProjectileLauncher` (player blaster on a key, or an auto turret), `SpawnPoint`, `LifelineHUD` components, plus the `api`, `bars`, `numbers`, `feedback` and `zone` modules.

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