Log inGet started
World

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

FieldDefaultWhat it does
lookglowRingglowRing (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).
radius3Radius of the hill in metres.
height3Height 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.
moveEvery0Seconds between moves during a round (0 = never moves).
warnSeconds3Before a move the floor lights blink faster and faster and the label counts down MOVING IN 3.
previewlivelive 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)

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