Commands & Events
Player Commands
| Command | Key | Description |
|---|---|---|
/openRatio | F7 (default) | Toggles the personal KD stats NUI panel open/closed. The key can be rebound in the GTA V key settings or changed via MBT.OpenKey.Key in config.lua. |
The key binding is registered via RegisterKeyMapping('openRatio', "Open Ratio Interface", 'keyboard', MBT.OpenKey["Key"]) and only active when MBT.OpenKey.Active = true.
Personal Stats NUI
The NUI panel shows:
| Stat | Description |
|---|---|
| Kills | Total player kills recorded this session + from database |
| Deaths | Total deaths (excluding blacklisted causes) |
| Headshots | Kills where the final hit landed on bone 31086 (head) |
| KD Ratio | Kills / max(Deaths, 1), formatted to 2 decimal places |
The panel updates in real time every time you score a kill or die.
In-World Scoreboard (DUI)
The mbt_scoreboard prop renders a live HTML leaderboard (html/leaderboard.html) as a DUI texture on the 3D model surface. The leaderboard refreshes every MBT.DUI.Refresh seconds (default 30) and shows all players on the server ranked by KD ratio.
The DUI is only rendered when the player is within MBT.DUI.Distance units of the prop (default 20).
Developer Reference
Client → Server events
| Event | Payload | Description |
|---|---|---|
mbt_ratio:weaponDamageEvent | { killedByPlayer, killerServerId, killerClientId, deathCause, bone, victimCoords, killerCoords, distance } | Fired by the victim's client on death. Server increments death/kill/headshot counters and pushes updated stats to both players. |
mbt_ratio:deliverPrize | prizeTable | Fired by the winner's client after the TimeBeforeWinnerCheck delay. Server calls MBT.DeliverPrizeFunction to grant items. |
Server → Client events
| Event | Target | Description |
|---|---|---|
mbt_ratio:initUI | specific player | Sent on join with the player's saved stats { Kills, Deaths, Headshots, Name }. Populates the NUI on load. |
mbt_ratio:setData | killer + victim | Pushed after every valid kill/death. Updates NUI stats in real time. |
mbt_ratio:retrieveDUIUpdate | all (-1) | Broadcasts the full sorted scoreboard array to all clients so the DUI leaderboard can update. |
mbt_ratio:triggerWinner | winner only | Tells the winner's client to start the prize delivery sequence (waits TimeBeforeWinnerCheck seconds, then triggers mbt_ratio:deliverPrize). |
mbt_ratio:successfullDelivered | winner only | Sent after a successful prize delivery. Triggers a congratulation screen in the NUI. |
mbt_ratio:openInterface | any | Opens the NUI panel. Can be triggered from other resources. |
Server-only events
| Event | Description |
|---|---|
mbt_ratio:manualSaving | Triggers an immediate save of all player stats to MySQL. Use this if MBT.UseTxAdmin = false and you need to flush data before a restart. |
mbt_ratio:updateJson | Internal — writes the updated draws.json to disk after a prize delivery state change. |
NUI Callbacks (HTML → Lua)
| Callback | Payload | Description |
|---|---|---|
nuiIsReady | — | Fired when the NUI page finishes loading. Triggers Init() on the client (spawns prop, sets up events). |
exit | — | Fired when the player closes the NUI. Releases NUI focus. |
NUI Messages (Lua → HTML)
action | Payload fields | Description |
|---|---|---|
getUISettings | MBT.UI | Sends label and description config to the NUI on load. |
update | kills, deaths, headshots, kd | Updates all stat values in the personal panel. |
visible | isVisible (boolean) | Shows or hides the NUI panel. |
prize | userData.Name | Displays the prize-won congratulation screen with the winner's name. |
DUI Messages (Lua → leaderboard.html)
Sent via SendDuiMessage(duiObj, json.encode({ type, payload })):
type | Payload | Description |
|---|---|---|
setupScore | { scoreTable, playerName } | Full sorted leaderboard array + local player name. Updates the scoreboard display on the prop. |
Each entry in scoreTable contains:
| Field | Type | Description |
|---|---|---|
License | string | Player identifier (license hash) |
Name | string | Display name |
KDN | number | KD ratio as a number (for sorting) |
KDS | string | KD ratio formatted as a 2-decimal string |
Rank | number | Position in the sorted leaderboard (1 = highest KD) |
Death Validation
Deaths are only counted when all of the following are true:
data.killedByPlayer == true— the kill came from another player, not the environmentisDeathValid(data.deathCause)— the weapon hash is not inMBT.BlacklistedDeathCauseLocalPlayer.state.ratioListening == true— the player has not disabled tracking (defaulttrue)
Deaths caused by vehicles, fall damage, or other environment sources are never counted because killedByPlayer will be false.
Prize Draw Flow
Server starts → MySQL loads all player records into memory
→ Every DUI.Refresh seconds: recalculate KD leaderboard, broadcast to clients
→ First cycle also calls checkDrawDay()
→ If today == configured draw day AND draw not already delivered:
→ Roll prize from PrizeInfo loot table
→ Record winner (highest KD > 0) in draws.json
→ Register playerLoaded listener for the winner's identifier
→ When winner logs in:
→ Wait TimeBeforeWinnerCheck seconds
→ Client fires mbt_ratio:deliverPrize with prizeTable
→ Server calls MBT.DeliverPrizeFunction
→ On success: mark draws.json Delivered = true
→ On failure: retry after 20 secondsThe draw is skipped for players with KD = 0 — the script searches from the top of the sorted list for the first player with KDN > 0.