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 delay. Server calls 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`)

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`	(boolean)

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)

Death Validation

Deaths are only counted when all of the following are true:

data.killedByPlayer == true — the kill came from another player, not the environment
isDeathValid(data.deathCause) — the weapon hash is not in MBT.BlacklistedDeathCause
LocalPlayer.state.ratioListening == true — the player has not disabled tracking (default true)

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

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

isVisible