Commands & Events

Player Controls

All controls are registered dynamically — they only exist while the relevant game phase is active.

Lobby phase

Action	Key	Condition
Open match menu / start player selection	`E`	Standing near the KTF NPC

Player selection UI

Key	Action
`→ Right Arrow`	Highlight next player
`← Left Arrow`	Highlight previous player
`↓ Down Arrow`	Select / deselect highlighted player
`ENTER`	Confirm selection and start countdown
`BACKSPACE`	Cancel and close selection UI

In-match

Action	Key	Condition
Pick up / capture flag	`E`	Within 2.5 units of the flag and flag is available
Open stash menu	`E`	Standing on the stash marker

Flag Capture Flow

Player walks within 2.5 units of the flag — a "Pick flag" hint appears
Player presses E — a circular progress bar runs for MBT.CaptureTime seconds
If the bar completes without interruption, the flag attaches to the player's back (bone 24816)
The server locks the flag state so no other player can capture it simultaneously
Score begins accumulating every second
On death or when another player captures the dropped flag, the sequence restarts

Score System

Score = total seconds the flag was held during the match

The leaderboard syncs every MBT.UpdateVip seconds (default 3). The player with the highest cumulative hold time at the end of the match wins.

Developer Reference

Client → Server events

Event	Payload	Description
`mbt_ktf:startChecks`	`{ players }`	Sent after player selection is confirmed; initiates the match server-side.
`mbt_ktf:handleFlagState`	`{ state }`	Notifies server that the flag availability changed (locked/available).
`mbt_ktf:checkFlagState`	—	Client requests the current flag lock state before attempting capture.

Server → Client events

Event	Target	Description
`mbt_ktf:startPreMatch`	selected players	Opens the player selection UI on the host's screen.
`mbt_ktf:startGame`	all participants	Teleports players to the arena and starts the match.
`mbt_ktf:triggerNotify`	all	Shows an ox_lib notification.
`mbt_ktf:Notify`	all	Shows a sliding in-NUI notification.

Global State

Key	Type	Description
`GlobalState.ctfGameEnded`	`boolean`	Set to `true` when the match has ended.
`LocalPlayer.state.isInKtf`	`boolean`	Set per-player; `true` while participating in a match.

NUI Messages (Lua → HTML)

Type	Payload	Description
`"ui"`	`{ show: boolean }`	Shows or hides the game HUD.
`"flag"`	`{ id, name }`	Updates the flag-holder display (name + blip).
`"show"`	`{ text }`

NUI Callbacks (HTML → Lua)

Callback (POST)	Description
`https://mbt_ktf/endGame`	Fired when the game-over animation finishes; passes `{ id, name }` of the winner.

Match Lifecycle (Server)

Player presses E near NPC
    → mbt_ktf:startChecks (client → server)
        → Server validates minimum players
        → All participants moved to routing bucket
        → Intro camera starts
        → Flag spawns, pickups spawn, NPCs spawn
        → Game timer starts (EventDuration minutes)
 
During match:
    → updateVipThread — score sync every UpdateVip seconds
    → sendFlagOwnerCoordsThread — blip sync every