Match Flow Kit: Countdowns, Rounds and Results
README.md
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
radiusof the centre across the floor, and from 0.5 m below the floor up toheightabove it. It draws the hill from that, and firesonEnter/onExitlocally. - Only the machine in charge of the match (
match:isAuthority()) reportssetOnHill(player, true/false), and only while the match format iskingOfTheHill. 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,heightorlabelchanges. 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 }.stateisidle,heldorcontested,mineis true when this machine's player holds the hill, andnextMoveInis -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)
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
-- 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
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