Configuration

← README · Install · Developer API · FAQ

Three files, all readable in both editions:

File	What's in it
config.lua	framework, admin, lobby, hub, modes, match rules, damage, HUD, item pictures, zone, airdrops, vehicles, bots, rewards, keys
config/loot.lua	items, rarity tiers, attachments, carry limits, loot pools, bot loadouts, world props
config/maps.lua	the arenas

Restart the resource after editing (ensure lumo-battleroyale in the console).

---

General

Config.Debug = false        -- true adds /brdebug (coords + match state in F8). Keep false on a live server.
Config.Framework = 'auto'   -- 'auto' | 'qbx' | 'qb' | 'esx' | 'standalone'
Config.Target = 'auto'      -- 'auto' | 'qb' | 'ox' | 'none' (none = walk up and press E)
Config.Admin = { permissions = { 'admin', 'god' }, ace = 'lumo.battleroyale.admin' }

auto picks Qbox, then QBCore, then ESX, then standalone. For the target it picks a real qb-target first, then ox_target. On ESX use permissions = { 'admin', 'superadmin' }.

Lobby

Key	Default
command	false	a command that opens the lobby anywhere, e.g. 'br'. By default players use the hub
leaveCommand	'brleave'	leave the queue or the match
adminCommand	'bradmin'	the admin panel
minPlayers	1	humans needed to start the countdown (bots fill the rest)
maxPlayers	32	humans per match
countdown / fullCountdown	45 / 10	seconds to launch, and once the lobby is full
matchSize	100	humans + bots per match
allowConcurrentMatches	true	a new queue can launch while another match runs

Hub

Config.Hub.coords is where the camp stands (vec4; the ground Z is found at runtime). Admins can move it in game with Move hub here, which writes data/hub.json and takes priority over the config.

• blip: sprite, colour, scale, label, shortRange, and launchColour (used while a queue counts down).
• ped: the instructor model. drawDistance: props and screens exist only while a player is this close.
• props: decoration, as offsets from the hub (x right, y forward, z up, h heading).
• wall: the big status screen (prop_huge_display_01) and its brightness.
• computers: the terminal desks, monitor model, station positions, camera, and the lobby page size on the monitor.

Modes

Config.Modes = {
    solo  = { label = 'Solo',  teamSize = 1 },
    duo   = { label = 'Duo',   teamSize = 2 },
    squad = { label = 'Squad', teamSize = 4 },
}

Remove a line to turn a mode off, but keep solo: the lobby and /brtest default to it. A new team size (e.g. trio = { label = 'Trio', teamSize = 3 }) needs only a key, a label and a team size.

Match

Key	Default
bucketBase	7300	routing buckets 7301, 7302 … one per match. Change it if another script uses these
warmup	30	seconds of free-fire warm-up
warmupWeapon	WEAPON_PISTOL
endDelay	15	seconds on the results screen
maxDuration	1800	hard stop, in seconds
friendlyFire	false
knockedBleedout / reviveTime / reviveHealth	30 / 6 / 30	Duo/Squad knocked state
spectate / spectateBots	true / true	allow spectating, and keep a bots-only match running while someone watches
teamRadio / radioBase	true / 900	pma-voice channel per team
aiDamage	0.6	damage bots deal to players (1.0 = full GTA damage)

Config.Damage sets the headshot multiplier, helmet and vest reduction per level, vest durability, fall damage and a damage multiplier per weapon class. Config.Health = { max = 800, floor = 700 } is the hidden health floor that keeps frameworks from seeing a death. Leave it unless you know why you're changing it.

HUD

Config.Hud switches each helper on or off: gunfire (+ gunfireRange), aimTags, damageDirection, teammateMarkers, lootBeams, minimap, crosshair, and mph for the speedometer.

Visual sound (Config.Hud.sound)

What a player would hear shows up on the minimap, the pause map and the compass. Teammates never show.

Key	Default	Meaning
gunfire / gunfireRange	true / 250.0	enemy shots: gun icon + red area on the maps, red tick on the compass
sound.silencedRange	45.0	silenced shots are only heard this close (0 = never)
sound.footsteps	true	orange footprints for enemies moving near you
sound.sprintRange / runRange / walkRange	45 / 30 / 12	how far each pace is heard; crouched or stealth movement is silent
sound.vehicles / vehicleRange	true / 140.0	enemy vehicles with the engine running
sound.blur	0.08	far marks sit up to this share of the distance off the real spot (a direction, not a wallhack)
sound.pauseMap	true	false keeps the marks on the minimap only

Config.Hud.minimap = true keeps the radar on during a match, even if the city HUD hides it on foot.

City HUD (Config.CityHud)

A function called with false when a player enters a match and true when they're home. Use it for a HUD that has its own show/hide export. HUDs without one need the one-line guard in Installation.

Item pictures

Config.Images = {
    base = 'auto',
    items = {},
}

base: the folder that file names are joined to.

Value	Pictures come from
'auto'	the first running inventory: lumo-inventory, ox_inventory, qb-inventory, ps-inventory, lj-inventory, qs-inventory, core_inventory, codem-inventory. With none, 'local'
'local'	this resource's html/images/ folder. Drop your own PNG/WEBP/JPG files there
'https://…/'	any web folder (your CDN, Discord attachments, fivemanage …), ending in /
'nui://res/path/'	another resource's folder, e.g. 'nui://my-inventory/html/images/'
false	no pictures, only lettered tiles

Each item's image in config/loot.lua is either a file name ('weapon_pistol.png', joined to base) or a full link (https://…, nui://…), which is used as is.

items overrides single items without editing the loot file:

items = {
    helmet1 = 'helmet_light.png',                                  -- file in the base folder
    heavysniper = 'https://cdn.example.com/items/heavysniper.webp',  -- full link
},

Any picture that is missing or fails to load shows a lettered tile in the item's rarity colour. Helmets ship without a picture because the common inventories have none, so give them one here if you like.

Loot (config/loot.lua)

Items

Each entry in Loot.items is an item key and its definition:

pistol   = W('side', 'WEAPON_PISTOL', 'pistol', 'pistol', 1, 'Pistol'),   -- slot, weapon, ammo, class, tier, label
bandage  = { type = 'heal', heal = 20, cap = 75, time = 3, amount = 3, tier = 1, label = 'Bandage', image = 'bandage.png' },

type	Fields
weapon	slot (primary · side · melee), weapon, ammo, class, tier, label (W() fills image from the weapon name)
ammo	ammo (pistol · smg · rifle · shotgun · sniper · rocket), amount
heal	heal HP, cap (won't heal past), time seconds to use, amount per pickup
boost	regen HP/s, duration, optional speed sprint multiplier, time, amount
plate	armour (vest durability restored), time, amount
armor / helmet / backpack	level 1–3
throw	weapon, amount
attach	kind (scope · muzzle · grip · mag · light), level

Every item also takes tier (1 common … 5 legendary, colours in Loot.tiers), label and image.

Adding a weapon: add a line to Loot.items with any GTA weapon name, then give it a weight in a pool (Loot.pools.ground and/or Loot.pools.airdrop). Higher weight = more common.

Other tables

• Loot.components: which GTA components each attachment level tries, first match wins.
• Loot.capacity: carry limits per backpack level. Loot.ammoCapScale scales the ammo limit per ammo type.
• Loot.startAmmo: ammo that comes with a freshly picked-up weapon.
• Loot.botLoadouts: kits for admin-spawned test bots, per skill tier.
• Loot.props / Loot.itemProps: the world model for each item type, and per-item overrides.

Config.LootDensity (default 2.2) multiplies every map's loot. Config.LootCaches places small caches on a grid so open ground has loot too.

Zone, airdrops, vehicles

• Config.Zone.phases: one row per phase. wait = seconds the next circle is shown, shrink = closing time, radius = share of the map radius, dps = damage per second outside. Add or remove rows freely. poiBias is the chance a circle centres on a named place.
• Config.Airdrops: enabled, fromPhase, perPhase, fallTime, and items rolled from the airdrop pool.
• Config.Vehicles: enabled, spawnRadius and the default models. A map can list its own vehicleModels.
• Config.Plane: aircraft model, altitude, speed, path length and the forced parachute height.

Bots

Key	Default
enabled / maxBots	true / 99
fillTeams	true	bot teammates fill empty Duo/Squad seats
materializeRadius / dematerializeRadius	350 / 420	when a bot becomes a real ped near a player (keep the second below ~424)
skirmishRange / skirmishChance	80 / 0.02	off-screen bots fighting each other
landWithPistol	0.08	share of bots that land with a pistol
hunterShare / hunterRange	0.35 / 700	share of bots that stalk the nearest player
skills	3 tiers	weight, accuracy, sight, hearing, combat ability, fire rate and reaction time per tier
accuracyPerPhase / landingGrace	2 / 30	bots sharpen as the circle closes; half accuracy just after landing
models		ped models (story/ambient models only; freemode peds spawn undressed)
names / tag		kill-feed names and an optional prefix such as '[BOT] '

Fewer bots means less work for clients: /brbots 40 or Config.Lobby.matchSize = 40.

Rewards

Config.Rewards = {
    enabled = true,
    account = 'cash',                -- 'cash' / 'bank' (ESX: 'cash' is sent as 'money')
    participation = 50,
    perKill = 150, perBotKill = 40,
    placement = { [1] = 2500, [2] = 1200, [3] = 800, [5] = 400, [10] = 150 },
    items = { [1] = {} },
    xp = { participation = 20, perKill = 40, win = 300, perMinute = 4 },
}

placement and items use the best matching tier: [5] = 400 pays 4th and 5th place. Item rewards are inventory item names from your server:

items = {
    [1] = { { name = 'goldbar', amount = 1 } },
    [3] = { { name = 'bandage', amount = 5 } },
},

Items go through ox_inventory when it runs, otherwise through the framework's own inventory. Standalone servers get XP and stats only.

Keys

Config.Keys holds the default key for each action (FiveM key-mapping names such as 'F', 'TAB', 'MOUSE_MIDDLE', 'BACK'). Players rebind them in Settings › Key Bindings › FiveM, and their choice wins.

Maps (config/maps.lua)

{
    id = 'paleto', label = 'Paleto Bay',
    description = 'Small town, forest and the sawmill. Close-quarters fights.',
    center = vec2(-300.0, 6000.0), radius = 850.0,
    warmup = vec3(-560.0, 5330.0, 70.0),
    weather = 'OVERCAST', hour = 12,
    scatter = 90, vehicles = 10,
    pois = {
        { label = 'Paleto Town', coords = vec2(-150.0, 6380.0), r = 170.0, loot = 44 },
        -- …
    },
},

• center / radius: the playable circle. warmup: the staging point (the ground Z is found at runtime).
• pois: named places. Loot clusters there and late circles prefer them. Every POI must sit inside the circle.
• scatter: loot spread over the whole map. vehicles: how many vehicles spawn near POIs.
• island = 'HeistIsland': loads Cayo Perico for match players only.
• weather / hour: the sky during the match. Optional vehicleModels.

To find coordinates, set Config.Debug = true and use /brdebug, which prints your position in F8.