.json` (e.g. `de.json`).
{% endstep %}
{% step %}
## Translate the values
Translate the values. Keys stay as they are; `%s` placeholders must survive.
{% endstep %}
{% step %}
## Set the locale
```lua
cfg.locale = 'de'
```
{% endstep %}
{% endstepper %}
Top-level keys are server notifications, everything under `"ui"` is the interface. Missing keys fall back to showing the key name, so a partial translation still runs.
# Troubleshooting
Every failure mode surfaces in the debug overlay. Open it with `/decals_debug` (admin-only; `/decals_debug ` opens it on another player's screen so they can read values to you), then check the cards top to bottom.
### 1. DECALS.DAT PROBE says FAILED
The decal types from `rm_decalv_assets` never registered in this session, so nothing can render no matter what else is right. Two causes:
* **The player joined while `rm_decalv_assets` wasn't running.** Its decal types mount when the game level loads, i.e. at join. Make sure it starts at boot, then have the player **reconnect**. Restarting `rm_decalv_assets` does *not* fix already-connected players.
* **Another resource owns the level meta.** Check the **GTA5.META OWNERS** card: it must say `rm_decalv_assets (expected)`. If a map/meta resource is listed instead, it wins the `replace_level_meta` conflict. Load it before `rm_decalv_assets` or remove its override.
### 2. DECAL TYPE SLOTS shows 31 instead of 280
Milder form of check 1, same causes: the player joined while `rm_decalv_assets` wasn't running, either because it never started at boot or because it was being restarted at that moment. The session then falls back to the game's own 31 built-in decal types, so decals render but only 31 distinct textures fit. Start `rm_decalv_assets` at boot, leave it running, and have the affected player reconnect to restore the full 280.
### 3. CATALOG isn't "Loaded"
The client never received the catalog. Read the **server** console from the last `rm_decalv` start:
* `File not found: [x.webp]` means the entry was pruned; the image is missing from `rm_decalv/assets/`.
* `[x] has an unsupported file extension` means only webp/png/jpg are accepted (gif when enabled).
* A Lua error in `decals.lua` stops the whole catalog. Fix the syntax and restart.
### 4. One specific decal is blank
While placing, a small **preview sprite** sits in the bottom-right corner showing the raw texture. Read it like this:
* **Sprite visible, decal missing:** the texture is fine; the decal types didn't register in this session. Back to checks 1 and 2.
* **Sprite blank too:** the texture never resolved. Wrong `textureDict`/`textureName`, the ytd isn't in `rm_decalv_assets/stream/`, or the dict was updated without players reconnecting. For image-file decals, check the **RUNTIME TEXTURE POOL** card: a full bucket (e.g. `512² 16/16`) means too many distinct image decals are in range at once, so move the pack into a dictionary (recommended method).
### 5. Decals exist but don't draw right now
The **RENDERING** card counts what's loaded vs what's drawn:
* **Graffiti rows > rendered:** the extras are beyond `cfg.rendering.distance` or over `cfg.rendering.graffitiBudget` (farthest drop first).
* **Sticker vehicles tracked > 0, rendered 0:** the vehicles are out of render range, or currently hidden by visibility culling (blocked from view / behind the camera); they redraw as soon as they come back into view.
* **Only one player affected:** ask them to open the catalog and check the gear icon: players can turn sticker and graffiti rendering off for themselves, and the choice persists between sessions.
### 6. Decals vanish near a specific vehicle (ENGINE says Stalled)
The **ENGINE** cell in the status strip probes live whether GTA's decal engine is accepting new decals. If it reads **Stalled**, some vehicle model on your server is overloading the engine: unoptimized high-poly conversions make every decal cost many times more than it should, and past a budget the engine stops creating **any** new decals in that player's game (all decal types, other scripts' decals included) until the load drops. The stall is per client, but every player who renders that vehicle's stickers hits the same wall on their own screen, so in practice it reads as server-wide. Typical symptoms: previews stop rendering near a certain car, stickers on healthy cars blink out and return when that car is stored.
The script protects itself automatically (it sheds load and recovers), but the real fix is finding and blacklisting the model:
1. Add `cfg.dev = true` to `cfg.lua` and restart the resource.
2. Run `/decals_meshprobe ` for a suspect, or `/decals_meshprobe all` to sweep every vehicle model on the server (takes a while; `/decals_meshprobe stop` aborts).
3. The run ends with a summary and **ready-to-paste `cfg.blacklistModels` lines** for every model that stalled the engine. Paste them, remove `cfg.dev`, restart.
For the vehicle's creator: the fix on their side is lowering body-panel polygon density, adding real LODs, and making the collision match the visible body. Vanilla-quality models pass the probe with a wide margin.
### 7. Flip switch is greyed out
Expected in three cases: the decal is a GIF (no flip variant exists), the texture dictionary has no `_f` twin (build one with `ytd-flip`), or you're placing on a wall (graffiti has no flip).
### 8. Console warnings worth acting on
Since 3.3.0 routine self-healing messages sit behind verbose logging so consoles stay quiet; run `setr ox:printlevel:rm_decalv verbose` (before resource start) when you want the full diagnostic stream. The warnings below always print:
* `decal capacity: X of 280 slots...`: see check 2.
* `Asset ... uses N MiB of physical memory`: a custom ytd is oversized; split it into smaller dictionaries.
* `no texture source registered for x.webp`: a placed decal's catalog entry was removed. Delete the orphaned decal from the admin panel or restore the entry.
* `N asset file(s) not referenced by decals.lua`: imported files whose snippet never got pasted. Paste the entries or delete the files.
{% hint style="info" %}
Still stuck? Open a ticket in our [Discord](https://discord.gg/rainmad) with your server console output and a screenshot of the debug overlay. Those two cover nearly every case.
{% endhint %}
# Sea Battle: Dive, Sharks & Crate Tow!
***
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
## Step 1: Download and Prepare Files
#### **Download the Script from FiveM Keymaster**
* Visit the [FiveM Keymaster](https://keymaster.fivem.net/) site.
* Log in with your account credentials.
* In the **Granted Assets** section, locate the Sea Battle: Dive, Sharks & Crate Tow! script.
* Download the script files from Keymaster.
## Step 2: Add Script to Server Configuration
#### **Edit `server.cfg`**
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following line to ensure the Sea Battle: Dive, Sharks & Crate Tow! script start automatically with your server:
```
rm_seabattle
```
# Configuration
## General Configuration
```lua
Config = {}
----------------------------------
------------ General -------------
----------------------------------
Config.framework = {
name = "auto", -- esx | qb | auto (auto-detects)
targetScript = "ox_target", -- ox_target | qb-target
useOxNotify = true, -- use ox_lib notify instead of framework notify
debug = false, -- developer debug prints
}
Config.moneyOptions = {
moneyName = "money", -- account name, or item name if moneyIsItem
moneyIsItem = false,
}
Config.seaBattle = {
----------------------------------
---------- Event Start -----------
----------------------------------
start = {
auto = {
enabled = false,
interval = 30,
},
command = {
enabled = true,
name = "startseabattle",
staffList = {
["license:change_me"] = true,
}
},
npc = {
enabled = true,
model = "s_m_y_dockwork_01",
coords = vector4(-1611.922, 5262.081, 3.974, 206.627),
item = {
enabled = false,
itemName = "sea_intel", -- consumed to start when intelItem is enabled
removeItemOnUse = true,
},
},
requiredPlayers = 0,
maxConcurrent = 3, -- how many events can be active at once
cooldown = 10, -- minutes a drop slot stays locked after an event ends
missionTimer = 30, -- minutes before an undelivered event auto-destructs
},
notify = {
announce = true, -- big scaleform shard announcement
jobList = {}, -- empty = everyone is notified; else only these jobs
},
----------------------------------
---------- Plane & Drop ----------
----------------------------------
plane = {
lineLength = 600.0, -- plane fly-in line length over the drop point
planeSpeed = 150.0, -- km/h
planeModels = { "titan" },
pilotModels = { "s_m_m_pilot_01", "s_m_y_pilot_01" },
},
dropCoords = {
vector3(-1687.698, 5330.878, 0.324)
},
deliveryCoords = {
vector3(-1661.575, 5159.983, -0.249)
},
----------------------------------
------------- Blips --------------
----------------------------------
blipOptions = {
plane = {
enabled = true,
label = "Smuggler Plane",
sprite = 423,
color = 1,
scale = 1.2,
},
crate = {
enabled = true,
label = "Contraband Crate",
sprite = 478,
color = 5,
scale = 1.0,
},
npc = {
enabled = true,
label = "Maritime Contact",
sprite = 410,
color = 3,
scale = 0.9,
},
},
----------------------------------
--------- Crate & Towing ---------
----------------------------------
bob = {
enabled = true,
height = 0.35, -- vertical sway in meters
speed = 0.75, -- sway cycles per second
tilt = 1.25, -- pitch/roll sway in degrees
},
tow = {
attachDistance = 3.0, -- proximity radius (m) for the attach/cut text prompt
secureTime = 120, -- seconds you must hold next to the crate (under fire) before the rope can be grabbed
},
----------------------------------
------------- Guards -------------
----------------------------------
guards = {
enabled = true,
boatModel = "dinghy5",
pedModel = "s_m_y_blackops_01",
pedWeapon = "WEAPON_CARBINERIFLE",
boatCount = 3, -- guard boats spawned in a ring around the drop
accuracy = 10, -- ped weapon hit chance (0-100), lower = miss more
shootRate = 50, -- ped fire rate (0-1000); note: barely affects drive-by / mounted-gun firing
health = 200,
},
----------------------------------
------ Underwater & Sharks -------
----------------------------------
underwater = {
chance = 100, -- % chance an event also spawns the underwater layer
searchTime = 5, -- seconds the search progress bar takes
scuba = {
item = "rebreather", -- usable item that grants underwater air and is required to search the wrecks
duration = 120, -- seconds of air per use
},
wreckModels = { -- sunken junk to search
"prop_rub_carwreck_9",
"prop_rub_carwreck_8",
},
wreckAmount = {
min = 3,
max = 5,
},
searchPointsPerWreck = {
min = 1,
max = 3
},
shark = {
enabled = true,
amount = {
min = 3,
max = 5,
},
biteDamage = 20, -- damage per bite
biteCooldown = 1500, -- ms between bites from the same shark
}
},
----------------------------------
------- Equipment & Spear --------
----------------------------------
spear = {
item = "speargun", -- usable inventory item; on use the weapon is handed to the player
},
----------------------------------
---------- Maritime NPC ----------
----------------------------------
npcOptions = {
rentVehicles = {
{
model = "dinghy",
price = 100,
},
{
model = "seashark",
price = 50,
}
},
items = {
{
label = "Rebreather",
name = "rebreather",
price = 50,
},
{
label = "Speargun",
name = "speargun",
price = 100,
},
},
spawnCoords = { -- rent vehicles
vector4(-1602.375, 5260.171, 0.120, 24.24)
}
},
}
----------------------------------
------------- Loot ---------------
----------------------------------
Config.seaBattle.lootSystem = {
surface = {
itemAmount = function() return math.random(3, 6) end,
money = function() return math.random(5000, 15000) end,
categories = {
{
name = "weapon",
chance = 35,
items = {
{ itemName = "WEAPON_CARBINERIFLE", chance = 40, amount = function() return 1 end },
{ itemName = "WEAPON_SMG", chance = 35, amount = function() return 1 end },
{ itemName = "WEAPON_SNIPERRIFLE", chance = 18, amount = function() return 1 end },
{ itemName = "WEAPON_RPG", chance = 7, amount = function() return 1 end },
},
},
{
name = "valuable",
chance = 40,
items = {
{ itemName = "goldbar", chance = 50, amount = function() return math.random(1, 2) end },
{ itemName = "diamond", chance = 35, amount = function() return 1 end },
{ itemName = "artifact", chance = 15, amount = function() return 1 end },
},
},
{
name = "ammo",
chance = 25,
items = {
{ itemName = "rifle_ammo", chance = 50, amount = function() return math.random(60, 120) end },
{ itemName = "smg_ammo", chance = 30, amount = function() return math.random(60, 120) end },
{ itemName = "sniper_ammo", chance = 20, amount = function() return math.random(10, 20) end },
},
},
},
},
underwater = {
itemAmount = function() return math.random(1, 3) end,
money = function() return math.random(1000, 4000) end,
categories = {
{
name = "salvage",
chance = 60,
items = {
{ itemName = "scrap_metal", chance = 60, amount = function() return math.random(2, 5) end },
{ itemName = "copper", chance = 30, amount = function() return math.random(1, 3) end },
{ itemName = "electronics", chance = 10, amount = function() return 1 end },
},
},
{
name = "valuable",
chance = 40,
items = {
{ itemName = "goldbar", chance = 60, amount = function() return 1 end },
{ itemName = "diamond", chance = 40, amount = function() return 1 end },
},
},
},
},
}
----------------------------------
------------ Strings -------------
----------------------------------
Strings = {
["event_title"] = "Sea Battle",
["event_started"] = "A smuggler plane is dropping contraband at sea!",
["need_item"] = "You need: x%s %s",
["not_staff"] = "You are not allowed to do this.",
["no_slots"] = "Too many active operations right now.",
["not_enough_players"] = "Not enough players online for an operation.",
["spawn_occupied"] = "The boat spawn area is blocked.",
["add_item_log"] = "Player: %s\nIdentifier: %s\nItem: %s\nAmount: %s",
["add_money_log"] = "Player: %s\nIdentifier: %s\nMoney: $%s",
["start_log"] = "Started by: %s\nIdentifier: %s\nTrigger: %s\nEvent: %s",
["talk_to_contact"] = "Talk to Contact",
["rent_boat"] = "Rent Boat",
["rent_boat_desc"] = "Rent a boat to reach the open sea",
["buy_item"] = "Buy Item",
["buy_item_desc"] = "Dive gear and equipment",
["start_operation"] = "Start Operation",
["start_operation_desc"] = "Trigger a contraband sea drop",
["price"] = "Price: $%s",
["grab_rope"] = "[E] Grab Rope",
["cut_rope"] = "[E] Cut Rope",
["securing_rope"] = "Securing the rope...",
["tying_boat"] = "Tying to the boat...",
["cutting_rope"] = "Cutting the rope...",
["let_go_rope"] = "You let go of the rope.",
["attach_to_boat"] = "[E] Attach to boat [X] Cancel",
["go_to_boat"] = "[X] Cancel - go to your boat",
["delivery_point"] = "Delivery Point",
["deliver_prompt"] = "[E] Deliver Crate",
["delivering"] = "Delivering...",
["delivered"] = "Contraband delivered! You earned $%s.",
["sunken_wreck"] = "Sunken Wreck",
["search_wreck"] = "[E] Search Wreck",
["searching_wreck"] = "Searching the wreck...",
["need_rebreather"] = "You need a rebreather to dive here.",
["salvaged"] = "Salvaged contraband! You found $%s.",
["shark_blip"] = "Shark",
["scuba_on"] = "Rebreather on.",
["scuba_depleted"] = "Rebreather air depleted.",
}
```
### Heist Configuration
```
Config.heist = {
--------------------------
----- QUIET APPROACH -----
--------------------------
terminalHacking = {
coords = vector3(-623.15, -216.22, 53.54),
requiredItem = "hacker_phone",
removeItemOnUse = false,
-- minigame options
minigame = "none",
duration = 60, -- duration of hack minigame in seconds
solutionLength = 5, -- length of the solution string
policeAlertDuration = 30, -- seconds (after the hacking incident should the police be alerted)
},
plantingGasBomb = {
ventModel = "prop_aircon_m_04", -- model of the vent where the bomb should be planted
coords = vector3(-631.13, -228.23, 55.65),
offset = vector3(-0.83, -0.5, 0.8), -- offset from the coords where the bomb should be planted (relative to the vent)
requiredItem = "gas_bomb",
removeItemOnUse = true,
mask = {
enable = true,
requiredItem = "gas_mask",
removeItemOnUse = true,
clotheId = 175,
duration = 300, -- duration of the gas mask effect in seconds
damage = 5, -- damage dealt to the player every interval while the gas mask is active
damageInterval = 5, -- interval in seconds at which the damage is applied to the player while the gas mask is active
zone = vector4(-622.364, -231.020, 38.047, 11.0)
},
-- minigame options
minigame = "none",
},
--------------------------
----- LOUD APPROACH ------
--------------------------
vangelicoEntrance = {
coords = vector3(-631.760, -237.737, 38.073),
lockpick = {
requiredItem = "lockpick",
removeItemOnUse = true,
strength = 0.1, -- from 0.1 (easy) to 7 (hard)
difficulty = 0.1, -- from 0.1 (easy) to 7 (hard)
pins = 2, -- number of pins (max 9)
-- minigame options
minigame = "none",
},
thermite = {
offset = vector3(1.3, -0.03, 0.0),
requiredItem = "thermite_bomb",
removeItemOnUse = true,
-- minigame options
minigame = "default",
},
},
-------------------------
---- GENERAL OPTIONS ----
-------------------------
keypad = {
coords = vector3(-629.135, -230.949, 38.057),
searchCoords = {
vector3(-625.925, -226.127, 38.057),
vector3(-623.040, -235.807, 38.057),
vector3(-618.774, -236.339, 38.057),
vector3(-617.183, -231.740, 38.057),
vector3(-621.453, -225.867, 38.057),
vector3(-622.500, -229.772, 38.057),
vector3(-630.369, -232.243, 38.057)
},
},
doors = {
{ -- front doors
door_1_model = 1425919976,
door_2_model = 9467943,
door_1_coords = vector4(-631.95538330078, -236.33326721191, 38.206531524658, 306.60577392578),
door_2_coords = vector4(-630.42651367188, -238.43754577637, 38.206531524658, 305.39260864258),
status = "locked", -- "locked", "unlocked"
},
{ -- security room door
door_1_model = 1335309163,
door_1_coords = vector4(-629.13385009766, -230.15170288086, 38.20658493042, 36.000022888184),
status = "locked", -- "locked", "unlocked"
}
},
---------------------------
----- LOOTABLE OPTIONS ----
---------------------------
containers = {
-- Weapons allowed to smash jewelry cabinets (whitelisted weapons)
smashWeapons = {
'WEAPON_ASSAULTRIFLE',
'WEAPON_CARBINERIFLE',
'WEAPON_ADVANCEDRIFLE',
'WEAPON_BULLPUPRIFLE',
},
-- required items for certain loot actions:
requiredItems = {
paintings = {
requiredItem = "painting_knife",
removeItemOnUse = false,
},
displayCases = {
requiredItem = "glass_cutter",
removeItemOnUse = false,
},
statues = {
requiredItem = "bag",
removeItemOnUse = false,
}
},
-- Cabinets:
cabinets = {
{
coords = vector4(-626.83, -235.35, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-625.81, -234.7, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-626.95, -233.14, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-628.0, -233.86, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-625.7, -237.8, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-626.7, -238.58, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-624.55, -231.06, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.13, -232.94, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.29, -234.44, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.15, -233.66, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.19, -233.44, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-617.63, -230.58, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-618.33, -229.55, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.7, -230.33, 38.05, 125.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.95, -228.6, 38.05, 125.0),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.79, -227.6, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.42, -226.6, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.94, -227.18, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-624.91, -227.87, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.94, -228.05, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
}
},
-- Paintings:
paintings = {
{
model = 'h4_prop_h4_painting_01h',
coords = vector4(-627.21325683594, -228.30999755859, 38.106048583984, 92.391586303711),
rewards = {
{ itemName = "painting_01h", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01d',
coords = vector4(-622.79998779297, -225.13999938965, 38.106048583984, 339.9309387207),
rewards = {
{ itemName = "painting_01d", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01e',
coords = vector4(-617.0, -233.2200012207, 38.106048583984, 271.89691162109),
rewards = {
{ itemName = "painting_01e", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01b',
coords = vector4(-621.36102294922, -236.33099365234, 38.106048583984, 161.18635559082),
rewards = {
{ itemName = "painting_01b", amount = { min = 1, max = 1 } },
}
}
},
-- Display Cases:
displayCases = {
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_diamond_disp_01a",
rewardModel = "h4_prop_h4_diamond_01a",
coords = vector4(-617.4622, -227.4347, 37.057, 127.06),
rewardOffset = vector3(0.0, 0.0, 1.225),
rewards = {
{ itemName = "big_diamond", amount = 1 },
}
},
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_diamond_disp_01a",
rewardModel = "h4_prop_h4_art_pant_01a",
coords = vector4(-631.7185, -234.6784, 36.9402, -53.705),
rewardOffset = vector3(0.0, 0.0, 1.25),
rewards = {
{ itemName = "panther", amount = 1 },
}
},
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_neck_disp_01a",
rewardModel = "h4_prop_h4_necklace_01a",
coords = vector4(-628.8231, -238.7317, 36.8647, -53.705),
rewardOffset = vector3(0.0, 0.0, 1.2),
rewards = {
{ itemName = "diamond_necklace", amount = 1 },
}
}
},
-- Statues:
statues = {
{
tableModel = "v_ret_tablesml",
statueModel = "vw_prop_casino_art_panther_01b",
coords = vector4(-622.04541015625, -230.70222473145, 37.058856964111, 303.0),
rewards = {
{ itemName = "panther_statue", amount = { min = 1, max = 1 } },
}
}
},
-- Safes:
safes = {
{
model = "h4_prop_h4_safe_01a",
coords = vector4(-630.88995361328, -228.27618408203, 36.959362030029, 35.38557434082),
difficulty = 1, -- 1-4 (1 being the easiest, 4 being the hardest)
rewards = {
{ itemName = "money", amount = { min = 500, max = 1500 } },
}
}
}
},
}
Config.missionData = {
takePhoto = {
vector3(-632.86, -238.62, 38.07),
vector3(-623.01, -216.17, 53.54),
vector3(-622.48, -233.67, 59.16),
vector3(-623.24, -231.54, 38.06),
vector3(-626.04, -238.05, 38.06),
vector3(-629.15, -230.69, 38.06)
},
takeEquipment = {
pedModel = "g_m_y_mexgang_01",
coords = {
vector4(591.996, 2782.770, 42.481, 8.644)
},
items = {
{
name = "hacker_phone",
amount = 1
},
{
name = "gas_bomb",
amount = 1
},
{
name = "gas_mask",
amount = 4
},
{
name = "glass_cutter",
amount = 1
},
{
name = "painting_knife",
amount = 1
},
{
name = "bag",
amount = 1
},
}
},
takeClothes = {
pedModel = "s_m_m_autoshop_02",
coords = {
vector4(632.676, -3015.434, 6.336, 359.265)
},
items = {
{
name = "outfit_bag",
amount = 1
}
}
},
}
```
# Mad Racing System - Racing Tablet
***
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
## Step 1: Download and Prepare Files
#### **Download the Script from FiveM Keymaster**
* Visit the [FiveM Keymaster](https://keymaster.fivem.net/) site.
* Log in with your account credentials.
* In the **Granted Assets** section, locate the Mad Racing System - Racing Tablet script.
* Download the script files from Keymaster.
## Step 2: Add Script to Server Configuration
#### **Edit `server.cfg`**
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following line to ensure the Mad Racing System - Racing Tablet script start automatically with your server:
```
rm_racing
```
# Configuration
## General Configuration
```lua
lib.locale('en')
cfg = {}
-- ============================================================================
-- rm_racing — server configuration
--
-- Sections (in order):
-- 1. Framework & dependencies — qbox/qb/esx/standalone, ox_*, etc.
-- 2. Tablet & UI — /racing command, item gating, map tile
-- 3. Economy — money type used for prizes / fees
-- 4. User tiers & permissions — racer/creator/master/god + flag map
-- 5. Player profile defaults — pictures, picker palettes, name change cost
-- 6. ELO rating — Arpad K-factor + display tiers
-- 7. Race engine — countdown, grid layout, DNF timeout
-- 8. Race types — sprint/circuit/drift/etc.
-- 9. Drift scoring — points-per-second, combo, penalties
-- 10. Tracks — creator rules + tags + placeable objects
-- 11. Competitions — auto schedule, prize pool, vehicle classes
-- 12. Pink slips (1v1 vehicle wager) — allowed types, redeem locations
-- 13. Bounties (time-trial chase) — interval, prize, target formula
-- 14. Item payouts — item rolls per finishing position
-- 15. 3D GPS route renderer — line/arrow style, lookahead, sizing
-- 16. Discord webhooks — notifications channel + colors
-- 17. Limits — page sizes / row caps
-- ============================================================================
-- ============================================================================
-- 1. FRAMEWORK & DEPENDENCIES
-- ============================================================================
---@type 'auto' | 'qbox' | 'qb' | 'esx' | 'standalone'
cfg.framework = 'auto'
-- Standalone fallback (no qbox/qb/esx). license identifiers become the
-- citizenid and money uses a virtual wallet in `rm_racing_wallet` instead
-- of a framework account.
cfg.standalone = {
initialBalance = 10000, ---@type number -- credits new players start with
currencyLabel = 'credits', ---@type string -- displayed in modals / tooltips (informational only)
-- DEV ONLY: when true, the standalone bridge suffixes the citizenid with
-- the player's server id so two FiveM clients on the same license get
-- distinct profiles. Each session is treated as a separate player — new
-- profile row, new wallet with initialBalance. TURN OFF in production
-- or every reconnect orphans the previous profile.
perSessionId = false, ---@type boolean
}
---@type 'auto' | 'ox_target' | 'qb-target' | false
cfg.target = 'auto'
---@type 'rm_minigames' | 'ox_lib' | 'qb-minigames' | 'ps-ui' | 'bl_ui' | false
cfg.minigame = 'ox_lib'
---@type 'ox_lib' | 'qb' | 'esx' | 'okokNotify' | 'ps-ui'
cfg.notification = 'ox_lib'
---@type 'rm_racing' | 'ox_lib' | 'esx' | 'qb' | 'okokTextUI' | 'jg-textui'
-- 'rm_racing' = built-in NUI hint (RaceHud-styled, auto-chips for [KEY]).
-- Switch to a third-party system if you want it to match the rest of your
-- server's UI instead.
cfg.textUI = 'rm_racing'
---@type 'ox_lib' | 'qb' | 'esx' | false
cfg.progressbar = 'ox_lib'
---@type 'auto' | false | 'qb-vehiclekeys' | 'wasabi_carlock' | 'qs-vehiclekeys' | 'cd_garage' | 'Renewed-Vehiclekeys' | 'okokGarage' | 't1ger_keys' | 'MrNewbVehicleKeys'
cfg.vehiclelock = 'auto'
---@type false | 'default_dispatch' | 'cd_dispatch' | 'qs-dispatch' | 'ps-dispatch' | 'rcore_dispatch' | 'sonoran_cad' | 'origen_police' | 'redutzu-mdt' | 'lb-tablet' | 'core_dispatch' | 'tk_dispatch' | 'l2s-dispatch'
cfg.dispatch = false
-- Visual style for the in-world `[E] interact` prompt (used by some bridges).
cfg.interaction = {
controlId = 38,
text = 'E',
colors = {
background = { r = 241, g = 93, b = 56, a = 255 },
text = { r = 226, g = 232, b = 240, a = 255 },
},
}
-- Police count gating (kept for parity with other resources; unused here unless > 0).
cfg.requiredPoliceCount = 0
cfg.enableOldMethodForPoliceCount = false
-- ============================================================================
-- 2. TABLET & UI
-- ============================================================================
-- Chat command that opens the racing tablet. `/racing` by default.
cfg.command = 'racing' ---@type string
-- Inventory item that opens the racing tablet when used. Set to `false` to
-- disable item-gating (the /racing command always works).
cfg.tabletItem = 'rm_racing_tablet' ---@type string|false
-- NUI-specific UI tweaks. The TrackInfoPage's Leaflet preview renders a
-- GTA V tile background. Default points at the Rockstar Social Club tile
-- server (stable, dark styled). Set `tileUrl = false` for a blank
-- background that only shows the track polyline.
cfg.ui = {
tileUrl = 'https://s.rsg.sc/sc/images/games/GTAV/map/game/{z}/{x}/{y}.jpg', ---@type string|false
}
-- ============================================================================
-- 3. ECONOMY
-- ============================================================================
-- Money type used for entry fees and prizes.
cfg.moneyType = 'bank' ---@type 'cash' | 'bank'
-- ============================================================================
-- 4. USER TIERS & PERMISSIONS
--
-- Tier hierarchy is by INDEX, NOT by ELO threshold. Index 1 = highest;
-- the last entry is the default for everyone without an override. ELO-based
-- auto-assignment uses `min` (highest tier whose min the player meets). A
-- tier override on profile.tier (set via /createracinguser) wins over ELO.
-- ============================================================================
---@type { name: string, min: number }[]
cfg.tiers = {
{ name = 'God', min = 99999 }, -- never auto-assigned, must be granted
{ name = 'Master', min = 1850 },
{ name = 'Creator', min = 1700 },
{ name = 'Racer', min = 0 },
}
-- For each capability, the MINIMUM tier required. Anything at or above the
-- listed tier in cfg.tiers (lower index = higher tier) passes.
cfg.permissions = {
join = 'Racer', ---@type string -- join races / lobbies
create = 'Racer', ---@type string -- start a race (lobby or solo)
createTrack = 'Creator', ---@type string -- save a new track via the editor
createCrew = 'Racer', ---@type string -- found a crew
control = 'Master', ---@type string -- moderate own creations (delete tracks, etc.)
controlAll = 'God', ---@type string -- moderate everyone's creations
handleBounties = 'Master', ---@type string -- re-roll / cancel active bounties
runAdminCommands = 'God', ---@type string -- /createracinguser, /removeallracetracks etc.
}
-- ============================================================================
-- 5. PLAYER PROFILE DEFAULTS
-- ============================================================================
cfg.profile = {
pictureCount = 8, ---@type number -- number of presets in /web/public/profiles/1..N.png
checkpointColors = { 'orange', 'red', 'blue', 'navy', 'green', 'yellow', 'purple', 'white' },
gpsColors = { 'orange', 'red', 'blue', 'navy', 'green', 'yellow', 'purple', 'white' },
-- 3D checkpoint visual styles. 'classic' = the original tall translucent
-- pillar + sphere top. 'highway' = highway-style billboard sign on a
-- vertical pole, distance label updating live. 'nav' = GPS-style nav
-- panel (distance + direction arrow + street name from
-- GetStreetNameAtCoord). Persisted on profile.checkpoint_style
-- (default 'classic').
checkpointStyles = { 'classic', 'highway', 'nav' },
-- Default for the "show my 3D PlayerCard above my head to other
-- players" privacy preference. Each player can flip it individually
-- in their profile; new players inherit this default. Saved on
-- profile.card_visible (1 = visible, 0 = hidden).
cardVisibleByDefault = true,
nameChangeCost = 1000,
}
-- Crew emblem allow-list. Must mirror `web/src/constants/crewEmblems.ts`
-- exactly — server validates the picked emblem against this list before
-- inserting the crew, so a new icon there needs a new entry here too.
cfg.crew = {
emblems = {
'flag', 'trophy', 'crown', 'bolt', 'flame',
'skull', 'shield', 'swords', 'target', 'anchor',
'compass', 'gem', 'ghost', 'rocket', 'star',
'wrench', 'cog', 'eye', 'heart', 'crosshair',
},
}
-- ============================================================================
-- PlayerCard — in-world 3D nameplates rendered above racers / nearby players
--
-- Powered by rm_stream (DUI projected onto a billboard marker). The same
-- React PlayerCard component used in the tablet renders standalone via
-- `build/index.html?card=1&...`; one stream per visible player, attached
-- to their vehicle (preferred) or ped fallback. Distance-faded.
-- ============================================================================
cfg.playerCard = {
enabled = true, ---@type boolean
duringRace = true, ---@type boolean -- show above each racer's vehicle in-race
outOfRace = true, ---@type boolean -- show above nearby players' peds in free-roam
-- Render & culling. renderDistance is the same value rm_stream uses to
-- skip drawing — keep it tight to limit DUI overdraw on busy servers.
renderDistance = 50.0, ---@type number -- metres
maxConcurrent = 10, ---@type integer -- hard cap; closest-N kept, rest hidden
scanIntervalMs = 1000, ---@type integer -- free-roam scan cadence
-- Server-side profile cache TTL (seconds). A nearby-scan returns up to
-- maxConcurrent player summaries; cache means repeated scans don't slam
-- the DB if the same players hang around.
profileCacheSec = 30, ---@type number
-- Vertical offset above the attach entity. Vehicle uses model height +
-- this; ped uses ~head height + this. Tune per server vehicle pool.
vehicleOffsetZ = 0.8, ---@type number
pedOffsetZ = 0.6, ---@type number -- on top of head bone (already ~head height)
-- Card billboard sizing (passed to rm_stream). Width/height drive the
-- DUI texture resolution; scale is the world-space size of the marker
-- (1.0 ≈ 1 metre tall before distance falloff).
width = 600, ---@type integer -- DUI texture px
height = 200, ---@type integer
scale = 0.8, ---@type number -- world units
}
-- ============================================================================
-- 6. ELO RATING
-- ============================================================================
cfg.elo = {
initial = 1500, ---@type number -- starting rating for new players
kFactor = 32, ---@type number -- rating volatility (chess uses 10-40)
minParticipants = 1, ---@type number -- minimum racers required for ELO to apply
-- Display tiers shown on profiles / leaderboards (separate from cfg.tiers
-- which gates permissions). Purely cosmetic ranks based on ELO bands.
tiers = { ---@type { name: string, min: number }[]
{ name = 'Racer', min = 0 },
{ name = 'Host', min = 1600 },
{ name = 'Alien', min = 1850 },
},
}
-- ============================================================================
-- 7. RACE ENGINE
-- ============================================================================
cfg.race = {
countdownSec = 5, ---@type number -- 3-2-1-go countdown length
dnfTimeoutSec = 100, ---@type number -- racer kicked if still running this long after first finish
checkpointArriveDistance = 3.5, ---@type number -- on-foot trigger distance; vehicles use cp.radius
-- Players must be within this distance of cp1 when /start fires, otherwise
-- the race rejects start with a "too far from grid" modal.
maxDistanceFromGrid = 20.0,
-- Starting-grid layout. Racers are placed in a `columns` × ceil(N/columns)
-- grid behind cp1, all facing toward cp2.
grid = {
columns = 2, ---@type number -- racers per row
columnSpacing = 4.0, ---@type number -- m between side-by-side slots
rowSpacing = 5.0, ---@type number -- m between rows
backOffset = 4.0, ---@type number -- m added to cp1.radius for the front row
},
}
-- ============================================================================
-- 8. RACE TYPES
--
-- circuit = true → loops, supports laps
-- drift = true → drift scoring is the win condition
-- timeTrial → solo runs only, no lobby
-- elimination → last-place dropped each lap
-- ============================================================================
---@type { id: string, label: string, circuit: boolean, drift: boolean, timeTrial?: boolean, elimination?: boolean }[]
cfg.raceTypes = {
{ id = 'sprint', label = 'Sprint', circuit = false, drift = false },
{ id = 'circuit', label = 'Circuit', circuit = true, drift = false },
{ id = 'drift', label = 'Drift', circuit = false, drift = true },
{ id = 'drift_challenge', label = 'Drift challenge', circuit = true, drift = true },
{ id = 'time_trial', label = 'Time trial', circuit = false, drift = false, timeTrial = true },
{ id = 'elimination', label = 'Elimination', circuit = true, drift = false, elimination = true },
}
-- ============================================================================
-- 9. DRIFT SCORING
-- Used by drift & drift_challenge race types.
-- ============================================================================
cfg.drift = {
pointsPerSecond = 8, -- baseline points for sustained drift
angleThreshold = 12.0, -- degrees; below this, no drift
minSpeedMps = 10.0, -- metres/sec; below this, no drift
wallHitPenalty = 500, -- points lost when hitting a wall/entity mid-drift
comboMultiplierStep = 0.25, -- +25% points per sustained second up to max
comboMultiplierMax = 3.0,
tickMs = 100, -- scoring tick interval
}
-- ============================================================================
-- 10. TRACKS
-- ============================================================================
-- Creator rules — bounds enforced server-side at saveTrack.
cfg.track = {
minCheckpoints = 2,
maxCheckpoints = 300,
maxObjects = 600,
checkpointDefaultRadius = 15.0,
checkpointMinRadius = 10.0,
checkpointMaxRadius = 50.0,
creatorMoneyCost = 5000,
nameMaxLen = 40,
descriptionMaxLen = 140,
objectPlacementDistance = 3.5, ---@type number -- m in front of player for object preview spawn (fallback when raycast misses)
objectYawStep = 15.0,
}
-- Track tags shown on track cards.
cfg.trackTags = {
newTrackDays = 7, ---@type number -- track <= N days old → 'New'
popularMinTimesLastWeek = 25, ---@type number -- ≥ N races last week → 'Popular'
legendaryMinTimesDriven = 200, ---@type number -- ≥ N total races → 'Legendary'
}
-- "Author" of seed-tracks.sql tracks (creator_cid = ''). Substituted
-- server-side in decorateTrack so the listing UI doesn't fall back to
-- "Unknown" + default avatar. picture accepts:
-- - a numeric preset id '1'..'8' (web/public/profiles/N.png)
-- - a relative file ending in .png/.webp (web/public/, e.g.
-- 'eyescoloured.png' which ships alongside the NUI bundle)
-- - a full https:// URL (any image hostable to FiveM CEF)
cfg.seedTracks = {
creatorName = 'rm_racing',
creatorPicture = 'eyescoloured.png',
}
cfg.trackObjects = {
-- ============ Flags ============
{ id = 'flag_red', label = 'Red flag', model = 'prop_flagpole_2b' },
{ id = 'flag_blue', label = 'Blue flag', model = 'prop_flagpole_2c' },
{ id = 'flag_checkered', label = 'Checkered flag', model = 'prop_flagpole_2d' },
{ id = 'flag_beach_red', label = 'Beach flag (black)', model = 'prop_beachflag_01' },
{ id = 'flag_beach_blue', label = 'Beach flag (green)', model = 'prop_beachflag_02' },
-- ============ Tyres (single / pile) ============
{ id = 'tyre', label = 'Tyre', model = 'prop_wheel_tyre' },
{ id = 'tyre_stack', label = 'Tyre stack', model = 'prop_offroad_tyres02' },
{ id = 'tyre_offroad', label = 'Offroad tyre', model = 'prop_offroad_tyres01_tu' },
{ id = 'tyre_offroad_open', label = 'Offroad tyres (open)', model = 'prop_offroad_tyres01' },
{ id = 'tyre_snow', label = 'Snow tyre', model = 'prop_snow_tyre_01' },
{ id = 'tyre_industrial_1', label = 'Industrial tyre #1', model = 'v_ind_cm_tyre01' },
{ id = 'tyre_industrial_3', label = 'Industrial tyre #3', model = 'v_ind_cm_tyre03' },
{ id = 'tyre_industrial_6', label = 'Industrial tyre #6', model = 'v_ind_cm_tyre06' },
{ id = 'tyre_industrial_7', label = 'Industrial tyre #7', model = 'v_ind_cm_tyre07' },
{ id = 'tyre_procedural', label = 'Procedural tyre', model = 'ng_proc_tyre_01' },
{ id = 'tyre_junk_pile', label = 'Junk tyre cluster', model = 'v_46_cm_tyres' },
{ id = 'tyre_carware_pile', label = 'Carware tyre rack', model = 'imp_carwarecw_tyres' },
{ id = 'tyre_sea_pile', label = 'Sea tyre pile', model = 'ch1_12_sea_tyrepileb' },
{ id = 'tyre_shelves', label = 'Tyre shelves', model = 'v_71_tyreshelves' },
{ id = 'tyre_hoop_atomic', label = 'Atomic hoop tyre', model = 'stt_prop_hoop_tyre_01a' },
{ id = 'tyre_arrow', label = 'Arrow tyre', model = 'xs_prop_arrow_tyre_01a' },
{ id = 'tyre_gate_arch', label = 'Tyre gate arch', model = 'xs_prop_gate_tyre_01a_wl'},
-- ============ Tyre walls (basic) ============
{ id = 'tyre_wall', label = 'Tyre wall', model = 'prop_tyre_wall_03b' },
{ id = 'tyre_wall_short', label = 'Tyre wall (short)', model = 'prop_tyre_wall_01' },
{ id = 'tyre_wall_rolled', label = 'Tyre wall (rolled)', model = 'prop_tyre_wall_03' },
{ id = 'tyre_wall_mid', label = 'Tyre wall (mid)', model = 'prop_tyre_wall_03c' },
{ id = 'tyre_wall_yellow', label = 'Tyre wall (yellow)', model = 'prop_tyre_wall_04' },
{ id = 'tyre_wall_heavy', label = 'Tyre wall (heavy)', model = 'prop_tyre_wall_05' },
{ id = 'tyre_wall_curved', label = 'Tyre wall (curved)', model = 'xs_prop_wall_tyre_l_01a' },
{ id = 'tyre_wall_u_curve', label = 'Tyre wall (U-curve)', model = 'tr_prop_tr_tyre_wall_u_l'},
-- ============ Stunt tyre walls — straight (sponsor liveries) ============
{ id = 'stt_wall_basic', label = 'Stunt wall #1', model = 'stt_prop_tyre_wall_01' },
{ id = 'stt_wall_shitzu', label = 'Shitzu wall', model = 'stt_prop_tyre_wall_02' },
{ id = 'stt_wall_sprunk', label = 'Sprunk wall', model = 'stt_prop_tyre_wall_03' },
{ id = 'stt_wall_xero', label = 'Xero wall', model = 'stt_prop_tyre_wall_04' },
{ id = 'stt_wall_pisswasser', label = 'Pißwasser wall', model = 'stt_prop_tyre_wall_05' },
{ id = 'stt_wall_burgershot', label = 'Burger Shot wall', model = 'stt_prop_tyre_wall_06' },
{ id = 'stt_wall_cheetah', label = 'Cheetah wall', model = 'stt_prop_tyre_wall_07' },
{ id = 'stt_wall_globeoil', label = 'Globe Oil wall', model = 'stt_prop_tyre_wall_08' },
{ id = 'stt_wall_vapid', label = 'Vapid wall', model = 'stt_prop_tyre_wall_09' },
{ id = 'stt_wall_chevron', label = 'Chevron wall (black)', model = 'stt_prop_tyre_wall_010' },
{ id = 'stt_wall_patriot', label = 'Patriot wall', model = 'stt_prop_tyre_wall_011' },
{ id = 'stt_wall_pisswasser2', label = 'Pißwasser wall #2', model = 'stt_prop_tyre_wall_012' },
{ id = 'stt_wall_imponte_p', label = 'Imponte wall (purple)', model = 'stt_prop_tyre_wall_013' },
{ id = 'stt_wall_imponte_b', label = 'Imponte wall (black)', model = 'stt_prop_tyre_wall_014' },
{ id = 'stt_wall_fukaru_f', label = 'Fukaru F wall', model = 'stt_prop_tyre_wall_015' },
{ id = 'stt_wall_atomic_g', label = 'Atomic wall (green)', model = 'stt_prop_tyre_wall_016' },
{ id = 'stt_wall_pisswasser3', label = 'Pißwasser wall #3', model = 'stt_prop_tyre_wall_017' },
{ id = 'stt_wall_imponte_w', label = 'Imponte wall (white)', model = 'stt_prop_tyre_wall_018' },
-- ============ Stunt tyre walls — curved (L = left bend, R = right bend) ============
{ id = 'stt_curve_l3', label = 'Fukaru curve (L)', model = 'stt_prop_tyre_wall_0l3' },
{ id = 'stt_curve_r3', label = 'Fukaru curve (R)', model = 'stt_prop_tyre_wall_0r3' },
{ id = 'stt_curve_r1', label = 'Tyre wall curve (R)', model = 'stt_prop_tyre_wall_0r1' },
{ id = 'stt_curve_l2', label = 'Sprunk curve (L)', model = 'stt_prop_tyre_wall_0l2' },
{ id = 'stt_curve_l04', label = 'Xero curve (L)', model = 'stt_prop_tyre_wall_0l04' },
{ id = 'stt_curve_r04', label = 'Xero curve (R)', model = 'stt_prop_tyre_wall_0r04' },
{ id = 'stt_curve_l05', label = 'Sprunk curve (L)', model = 'stt_prop_tyre_wall_0l05' },
{ id = 'stt_curve_r05', label = 'Atomic curve (R)', model = 'stt_prop_tyre_wall_0r05' },
{ id = 'stt_curve_l06', label = 'Auto Exotic curve (L)', model = 'stt_prop_tyre_wall_0l06' },
{ id = 'stt_curve_r06', label = 'Pißwasser curve (R)', model = 'stt_prop_tyre_wall_0r06' },
{ id = 'stt_curve_l07', label = 'Fukaru curve (L)', model = 'stt_prop_tyre_wall_0l07' },
{ id = 'stt_curve_r07', label = 'Vapid curve (R)', model = 'stt_prop_tyre_wall_0r07' },
{ id = 'stt_curve_l08', label = 'Cheetah curve (L)', model = 'stt_prop_tyre_wall_0l08' },
{ id = 'stt_curve_r08', label = 'Cheetah curve (R)', model = 'stt_prop_tyre_wall_0r08' },
{ id = 'stt_curve_r09', label = 'Globe Oil curve (R)', model = 'stt_prop_tyre_wall_0r09' },
{ id = 'stt_curve_l010', label = 'Globe Oil curve (L)', model = 'stt_prop_tyre_wall_0l010'},
{ id = 'stt_curve_r010', label = 'Vapid curve (R)', model = 'stt_prop_tyre_wall_0r010'},
{ id = 'stt_curve_l012', label = 'Vapid curve (L)', model = 'stt_prop_tyre_wall_0l012'},
{ id = 'stt_curve_r012', label = 'Xero curve (R)', model = 'stt_prop_tyre_wall_0r012'},
{ id = 'stt_curve_l013', label = 'Junk Energy curve (L)', model = 'stt_prop_tyre_wall_0l013'},
{ id = 'stt_curve_r013', label = 'Nagasaki curve (R)', model = 'stt_prop_tyre_wall_0r013'},
{ id = 'stt_curve_l014', label = 'Cheetah curve (L)', model = 'stt_prop_tyre_wall_0l014'},
{ id = 'stt_curve_r014', label = 'Xero curve (R)', model = 'stt_prop_tyre_wall_0r014'},
{ id = 'stt_curve_l015', label = 'Nagasaki curve (L)', model = 'stt_prop_tyre_wall_0l015'},
{ id = 'stt_curve_r015', label = 'Burger Shot curve (R)', model = 'stt_prop_tyre_wall_0r015'},
{ id = 'stt_curve_l016', label = 'Atomic curve (L)', model = 'stt_prop_tyre_wall_0l016'},
{ id = 'stt_curve_l16', label = 'Fukaru green curve', model = 'stt_prop_tyre_wall_0l16' },
{ id = 'stt_curve_l017', label = 'Pißwasser curve (L)', model = 'stt_prop_tyre_wall_0l017'},
{ id = 'stt_curve_r017', label = 'Fukaru curve (R)', model = 'stt_prop_tyre_wall_0r017'},
{ id = 'stt_curve_l018', label = 'Imponte curve (L)', model = 'stt_prop_tyre_wall_0l018'},
{ id = 'stt_curve_r018', label = 'Nagasaki curve (R)', model = 'stt_prop_tyre_wall_0r018'},
{ id = 'stt_curve_l019', label = 'Fukaru curve (L)', model = 'stt_prop_tyre_wall_0l019'},
{ id = 'stt_curve_r019', label = 'Fukaru curve (R)', model = 'stt_prop_tyre_wall_0r019'},
{ id = 'stt_curve_l020', label = 'Fukaru F curve (L)', model = 'stt_prop_tyre_wall_0l020'},
-- ============ Chevron / direction walls (Tuner DLC arrows + lit panels) ============
{ id = 'chevron_lit', label = 'Chevron wall (lit)', model = 'sum_prop_ac_tyre_wall_lit_01' },
{ id = 'chevron_lit_l', label = 'Chevron wall lit (L)', model = 'sum_prop_ac_tyre_wall_lit_0l1' },
{ id = 'chevron_lit_r', label = 'Chevron wall lit (R)', model = 'sum_prop_ac_tyre_wall_lit_0r1' },
{ id = 'chevron_arrow_l', label = 'Chevron arrow (L)', model = 'sum_prop_ac_tyre_wall_u_l' },
{ id = 'chevron_arrow_r', label = 'Chevron arrow (R)', model = 'sum_prop_ac_tyre_wall_u_r' },
{ id = 'pit_arrow_l', label = 'PITS arrow (L)', model = 'sum_prop_ac_tyre_wall_pit_l' },
{ id = 'pit_arrow_r', label = 'PITS arrow (R)', model = 'sum_prop_ac_tyre_wall_pit_r' },
-- ============ Special ============
{ id = 'wall_nitrous', label = 'Nitrous boost wall', model = 'm24_2_prop_m42_tyre_wall_nos' },
-- ============ Cones / barriers / barrels / bales ============
{ id = 'cone', label = 'Traffic cone', model = 'prop_mp_cone_01' },
{ id = 'barrier', label = 'Barrier', model = 'prop_mp_barrier_02' },
{ id = 'barrel', label = 'Barrel', model = 'prop_barrel_02a' },
{ id = 'hay_bale', label = 'Hay bale', model = 'prop_offroad_bale01'},
}
-- ============================================================================
-- 11. COMPETITIONS
-- Auto-generated competition lobbies + manual competition rules.
-- ============================================================================
cfg.competition = {
-- Local server time HH:MM. Set to {} to disable the auto-scheduler.
autoSchedule = {
'12:00',
'16:00',
'19:00',
'22:00',
},
lobbyDurationSec = 900, ---@type number -- 15 min lobby before scheduler auto-starts (or auto-cancels if empty)
minRatingToHost = 1700, ---@type number -- min ELO to start a manual competition
prizePoolPerPlayer = 2500, ---@type number -- added to pool for each joined racer
-- Percent per finishing position; must sum to 100.
prizeDistribution = {
50, 25, 15, 10,
},
-- Vehicle classes pickable in lobby setup. id = -1 means "any class".
vehicleClasses = { ---@type { id: number, label: string }[]
{ id = -1, label = 'Any' },
{ id = 0, label = 'Compacts' },
{ id = 1, label = 'Sedans' },
{ id = 2, label = 'SUVs' },
{ id = 3, label = 'Coupes' },
{ id = 4, label = 'Muscle' },
{ id = 5, label = 'Sports Classics' },
{ id = 6, label = 'Sports' },
{ id = 7, label = 'Super' },
},
defaultMaxPlayers = 8,
phasingDefault = true,
-- Slipstream (drafting) — flips the engine's built-in slipstream
-- physics for the duration of the race via SetEnableVehicleSlipstreaming.
-- Global toggle (not per-vehicle), called once on start and once on end.
slipstreamDefault = false,
-- Private routing bucket — when on, race start moves every participant
-- (and their vehicle) into an isolated server bucket so non-racers in
-- the public world don't collide / desync with the race. Race end
-- restores everyone to bucket 0. Voice does NOT respect buckets —
-- proximity voice still bleeds through.
privateBucketDefault = false,
}
-- ============================================================================
-- 12. PINK SLIPS — wager your vehicle ownership in a 1v1 race.
--
-- The losing driver's vehicle gets transferred to the winner via the
-- framework bridge (qb/qbx → player_vehicles, esx → owned_vehicles).
-- Standalone has no inventory of vehicles, so the toggle is hidden in
-- the lobby UI when running standalone.
-- Claims are pending until the winner visits a redeemLocations entry and
-- interacts there — physical delivery, not a silent DB swap.
-- ============================================================================
cfg.pinkSlips = {
enabled = true,
-- Race types this flag CAN be applied to. Drift / elimination / TT are
-- excluded — pink slips need a clean position-based winner.
allowedTypes = { 'sprint', 'circuit' }, ---@type string[]
-- Forfeit window: if either player DNFs, the race still resolves and
-- the surviving racer claims. Set false to require both to finish.
awardOnDnf = true,
-- Where the winner picks up the vehicle. Each entry produces a blip
-- and a small interaction zone. Add as many as you like.
redeemLocations = {
{ x = 100.0, y = -1080.0, z = 29.2, label = 'Pink Slip Garage (Mission Row)' },
},
redeemBlip = {
sprite = 357, ---@type number
color = 1, ---@type number -- 1 = red
scale = 0.85,
label = 'Pink Slip Redeem',
},
}
-- ============================================================================
-- 13. BOUNTIES — time-trial chase prizes.
--
-- A scheduled job rolls one active bounty at a time. When a player runs
-- the bountied track in a Time Trial mode and finishes UNDER the
-- target_ms, they claim the prize. Bounties expire after `expireMin` if
-- unclaimed.
-- ============================================================================
cfg.bounties = {
enabled = true,
intervalMin = 30, ---@type number -- new roll every N minutes (also re-rolls if previous claimed/expired)
expireMin = 240, ---@type number -- auto-expire after N minutes (0 = never)
prize = 75000, ---@type number -- credits paid to the claimer
eligibleTrackTypes = { 'time_trial', 'sprint', 'circuit' }, ---@type string[]
requireRank = false, ---@type string|false -- e.g. 'Master' to gate claims; false = open
minResultsOnTrack = 0, ---@type number -- 0 = never block on race count (random track gets picked even on fresh DBs)
-- Target time formula. Bounty is computed as `best_ms * targetMult + random(extraMs)`.
-- 1.0 + small variance keeps it tight for top players; pad it (e.g. 1.10 →
-- 10% slower than best) for casual servers.
targetMult = 1.05,
extraMs = { min = 0, max = 3000 },
-- Fallback target for tracks with NO best time yet (fresh server / no
-- results on the picked track). Target = checkpoints_count × this value.
-- ~5 s per CP is a generous ballpark; tweak if your tracks are unusually
-- short or long.
fallbackMsPerCp = 5000,
}
-- ============================================================================
-- 14. ITEM PAYOUTS
--
-- Item rewards distributed alongside money prizes when a race finishes.
-- Each `lists.` is a weighted pool: an entry's `weight` is the chance
-- relative to the sum of weights in its list; `count` is rolled uniformly
-- in [min, max]. payoutStyle picks WHO gets a roll:
-- 'all' → every finisher gets one roll
-- 'topThree' → positions 1..3 each roll
-- 'onlyOne' → only the winner rolls
-- 'custom' → uses `perPosition[pos]` to pick which list(s) to roll
-- ============================================================================
cfg.itemPayouts = {
enabled = true, ---@type boolean -- enable when item names below exist in your inventory
defaultList = 'standard', ---@type string -- list rolled for non-custom styles
payoutStyle = 'topThree', ---@type 'all'|'topThree'|'onlyOne'|'custom'
minRaceLengthSec = 10, ---@type number -- skip payouts for short fluke races
onlyCompetitions = false, ---@type boolean -- if true, only ranked competitions drop items
---@type table
lists = {
standard = {
{ item = 'water', weight = 8, count = { min = 1, max = 3 } },
{ item = 'sandwich', weight = 6, count = { min = 1, max = 2 } },
{ item = 'lockpick', weight = 2, count = { min = 1, max = 1 } },
},
rare = {
{ item = 'lockpick', weight = 4, count = { min = 1, max = 2 } },
{ item = 'advancedlockpick', weight = 1, count = { min = 1, max = 1 } },
},
},
-- Only used when payoutStyle = 'custom'.
---@type table
perPosition = {
[1] = { 'rare', 'standard' },
[2] = { 'standard' },
[3] = { 'standard' },
},
}
-- ============================================================================
-- 15. 3D GPS ROUTE RENDERER
--
-- During a race the upcoming checkpoint polyline is drawn in 3D world
-- space so the player can follow the route without taking their eyes off
-- the road to glance at the minimap. Color is per-player (profile.gps_color)
-- and style is per-player (profile.gps_route_type). Set `enabled = false`
-- to disable the entire renderer.
-- ============================================================================
cfg.gps3d = {
enabled = true,
-- Number of upcoming checkpoints to render ahead of the player. 1 = next
-- one only; higher = full path preview (more drawcalls per frame).
lookahead = 4,
-- Default style; each player can override via profile.gps_route_type:
-- 'off' → nothing drawn
-- 'line' / 'arrow'→ legacy DrawLine-based renderer (no YTD needed)
-- any preset id → textured ribbon using the asset in stream/ (chevrons.ytd)
defaultStyle = 'classic',
-- Lift the line a hair above the road so it doesn't z-fight on inclines
-- but stays close to the surface — the car effectively drives over it
-- instead of under a floating ribbon.
heightOffset = 0.1,
-- Chevron arrow spacing (m) and dimensions for the LEGACY DrawLine path.
arrowSpacing = 6.0,
arrowLength = 1.6,
arrowWidth = 0.9,
-- Textured ribbon (preset) parameters. The YTD ships in stream/ — its
-- internal texture-dictionary name is what RequestStreamedTextureDict
-- expects (usually 'chevrons' even if the .ytd file was renamed).
textureDict = 'routes',
ribbonWidth = 1.35, -- half-width of the ribbon (m), so total = 2.7m
ribbonLift = 0.05, -- extra Z offset on top of heightOffset
ribbonRepeatM = 4.0, -- texture repeats every N metres along the path
-- Preset list. `id` is what gets stored in profile.gps_route_type;
-- `texture` is the entry inside textureDict to sample. Order here drives
-- the order shown in the profile picker.
--
-- Per-preset `repeatM` overrides the global ribbonRepeatM. Per-preset
-- `tintable = false` skips the player's gps_color tint and draws the
-- texture with white modulation, preserving the colors baked into the
-- texture itself. Per-preset `alpha` overrides the default 230 — the
-- chevron_line textures have an opaque white background in their alpha
-- channel, so we drop alpha to fade the slab and keep the chevrons
-- the dominant element.
presets = {
{ id = 'classic', label = 'Classic', texture = 'chevrons', repeatM = 4.0, tintable = true },
{ id = 'chevron_line_06', label = 'Line 06', texture = 'chevron_line_06', repeatM = 0.8, tintable = false, alpha = 130 },
{ id = 'chevron_line_07', label = 'Line 07', texture = 'chevron_line_07', repeatM = 0.8, tintable = false, alpha = 130 },
{ id = 'chevron_line_08', label = 'Line 08', texture = 'chevron_line_08', repeatM = 0.8, tintable = false, alpha = 130 },
{ id = 'chevron_fire_01', label = 'Fire', texture = 'chevron_fire_01', repeatM = 4.0, tintable = true },
{ id = 'chevron_ice_01', label = 'Ice', texture = 'chevron_ice_01', repeatM = 4.0, tintable = true },
{ id = 'chevron_neon_01', label = 'Neon', texture = 'chevron_neon_01', repeatM = 4.0, tintable = true },
},
}
-- ============================================================================
-- 16. DISCORD WEBHOOKS — config moved to server/webhook.lua
--
-- The webhook URL is sensitive credential data and must NOT live in cfg.lua,
-- which is shipped/escrowed as part of the resource. server/webhook.lua is
-- listed in escrow_ignore so customers can edit the URL after install
-- without seeing the rest of the source. Set `WEBHOOK_URL` at the top of
-- that file.
-- ============================================================================
-- ============================================================================
-- 17. LIMITS — page sizes / row caps
-- ============================================================================
cfg.limits = {
tracksPerRequest = 500,
leaderboardSize = 100,
recentEventsCount = 10,
recentRacesCount = 100,
trackBestResults = 10,
}
```
### Heist Configuration
```
Config.heist = {
--------------------------
----- QUIET APPROACH -----
--------------------------
terminalHacking = {
coords = vector3(-623.15, -216.22, 53.54),
requiredItem = "hacker_phone",
removeItemOnUse = false,
-- minigame options
minigame = "none",
duration = 60, -- duration of hack minigame in seconds
solutionLength = 5, -- length of the solution string
policeAlertDuration = 30, -- seconds (after the hacking incident should the police be alerted)
},
plantingGasBomb = {
ventModel = "prop_aircon_m_04", -- model of the vent where the bomb should be planted
coords = vector3(-631.13, -228.23, 55.65),
offset = vector3(-0.83, -0.5, 0.8), -- offset from the coords where the bomb should be planted (relative to the vent)
requiredItem = "gas_bomb",
removeItemOnUse = true,
mask = {
enable = true,
requiredItem = "gas_mask",
removeItemOnUse = true,
clotheId = 175,
duration = 300, -- duration of the gas mask effect in seconds
damage = 5, -- damage dealt to the player every interval while the gas mask is active
damageInterval = 5, -- interval in seconds at which the damage is applied to the player while the gas mask is active
zone = vector4(-622.364, -231.020, 38.047, 11.0)
},
-- minigame options
minigame = "none",
},
--------------------------
----- LOUD APPROACH ------
--------------------------
vangelicoEntrance = {
coords = vector3(-631.760, -237.737, 38.073),
lockpick = {
requiredItem = "lockpick",
removeItemOnUse = true,
strength = 0.1, -- from 0.1 (easy) to 7 (hard)
difficulty = 0.1, -- from 0.1 (easy) to 7 (hard)
pins = 2, -- number of pins (max 9)
-- minigame options
minigame = "none",
},
thermite = {
offset = vector3(1.3, -0.03, 0.0),
requiredItem = "thermite_bomb",
removeItemOnUse = true,
-- minigame options
minigame = "default",
},
},
-------------------------
---- GENERAL OPTIONS ----
-------------------------
keypad = {
coords = vector3(-629.135, -230.949, 38.057),
searchCoords = {
vector3(-625.925, -226.127, 38.057),
vector3(-623.040, -235.807, 38.057),
vector3(-618.774, -236.339, 38.057),
vector3(-617.183, -231.740, 38.057),
vector3(-621.453, -225.867, 38.057),
vector3(-622.500, -229.772, 38.057),
vector3(-630.369, -232.243, 38.057)
},
},
doors = {
{ -- front doors
door_1_model = 1425919976,
door_2_model = 9467943,
door_1_coords = vector4(-631.95538330078, -236.33326721191, 38.206531524658, 306.60577392578),
door_2_coords = vector4(-630.42651367188, -238.43754577637, 38.206531524658, 305.39260864258),
status = "locked", -- "locked", "unlocked"
},
{ -- security room door
door_1_model = 1335309163,
door_1_coords = vector4(-629.13385009766, -230.15170288086, 38.20658493042, 36.000022888184),
status = "locked", -- "locked", "unlocked"
}
},
---------------------------
----- LOOTABLE OPTIONS ----
---------------------------
containers = {
-- Weapons allowed to smash jewelry cabinets (whitelisted weapons)
smashWeapons = {
'WEAPON_ASSAULTRIFLE',
'WEAPON_CARBINERIFLE',
'WEAPON_ADVANCEDRIFLE',
'WEAPON_BULLPUPRIFLE',
},
-- required items for certain loot actions:
requiredItems = {
paintings = {
requiredItem = "painting_knife",
removeItemOnUse = false,
},
displayCases = {
requiredItem = "glass_cutter",
removeItemOnUse = false,
},
statues = {
requiredItem = "bag",
removeItemOnUse = false,
}
},
-- Cabinets:
cabinets = {
{
coords = vector4(-626.83, -235.35, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-625.81, -234.7, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-626.95, -233.14, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-628.0, -233.86, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-625.7, -237.8, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-626.7, -238.58, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-624.55, -231.06, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.13, -232.94, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.29, -234.44, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.15, -233.66, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.19, -233.44, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-617.63, -230.58, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-618.33, -229.55, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.7, -230.33, 38.05, 125.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.95, -228.6, 38.05, 125.0),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-619.79, -227.6, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-620.42, -226.6, 38.05, 305.0),
rayFire = 'DES_Jewel_Cab',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.94, -227.18, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab4',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-624.91, -227.87, 38.05, 36.17),
rayFire = 'DES_Jewel_Cab3',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
},
{
coords = vector4(-623.94, -228.05, 38.05, 216.17),
rayFire = 'DES_Jewel_Cab2',
rewards = {
{ itemName = "ring", amount = { min = 1, max = 2 } },
{ itemName = "necklace", amount = { min = 1, max = 3 } },
}
}
},
-- Paintings:
paintings = {
{
model = 'h4_prop_h4_painting_01h',
coords = vector4(-627.21325683594, -228.30999755859, 38.106048583984, 92.391586303711),
rewards = {
{ itemName = "painting_01h", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01d',
coords = vector4(-622.79998779297, -225.13999938965, 38.106048583984, 339.9309387207),
rewards = {
{ itemName = "painting_01d", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01e',
coords = vector4(-617.0, -233.2200012207, 38.106048583984, 271.89691162109),
rewards = {
{ itemName = "painting_01e", amount = { min = 1, max = 1 } },
}
},
{
model = 'h4_prop_h4_painting_01b',
coords = vector4(-621.36102294922, -236.33099365234, 38.106048583984, 161.18635559082),
rewards = {
{ itemName = "painting_01b", amount = { min = 1, max = 1 } },
}
}
},
-- Display Cases:
displayCases = {
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_diamond_disp_01a",
rewardModel = "h4_prop_h4_diamond_01a",
coords = vector4(-617.4622, -227.4347, 37.057, 127.06),
rewardOffset = vector3(0.0, 0.0, 1.225),
rewards = {
{ itemName = "big_diamond", amount = 1 },
}
},
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_diamond_disp_01a",
rewardModel = "h4_prop_h4_art_pant_01a",
coords = vector4(-631.7185, -234.6784, 36.9402, -53.705),
rewardOffset = vector3(0.0, 0.0, 1.25),
rewards = {
{ itemName = "panther", amount = 1 },
}
},
{
baseModel = "h4_prop_h4_glass_disp_01a",
displayModel = "h4_prop_h4_neck_disp_01a",
rewardModel = "h4_prop_h4_necklace_01a",
coords = vector4(-628.8231, -238.7317, 36.8647, -53.705),
rewardOffset = vector3(0.0, 0.0, 1.2),
rewards = {
{ itemName = "diamond_necklace", amount = 1 },
}
}
},
-- Statues:
statues = {
{
tableModel = "v_ret_tablesml",
statueModel = "vw_prop_casino_art_panther_01b",
coords = vector4(-622.04541015625, -230.70222473145, 37.058856964111, 303.0),
rewards = {
{ itemName = "panther_statue", amount = { min = 1, max = 1 } },
}
}
},
-- Safes:
safes = {
{
model = "h4_prop_h4_safe_01a",
coords = vector4(-630.88995361328, -228.27618408203, 36.959362030029, 35.38557434082),
difficulty = 1, -- 1-4 (1 being the easiest, 4 being the hardest)
rewards = {
{ itemName = "money", amount = { min = 500, max = 1500 } },
}
}
}
},
}
Config.missionData = {
takePhoto = {
vector3(-632.86, -238.62, 38.07),
vector3(-623.01, -216.17, 53.54),
vector3(-622.48, -233.67, 59.16),
vector3(-623.24, -231.54, 38.06),
vector3(-626.04, -238.05, 38.06),
vector3(-629.15, -230.69, 38.06)
},
takeEquipment = {
pedModel = "g_m_y_mexgang_01",
coords = {
vector4(591.996, 2782.770, 42.481, 8.644)
},
items = {
{
name = "hacker_phone",
amount = 1
},
{
name = "gas_bomb",
amount = 1
},
{
name = "gas_mask",
amount = 4
},
{
name = "glass_cutter",
amount = 1
},
{
name = "painting_knife",
amount = 1
},
{
name = "bag",
amount = 1
},
}
},
takeClothes = {
pedModel = "s_m_m_autoshop_02",
coords = {
vector4(632.676, -3015.434, 6.336, 359.265)
},
items = {
{
name = "outfit_bag",
amount = 1
}
}
},
}
```
# Blackmarkets: Player-Run Contraband Operation
{% hint style="warning" %}
**Pre-Installation Note**
This guide assumes you already know how to manage a FiveM server (start resources, run SQL, edit configs). Following the steps out of order is the most common cause of errors.
**Support**
If something isn't working after you've followed every step, open a ticket in our [Discord](https://discord.gg/rainmad) and include your server console output. Don't skip the [Installation](/resources/blackmarkets-player-run-contraband-operation/installation) and [Dependencies](/resources/blackmarkets-player-run-contraband-operation/dependencies) pages.
{% endhint %}
Blackmarket is a player-run dealing operation built around a hidden warehouse. Players order supply that drops somewhere on the map, build up stock, then take a cargo van out for a mobile street sale while police try to find and seize it. Buyers reach vendors through a phone app, and each warehouse is run like a small business: a shared vault, crew permissions, pricing and analytics.
It works on QBCore/Qbox and ESX (auto-detected), and bridges to whatever target, notification, dispatch, phone and vehicle-key resources you already run.
## Features
* **Warehouses:** an instanced underground warehouse per owner, created by an admin, with a laptop that runs the whole operation.
* **Supply orders & drops:** order goods from the vault, wait out a scaling ETA, then collect the drop from a random map location before the police get there.
* **Cargo van:** load stock into a van and take it out for a mobile sale. Weight/slot capacity, a stable plate, and a replacement flow after a seizure or destruction.
* **Van sales:** sell to walk-up customers through a basket UI with a live item-preview camera, and optionally broadcast the sale publicly with a police dispatch.
* **NPC vendor:** scheduled NPC sellers that drive in, park, sell, and depart on a real-world or in-game clock, set up from the admin panel.
* **Police gameplay:** officers can search or seize the van and destroy its cargo, with optional live van tracking and dispatch alerts.
* **Crew & permissions:** hire members with per-action permissions (place orders, drive, set prices, manage the vault, answer the door, and more) from role presets.
* **Shared vault & analytics:** orders are paid from the vault and sales drop back into it, with a 30-day dashboard for revenue, top items, top sellers and activity.
* **Phone app:** buyers browse public vendors, start an anonymous chat, and receive live van locations. Vendors reply and block abusive contacts from the laptop inbox.
* **Door & knock system:** guests knock, the crew admits or rejects them, and each warehouse runs in its own routing bucket.
* **Admin panel:** create and delete warehouses, edit drops and NPC vendors in-world, inspect stock/vault/members, and read a full audit log.
* **Discord logging:** categorized webhook logs for admin, economy, police, social and security events.
* **Black money support:** pay out in cash, a black-money item, an account, or marked bills.
## Preview
{% embed url="" %}
## Dependencies
A framework, `ox_lib`, `oxmysql` and a target/inventory resource are required. See the full list on the [Dependencies](/resources/blackmarkets-player-run-contraband-operation/dependencies) page before installing.
## Next steps
1. [Dependencies](/resources/blackmarkets-player-run-contraband-operation/dependencies)
2. [Installation](/resources/blackmarkets-player-run-contraband-operation/installation)
3. [Configuration](/resources/blackmarkets-player-run-contraband-operation/configuration)
# Dependencies
Install and start every **required** dependency *before* the Blackmarket resource. Optional resources only need to be present if you want the feature they power.
## Required
| Resource | Purpose | Notes |
| ------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Framework** | Player data, money, jobs | `QBCore` / `Qbox` or `ESX`. Auto-detected by default (`cfg.bridge.framework = 'auto'`). |
| [**ox\_lib**](https://github.com/overextended/ox_lib) | UI, callbacks, locales, caching | Required by the whole resource. Must start before Blackmarket. |
| [**oxmysql**](https://github.com/overextended/oxmysql) | Database | All tables are created automatically on first start — no SQL import needed. |
| **Inventory** | Items, weapons, item images | Uses your server's existing inventory. Every entry in `cfg.items` must exist in it (as an item or a weapon). |
| **Target** | World interactions | `ox_target` or `qb-target`. Auto-detected (`cfg.bridge.target = 'auto'`). |
## Optional
| Resource | Powers | Config key |
| --------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------ |
| **lb-phone** / **yseries** | The Blackmarket phone app (vendor chat) | `cfg.bridge.phone` |
| **Dispatch system** | Police alerts for drops & public sales | `cfg.bridge.dispatch` |
| **Vehicle keys** | Hand the van keys to the driver | `cfg.bridge.vehiclelock` |
| **Notification / TextUI / Progressbar** | Visual style of prompts and notifies | `cfg.bridge.notification`, `cfg.bridge.textUI`, `cfg.bridge.progressbar` |
{% hint style="info" %}
The bridge ships built-in adapters for notifications, text UI and progress bars, so the script runs without any of those resources. Point the matching `cfg.bridge.*` key at your own resource to use it instead. See [Phone & Integrations](/resources/blackmarkets-player-run-contraband-operation/phone-and-integrations) for the full list of supported resources.
{% endhint %}
## No external screenshot resource
Member and owner mugshots are generated with native ped-headshot APIs, so you **do not** need `screenshot-basic` or any image-host resource.
# Installation
{% stepper %}
{% step %}
## Install dependencies
Make sure every resource on the [Dependencies](/resources/blackmarkets-player-run-contraband-operation/dependencies) page is installed and starts **before** Blackmarket. At minimum: your framework, `ox_lib`, `oxmysql`, an inventory and a target resource.
{% endstep %}
{% step %}
## Add the resource
1. Download the asset from the FiveM Keymaster (Granted Assets) or your order, and unzip it.
2. Drop the `rm_blackmarkets` folder into your server's `resources` directory (for example `resources/[rainmad]/rm_blackmarkets`).
{% hint style="danger" %}
Do **not** rename the resource folder. It must stay `rm_blackmarkets` — the database tables, state bags and events are all keyed to that name.
{% endhint %}
{% endstep %}
{% step %}
## Start the resource
Add it to your `server.cfg`, after its dependencies:
```cfg
ensure oxmysql
ensure ox_lib
ensure ox_inventory # or your inventory
ensure ox_target # or qb-target
ensure rm_blackmarkets
```
{% endstep %}
{% step %}
## Database
There is **nothing to import**. On the first start the resource creates its tables automatically through `oxmysql`:
* `rm_blackmarkets_warehouses`, `rm_blackmarkets_members`, `rm_blackmarkets_inventory`, `rm_blackmarkets_orders`
* `rm_blackmarkets_sales_log`, `rm_blackmarkets_vault_log`, `rm_blackmarkets_audit_log`
* phone tables (only when `cfg.bridge.phone` isn't `false`): `rm_blackmarkets_warehouse_public`, `rm_blackmarkets_conversations`, `rm_blackmarkets_messages`
{% endstep %}
{% step %}
## Register your items
Every item in `cfg.items` (weapons, ammo, drugs, tools…) must already exist in your **inventory**. Items that are not registered there cannot be ordered, stocked or sold. See [How to Add an Item](/resources/blackmarkets-player-run-contraband-operation/how-to-add-an-item).
{% endstep %}
{% step %}
## Grant admin access
By default, anyone with FiveM's built-in `command` ace (the server console, usually `group.admin`) can open the admin panel. To allow specific staff without that ace, add their identifiers to `cfg.admin.allowedIdentifiers`. Then run the command (default `/bm_admin`) in-game to create your first warehouse.
```lua
cfg.admin = {
command = 'bm_admin',
allowedIdentifiers = {
['license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] = true,
},
}
```
See [Admin Panel](/resources/blackmarkets-player-run-contraband-operation/admin-panel) for what the panel can do.
{% endstep %}
{% step %}
## Configure
Open `cfg.lua` and set your framework/target, currency, items, warehouse coordinates, police jobs and the rest. The [Configuration](/resources/blackmarkets-player-run-contraband-operation/configuration) page walks through every section.
{% hint style="success" %}
After your first start, type `/bm_admin`, create a warehouse, and assign it an owner.
{% endhint %}
{% endstep %}
{% endstepper %}
# Configuration
Everything is configured in **`cfg.lua`**. After editing, restart the resource (`ensure rm_blackmarkets`).
## Locale & bridge
```lua
cfg.locale = 'en' -- locale file in /locales (en.json by default)
cfg.bridge = {
framework = 'auto', -- 'auto' | 'qb' | 'esx'
target = 'auto', -- 'auto' | 'ox_target' | 'qb-target' | false
notification = 'builtin', -- builtin | ox_lib | qb | esx | okokNotify | ps-ui | lation_ui | wasabi_notify | zsxui
textUI = 'builtin', -- builtin | ox_lib | esx | qb | okokTextUI | jg-textui
progressbar = 'builtin', -- builtin | ox_lib | qb | esx | wasabi_uikit | lation_ui | zsxui | false
vehiclelock = 'auto', -- auto | false | qb-vehiclekeys | wasabi_carlock | qs-vehiclekeys | ... | jaksam
dispatch = false, -- false | default_dispatch | cd_dispatch | ps-dispatch | rcore_dispatch | ...
phone = 'auto', -- auto | lb-phone | yseries | false
}
```
`'auto'` tries known resources in order and uses the first one that is running. Set an explicit value to force one, or `false` to disable that integration. The full list of supported values for each key is in [Phone & Integrations](/resources/blackmarkets-player-run-contraband-operation/phone-and-integrations).
## NUI
```lua
cfg.nui = {
primaryColor = '#f15d38', -- accent color of every panel
itemImagesPath = 'ox_inventory/web/images/', -- where item icons are served from
overlays = { -- on-screen position of each HUD overlay
driver = 'top-right',
vanInspect = 'top-right',
door = 'top-right',
seller = 'top-left',
customer = 'right-center',
customerCart = 'left-center',
},
}
```
`primaryColor` also accepts an `{ r, g, b, a }` table. `itemImagesPath` is a resource-relative path; the script adds the `nui://` prefix itself, so don't include it. Each overlay accepts any of the nine anchor positions (`top-left`, `center`, `bottom-right`, …).
## Interaction prompt
```lua
cfg.interaction = {
controlId = 38, -- key for "press to interact" (38 = E)
text = 'E',
colors = {
background = '#f15d38ff',
text = '#e2e8f0ff',
},
}
```
## Police
```lua
cfg.police = {
jobs = { 'police', 'sasp', 'bcso', 'sheriff' }, -- jobs treated as officers
countMethod = 'fast', -- 'fast' (state-based) | 'scan' (per-player check)
seize = { progressMs = 5000 }, -- van seizure cast time
search = { enabled = true, progressMs = 4000 }, -- van search cast time
}
```
`jobs` decides who counts as police for drop gating, dispatch and the seize/search interactions. `countMethod` controls how the live officer count is measured; leave it on `fast` unless you have a reason to change it.
## Warehouse
The core of each operation. Coordinates here are the **default template** used when an admin creates a warehouse (the entrance/exit are then placed in-world per warehouse).
```lua
cfg.warehouse = {
coords = {
door = vec4(1087.12, -3099.38, -39.35, 270.0), -- on-foot interior door
laptop = vec3(1087.74, -3101.30, -39.20), -- laptop interaction point
fallbackExit = vec4(-269.41, -956.32, 31.22, 200.0), -- where players are sent if their warehouse is deleted
vehicle = {
park = vec4(1095.8, -3099.54, -39.35, 90.0), -- where the van parks inside
entry = vec4(1101.68, -3099.54, -39.35, 90.0), -- where the van enters/exits the interior
camPos = vec3(1087.21, -3102.49, -36.43),
camRot = vec3(-29.95, 0.00, -57.32),
},
},
crates = { enabled = true, slots = { --[[ decorative crate props ]] } },
blip = { enabled = true, sprite = 478, color = 5, scale = 0.8, label = locale('blip.warehouse') },
defaults = { stock = {}, vault = 0 }, -- starting stock/vault for a brand-new warehouse
vault = { maxBalance = false }, -- false = no ceiling, or a number cap
pricing = { default = 2.0, limit = { min = 0.0, max = 5.0 } }, -- sale-price multiplier of supply price
}
```
* **`crates.slots`** are purely cosmetic crate props placed inside the interior.
* **`pricing`** sets the default sale-price multiplier and the min/max range owners may set per item.
## Items
The master catalog. Anything sellable, orderable or stockable must be listed here **and** exist in your inventory.
```lua
cfg.items = {
{ name = 'WEAPON_PISTOL', supplyPrice = 250 },
{ name = 'WEAPON_APPISTOL', supplyPrice = 850, maxPerSupplyOrder = 8 },
{ name = 'coke_brick', supplyPrice = 1500 },
{ name = 'meth', supplyPrice = 80, maxPerSupplyOrder = 100 },
-- ...
}
```
| Field | Required | Meaning |
| ----------------------------------------- | -------- | ----------------------------------------------------------- |
| `name` | Yes | Item/weapon name as registered in your inventory. |
| `supplyPrice` | Yes | Cost to order one unit (the buy price from the vault). |
| `label` | No | Display name override (otherwise taken from the inventory). |
| `weight` | No | Per-unit weight override for van capacity. |
| `minPerSupplyOrder` / `maxPerSupplyOrder` | No | Per-order quantity limits for this item. |
| `propModel` | No | Custom prop shown in the van item-preview camera. |
Full walkthrough on [How to Add an Item](/resources/blackmarkets-player-run-contraband-operation/how-to-add-an-item).
## Supply orders
```lua
cfg.supplyOrder = {
maxConcurrentOrders = 2, -- active orders per warehouse
defaultMinPerSupplyOrder = 1,
defaultMaxPerSupplyOrder = 10,
deliveryFee = 1000, -- flat fee added on top of the items
minOrderTotal = 1000, -- minimum subtotal to place an order (or false)
scaling = { -- bigger orders take longer and draw more police attention
maxAtSubtotal = 50000, -- subtotal at which ETA/dispatch hit their max
baseEtaSeconds = 1200,
maxEtaSeconds = 4800,
baseDispatchChance = 0.3,
maxDispatchChance = 1.0,
},
refundOnCancel = false, -- refund the vault if an order is cancelled
drop = {
claimSeconds = 1800, -- time to collect a ready drop before it expires
locations = { --[[ vector4 list of possible drop points ]] },
model = `prop_cs_cardbox_01`,
minPoliceCount = 0, -- min officers online before a drop can be revealed
dispatch = { enabled = true, code = 'SUPPLY_PICKUP', message = locale('dispatch.supply_pickup'), blip = { sprite = 616, color = 1 } },
livePoliceTrack = { enabled = false, durationSeconds = 180, updateIntervalMs = 2000, blip = { --[[...]] } },
},
}
```
* **`scaling`** makes the order ETA and the police-dispatch chance ramp up linearly with the order subtotal, up to `maxAtSubtotal`.
* **`drop.locations`** is the pool the server randomly picks from when an order goes *ready*. Add your own `vec4` points or edit them live from the admin panel ([Admin Panel](/resources/blackmarkets-player-run-contraband-operation/admin-panel)).
* **`livePoliceTrack`** optionally pins a live, updating blip on the suspect during pickup.
## Van
```lua
cfg.van = {
model = `speedo4`,
color = { primary = 0, secondary = 0 }, -- vehicle color ids
platePattern = false, -- false = random, or a pattern like '11AAA111'
cargoLostOnDestroy = true, -- destroyed van also wipes its cargo
capacity = { mode = 'weight', max = 150000 }, -- 'weight' | 'slots' | false
exteriorProps = { --[[ decorative props attached to the van ]] },
orderProp = { --[[ the box prop shown while carrying an order ]] },
replacement = {
requireAfterSeize = true, -- must order a new van after a seizure
requireAfterDestroy = false,
fee = 50000, -- vault cost of a replacement van
deliveryDelaySeconds = 600,
},
}
```
* **`capacity.mode`** — `weight` uses each item's weight, `slots` counts item stacks, `false` disables limits.
* **`replacement`** controls whether losing the van (seizure/destruction) forces a paid replacement before the warehouse can operate again.
## Sale
Controls the mobile van sale and the customer experience.
```lua
cfg.sale = {
publicShare = {
mode = 'optional', -- 'always' | 'optional' | 'never' — broadcast the sale publicly
dispatch = { enabled = true, code = 'PUBLIC_SALE', message = locale('dispatch.public_sale') },
blip = { color = 1, sprite = 616, scale = 0.9, label = locale('blip.sale') },
},
forceFirstPerson = false,
sellerPose = { --[[ where/how the seller sits at the van ]] },
customerCam = { enabled = true, distance = 2.2, height = 0.5, fov = 45.0 },
itemPreview = { enabled = true, defaultProp = `v_ind_cs_box02`, --[[ zoom/offset for the 3D item preview ]] },
}
```
* **`publicShare.mode`** — `always` forces the sale onto the public map/dispatch, `never` hides it, `optional` lets the seller choose.
* **`itemPreview`** renders the highlighted item as a 3D prop on the van with an optional zoom; use a per-item `propModel` (in `cfg.items`) to override the prop.
## Member presets
Role templates offered when hiring crew. Each preset is a set of permission flags.
```lua
cfg.memberPresets = {
{
id = 'manager', label = 'Manager',
permissions = { placeOrder = true, pickupOrder = true, orderVan = true, vanCargo = true,
driveVan = true, setSalePrice = true, openSale = true, vaultDeposit = true, vaultWithdraw = true,
viewFinancials = true, answerDoor = true, manageMembers = true, chatRespond = true },
},
{
id = 'worker', label = 'Worker',
permissions = { pickupOrder = true, vanCargo = true, driveVan = true, openSale = true,
vaultDeposit = true, answerDoor = true, chatRespond = true },
},
}
```
Owners can fine-tune individual permissions per member from the laptop afterwards; presets are just the starting point. The full permission key list is shown in the Members tab and on [Admin Panel](/resources/blackmarkets-player-run-contraband-operation/admin-panel).
## Admin
```lua
cfg.admin = {
command = 'bm_admin', -- command that opens the admin panel (or false to disable)
allowedIdentifiers = { -- identifiers allowed without an ace permission
-- ['license:xxxxxxxx'] = true,
},
}
```
Players with the `command` ace are always allowed. See [Admin Panel](/resources/blackmarkets-player-run-contraband-operation/admin-panel).
## NPC vendor
```lua
cfg.npcVendor = {
enabled = true,
npcModel = `a_m_m_business_01`,
pricingMultiplier = 3.0, -- sell price = item price override, else supplyPrice * multiplier
vendors = { --[[ one or more scheduled NPC vendors ]] },
}
```
This is large enough to have its own page — see [NPC Vendor](/resources/blackmarkets-player-run-contraband-operation/npc-vendor).
## Black money
```lua
cfg.blackMoney = {
enabled = false, -- pay sales in black money instead of cash
type = 'item', -- 'item' | 'account' | 'markedbills'
item = 'black_money',
account = 'black_money',
metadataKey = 'worth', -- metadata key for markedbills worth
}
```
When disabled, sales pay out in regular cash.
## Retention
```lua
cfg.retention = {
logs = 30, -- days to keep sales/vault/audit logs
conversations = 30, -- days to keep phone chats (0 disables pruning)
}
```
A daily cron prunes anything older than these windows. Set a value to `0` to keep records forever.
# How to Add an Item
Every item that can be **ordered, stocked or sold** lives in `cfg.items`. Adding one is two steps: register it in your inventory, then list it here.
{% stepper %}
{% step %}
## Register the item in your inventory
The item or weapon must already exist in your inventory. Items and weapons are usually registered separately — in ox\_inventory, for example, items live in `data/items.lua` and weapons in `data/weapons.lua`. Blackmarket doesn't create them; it only trades what your server already has.
{% endstep %}
{% step %}
## Add it to `cfg.items`
```lua
cfg.items = {
-- existing entries...
{ name = 'WEAPON_HEAVYPISTOL', supplyPrice = 950, maxPerSupplyOrder = 8 },
{ name = 'lockpick', supplyPrice = 120, label = 'Lockpick', maxPerSupplyOrder = 25 },
}
```
### Fields
| Field | Required | Default | Description |
| ------------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | — | Item/weapon name, exactly as in your inventory. |
| `supplyPrice` | Yes | — | Cost to order one unit from the vault. The sale price defaults to `supplyPrice × cfg.warehouse.pricing.default`. |
| `label` | No | inventory label | Display name override in the UI. |
| `weight` | No | inventory weight | Per-unit weight used for van capacity (`capacity.mode = 'weight'`). |
| `minPerSupplyOrder` | No | `cfg.supplyOrder.defaultMinPerSupplyOrder` | Minimum units per order for this item. |
| `maxPerSupplyOrder` | No | `cfg.supplyOrder.defaultMaxPerSupplyOrder` | Maximum units per order for this item. |
| `propModel` | No | `cfg.sale.itemPreview.defaultProp` | Prop shown in the van's 3D item-preview camera. |
{% hint style="warning" %}
After editing `cfg.items`, **restart the resource**. New items do not appear in already-open laptops or sales until the next session.
{% endhint %}
{% endstep %}
{% endstepper %}
## Set its price
* **Supply price** (the buy cost) is fixed in `cfg.items`.
* **Sale price** (what customers pay) is set per warehouse from the laptop's **Pricing** tab, within the `cfg.warehouse.pricing.limit` range. New items start at `supplyPrice × pricing.default`.
# Admin Panel
The entire script is managed in-game from a single admin panel. There are no other commands; one command opens it, and everything else happens in the UI.
## Opening the panel
| Command | Default | Access | Opens |
| ----------- | ------------------------------------ | ----------- | --------------- |
| `/bm_admin` | configurable via `cfg.admin.command` | admins only | The admin panel |
Set `cfg.admin.command = false` to remove the command entirely.
## Who is an admin?
A player is treated as an admin if **either** is true:
1. They have FiveM's built-in `command` ace (the server console, and usually `group.admin`), **or**
2. Their identifier is listed in `cfg.admin.allowedIdentifiers`.
```lua
cfg.admin = {
command = 'bm_admin',
allowedIdentifiers = {
['license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'] = true,
['license:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'] = true,
},
}
```
{% hint style="info" %}
You can find a player's `license:` identifier with `/bm_admin` once they're connected — or from txAdmin / your server console. Use the `license:` identifier, not the Steam or Discord one, for the most stable match.
{% endhint %}
Admins also bypass per-warehouse permission checks, so they can inspect and manage any warehouse.
## The dashboard
The panel has four tabs:
{% tabs %}
{% tab title="Warehouses" %}
* **Create a warehouse** through a step-by-step wizard: pick the owner (any online player), place the entrance and the vehicle exit in-world, optionally pre-fill starter stock, seed the vault, and pre-hire crew with a role preset.
* **Inspect** any existing warehouse to see and edit:
* **Overview** — vault, member count, players inside, active orders; transfer ownership; edit coordinates; teleport in.
* **Stock** — view warehouse + van stock, wipe either.
* **Members** — hire/remove crew, set roles & permissions.
* **Inside** — see who is in the bucket and who is knocking; eject one player or everyone.
* **Settings** — edit the public storefront (vendor name, description, avatar) as an admin (logged).
* **Vault override** — credit or debit any warehouse's vault (clamped to the configured ceiling/floor, and logged).
* **Force-respawn the van**, **delete** the warehouse, and more.
{% endtab %}
{% tab title="Drops" %}
Manage the supply-drop location pool (`cfg.supplyOrder.drop.locations`). **Pick a new spot in-world**, then copy the generated `vec4(...)` line into your config. You can also teleport to existing drop points to check them.
{% hint style="warning" %}
Locations you pick in the Drops/NPC tools are written to your **clipboard as config lines** — they are not auto-saved. Paste them into `cfg.lua` and restart for them to persist.
{% endhint %}
{% endtab %}
{% tab title="NPC Vendor" %}
A full wizard to create [NPC Vendors](/resources/blackmarkets-player-run-contraband-operation/npc-vendor): name, schedule (real/game/always-open), items & pricing, and reachable spawn locations validated in-world. It outputs a config block you paste into `cfg.npcVendor.vendors`. You can also **force-start / force-stop** vendors live to test them.
{% endtab %}
{% tab title="Logs" %}
A 30-day audit trail of admin actions (warehouse create/delete, ownership transfers, ejects, vault adjustments, stock wipes, van respawns, coordinate edits, NPC force start/stop, storefront edits). Retention is controlled by `cfg.retention.logs`.
{% endtab %}
{% endtabs %}
## Member permissions reference
Owners (and admins) grant these per member. Presets in `cfg.memberPresets` bundle them; the laptop Members tab fine-tunes each one.
| Key | Group | Allows |
| ---------------- | ------------------ | ------------------------------------------------- |
| `placeOrder` | Orders | Spend the vault on supply orders |
| `pickupOrder` | Orders | Collect ready supply drops |
| `orderVan` | Orders | Order a replacement van after a loss |
| `vanCargo` | Stock & van | Move stock between warehouse and van |
| `driveVan` | Stock & van | Drive the van out for runs |
| `setSalePrice` | Stock & van | Edit warehouse-wide sale prices |
| `openSale` | Stock & van | Start a van sale outside |
| `viewFinancials` | Vault & financials | See vault balance, revenue and analytics |
| `vaultDeposit` | Vault & financials | Add funds to the vault |
| `vaultWithdraw` | Vault & financials | Take funds out of the vault |
| `answerDoor` | People | Admit/reject knocks, kick guests |
| `manageMembers` | People | Add, edit, remove members *(owner-only to grant)* |
| `chatRespond` | People | Reply to phone-app messages |
# NPC Vendor
NPC vendors are server-run sellers that **drive a van to a spot, park, sell from a customer UI, then depart** on a schedule. They give players a baseline place to buy without a live owner online. Everything lives under `cfg.npcVendor`.
{% hint style="success" %}
You don't have to write this config by hand. The admin panel has an **NPC Vendor wizard** that lets you pick locations in-world, set the schedule and items, and then copies a ready-to-paste config block. See [Admin Panel](/resources/blackmarkets-player-run-contraband-operation/admin-panel).
{% endhint %}
## Global settings
```lua
cfg.npcVendor = {
enabled = true, -- master switch for all NPC vendors
npcModel = `a_m_m_business_01`, -- default ped model
pricingMultiplier = 3.0, -- default sell price = item supplyPrice × this
vendors = { --[[ list of vendors, see below ]] },
}
```
`pricingMultiplier` turns each item's `cfg.items.supplyPrice` into a sell price. A per-item `price` (below) overrides it.
## A vendor
```lua
vendors = {
{
name = 'Paleto Bay', -- label shown only in the admin dashboard
npcModel = `a_m_m_business_01`, -- optional per-vendor model override
pricingMultiplier = 3.0, -- optional per-vendor multiplier override
locations = { -- van parks/sells at one of these (picked per spawn)
vec4(-280.70, 6034.97, 30.52, 231.17),
},
schedule = {
enabled = true,
mode = 'real', -- 'real' (clock) | 'game' (in-game hour)
real = { -- cron windows when mode = 'real'
{ open = '0 19 * * *', close = '0 23 * * *' },
},
game = { -- hour windows when mode = 'game'
-- { startHour = 19, stopHour = 23 },
},
},
items = { -- what this vendor sells
{ name = 'WEAPON_PISTOL' }, -- uses pricingMultiplier
{ name = 'WEAPON_SMG', price = 12000 }, -- fixed price override
{ name = 'ammo-9' },
},
},
}
```
### Fields
| Field | Required | Description |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `name` | No | A label shown only in the admin dashboard. |
| `locations` | Yes | One or more `vec4` spots. The server picks one each time the vendor spawns and drives the van there by road. |
| `npcModel` | No | Per-vendor ped override (else the global `npcModel`). |
| `pricingMultiplier` | No | Per-vendor multiplier override (else the global one). |
| `schedule` | Yes | When the vendor is open (see below). |
| `items` | Yes | List of `{ name, price? }`. `name` must be in `cfg.items`; `price` overrides the multiplier. |
## Schedules
* **`mode = 'real'`** uses real-world time. Each window is a pair of cron expressions: `open` and `close`.
```lua
real = {
{ open = '0 19 * * *', close = '0 23 * * *' }, -- every day, 19:00–23:00
{ open = '0 12 * * 6', close = '0 18 * * 6' }, -- Saturdays, 12:00–18:00
}
```
* **`mode = 'game'`** uses the in-game clock with `startHour`/`stopHour` (0–23). Windows that wrap past midnight (e.g. `startHour = 22, stopHour = 4`) are supported.
```lua
game = {
{ startHour = 19, stopHour = 23 },
}
```
* **`enabled = false`** makes the vendor **always open** — it spawns permanently and never departs.
{% hint style="info" %}
When a vendor opens it drives in (`pre-spawn → driving → parking → open`) and when it closes it drives off (`departing`). You can force-start or force-stop any vendor live from the admin panel for testing.
{% endhint %}
## Picking valid locations
A location must be reachable by road. When you pick a spot in the admin wizard it's validated against the nearest road: you'll get an error if there's no road nearby, or the closest one is too far. Pick spots near drivable roads, not deep off-road or inside interiors.
# Discord Log
Blackmarket can post rich, categorized embeds to a Discord webhook. Logging is configured at the top of **`server/discord_log.lua`**.
## Setup
```lua
local config = {
enabled = false, -- turn logging on
webhook = 'WEBHOOK_HERE', -- your Discord webhook URL
botName = 'Blackmarket', -- username shown on the embeds
categories = { -- toggle whole categories on/off
admin = true,
economy = true,
police = true,
social = true,
security = true,
},
}
```
1. Create a webhook in **Discord → Channel Settings → Integrations → Webhooks**.
2. Paste its URL into `webhook`.
3. Set `enabled = true`.
4. Restart the resource.
{% hint style="info" %}
You can point each category at a different channel by duplicating the webhook logic, but the simplest setup is one webhook with the categories you care about left `true`.
{% endhint %}
## Categories & events
Each embed is color-coded by category. Turn off a category by setting it to `false`.
| Category | Color | Logged events |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **ADMIN** | red | Every admin-panel action (create/delete warehouse, transfer ownership, eject, vault adjust, stock/van wipe, force-respawn van, edit coords/storefront, NPC force start/stop, member add/edit/remove). |
| **ECONOMY** | blue | Supply order placed/cancelled, drop picked up, order offloaded, replacement van ordered, van sale opened/closed, customer purchase, NPC vendor purchase, vault deposit/withdraw. |
| **POLICE** | orange | Van searched, van cargo seized, van destroyed. |
| **SOCIAL** | green | Member added, member permissions updated, member removed. |
| **SECURITY** | purple | Anti-abuse signals: customer refund lost on mid-purchase disconnect, vault deposit lost on disconnect, permission-denied attempts. |
Every embed includes the warehouse (`#id` + owner) and the actor (name + identifier) when they apply, plus event-specific fields (amounts, item lists, ETAs, coordinates…).
{% hint style="warning" %}
If `enabled = true` but no logs appear, double-check the webhook URL is complete and that the channel still exists. A revoked or wrong URL fails silently.
{% endhint %}
# Translate Strings
All player-facing text lives in JSON locale files under **`/locales`**. The script ships with `en.json`.
## Switch language
Set the locale in `cfg.lua`:
```lua
cfg.locale = 'en' -- loads /locales/en.json
```
The value must match a file name in `/locales` (without the `.json`).
## Add a new language
1. Copy `locales/en.json` to a new file, e.g. `locales/fr.json`.
2. Translate the **values** only — never change the keys.
3. Set `cfg.locale = 'fr'` and restart the resource.
```json
{
"prompt": {
"open_laptop": "Ouvrir l'ordinateur",
"knock_door": "Frapper"
},
"notify": {
"no_permission": "Vous n'avez pas la permission pour cette action."
}
}
```
{% hint style="danger" %}
Only edit the text on the **right** of each `:`. Changing or removing a key (the left side) will break the string and may error in-game.
{% endhint %}
## Placeholders
Some strings contain placeholders that the script fills in at runtime. Keep them exactly as they are, in a spot that still reads naturally:
* `%s` — a string (a name, an amount, an item label).
* `%d` — a whole number.
* `%s%%` — a number followed by a literal percent sign.
The same rule applies wherever a string lives — for example `notify.van_seized` and `ui.orders.order_placed`:
```json
"van_seized": "Van seized. %d items destroyed.",
"order_placed": "Order placed — arriving in ~%s min."
```
## Where text is grouped
The locale file is organized by area so you can find strings quickly:
| Section | Covers |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt` | Interaction prompts ("Open Laptop", "Knock"…) |
| `notify` | Server notifications |
| `progress` | Progress-bar labels |
| `command` | Command help text |
| `blip` / `dispatch` | Map blips and police dispatch messages |
| `activity` | Vault/sales activity descriptions |
| `editor` | Placement-tool hints (drop / NPC vendor / warehouse editors) |
| `ui.*` | Every NUI panel: laptop tabs, orders, stock, pricing, vault, analytics, members, inbox, settings, van, sale, customer, phone app, door, admin, editor |
{% hint style="info" %}
The `ui` section is by far the largest — it holds all the in-panel text. Translate it last, once the gameplay strings (`prompt`, `notify`) are done, so you can test in-game as you go.
{% endhint %}
# Phone & Integrations
Blackmarket bridges to the resources you already run. Every integration is one key in `cfg.bridge` (plus a couple of dedicated config blocks). `'auto'` picks the first supported resource that is running; an explicit name forces one; `false` disables it.
## Phone app
The **Blackmarket** phone app lets buyers browse public vendors, start an anonymous chat (the buyer shows up only under a generated alias), share their live location, and receive the van's location back. Vendors reply from the laptop **Inbox** tab.
```lua
cfg.bridge.phone = 'auto' -- 'auto' | 'lb-phone' | 'yseries' | false
```
| Value | Phone |
| ---------- | ----------------------------------------------------------------------------------------- |
| `auto` | Tries `lb-phone`, then `yseries`. |
| `lb-phone` | [lb-phone](https://docs.lbscripts.com/) |
| `yseries` | yseries phone |
| `false` | Disables the phone app (warehouses can still operate; only the buyer-facing app is gone). |
A warehouse only appears in the app after the owner enables **Public listing** in the laptop **Settings** tab (vendor name, description, avatar URL). The phone database tables are created on first start, as long as `cfg.bridge.phone` isn't set to `false`.
{% hint style="info" %}
Conversations and messages are pruned after `cfg.retention.conversations` days (default 30). Set it to `0` to keep them forever.
{% endhint %}
## Notifications
```lua
cfg.bridge.notification = 'builtin'
```
Supported: `builtin`, `ox_lib`, `qb`, `esx`, `okokNotify`, `ps-ui`, `lation_ui`, `wasabi_notify`, `zsxui`.
## Text UI
```lua
cfg.bridge.textUI = 'builtin'
```
Supported: `builtin`, `ox_lib`, `esx`, `qb`, `okokTextUI`, `jg-textui`.
## Progress bar
```lua
cfg.bridge.progressbar = 'builtin'
```
Supported: `builtin`, `ox_lib`, `qb`, `esx`, `wasabi_uikit`, `lation_ui`, `zsxui`, or `false`.
## Target
```lua
cfg.bridge.target = 'auto'
```
Supported: `auto`, `ox_target`, `qb-target`, or `false`.
## Dispatch
Used for police alerts on supply pickups and public sales.
```lua
cfg.bridge.dispatch = false
```
Supported: `false`, `default_dispatch`, `cd_dispatch`, `qs-dispatch`, `ps-dispatch`, `rcore_dispatch`, `sonoran_cad`, `origen_police`, `redutzu-mdt`, `lb-tablet`, `core_dispatch`, `tk_dispatch`, `l2s-dispatch`, `bub-mdt`, `fd_dispatch`, `kartik-mdt`, `piotreq_gpt`, `p_mdt`, `wasabi_mdt`.
The alert codes/messages/blips are configured per feature in `cfg.supplyOrder.drop.dispatch` and `cfg.sale.publicShare.dispatch`.
## Vehicle keys
Hands the van keys to whoever drives it out.
```lua
cfg.bridge.vehiclelock = 'auto'
```
Supported: `auto`, `false`, `qb-vehiclekeys`, `wasabi_carlock`, `qs-vehiclekeys`, `cd_garage`, `Renewed-Vehiclekeys`, `okokGarage`, `t1ger_keys`, `MrNewbVehicleKeys`, `jaksam`.
## Framework
```lua
cfg.bridge.framework = 'auto' -- 'auto' | 'qb' | 'esx'
```
`auto` detects QBCore/Qbox or ESX. Force one only if auto-detection guesses wrong.
## Black money
By default sales pay out in **cash**. To pay in black money instead:
```lua
cfg.blackMoney = {
enabled = true,
type = 'item', -- 'item' | 'account' | 'markedbills'
item = 'black_money', -- when type = 'item'
account = 'black_money', -- when type = 'account'
metadataKey = 'worth', -- when type = 'markedbills'
}
```
| `type` | Pays out as |
| ------------- | ------------------------------------------------------------------------ |
| `item` | A stackable inventory item named by `item`. |
| `account` | A framework money account named by `account` (e.g. ESX `black_money`). |
| `markedbills` | A marked-bills item whose value is stored in metadata key `metadataKey`. |
Make sure the chosen item/account actually exists in your framework/inventory.
# 3D Hacking Device: In-hand phone hacking tool
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
## Step 1: Download and Prepare Files
#### **Download the Script from FiveM Keymaster**
* Visit the [FiveM Keymaster](https://keymaster.fivem.net/) site.
* Log in with your account credentials.
* Locate the **3D Hacking Device** script in your **Granted Assets** section.
* Download the script files from Keymaster.
## Step 2: Add Script to Server Configuration
#### **Edit `server.cfg`**
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following line to ensure the **3D Hacking Device** script starts with your server:
```
ensure rm_hackingdevice
```
# Configuration
```lua
lib.locale('en')
cfg = {}
---@type 'auto' | 'qb' | 'esx'
cfg.framework = 'auto'
---@type 'auto' | 'ox_target' | 'qb-target' | false
cfg.target = 'auto'
---@type 'rm_minigames' | 'ox_lib' | 'qb-minigames' | 'ps-ui' | 'bl_ui' | false
cfg.minigame = 'ox_lib'
---@type 'ox_lib' | 'qb' | 'esx' | 'okokNotify' | 'ps-ui'
cfg.notification = 'ox_lib'
---@type 'ox_lib' | 'esx' | 'qb' | 'okokTextUI' | 'jg-textui'
cfg.textUI = 'ox_lib'
---@type 'ox_lib' | 'qb' | 'esx' | false
cfg.progressbar = 'ox_lib'
---@type 'auto' | false | 'qb-vehiclekeys' | 'wasabi_carlock' | 'qs-vehiclekeys' | 'cd_garage' | 'Renewed-Vehiclekeys' | 'okokGarage' | 't1ger_keys' | 'MrNewbVehicleKeys'
cfg.vehiclelock = 'auto'
---@type false | 'default_dispatch' | 'cd_dispatch' | 'qs-dispatch' | 'ps-dispatch' | 'rcore_dispatch' | 'sonoran_cad' | 'origen_police' | 'redutzu-mdt' | 'lb-tablet' | 'core_dispatch' | 'tk_dispatch' | 'l2s-dispatch'
cfg.dispatch = false
cfg.interaction = {
controlId = 38, ---@type number
text = 'E', ---@type string
colors = {
background = { r = 241, g = 93, b = 56, a = 255 }, ---@type { r: number, g: number, b: number, a: number }
text = { r = 226, g = 232, b = 240, a = 255 }, ---@type { r: number, g: number, b: number, a: number }
},
}
cfg.requiredPoliceCount = 0 ---@type number
cfg.enableOldMethodForPoliceCount = false ---@type boolean -- not recommended
-- ========== Hacking Device ==========
cfg.itemName = 'rm_hacking_device' ---@type string inventory item name that opens the device
cfg.shouldRemove = false ---@type boolean remove the item from the player's inventory on each use
cfg.HackHoldDuration = 1500 ---@type number ms to lock onto a target while holding Z
cfg.ActionArmWindow = 10000 ---@type number ms — after picking an action the user has this long to lock a target with Z
cfg.MaxActionRange = 80.0 ---@type number max distance (m) between hacker and target for an action to succeed
cfg.debug = false ---@type boolean prints per-action server log when true
cfg.Actions = {
Vehicle = {
{ id = 'disable_engine', cost = 25, cooldown = 8000 },
{ id = 'open_doors', cost = 25, cooldown = 5000 },
{ id = 'steer_right', cost = 50, cooldown = 10000 },
{ id = 'steer_left', cost = 50, cooldown = 10000 },
{ id = 'explode_box', cost = 100, cooldown = 15000 },
{ id = 'unlock_doors', cost = 30, cooldown = 5000 },
{ id = 'explode_car', cost = 150, cooldown = 30000 },
},
Human = {
{ id = 'steal_money', cost = 75, cooldown = 20000 },
{ id = 'fake_dispatch', cost = 40, cooldown = 30000 },
{ id = 'fake_ring', cost = 15, cooldown = 5000 },
{ id = 'wipe_gps', cost = 30, cooldown = 8000 },
{ id = 'drop_weapon', cost = 70, cooldown = 20000 },
},
}
cfg.giveCreditCommand = 'givecredit' ---@type string
cfg.giveCreditAlloweds = {
-- ['steam:00000000a000a00'] = true,
-- ['license:0aa00a00a00aa000a000000a00000a00a00aa000'] = true,
-- ['license2:0aa00a00a00aa000a000000a00000a00a00aa000'] = true,
-- ['fivem:0000000'] = true,
}
```
# Biker Melee (melee weapons on bikes)
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
## Step 1: Download and Prepare Files
#### **Download the Script from FiveM Keymaster**
* Visit the [FiveM Keymaster](https://keymaster.fivem.net/) site.
* Log in with your account credentials.
* Locate the **Biker Melee (melee weapons on bikes)** script in your Granted Assets section.
* Download the script files from Keymaster.
## Step 2: Add Script to Server Configuration
#### **Edit `server.cfg`**
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following line to ensure the **Biker Melee (melee weapons on bikes)** script starts with your server:
```
ensure rm_bikermelee
```
# Configuration
```lua
cfg = {}
---@type 'auto' | 'qb' | 'esx'
cfg.framework = 'auto'
---@type 'auto' | 'ox_inventory' | 'qs-inventory' | 'codem-inventory' | 'core_inventory' | 'tgiann-inventory' | 'origen_inventory' | 'one_inventory' | 'jpr-inventory' | 'qb-inventory' | 'ps-inventory'
cfg.inventory = 'auto'
---@type 'ox_lib' | 'qb' | 'esx' | 'okokNotify' | 'ps-ui'
cfg.notification = 'ox_lib'
-- Melee controls & tuning. Control IDs are GTA input indices (see the comments).
-- https://docs.fivem.net/docs/game-references/controls/
cfg.melee = {
-- ── Attack keys (map naturally to LMB/RMB on keyboard and LT/RT on gamepad) ──
keyboardLeftAttack = 25, -- INPUT_AIM (RMB)
keyboardRightAttack = 24, -- INPUT_ATTACK (LMB)
-- ── Weapon select keys ──
swapWeaponsKey = 194, -- INPUT_FRONTEND_RRIGHT (Backspace)
nextWeaponControl = 99, -- INPUT_VEH_SELECT_NEXT_WEAPON ([)
prevWeaponControl = 100, -- INPUT_VEH_SELECT_PREV_WEAPON (])
-- ── Throw mode keys ──
throwModeKey = 47, -- INPUT_DETONATE (G) — toggle throw mode
throwReleaseKey = 24, -- INPUT_ATTACK (LMB) — release the throw
-- ── Master on/off (lib.addKeybind key name; players can rebind in pause menu) ──
toggleKey = 'J', -- toggles Biker Melee mode on/off (default on)
-- ── Behaviour toggles ──
onlyMeleeOnUnarmed = false,
ejectPedOffBike = false,
drawWeaponUI = true,
weaponUICenter = true,
weaponUIVanish = true,
swapBetweenGunsAndMelee = false,
-- ── Physics / tuning ──
kickForwardVelocity = 0.0,
kickUpwardVelocity = 0.0,
vehicleDamage = 0.0,
throwSpeed = 30.0,
throwGravity = 9.81,
throwMaxSteps = 35,
throwTimeStep = 0.05,
}
-- Melee weapons: inventory item key → in-hand prop + display name + type.
-- wpnType 'blade' deals more damage than 'blunt'.
cfg.meleeWeapons = {
WEAPON_BAT = { propModel = `w_me_bat`, name = 'Bat', wpnType = 'blunt' },
WEAPON_CROWBAR = { propModel = `w_me_crowbar`, name = 'Crowbar', wpnType = 'blade' },
WEAPON_GOLFCLUB = { propModel = `w_me_gclub`, name = 'Golfclub', wpnType = 'blunt' },
WEAPON_HAMMER = { propModel = `w_me_hammer`, name = 'Hammer', wpnType = 'blunt' },
WEAPON_HATCHET = { propModel = `prop_w_me_hatchet`, name = 'Hatchet', wpnType = 'blade' },
WEAPON_KNIFE = { propModel = `w_me_knife_01`, name = 'Knife', wpnType = 'blade' },
WEAPON_MACHETE = { propModel = `w_me_machette_lr`, name = 'Machete', wpnType = 'blade' },
WEAPON_NIGHTSTICK = { propModel = `w_me_nightstick`, name = 'Nightstick', wpnType = 'blunt' },
WEAPON_POOLCUE = { propModel = `w_me_poolcue`, name = 'Poolcue', wpnType = 'blunt' },
WEAPON_SWITCHBLADE = { propModel = `w_me_switchblade`, name = 'Switchblade', wpnType = 'blade' },
WEAPON_WRENCH = { propModel = `w_me_wrench`, name = 'Wrench', wpnType = 'blunt' },
}
-- Order the script picks weapons in (first owned = first selected). Every key
-- here must exist in cfg.meleeWeapons above.
cfg.meleeItemPriority = {
'WEAPON_BAT',
'WEAPON_CROWBAR',
'WEAPON_GOLFCLUB',
'WEAPON_HAMMER',
'WEAPON_HATCHET',
'WEAPON_KNIFE',
'WEAPON_MACHETE',
'WEAPON_NIGHTSTICK',
'WEAPON_POOLCUE',
'WEAPON_SWITCHBLADE',
'WEAPON_WRENCH',
}
```
# Jobs V: Legal Multiplayer Job Pack
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
{% stepper %}
{% step %}
## Download and Prepare Files
#### **Download the Script from FiveM Keymaster**
* Visit the [FiveM Keymaster](https://keymaster.fivem.net/) site.
* Log in with your account credentials.
* In the **Granted Assets** section, locate the **Jobs V: Legal Multiplayer Job Pack** scripts.
* Download both archives:
* `rm_jobsv` — the main script
* `rm_jobsv_assets` — the asset pack
#### **Place the Folders**
Drop both folders into your server's `resources/` directory, for example under `[rainmad]/`:
```
resources/[rainmad]/rm_jobsv/
resources/[rainmad]/rm_jobsv_assets/
```
{% endstep %}
{% step %}
## Add the Scripts to `server.cfg`
Add these lines to your `server.cfg`, **in this order** (assets must start before the main script):
```
ensure rm_jobsv_assets
ensure rm_jobsv
```
{% endstep %}
{% step %}
## Verify Dependencies
The resource depends on the following — make sure they are started **before** `rm_jobsv`:
* `oxmysql`
* `ox_lib`
{% endstep %}
{% step %}
## Database
There is **nothing to import manually**. The tables (`rm_jobsv`, `rm_jobsv_payout_buckets`) are created automatically on first boot.
{% endstep %}
{% endstepper %}
# Configuration
Configuration is split across three layers:
* **`shared/main_config.lua`** — global, server-wide settings (framework, money, daily featured, level system, admins, locale strings).
* **`shared/ui_config.lua`** — UI defaults and web locale strings sent to the tablet UI.
* **`shared/jobs/.lua`** — per-job content (reward, dialog, taskbar, blips, vehicle, locations).
## Framework
```lua
Config.framework = {
name = "auto", -- "esx" | "qb" | "auto" (auto-detects)
targetScript = "ox_target", -- "ox_target" | "qb-target" | "qtarget"
useOxNotify = true, -- send notifications via ox_notify
debug = false, -- enable verbose debug + zone outlines
}
```
## Money
```lua
Config.moneyOptions = {
moneyName = "money",
moneyIsItem = false,
}
```
## Daily Featured Job
```lua
Config.dailyFeaturedJob = {
enabled = true,
bonusMultiplier = 1.25, -- 1.25 = +25% payout on the featured job
rotationHour = 24, -- UTC hour to rotate (24 = 00:00 UTC)
}
```
The featured job is **deterministic** — picked from a sorted, alphabetical pool seeded by the UTC date, so all players see the same featured job and a server restart never changes it within the same day.
## Vehicle Cleanup
```lua
Config.vehicleCleanup = {
enabled = false,
abandonTimeoutMs = 180000, -- 3 min: how long until an abandoned vehicle despawns
distanceThreshold = 100.0, -- meters: distance from owner before considered abandoned
checkIntervalMs = 30000, -- 30 sec: server thread interval
}
```
## General
```lua
Config.general = {
nearbyPlayersDistance = 5.0, -- crew invite range
inviteExpireTime = 60, -- seconds before a crew invite expires
sqlSaveInterval = 10, -- minutes between periodic progress flushes
jobCompleteAutoEnd = 30, -- seconds before the complete modal auto-closes if leader idle
level = {
perLevelExpAmount = 1000, -- account-level XP per level
maxLevel = 30,
},
jobLevel = {
perLevelExpAmount = 1000, -- per-job XP per level
maxLevel = 10,
bonusPerLevel = 0.02, -- +2% money bonus per per-job level
},
jobCenter = {
pedModel = "s_m_y_uscg_01",
coords = vector4(-268.823, -956.624, 30.223, 204.099),
},
}
```
## Admins
```lua
Config.admins = {
identifiers = {
["license:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"] = true,
-- ["steam:110000100000000"] = true,
},
}
```
Listed identifiers gain access to the in-game admin panel (KPIs, charts, per-job stats, job config, lobby view, and the job editor).
## Bucket Retention
```lua
Config.bucketRetentionDays = 90 -- delete payout buckets older than N days, 0 = never
```
## Per-job Configuration (Shared Structure)
Every job in `shared/jobs/` follows the same skeleton. Example from `shared/jobs/cleaner.lua`:
```lua
Config.jobs.cleaner = {
disabled = false,
reward = {
money = { min = 900, max = 1400 },
exp = 110,
},
webConfig = {
name = "Cleaner",
beginnerFriendly = true,
description = "Keep the city pristine — collect waste and sanitize public areas.",
reqLevel = 1, -- account level required to start
players = "1-2", -- recommended crew size (string, display only)
duration = "20 min", -- average duration (string, display only)
objectives = { "Mop, wipe and sweep", "Pressure-wash the dirt", "Clear zones" },
image = "./images/cleaner.png",
},
timeBonus = {
time = 20, -- complete under N minutes for a bonus
multiplier = 1.25, -- +25% reward
perPlayerReduction = 2, -- subtract N minutes per extra crew member
},
npc = { -- dispatcher NPC at the depot
model = "s_m_m_autoshop_01",
coords = vector4(-292.370, -985.516, 30.080, 299.325),
},
vehicle = { -- work vehicle the leader spawns
model = "bison",
leaderOnly = true,
vehicleSpawnCoords = {
vector4(-297.940, -990.581, 30.583, 342.457),
vector4(-301.425, -989.447, 30.583, 339.084),
},
},
locations = { ... }, -- job-specific work locations
}
```
# Jobs
Each job below lists what it is and the steps the player goes through during a shift.
### Butcher
Process chickens at the slaughterhouse — catch, slaughter, shackle, then package the cuts for delivery.
{% stepper %}
{% step %}
## Catch the chickens
Approach the chicken pen, catch the chickens, then load them into the cage truck.
{% endstep %}
{% step %}
## Slaughter the chickens
Bring the cage to the slaughterhouse and process each chicken at the station.
{% endstep %}
{% step %}
## Shackle the chickens
Hang the slaughtered chickens on the overhead shackle line for plucking.
{% endstep %}
{% step %}
## Package & deliver
Vacuum-seal the cuts and stack the boxes in the delivery van.
{% endstep %}
{% endstepper %}
### Car Wash
Drive the wash van to stranded customers and detail their vehicles on the spot.
{% stepper %}
{% step %}
## Take the wash van
Spawn the wash van from the depot and head out.
{% endstep %}
{% step %}
## Drive to find a customer
Drive around until dispatch finds a customer.
{% endstep %}
{% step %}
## Spray wash
Spray the vehicle from every side.
{% endstep %}
{% step %}
## Sponge scrub
Scrub the vehicle at the marked spots.
{% endstep %}
{% step %}
## Rinse off
Rinse the vehicle from every side.
{% endstep %}
{% step %}
## Polish & wipe
Polish the vehicle at the marked spots.
{% endstep %}
{% step %}
## Hand the keys back
Return the keys and collect the payment.
{% endstep %}
{% endstepper %}
### Cleaner
Keep public areas tidy — mop stains, wipe windows, sweep trash and pressure-wash dirt zones.
{% stepper %}
{% step %}
## Mop the stains
Use the mop on each stain marker to clean it up.
{% endstep %}
{% step %}
## Wipe the windows
Wipe down every window marker with the cloth.
{% endstep %}
{% step %}
## Sweep the floors
Sweep up the trash piles with the broom.
{% endstep %}
{% step %}
## Pressure-wash the dirt
Use the pressure washer to blast the marked dirt area.
{% endstep %}
{% endstepper %}
### Courier
Drive a delivery van around the city handing parcels to each customer.
{% stepper %}
{% step %}
## Get vehicle from depot
Spawn the delivery van at the loading bay.
{% endstep %}
{% step %}
## Deliver each package
Drive to each drop and hand the parcels to the customer.
{% endstep %}
{% endstepper %}
### Dockworker
Move shipping containers at the port using container handlers.
{% stepper %}
{% step %}
## Take a handler
Spawn a container handler from the depot.
{% endstep %}
{% step %}
## Load containers onto trailers
Pick up each container and place it on a trailer.
{% endstep %}
{% endstepper %}
### Electrician
Diagnose and repair power faults around the city — minigame-driven (terminal, cable, fuse, probe, scope).
{% stepper %}
{% step %}
## Fix the faults
Diagnose and repair every marked electrical fault around the city.
{% endstep %}
{% step %}
## Return to the foreman
All faults repaired — head back to the dispatcher to close out the shift.
{% endstep %}
{% endstepper %}
### Farmer
Plow the field, plant pumpkin seeds, tend the seedlings, then harvest and dump the load.
{% stepper %}
{% step %}
## Plow the field
Drive your tractor with the rake trailer over every marked spot to break the soil.
{% endstep %}
{% step %}
## Plant seeds at marked spots
Step out of the tractor, walk up to each marker and plant by hand.
{% endstep %}
{% step %}
## Water and fertilize the seedlings
Apply water or manure to each seedling that needs it.
{% endstep %}
{% step %}
## Wait for the pumpkins to grow
The seedlings need a little time to mature into pumpkins.
{% endstep %}
{% step %}
## Harvest and load pumpkins
Pull each pumpkin off and drop it into the grain trailer.
{% endstep %}
{% step %}
## Dump the trailer at the dump site
Drive the loaded grain trailer to the dump site and empty it.
{% endstep %}
{% step %}
## Return to the foreman
Head back to the farm foreman to close out the shift.
{% endstep %}
{% endstepper %}
### Firefighter
Drive the fire truck to the scene, run a two-person hose to put out fires, and rescue a stranded cat if one is on site.
{% stepper %}
{% step %}
## Get a fire truck
Spawn a fire truck from the station.
{% endstep %}
{% step %}
## Take the hose from the truck
Grab a hose from the side of the fire truck.
{% endstep %}
{% step %}
## Extinguish the fires
Use the hose to put out every fire at the scene.
{% endstep %}
{% step %}
## Rescue the stranded cat
Pick up the cat and bring it back to safety.
{% endstep %}
{% step %}
## Return to the dispatcher
Head back to the dispatcher to close the shift.
{% endstep %}
{% endstepper %}
### Forklift
Pick the right crates with a forklift and run them down the conveyor belt.
{% stepper %}
{% step %}
## Get a forklift
Spawn a forklift at the loading bay.
{% endstep %}
{% step %}
## Load the belt
Pick up crates with the forklift and place them on the conveyor belt.
{% endstep %}
{% step %}
## Run the conveyor
Start the conveyor to process each set of crates.
{% endstep %}
{% endstepper %}
### Gardener
Mow grass, trim plants and grow flowers across the city's gardens.
{% stepper %}
{% step %}
## Mow grass
Drive the lawn mower over every grass patch on the property.
{% endstep %}
{% step %}
## Cut plants
Trim each marked plant by hand with the shears.
{% endstep %}
{% step %}
## Plant flowers
Plant, water and fertilize the flowers at each marker.
{% endstep %}
{% endstepper %}
### Locksmith
Drive to stranded customers, read their lock pattern, cut a key on the van, and deliver it.
{% stepper %}
{% step %}
## Take the work van
Spawn the locksmith van from the dispatcher.
{% endstep %}
{% step %}
## Service every customer
Drive to each stranded customer, read their lock pattern, cut the key at your van and deliver it.
{% endstep %}
{% step %}
## Return to the dispatcher
All customers served — head back to close out the shift.
{% endstep %}
{% endstepper %}
### Lumberjack
Fell trees with a chainsaw, buck them into logs, load the hauler and dump at the sawmill.
{% stepper %}
{% step %}
## Take a truck
Spawn a hauler truck from the foreman's depot.
{% endstep %}
{% step %}
## Fell a tree
Use your chainsaw to drop a tree and buck it into logs.
{% endstep %}
{% step %}
## Load the trunk
Stack the bucked logs into your truck's trunk.
{% endstep %}
{% step %}
## Dump at the sawmill
Drive the loaded truck to the sawmill and dump the logs.
{% endstep %}
{% endstepper %}
### Miner
Swing a pickaxe at the quarry, load the ore into a hauler, and unload at the crusher.
{% stepper %}
{% step %}
## Take a truck
Spawn a hauler truck from the foreman's depot.
{% endstep %}
{% step %}
## Mine ore from the rocks
Swing your pickaxe to break ore off the rocks.
{% endstep %}
{% step %}
## Load the trunk
Stack the mined ore into your truck's trunk.
{% endstep %}
{% step %}
## Drop ore at the crusher
Drive the loaded truck to the crusher and unload each ore.
{% endstep %}
{% step %}
## Return to the foreman
All ore processed — head back to finish the shift.
{% endstep %}
{% endstepper %}
### Movers
Pack a client's belongings, load the truck, drive to the new home and unpack.
{% stepper %}
{% step %}
## Pack the items
Wrap and box up each item at the client's place.
{% endstep %}
{% step %}
## Load the box into the truck
Carry the packed box to the truck and load it in.
{% endstep %}
{% step %}
## Drive to the new home
Drive the moving truck to the destination address.
{% endstep %}
{% step %}
## Unpack the items
Place each item at its spot in the new home.
{% endstep %}
{% step %}
## Return to the dispatcher
Drive the truck back and finish the shift.
{% endstep %}
{% endstepper %}
### Newsroom
Write the morning edition at the laptop, print copies on the press, then deliver papers around town.
{% stepper %}
{% step %}
## Write pages at the laptop
Use the editor's laptop on the press floor to write each page.
{% endstep %}
{% step %}
## Print copies on the press
Run the printers on the press floor to print each copy.
{% endstep %}
{% step %}
## Deliver newspapers around town
Drive around town and throw papers at each delivery marker.
{% endstep %}
{% endstepper %}
### Pizzeria
Roll dough, sauce, top, bake, and deliver pizzas before they go cold.
{% stepper %}
{% step %}
## Prepare an order
Roll the dough, spread sauce, add toppings and bake the pizza.
{% endstep %}
{% step %}
## Deliver to customers
Drive to each delivery marker and hand the pizza over before it goes cold.
{% endstep %}
{% step %}
## Return to the dispatcher
All deliveries complete — head back to close out the shift.
{% endstep %}
{% endstepper %}
### Salvage Diver
Take a submersible down to the sea floor, attach the rope to sunken crates and surface them.
{% stepper %}
{% step %}
## Get a submersible
Spawn a submersible from the dock to dive.
{% endstep %}
{% step %}
## Recover the crates
Attach the rope to each sunken crate and surface it.
{% endstep %}
{% step %}
## Return to the dispatcher
Head back to the dispatcher to close the shift.
{% endstep %}
{% endstepper %}
### Taxi
Pick up NPC fares, drive them safely to their destination, and keep them happy along the way.
{% stepper %}
{% step %}
## Pick up customer
Drive to the pickup marker and let the customer board.
{% endstep %}
{% step %}
## Drop off customer
Drive carefully to the destination and drop them off.
{% endstep %}
{% endstepper %}
### Tow Truck
Hook broken-down vehicles, winch them onto the flatbed and deliver them to the impound.
{% stepper %}
{% step %}
## Take the work truck
Spawn the flatbed truck from the dispatcher.
{% endstep %}
{% step %}
## Drive to the broken vehicle
Find the marked broken vehicle and hook it up to the flatbed.
{% endstep %}
{% step %}
## Winch the vehicle onto the flatbed
Operate the winch to pull the hooked vehicle onto the bed.
{% endstep %}
{% step %}
## Deliver to the impound
Tow the secured vehicle to the impound drop-off.
{% endstep %}
{% endstepper %}
### Trucker
Spawn the rig, hook up a trailer, haul it to the dropoff and return to the depot.
{% stepper %}
{% step %}
## Take the work truck
Spawn the truck from the dispatcher.
{% endstep %}
{% step %}
## Hook up your trailer
Drive the truck to the trailer marker and back into it.
{% endstep %}
{% step %}
## Deliver to dropoff
Haul the trailer to the dropoff marker.
{% endstep %}
{% step %}
## Return to depot to finish
Drive the truck back to the depot to close the shift.
{% endstep %}
{% endstepper %}
# Exports & Hooks
Jobs V exposes server-side events and exports so you can hook your own systems into the job loop — reward multipliers, custom logging, achievement trackers, whitelisting, and so on.
{% hint style="info" %}
All events and exports below are **server-side only**. The event prefix is the resource folder name — if you renamed the resource, replace `rm_jobsv` with your folder name.
{% endhint %}
### Events
Register these with a standard `AddEventHandler` in any server file of your own resource.
#### `rm_jobsv:jobStarted`
Fires when a player clocks in. In a crew, it fires once **per member**.
| Parameter | Type | Description |
| --------- | -------- | ----------------------------------- |
| `source` | `number` | Server ID of the player |
| `jobId` | `string` | Job identifier, e.g. `"lumberjack"` |
```lua
AddEventHandler("rm_jobsv:jobStarted", function(source, jobId)
print(("%s started the %s job"):format(GetPlayerName(source), jobId))
end)
```
#### `rm_jobsv:jobStopped`
Fires when a player clocks out — whether the shift was completed, cancelled, or ended by disconnect. Also fires once per crew member.
| Parameter | Type | Description |
| --------- | -------- | ----------------------- |
| `source` | `number` | Server ID of the player |
| `jobId` | `string` | Job identifier |
```lua
AddEventHandler("rm_jobsv:jobStopped", function(source, jobId)
activeWorkers[source] = nil
end)
```
#### `rm_jobsv:shiftCompleted`
Fires when a shift is paid out, **after** the money and EXP have been given. Fires once per crew member with that member's own share.
| Parameter | Type | Description |
| --------- | --------- | --------------------------------------------------------------------- |
| `source` | `number` | Server ID of the player |
| `jobId` | `string` | Job identifier |
| `payout` | `number` | Money paid to this player, including level, prestige and time bonuses |
| `exp` | `number` | EXP awarded — `0` if no work was done |
| `worked` | `boolean` | `false` if the player clocked out without completing any task |
```lua
AddEventHandler("rm_jobsv:shiftCompleted", function(source, jobId, payout, exp, worked)
if not worked then return end
exports["my_resource"]:addReputation(source, jobId, 1)
end)
```
{% hint style="warning" %}
A player can end a shift without doing anything. Always check `worked` before granting extra rewards, otherwise players can farm your reward by starting and stopping the job repeatedly.
{% endhint %}
#### `rm_jobsv:taskProgressed`
Fires every time the player advances their daily task.
| Parameter | Type | Description |
| ---------- | -------- | -------------------------------------- |
| `source` | `number` | Server ID of the player |
| `taskId` | `string` | Daily task identifier |
| `progress` | `number` | Current progress after this increment |
| `target` | `number` | Progress required to complete the task |
```lua
AddEventHandler("rm_jobsv:taskProgressed", function(source, taskId, progress, target)
if progress >= target then
print(("%s finished daily task %s"):format(GetPlayerName(source), taskId))
end
end)
```
### Exports
#### `getPlayerExp`
Returns the player's **total account EXP** across all jobs.
```lua
local exp = exports["rm_jobsv"]:getPlayerExp(source)
```
**Returns:** `number` — `0` if the player has no progress yet.
#### `getPlayerLevel`
Returns the player's **account level**, calculated from total EXP and capped at `Config.general.level.maxLevel`.
```lua
local level = exports["rm_jobsv"]:getPlayerLevel(source)
if level < 10 then
-- deny access to a level-gated feature
end
```
**Returns:** `number` — `1` if the player has no progress yet.
#### `getPlayerJobExp`
Returns the player's progress **for a single job**.
```lua
local data = exports["rm_jobsv"]:getPlayerJobExp(source, "miner")
print(data.exp, data.level)
```
| Field | Type | Description |
| ------- | -------- | ----------------------------------------------------------- |
| `exp` | `number` | EXP earned in this job |
| `level` | `number` | Per-job level, capped at `Config.general.jobLevel.maxLevel` |
**Returns:** `table` — `{ exp = 0, level = 1 }` if the player has never worked that job.
### Example: job-level whitelist
Combining an export with an event to gate a door behind mining experience:
```lua
RegisterNetEvent("myscript:openMineDoor", function()
local data = exports["rm_jobsv"]:getPlayerJobExp(source, "miner")
if data.level < 5 then
TriggerClientEvent("myscript:notify", source, "You need Miner level 5.")
return
end
TriggerClientEvent("myscript:doorOpened", source)
end)
```
# Custom Plates with Flipper
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
{% stepper %}
{% step %}
### Download and Prepare Files
#### Download the Script from FiveM Portal
* Visit the [FiveM Portal](https://portal.cfx.re/assets/granted-assets) site.
* Log in with your account credentials.
* Locate the **Custom Plates with Flipper** script in your Granted Assets section.
* Download the script files from Portal.
#### Install and Configure ox\_lib
* Download the latest version of **ox\_lib** from the [official GitHub page](https://github.com/CommunityOx/ox_lib/releases).
* Extract the `ox_lib` files to your `resources` folder.
* In your `server.cfg`, ensure that `ox_lib` starts before the **Custom Plates with Flipper** script by adding the appropriate start lines (see next step for example).
{% endstep %}
{% step %}
### Add Script to Server Configuration
#### Edit `server.cfg`
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following lines to ensure the required resources start with your server:
{% code title="server.cfg" %}
```
ensure ox_lib
ensure rm_customplate
ensure rm_customplate_assets
```
{% endcode %}
{% endstep %}
{% endstepper %}
# Configuration
```lua
lib.locale('en')
cfg = {}
-- Enables developer commands (/fake_plate, /plate_remover, /plate_flipper).
cfg.debug = false
-- ============================================================
-- BRIDGE CONFIGURATION
-- ============================================================
-- 'auto' detects QBCore or ESX automatically.
---@type 'auto' | 'qb' | 'esx'
cfg.framework = 'auto'
---@type 'ox_lib' | 'qb' | 'esx' | 'okokNotify' | 'ps-ui'
cfg.notification = 'ox_lib'
---@type 'ox_lib' | 'esx' | 'qb' | 'okokTextUI' | 'jg-textui'
cfg.textUI = 'ox_lib'
-- false = no progress bar, actions are instant.
---@type 'ox_lib' | 'qb' | 'esx' | false
cfg.progressbar = 'ox_lib'
cfg.script = {
-- QB/QBX -> player_vehicles | ESX -> owned_vehicles, The name of the database table where vehicle data is stored
-- Vehicles table. Must have a 'plate' column.
-- A 'custom_plate' LONGTEXT column is created automatically if missing.
dbTableName = 'player_vehicles',
-- Only the vehicle owner can apply/remove/flip plates (checked via bridge).
requireOwnership = false,
-- Player items that open the paint editor. Leave empty ({}) for presser-only setup.
-- shouldRemoveItem: consume the item on install.
-- editorSize: paint canvas resolution (matches the plate aspect ratio).
items = {
{ item = 'rm_plate_rectangle_s', group = 'rectangle_s', shouldRemoveItem = true, editorSize = { width = 400, height = 100 } },
{ item = 'rm_plate_rectangle_m', group = 'rectangle_m', shouldRemoveItem = true, editorSize = { width = 500, height = 150 } },
{ item = 'rm_plate_rectangle_l', group = 'rectangle_l', shouldRemoveItem = true, editorSize = { width = 600, height = 200 } },
{ item = 'rm_plate_square_s', group = 'square_s', shouldRemoveItem = true, editorSize = { width = 400, height = 200 } },
{ item = 'rm_plate_square_m', group = 'square_m', shouldRemoveItem = true, editorSize = { width = 500, height = 300 } },
{ item = 'rm_plate_square_l', group = 'square_l', shouldRemoveItem = true, editorSize = { width = 600, height = 400 } },
},
-- Toggleable plate, switched with G in the driver seat. Set to nil to disable.
-- allowCustomDesign: false = black plate only, no editor option.
flipperItem = {
item = 'rm_plate_flipper',
shouldRemoveItem = false,
allowCustomDesign = true,
},
-- Strips all custom plates and flippers from a vehicle. Set to nil to disable.
removerItem = {
item = 'rm_plate_remover',
shouldRemoveItem = false,
},
-- Progress bar durations (ms).
progressDuration = {
install = 3000,
remove = 2000,
},
-- Animation during progress bars. Set to false to skip the anim.
progressAnim = {
dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
name = 'machinic_loop_mechandplayer',
},
-- Plates spawn within renderDistance and despawn past removeRenderDistance.
-- The gap is hysteresis to stop flickering at the boundary.
renderDistance = 50.0,
removeRenderDistance = 65.0,
-- Mechanic workstations. Each is a world prop with a proximity prompt.
-- color: SetObjectTextureVariant index.
-- 0 = green 1 = red 2 = dark yellow 3 = green
-- 4 = cyan 5 = blue 6 = navy 7 = dark blue
-- 8 = purple 9 = pink 10 = pink 11 = red
platePressers = {
{
coords = vec3(-227.1, -1330.19, 29.89),
rotation = vector3(0.0, 0.0, 90.0),
allowedJobs = { 'mechanic' },
color = 2,
},
{
coords = vec3(-1082.41, -3283.27, 12.94),
rotation = vector3(0.0, 0.0, 0.0),
allowedJobs = { 'mechanic' },
color = 1,
},
},
}
```
# Language
```json
{
"plate_already_exists": "This vehicle already has a custom plate. Remove it first.",
"no_vehicle_nearby": "No nearby vehicle found.",
"no_player_nearby": "No nearby player found.",
"cannot_use_in_vehicle": "You must exit the vehicle first.",
"not_vehicle_owner": "You do not own this vehicle.",
"no_item": "You don't have the required item.",
"progress_install": "Installing plate...",
"progress_remove": "Removing plate...",
"second_plate_header": "Custom Plate",
"second_plate_content": "Would you like to add a **front plate** with the same design?",
"presser_unauthorized": "You are not authorized to use this presser.",
"presser_textui": "[E] Plate Presser",
"presser_menu_title": "Plate Presser",
"presser_select_size": "Select Plate Size",
"presser_size_selected": "Selected: %s",
"presser_size_not_selected": "Not selected",
"presser_size_shape": "Size & Shape",
"plate_rectangle_l": "Rectangle Large",
"plate_rectangle_m": "Rectangle Medium",
"plate_rectangle_s": "Rectangle Small",
"plate_square_l": "Square Large",
"plate_square_m": "Square Medium",
"plate_square_s": "Square Small",
"presser_give_editor": "Give Paint Editor",
"presser_give_editor_desc": "Open editor for closest player",
"presser_press_plate": "Press Plate",
"presser_design_ready": "Design ready — press to attach",
"presser_waiting_design": "Waiting for design...",
"presser_design_received": "Design received! Open presser menu to press the plate.",
"flipper_type_header": "Plate Flipper",
"flipper_type_label": "Flipper Type",
"flipper_type_custom": "Custom Design",
"flipper_type_black": "Black Plate",
"flipper_select_group": "Select Plate Size",
"flipper_group_label": "Plate Group",
"flipper_already_installed": "This vehicle already has a flipper installed. Remove it first.",
"flipper_cooldown": "Please wait before toggling the flipper again.",
"flipper_use": "[G] Use Flipper",
"flipper_revert": "[G] Revert Flipper",
"enable_cursor": "Enable Cursor",
"translate_mode": "Translate Mode",
"rotate_mode": "Rotate Mode",
"toggle_space": "Relative/World",
"done_editing": "Done Editing",
"close_gizmo_description": "Close gizmo",
"ui": {
"save": "Save",
"close": "Close",
"font": "Font",
"selection": "Selection",
"brush": "Brush",
"line": "Line",
"line_thickness": "Line Thickness",
"line_type": "Line Type",
"polygon": "Polygon",
"curve": "Curve",
"lines": "Lines",
"shapes": "Shapes",
"rect": "Rectangle",
"square": "Square",
"circle": "Circle",
"text": "Text",
"add_picture_from_url": "Add_picture_from_url",
"undo": "Undo",
"redo": "Redo",
"clear": "Clear",
"color": "Color",
"inner_color": "Inner Color",
"arrows": "Arrows",
"number_of_points": "Number of Points",
"bold": "Bold",
"italic": "Italic",
"opacity": "Opacity",
"grid": "Grid",
"unlocked": "Unlocked",
"locked": "Locked",
"hide": "Hide",
"show": "Show",
"background_color": "Background Color",
"no_layer_yet": "No layer yet",
"toggle_layers_panel": "Toggle layers panel",
"url": "URL"
}
}
```
# Exports
All exports are accessible via `exports.rm_customplate:(...)`.
***
### Client Exports
#### `isPlateHidden(vehicle)`
Returns whether the vehicle's real plate is currently hidden by an active flipper.
**Parameters**
| Name | Type | Description |
| --------- | -------- | --------------------- |
| `vehicle` | `number` | Vehicle entity handle |
**Returns**
| Type | Description |
| --------- | -------------------------------------------------------------------- |
| `boolean` | `true` if the flipper is installed and toggled on, `false` otherwise |
**Example**
```lua
if exports.rm_customplate:isPlateHidden(cache.vehicle) then
print('plate is hidden by flipper')
end
```
***
#### `hasCustomPlate(vehicle)`
Returns whether the vehicle has any custom plate data attached (normal custom plate or flipper).
**Parameters**
| Name | Type | Description |
| --------- | -------- | --------------------- |
| `vehicle` | `number` | Vehicle entity handle |
**Returns**
| Type | Description |
| --------- | ---------------------------------------------------------------------------------------- |
| `boolean` | `true` if the vehicle has at least one rendered plate or flipper data, `false` otherwise |
**Example**
```lua
local veh = lib.getClosestVehicle(GetEntityCoords(cache.ped), 5.0, false)
if veh and exports.rm_customplate:hasCustomPlate(veh) then
print('this vehicle has a custom plate')
end
```
***
#### `getPlateData(vehicle)`
Returns the plate data attached to the vehicle, or `nil` if none. If a flipper is installed it is returned first; otherwise the normal plate data is read from the entity's state bag.
**Parameters**
| Name | Type | Description |
| --------- | -------- | --------------------- |
| `vehicle` | `number` | Vehicle entity handle |
**Returns**
| Type | Description |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `table \| nil` | Flipper data if installed, otherwise normal plate array, or `nil` if the vehicle has no custom plate data |
**Return shape**
Normal custom plate (array of plate entries):
```lua
{
[1] = { base64 = string, offset = { x, y, z }, rotation = { x, y, z }, plateModel = string },
[2] = { ... }, -- optional front plate
}
```
Black flipper:
```lua
{
flip = true,
black = true,
base64 = string,
active = boolean,
}
```
Custom flipper:
```lua
{
flip = true,
active = boolean,
plates = {
[1] = { base64 = string, offset = { x, y, z }, rotation = { x, y, z }, plateModel = string },
[2] = { ... }, -- optional front plate
},
}
```
**Example**
```lua
local data = exports.rm_customplate:getPlateData(cache.vehicle)
if data then
if data.flip then
print(('flipper active=%s'):format(tostring(data.active)))
else
print(('normal plate, %d entry(ies)'):format(#data))
end
end
```
***
### Server Exports
#### `isPlateHidden(plate)`
Returns whether the vehicle's plate is currently hidden by an active flipper.
**Parameters**
| Name | Type | Description |
| ------- | -------- | ------------------------------------- |
| `plate` | `string` | Vehicle plate text (e.g. `"ABC1234"`) |
**Returns**
| Type | Description |
| --------- | ------------------------------------------------------------------ |
| `boolean` | `true` if a flipper is installed and toggled on, `false` otherwise |
**Example**
```lua
if exports.rm_customplate:isPlateHidden('ABC1234') then
print('plate hidden')
end
```
***
#### `hasCustomPlate(plate)`
Returns whether the given plate has any custom plate data persisted.
**Parameters**
| Name | Type | Description |
| ------- | -------- | ------------------ |
| `plate` | `string` | Vehicle plate text |
**Returns**
| Type | Description |
| --------- | ---------------------------------------------------------------------------------------- |
| `boolean` | `true` if the cache has data for this plate (normal plate or flipper), `false` otherwise |
**Example**
```lua
if exports.rm_customplate:hasCustomPlate('ABC1234') then
print('this plate has custom data')
end
```
***
#### `getPlateData(plate)`
Returns the full server-side plate data record, or `nil` if no data exists for the plate.
**Parameters**
| Name | Type | Description |
| ------- | -------- | ------------------ |
| `plate` | `string` | Vehicle plate text |
**Returns**
| Type | Description |
| -------------- | -------------------------------------------------------------- |
| `table \| nil` | Plate data table, or `nil` if nothing is stored for this plate |
**Return shape**
Normal custom plate (array of plate entries):
```lua
{
[1] = { base64 = string, offset = { x, y, z }, rotation = { x, y, z }, plateModel = string },
[2] = { ... }, -- optional front plate
}
```
Black flipper:
```lua
{
flip = true,
black = true,
base64 = string,
active = boolean,
}
```
Custom flipper:
```lua
{
flip = true,
active = boolean,
plates = {
[1] = { base64 = string, offset = { x, y, z }, rotation = { x, y, z }, plateModel = string },
[2] = { ... }, -- optional front plate
},
}
```
**Example**
```lua
local data = exports.rm_customplate:getPlateData('ABC1234')
if data then
if data.flip then
print(('flipper active=%s'):format(tostring(data.active)))
else
print(('normal plate, %d entry(ies)'):format(#data))
end
end
```
# Commands
### `/rm_flipper_toggle`
Toggles the plate flipper on the vehicle the player is currently driving. Default keybind: **G**.
The flipper must already be installed on the vehicle and the player must be in the driver seat. A 2-second cooldown prevents spam. Plays the flip animation and sound, then attaches the alternate plate.
**Parameters** — none.
**Permission** — open to all players. Validated server-side (ownership check if enabled in `cfg.script.requireOwnership`).
**Example**
```
/rm_flipper_toggle
```
Or simply press **G** while sitting in the driver seat of a flipper-equipped vehicle.
***
### Developer Commands
These commands are registered only when `cfg.debug = true` in `cfg.lua`. Keep them off in production.
#### `/fake_plate`
Opens the paint editor for a `rectangle_l` plate on the nearest vehicle, bypassing the item check on the client side. The server still validates ownership and item possession before applying.
**Parameters** — none.
**Example**
```
/fake_plate
```
***
#### `/plate_remover`
Triggers the plate remover flow on the nearest vehicle.
**Parameters** — none.
**Example**
```
/plate_remover
```
***
#### `/plate_flipper`
Triggers the flipper install flow (size/type selection, gizmo placement, editor) on the nearest vehicle, bypassing the item check on the client side.
**Parameters** — none.
**Example**
```
/plate_flipper
```
# 3D Tuning Tablet
{% hint style="warning" %}
**Important Information**
* **Pre-Installation Note:** This guide assumes you have a basic understanding of FiveM server management. If you are not a developer or are unfamiliar with server configurations, please follow the steps closely. Any errors during installation could lead to script malfunctions or server issues.
* **Support:** If you encounter problems after installation, check the "Common Questions" section at the end of this guide for solutions. For further assistance, you may need to consult with a developer or reach out to the script’s support team.
{% endhint %}
# Installation
{% stepper %}
{% step %}
### Download and Prepare Files
#### Download the Script from FiveM Portal
* Visit the [FiveM Portal](https://portal.cfx.re/assets/granted-assets) site.
* Log in with your account credentials.
* Locate the **3D Tuning Tablet** script in your Granted Assets section.
* Download the script files from Portal.
#### Install and Configure ox\_lib
* Download the latest version of **ox\_lib** from the [official GitHub page](https://github.com/CommunityOx/ox_lib/releases).
* Extract the `ox_lib` files to your `resources` folder.
* In your `server.cfg`, ensure that `ox_lib` starts before the **3D Tuning Tablet** script by adding the appropriate start lines (see next step for example).
{% endstep %}
{% step %}
### Add Script to Server Configuration
#### Edit `server.cfg`
* Open the `server.cfg` file located in the root directory of your FiveM server.
* Add the following lines to ensure the required resources start with your server:
{% code title="server.cfg" %}
```
ensure ox_lib
ensure rm_3dtuning_assets
ensure rm_3dtuning
```
{% endcode %}
{% endstep %}
{% endstepper %}
# Configuration
```lua
lib.locale('en')
cfg = {}
---@type 'auto' | 'qb' | 'esx'
cfg.framework = 'auto'
---@type 'ox_lib' | 'qb' | 'esx' | 'okokNotify' | 'ps-ui'
cfg.notification = 'ox_lib'
---@type 'ox_lib' | 'esx' | 'qb' | 'okokTextUI' | 'jg-textui'
cfg.textUI = 'ox_lib'
---@type 'ox_lib' | 'qb' | 'esx'
cfg.progressbar = 'ox_lib'
cfg.givenitroCommand = 'givenitro'
cfg.givenitroAlloweds = {
-- ['steam:00000000a000a00'] = true,
-- ['license:0aa00a00a00aa000a000000a00000a00a00aa000'] = true,
-- ['license2:0aa00a00a00aa000a000000a00000a00a00aa000'] = true,
-- ['fivem:0000000'] = true,
}
cfg.general = {
databaseTableName = 'player_vehicles', -- QB/QBX -> player_vehicles | ESX -> owned_vehicles
fakePlate = false, -- Set true if your server uses a fake-plate system (requires fakeplate column)
requireTurboMod = false, -- Require a turbo mod on the vehicle for nitrous to work
items = {
tablet = {
itemName = 'rm_car_tablet',
requireOwnership = false,
allowedJobs = false, -- Or a table like { 'mechanic', 'bennys' }
allowedClasses = {
[0] = true, [1] = true, [2] = true, [3] = true, [4] = true,
[5] = true, [6] = true, [7] = true, [9] = true, [22] = true,
},
blacklistedVehicles = {
[`sultan2`] = true,
},
shouldRemove = true,
progressBar = true,
},
nitro_bottles = {
requireOwnership = false,
allowedJobs = false,
-- Each item uses its own bottle texture variant (the physical bottle color).
-- The nitrous particle flame color is picked at install time via dialog (independent of the item).
items = {
{ itemName = 'rm_nitro_default', colorVariant = 0 },
{ itemName = 'rm_nitro_white', colorVariant = 1 },
{ itemName = 'rm_nitro_green', colorVariant = 3 },
{ itemName = 'rm_nitro_yellow', colorVariant = 4 },
{ itemName = 'rm_nitro_red', colorVariant = 5 },
{ itemName = 'rm_nitro_black', colorVariant = 6 },
{ itemName = 'rm_nitro_dgreen', colorVariant = 7 },
{ itemName = 'rm_nitro_brown', colorVariant = 8 },
{ itemName = 'rm_nitro_gray', colorVariant = 9 },
{ itemName = 'rm_nitro_purple', colorVariant = 10 },
{ itemName = 'rm_nitro_orange', colorVariant = 11 },
{ itemName = 'rm_nitro_pink', colorVariant = 12 },
},
allowedClasses = {
[0] = true, [1] = true, [2] = true, [3] = true, [4] = true,
[5] = true, [6] = true, [7] = true, [9] = true, [22] = true,
},
blacklistedVehicles = {
[`sultan2`] = true,
},
shouldRemove = true,
progressBar = true,
},
},
nitrous = {
defaultKey = 'LSHIFT',
requireTablet = false,
boost = 75.0, -- Engine power multiplier when nitrous is active
antiSpamCooldown = 5000, -- ms between activations
drain = 1.0, -- Drain per tick (100ms)
minSpeed = 10.0, -- km/h
minRpm = 0.2, -- 0.0 - 1.0
purgeOnRelease = true,
purgeOnReleaseDuration = 1000, -- ms
commands = {
nitrobar = 'nitrobar',
move_nitrobars = 'move_nitrobar',
reset_nitrobars = 'reset_nitrobar',
},
nitro_tanks = {
max_count = 3, -- Default max tanks per vehicle
vehicles = {
[`sultan2`] = 1, -- Per-model override
}
},
installAnim = {
dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
name = 'machinic_loop_mechandplayer',
duration = 4000,
},
openDoorsOnPlace = true,
nitro_object = {
defaultBone = 0, -- Bone the nitrous object is attached to
},
ptfx = {
bones = { "exhaust", "exhaust_2", "exhaust_3", "exhaust_4", "exhaust_5", "exhaust_6", "exhaust_7", "exhaust_8", "exhaust_9", "exhaust_10", "exhaust_11", "exhaust_12", "exhaust_13", "exhaust_14", "exhaust_15", "exhaust_16" },
colors = {
[0] = { size = 0.5, label = 'exhaust_color_blue' },
[1] = { size = 0.5, label = 'exhaust_color_white' },
[2] = { size = 0.5, label = 'exhaust_color_purple' },
[3] = { size = 0.5, label = 'exhaust_color_green' },
[4] = { size = 0.5, label = 'exhaust_color_yellow' },
[5] = { size = 0.5, label = 'exhaust_color_red' },
[6] = { size = 0.5, label = 'exhaust_color_pink' },
[7] = { size = 0.5, label = 'exhaust_color_orange' },
[8] = { size = 0.5, label = 'exhaust_color_cyan' },
[9] = { size = 0.5, label = 'exhaust_color_darkblue' },
[10] = { size = 0.5, label = 'exhaust_color_darkgreen' },
[11] = { size = 0.5, label = 'exhaust_color_brown' },
[12] = { size = 0.5, label = 'exhaust_color_black' },
},
}
},
purge = {
defaultKey = 'G',
bone = 'bonnet',
sprayCount = 4,
sprayOffset = { x = 0.5, y = 0.05, z = 0.0 },
sprayRotation = { left = vector3(40.0, -20.0, 0.0), right = vector3(40.0, 20.0, 0.0) },
sprayScale = 0.5,
},
glowingDiscs = {
defaultKey = '',
onlyBackWheels = true,
ptfx = {
offset = vector3(-0.02, 0.0, 0.0),
rotation = vector3(0.0, 0.0, 90.0),
scale = 0.5,
},
customOffsets = {
[`sultanrs`] = {
front = { offset_x = 0.0, offset_scale = 1.0 },
rear = { offset_x = 0.0, offset_scale = 1.0 },
}
}
},
drift_mode = {
defaultKey = 'LCONTROL',
maxSpeed = 75.0, -- km/h
},
drift_hd = {
defaultKey = 'LCONTROL', -- Same as drift_mode so both can stack
defaultPreset = 'default',
vehicles = {
-- Per-model preset mapping. Presets defined in client/drift/presets.lua
[`sultan2`] = 'drift_hard',
[`miata`] = 'drift_miata',
},
},
sport_mode = {
defaultKey = '',
powerMultiplier = 150.0,
interruptDuration = 200,
},
popcorn = {
defaultKey = '',
rpm = 0.65,
ptfx = {
{ size = 0.25, offset = vector3(0.0, -0.1, 0.0), rotation = vector3(0.0, 0.0, -180.0) },
{ size = 0.95, offset = vector3(0.0, -0.1, 0.0), rotation = vector3(0.0, 0.0, 0.0) },
},
},
drift_smoke = {
defaultKey = '',
onlyBackWheels = true,
ptfx = {
offset = vector3(0.05, 0.0, 0.0),
rotation = vector3(0.0, 0.0, 0.0),
}
},
throttle_control = {
defaultKey = '',
maxRpm = 0.8,
maxSpeed = 200,
allowedClasses = {
[0] = true, [1] = true, [2] = true, [3] = true,
[4] = true, [5] = true, [6] = true, [7] = true,
}
},
rollback_handbrake = {
defaultKey = '',
rollbackConfig = {
enabled = true,
duration = 30,
strength = 10,
},
handbrakeTurnConfig = {
enabled = true,
strength = 1.5,
}
},
interior_light = { defaultKey = '' },
neon_light = { defaultKey = '' },
shunt = {
defaultKey = 'LCONTROL',
magnitude = 18.0,
upForce = 500 * 100,
cooldown = 15000, -- ms
camShakeIntensity = 0.25,
camShakeDuration = 500, -- ms
velocityLerpDuration = 500, -- ms
},
custom_exhaust = {
itemName = 'rm_custom_exhaust',
requireOwnership = false,
allowedJobs = false,
allowedClasses = {
[0] = true, [1] = true, [2] = true, [3] = true, [4] = true,
[5] = true, [6] = true, [7] = true, [9] = true, [22] = true,
},
blacklistedVehicles = {
[`sultan2`] = true,
},
shouldRemove = true,
progressBar = true,
installAnim = {
dict = 'anim@amb@clubhouse@tutorial@bkr_tut_ig3@',
name = 'machinic_loop_mechandplayer',
duration = 4000,
},
remover = {
itemName = 'rm_exhaust_remover',
shouldRemove = true,
progressBar = true,
},
prop = `imp_prop_impexp_exhaust_05`,
animDict = 'anim@heists@box_carry@',
animName = 'idle',
installTime = 5000,
maxDistance = 5.0,
throttleLiftRpm = 0.7,
ptfxDuration = 300, -- ms
fireCooldown = 100, -- ms between two backfire events on same vehicle
backfirePtfx = { size = 0.95, offset = vector3(0.0, -0.1, 0.0), rotation = vector3(0.0, 0.0, 0.0) },
ptfx = {
bones = { "exhaust", "exhaust_2", "exhaust_3", "exhaust_4", "exhaust_5", "exhaust_6", "exhaust_7", "exhaust_8", "exhaust_9", "exhaust_10", "exhaust_11", "exhaust_12", "exhaust_13", "exhaust_14", "exhaust_15", "exhaust_16" },
colors = {
[0] = { size = 0.5, label = 'exhaust_color_blue' },
[1] = { size = 0.5, label = 'exhaust_color_white' },
[2] = { size = 0.5, label = 'exhaust_color_purple' },
[3] = { size = 0.5, label = 'exhaust_color_green' },
[4] = { size = 0.5, label = 'exhaust_color_yellow' },
[5] = { size = 0.5, label = 'exhaust_color_red' },
[6] = { size = 0.5, label = 'exhaust_color_pink' },
[7] = { size = 0.5, label = 'exhaust_color_orange' },
[8] = { size = 0.5, label = 'exhaust_color_cyan' },
[9] = { size = 0.5, label = 'exhaust_color_darkblue' },
[10] = { size = 0.5, label = 'exhaust_color_darkgreen' },
[11] = { size = 0.5, label = 'exhaust_color_brown' },
[12] = { size = 0.5, label = 'exhaust_color_black' },
},
},
},
menu = {
{ label = locale('menu_nitrous'), name = 'nitrous', icon = 'fire', enabled = true },
{ label = locale('menu_purge'), name = 'purge', icon = 'smog', enabled = true },
{ label = locale('menu_popcorn'), name = 'popcorn', icon = 'bomb', enabled = true },
{ label = locale('menu_glow'), name = 'glow', icon = 'fire', enabled = true },
{ label = locale('menu_drift'), name = 'drift', icon = 'cog', enabled = true },
{ label = locale('menu_drift_hd'), name = 'drift_hd', icon = 'cog', enabled = true },
{ label = locale('menu_drift_smoke'), name = 'smoke', icon = 'smog', enabled = true },
{ label = locale('menu_sport_mode'), name = 'sport_mode', icon = 'cog', enabled = true },
{ label = locale('menu_throttle_control'), name = 'throttle_control', icon = 'cog', enabled = true },
{ label = locale('menu_rollback'), name = 'rollback', icon = 'cog', enabled = true },
{ label = locale('menu_neon'), name = 'neon', icon = 'lightbulb', enabled = true },
{ label = locale('menu_interior_lights'), name = 'interior_lights', icon = 'lightbulb', enabled = true },
{ label = locale('menu_shunt'), name = 'shunt', icon = 'bolt', enabled = true },
},
}
```
# Language
```json
{
"translate_mode": "Translate",
"rotate_mode": "Rotate",
"toggle_space": "Relative/World",
"enable_cursor": "Toggle Cursor",
"done_editing": "Done",
"close_gizmo_description": "Cancel",
"menu_nitrous": "NITROUS",
"menu_purge": "PURGE",
"menu_popcorn": "POP-CORN",
"menu_glow": "GLOWING DISCS",
"menu_drift": "DRIFT+ MODE",
"menu_drift_hd": "DRIFT MODE+HD",
"menu_drift_smoke": "DRIFT SMOKE",
"menu_sport_mode": "SPORT+ MODE",
"menu_throttle_control": "THROTTLE CONTROL",
"menu_rollback": "ROLLBACK & HANDBRAKE",
"menu_neon": "NEON",
"menu_interior_lights": "INTERIOR LIGHTS",
"menu_shunt": "SHUNT BOOST",
"nitrous_enabled": "Nitrous enabled",
"nitrous_disabled": "Nitrous disabled",
"purge_enabled": "Purge activated",
"purge_disabled": "Purge deactivated",
"drift_smoke_enabled": "Drift smoke enabled",
"drift_smoke_disabled": "Drift smoke disabled",
"popcorn_enabled": "Popcorn enabled",
"popcorn_disabled": "Popcorn disabled",
"glow_enabled": "Glow brakes enabled",
"glow_disabled": "Glow brakes disabled",
"throttle_enabled": "Throttle control enabled",
"throttle_disabled": "Throttle control disabled",
"rollback_enabled": "Rollback & Handbrake enabled",
"rollback_disabled": "Rollback & Handbrake disabled",
"sport_mode_enabled": "Sport mode enabled",
"sport_mode_disabled": "Sport mode disabled",
"drift_enabled": "Drift mode enabled",
"drift_disabled": "Drift mode disabled",
"drift_hd_enabled": "Drift HD mode enabled",
"drift_hd_disabled": "Drift HD mode disabled",
"interior_light_toggled": "Interior lights toggled",
"neon_light_toggled": "Neon lights toggled",
"keybind_nitrous": "Hold Nitrous",
"keybind_purge": "Hold Purge",
"keybind_drift_smoke": "Toggle Drift Smoke",
"keybind_popcorn": "Toggle Popcorn",
"keybind_glow": "Toggle Glow Brakes",
"keybind_throttle": "Toggle Throttle Control",
"keybind_rollback": "Toggle Rollback & Handbrake",
"keybind_sport_mode": "Toggle Sport Mode",
"keybind_drift": "Hold Drift Mode",
"keybind_drift_hd": "Hold Drift HD Mode",
"keybind_interior_light": "Toggle Interior Lights",
"keybind_neon": "Toggle Neon Lights",
"keybind_shunt": "Forward Shunt",
"toggle_tablet": "Open Vehicle Tablet",
"nitrous_cooldown": "Nitrous is on cooldown, please wait",
"nitro_not_in_vehicle": "You must be in a vehicle",
"nitro_max_tanks": "This vehicle has reached the maximum number of nitrous tanks",
"vehicle_not_owned": "You must own this vehicle to do that.",
"vehicle_class_not_allowed": "This vehicle type is not supported",
"vehicle_blacklisted": "This vehicle is not compatible",
"vehicle_occupied": "Someone is in the vehicle, cannot install nitrous",
"vehicle_occupied_exhaust": "Someone is in the vehicle, cannot modify the exhaust",
"tablet_already_installed": "This vehicle already has a tablet installed",
"nitro_requires_turbo": "This vehicle requires a turbo modification to use nitrous",
"exit_tablet": "Exit Tablet",
"remove_tablet": "Remove Tablet",
"tablet_not_installed": "This vehicle does not have a tablet installed.",
"tablet_not_driving": "You must be the driver to use the tablet.",
"tablet_vehicle_moving": "You must stop the vehicle to use the tablet.",
"tablet_removed": "Tablet has been removed from the vehicle",
"givenitro_no_auth": "You have no authorization for this.",
"givenitro_not_in_vehicle": "You must be in a vehicle.",
"givenitro_player_not_online": "Player ID %d is not online.",
"givenitro_player_not_in_vehicle": "Player ID %d is not in a vehicle.",
"givenitro_success": "Added %d nitrous tank(s) to vehicle.",
"job_not_allowed": "Your job does not allow you to use this item.",
"nitrobar_not_in_vehicle": "You must be in a vehicle.",
"nitrobar_no_nitro": "This vehicle has no nitrous installed.",
"nitrobar_hidden": "Nitro bar hidden.",
"nitrobar_shown": "Nitro bar shown.",
"nitrobar_confirm_position": "Confirm",
"nitrobar_move_mode": "Drag the nitro bar to your desired position.",
"nitrobar_position_reset": "Nitro bar position reset.",
"progress_tablet_opening": "Opening tablet...",
"progress_tablet_install": "Installing tablet...",
"nitro_color_dialog_title": "Select Nitrous Color",
"progress_nitro_install": "Installing nitrous...",
"shunt_activated": "Shunt boost activated!",
"shunt_cooldown": "Shunt boost is on cooldown",
"exhaust_no_vehicle_nearby": "No vehicle nearby",
"exhaust_carry_textui": "[Enter] Install Exhaust | [ESC] Cancel",
"exhaust_sound_checkbox": "Sound Effect",
"exhaust_color_dialog_title": "Select Exhaust Color",
"exhaust_color_blue": "Blue",
"exhaust_color_white": "White",
"exhaust_color_purple": "Purple",
"exhaust_color_green": "Green",
"exhaust_color_yellow": "Yellow",
"exhaust_color_red": "Red",
"exhaust_color_pink": "Pink",
"exhaust_color_orange": "Orange",
"exhaust_color_cyan": "Cyan",
"exhaust_color_darkblue": "Dark Blue",
"exhaust_color_darkgreen": "Dark Green",
"exhaust_color_brown": "Brown",
"exhaust_color_black": "Black",
"exhaust_installed": "Custom exhaust installed!",
"exhaust_removed": "Custom exhaust removed!",
"exhaust_not_installed": "This vehicle does not have a custom exhaust installed.",
"progress_exhaust_install": "Installing custom exhaust...",
"progress_exhaust_remove": "Removing custom exhaust...",
"tablet_device_connected": "DEVICE CONNECTED"
}
```
# Exports
All exports are accessible via `exports.rm_3dtuning:(...)`.
***
### Client Exports
#### `getNitroData(plate)`
Returns current client-side nitrous state for the given vehicle plate.
**Parameters**
| Name | Type | Description |
| ------- | -------- | ---------------------------------------- |
| `plate` | `string` | Vehicle plate (auto-trimmed internally). |
**Returns**
| Type | Description |
| -------------- | --------------------------------------------------------- |
| `table \| nil` | Nitrous state object, or `nil` if vehicle has no nitrous. |
**Return shape**
| Field | Type | Description |
| ------------- | -------------------- | ---------------------------------------------------- |
| `hasnitro` | `boolean` | `true` when at least one tank is installed. |
| `tanks` | `integer` | Total number of installed tanks. |
| `tankLevels` | `table` | 1-indexed map, each entry `0–100` (percent drained). |
| `currentTank` | `integer` | Index of the tank currently being consumed. |
**Example**
```lua
local data = exports.rm_3dtuning:getNitroData('ABC1234')
if data and data.hasnitro then
print(('tanks=%d currentTank=%d'):format(data.tanks, data.currentTank))
end
```
***
#### `isNitroActive()`
Returns whether the local player is actively holding the nitrous activation key right now.
**Parameters** — none.
**Returns**
| Type | Description |
| --------- | --------------------------------------- |
| `boolean` | `true` while nitrous is being consumed. |
***
#### `getVehicleFeatures(plate)`
Returns the tablet menu toggle states for the given vehicle.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| ------- | ----------------------- |
| `table` | Feature-to-boolean map. |
**Return shape** (all fields are `boolean`)
| Field | Description |
| ------------------ | ----------------------------- |
| `nitrous` | Nitrous enabled. |
| `purge` | Purge enabled. |
| `popcorn` | Popcorn backfire enabled. |
| `glow` | Glowing brake discs enabled. |
| `drift` | Drift+ mode enabled. |
| `drift_hd` | Drift HD mode enabled. |
| `smoke` | Drift smoke enabled. |
| `sport_mode` | Sport mode enabled. |
| `throttle_control` | Throttle control enabled. |
| `rollback` | Rollback & handbrake enabled. |
| `neon` | Neon lights enabled. |
| `interior_lights` | Interior lights enabled. |
| `shunt` | Shunt boost enabled. |
***
#### `getCurrentVehicleFeatures()`
Returns the tablet feature toggles of the vehicle the local player is currently inside.
**Parameters** — none.
**Returns**
| Type | Description |
| ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `table` | Same shape as [`getVehicleFeatures`](https://docs.rainmad.com/resources/3d-tuning-tablet/exports#getvehiclefeatures-plate). |
***
#### `getCurrentExhaust()`
Returns custom exhaust data for the vehicle the local player is currently inside.
**Parameters** — none.
**Returns**
| Type | Description |
| -------------- | -------------------------------------------------------------------------------- |
| `table \| nil` | Exhaust data, or `nil` if not inside a vehicle or vehicle has no custom exhaust. |
**Return shape**
| Field | Type | Description |
| ------- | --------- | -------------------------------------- |
| `color` | `integer` | Selected flame color index (`0–12`). |
| `sound` | `boolean` | Whether the backfire sound is enabled. |
***
### Server Exports
#### `getNitroData(plate)`
Returns the server-side cached nitrous record for the given plate.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| -------------- | --------------------------------------------------- |
| `table \| nil` | Cached record, or `nil` if no nitrous is installed. |
**Return shape**
| Field | Type | Description |
| ------------ | --------- | -------------------------------------------------------------------- |
| `hasnitro` | `boolean` | Always `true` when a record is returned. |
| `nos_level` | `number` | Current tank drain level (`0–100`, percent drained of current tank). |
| `nos_bottle` | `integer` | Total installed tanks. |
| `color` | `integer` | Selected particle flame color index (`0–12`). |
***
#### `hasTablet(plate)`
Checks whether the given vehicle has a tablet installed.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| --------- | --------------------------------- |
| `boolean` | `true` if a tablet record exists. |
***
#### `getTabletData(plate)`
Returns the tablet offset/rotation record for the given vehicle.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| -------------- | --------------------------------------------------- |
| `table \| nil` | Tablet placement record, or `nil` if not installed. |
**Return shape**
| Field | Type | Description |
| ---------- | --------- | ------------------------------------- |
| `offset` | `vector3` | Local offset from the vehicle origin. |
| `rotation` | `vector3` | Local rotation (pitch, roll, yaw). |
***
#### `hasExhaust(plate)`
Checks whether the given vehicle has a custom exhaust installed.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| --------- | ----------------------------------------- |
| `boolean` | `true` if a custom exhaust record exists. |
***
#### `getExhaustData(plate)`
Returns the server-side cached custom exhaust record for the given vehicle.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| -------------- | ------------------------------------------ |
| `table \| nil` | Exhaust record, or `nil` if not installed. |
**Return shape**
| Field | Type | Description |
| ------- | --------- | -------------------------------------- |
| `color` | `integer` | Selected flame color index (`0–12`). |
| `sound` | `boolean` | Whether the backfire sound is enabled. |
***
#### `getVehicleFeatures(plate)`
Returns the persisted tablet menu toggle states for the given vehicle.
**Parameters**
| Name | Type | Description |
| ------- | -------- | -------------- |
| `plate` | `string` | Vehicle plate. |
**Returns**
| Type | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `table \| nil` | Same shape as the client [`getVehicleFeatures`](https://docs.rainmad.com/resources/3d-tuning-tablet/exports#getvehiclefeatures-plate), or `nil` if the vehicle has no saved feature state yet. |
# Commands
All commands can be renamed in `cfg.lua` — the names documented below are the defaults.
***
### Client Commands
#### `/nitrobar`
Toggles the nitrous HUD bar on/off for the vehicle the player is currently driving.
**Config key:** `cfg.general.nitrous.commands.nitrobar` (default: `"nitrobar"`)
**Usage:** `/nitrobar`
**Preconditions**
| Check | Error message (locale key) |
| ------------------------------------ | -------------------------- |
| Player must be in a vehicle. | `nitrobar_not_in_vehicle` |
| Vehicle must have nitrous installed. | `nitrobar_no_nitro` |
***
#### `/move_nitrobar`
Enters drag mode so the player can reposition the nitrous HUD bar on their screen.
**Config key:** `cfg.general.nitrous.commands.move_nitrobars` (default: `"move_nitrobar"`)
**Usage:** `/move_nitrobar`
**Preconditions**
| Check | Error message (locale key) |
| ------------------------------------ | -------------------------- |
| Player must be in a vehicle. | `nitrobar_not_in_vehicle` |
| Vehicle must have nitrous installed. | `nitrobar_no_nitro` |
***
#### `/reset_nitrobar`
Resets the nitrous HUD bar to its default screen position.
**Config key:** `cfg.general.nitrous.commands.reset_nitrobars` (default: `"reset_nitrobar"`)
**Usage:** `/reset_nitrobar`
***
### Server Commands
#### `/givenitro`
Admin command. Adds nitrous tanks to the target player's current vehicle.
**Config key:** `cfg.givenitroCommand` (default: `"givenitro"`)
**Usage:** `/givenitro [playerid] [count]`
**Parameters**
| Name | Type | Required | Description |
| ---------- | -------- | -------- | --------------------------------------------------- |
| `playerid` | `number` | Yes | Target player's server ID. |
| `count` | `number` | No | Number of tanks to add. Defaults to `1` if omitted. |
**Authorization**
Allowed if **either** of the following is true:
* The caller has the `command` ACE permission, **or**
* One of the caller's identifiers is listed in `cfg.givenitroAlloweds` (`steam:`, `license:`, `license2:`, `fivem:`).
**Preconditions**
| Check | Error message (locale key) |
| --------------------------------------- | --------------------------------- |
| Target player must be online. | `givenitro_player_not_online` |
| Target player must be inside a vehicle. | `givenitro_player_not_in_vehicle` |
**Behavior**
Adds the requested amount of nitrous tanks to the target vehicle, clamped to the vehicle's per-model maximum (`cfg.general.nitrous.nitro_tanks`). The caller receives a success notification.
**Example**
```
/givenitro 12 2
```
Gives `2` nitrous tanks to the player with server ID `12`.
---
[Next Page](/llms-full.txt/1)