Configuration

Overview

• shared/config.lua: building, surfaces, locks, UI, raids, weapons damage, crews, electricity, defenses, elevator, beds, skills and theme
• shared/data/flag_tiers.lua: cupboard and community flag tiers, with radius, upkeep, stock and piece limits
• shared/data/models.lua: every buildable piece with its item, category, cost and health
• shared/data/permissions.lua: crew permissions and presets
• server/config_server.lua: webhooks, admin ACE nodes, lock pepper and banned crew names

Staff can also change many values from the admin panel. Those are saved to ml_bb_settings and apply on top of the files.

General

1Config.Language = 'en'
2Config.Debug = false
3Config.AdminFreeBuild = false
4Config.AdminKey = 'F10'
5Config.Admin.MinimizeKey = 'F9'
6Config.DrawDistance = 300.0
7Config.SyncDistance = 100.0
8Config.UseRoutingBuckets = false
9Config.MaxTotalProps = 50000
10Config.MaxPropsPerOwner = 1500
11Config.RealisticMode = true

• Language: language file to load from the locales/ folder
• Debug: console debug output
• AdminFreeBuild: staff build without paying materials
• AdminKey: key that opens the admin panel, rebindable in the FiveM key settings
• Admin.MinimizeKey: hides and restores the admin panel while it is open
• DrawDistance, SyncDistance: meters at which pieces are drawn and synced to players
• UseRoutingBuckets: keeps bases separate per routing bucket
• MaxTotalProps, MaxPropsPerOwner: server-wide and per-player piece caps
• RealisticMode: every foundation must trace back to solid ground. Removing a piece that would leave others hanging is always blocked

Building

1Config.Building = {
2    maxPlaceDistance = 10.0,
3    keepBuilding = true,
4    targetStructures = true,
5    manageStructureKey = 'J',
6    showTutorial = true,
7    foundationsAlwaysNeedGround = false,
8    structuralCollapse = true,
9    rotStep = 15.0,
10    rotStepFine = 1.0,
11    heightStep = 0.05,
12    heightStepFine = 0.01,
13    hingeMaxAngle = 150.0,
14    controlsDisplay = 'dui',
15    repeatBuild = true,
16    undoWindow = 20,
17    alignToSlope = true,
18    maxSlopeTilt = 30.0,
19    ceilingMinSupports = 2,
20    blockUnderground = true,
21    claimRadiusDefault = 40.0,
22    maxFlagsPerOwner = 1,
23    flagRelocateCooldown = 300000,
24    disabledZones = {
25        { coords = vec3(-47.51, -984.7, 29.32), radius = 3075.0, label = 'South City' },
26        { coords = vec3(2198.0, 3181.37, 49.75), radius = 500.0,  label = 'Safe Zone' },
27        { coords = vec3(1688.12, 2594.93, 45.56), radius = 300.0,  label = 'Prison' },
28    },
29}

• maxPlaceDistance: farthest a piece can be placed from the player
• keepBuilding, repeatBuild: stay in build mode after a placement and repeat the same piece
• targetStructures, manageStructureKey: open the panel of a piece by targeting it or with the key
• showTutorial: shows the placement key hints. false hides them
• foundationsAlwaysNeedGround: every foundation must touch the ground, also with realistic mode off
• structuralCollapse: pieces left without support fall when a supporting piece is destroyed
• rotStep, rotStepFine, heightStep, heightStepFine: rotation and height steps, normal and fine
• hingeMaxAngle: widest bend between two perimeter walls joined edge to edge
• controlsDisplay: where the placement controls show. 'dui' draws them next to the player
• undoWindow: seconds during which the owner can undo the last placement, within reach of it
• alignToSlope, maxSlopeTilt: tilt pieces to the ground up to this angle
• ceilingMinSupports: supports a ceiling needs before it can be placed
• blockUnderground: refuses pieces placed below the ground
• claimRadiusDefault, maxFlagsPerOwner, flagRelocateCooldown: default claim radius, flags per player and cooldown in milliseconds before a flag can be moved
• disabledZones: areas where nobody can build

The same table holds fine placement values (ground tolerances, snap stickiness, floating platform motion, DUI hint position). Leave them as they are unless placement feels off on your map.

Bridges

1Config.Bridge = {
2    enabled = true,
3    maxLength = 40.0,
4    minLength = 3.0,
5    costPerMeter = { wood = 2 },
6}

Rope bridges between two posts, with planks, sag and rope rails built along the span. Longer bridges cost more wood.

Surfaces

1Config.SurfaceCheck = {
2    enabled = true,
3    mode    = 'blacklist',
4    appliesTo = {
5        foundation = true,
6    },
7}

• mode: 'blacklist' refuses the surfaces in blacklist (roads, concrete, floors, water, metal, glass), 'whitelist' allows only those in whitelist (sand, dirt, grass, gravel, rock)
• appliesTo: piece types the check runs on. Only foundations ship checked

Materials and Upkeep

1Config.Materials = {
2    returnMaxPercentage = 0.5,
3    pickup = {
4        enabled = true,
5        minLifePct = 1.0,
6    },
7    items = {
8        wood   = 'wood',
9        stone  = 'stone',
10        metal  = 'metal',
11        scraps = 'metal_scrap',
12    },
13}
14
15Config.Upkeep = {
16    allowUpgradeAll = false,
17    cupboardUseDistance = 10.0,
18    orphanDecay = {
19        enabled       = true,
20        intervalMs    = 5 * 60 * 1000,
21        damagePerTick = 15.0,
22    },
23}

• returnMaxPercentage: largest share of the cost given back when a piece outside a flag is removed. Inside a flag the tier's refundOnDestroy applies
• pickup: the owner, or crew with canRemoveProps, picks undamaged pieces back up as items. Not during a raid, and not for cupboards, elevators, machines, storages with items or generators with fuel
• items: item names of the four materials
• allowUpgradeAll: adds an upgrade-all button to the cupboard
• cupboardUseDistance: how close a player must be to use a cupboard
• orphanDecay: pieces outside any flag lose health on this interval

Flag Tiers

shared/data/flag_tiers.lua defines upkeep_t1 (Personal), upkeep_t2 (Medium), upkeep_t3 (Faction) and community. Each tier sets:

• buildRadius, claimRadius: where its owners can build, and where no other flag can be placed
• upgradeTo, upgradeCost: the next tier and its cost
• upkeepInterval, decayPerTick: how often upkeep is paid and how much health an unpaid piece loses
• stockCap: most material of each type the cupboard holds
• flagLimits: total pieces, and limits per type, category and model
• permissions: whether raids, decay, repairs and upgrades apply, whether building needs the flag, and blocked types, models or categories
• notify: low-stock warning threshold, cooldown and webhook
• refundOnDestroy: refund share for pieces without their own return materials

Staff can add more tiers from the admin panel. They are saved to the database.

Locks

1Config.Locks = {
2    autoInstall = false,
3    installItem = 'lock_mechanism',
4    lockPlacement = true,
5    lockedByDefault = {
6        doors    = false,
7        storages = false,
8    },
9    lockpick = {
10        enabled        = true,
11        onlyDuringRaid = true,
12        alertOwner     = true,
13        tiers = {
14            [1] = { item = 'lockpick_basic',      timeMs = 6000,  wear = 34 },
15            [2] = { item = 'lockpick_reinforced', timeMs = 9000,  wear = 50 },
16            [3] = { item = 'lockpick_hardened',   timeMs = 12000, wear = 50 },
17        },
18    },
19}

• autoInstall, installItem: put a code lock on every new door and storage, or only when the player uses lock_mechanism
• lockPlacement: the player places the keypad prop where they want
• lockedByDefault: new doors and storages start locked
• lockpick: picks a coded door during an open raid, with an alert to the owner. The pick grade must reach the door tier, timeMs is the time per door tier, and wear is durability lost per use (0 consumes the pick)

Interface

1Config.UI = {
2    theme                  = 'default',
3    enableRadialMenu       = true,
4    buildWheelKeybind      = true,
5    buildWheelKey          = 'B',
6    buildWheelRequiresItem = true,
7    buildWheelItem         = 'construction_hammer',
8}

• buildWheelKey: opens the build wheel. With buildWheelRequiresItem, only while carrying the construction_hammer
• allowUpgradeFromPanel, allowRepairFromPanel, allowDemolishFromPanel, allowLockManagementFromPanel, allowFuelFromPanel, allowCircuitFromPanel, allowBedSleepFromPanel: buttons shown in the piece panel, all on by default
• showUpkeepInfo, showRefundInfo: upkeep and refund chips in the panel

Config.BuildAnim sets the hammering animation, walk to the spot, hammer prop and finish effects, and Config.UseProgressBar shows a progress bar while building.

Raids

1Config.Raid = {
2    enabled = true,
3    raidSlidingMinutes = 15,
4    disableOfflineRaiding = true,
5    offlineGraceMinutes = 15,
6    raidWindowMinutes = 60,
7    blockRepairDuringRaid = true,
8    blockUpgradeDuringRaid = true,
9    blockBuildingDuringRaid = true,
10    notifyDiscord = true,
11    notifyInGame = true,
12    notifyAllCrew = true,
13    notifyCooldownMinutes = 25,
14    raidSchedule = false,
15    lootBypassEnabled = true,
16    lootBypassItems = { 'lock_picker' },
17    lootBypassConsume = true,
18    lootBypassTimeMs = 8000,
19}

• raidSlidingMinutes: a base stays under raid for this long after the last hit
• disableOfflineRaiding, offlineGraceMinutes: protect a base when its whole crew is offline, after this grace period
• raidWindowMinutes: a raid stays open for this long from its first hit
• blockRepairDuringRaid, blockUpgradeDuringRaid, blockBuildingDuringRaid: what is locked while under raid
• notifyDiscord, notifyInGame, notifyAllCrew, notifyCooldownMinutes: raid alerts
• raidSchedule: limit raids to a list of { from, to } game hours
• lootBypassEnabled, lootBypassItems, lootBypassConsume, lootBypassTimeMs: during an open raid, a lock_picker opens locked storage without blowing it up

The same table limits weapon reach and hit rate. Config.WeaponsDamageByName sets the damage of each weapon against structures, Config.MeleeWeapons lists melee weapons, and Config.ExplosiveItems sets plant time, fuse and damage of weapon_stickybomb, weapon_grenade and c4_charge.

Crews

1Config.Crew = {
2    lockDuringRaid = true,
3    raidLockMinutes = 10,
4    raidLockAdminBypass = false,
5    logActions = true,
6}

• lockDuringRaid, raidLockMinutes: membership, permission changes, invites and transfers are locked for this long after the last raid hit on the crew's base
• raidLockAdminBypass: lets staff override the raid lock
• logActions: keeps the crew history

Crew name length and the banned word list are in server/config_server.lua. Config.CrewUI sets how names show and the radius for inviting nearby players.

Electricity

1Config.Electricity = {
2    lightsRequirePower = true,
3    cableItem = 'electric_cable',
4    cablePerMeter = 0.2,
5    maxCableLength = 30.0,
6    circuitLimits = {
7        maxGenerators        = 8,
8        maxBatteries         = 6,
9        maxPowerUsers        = 50,
10        maxPowerDistributors = 25,
11        maxCircuitSize       = 100,
12    },
13    fuelTypes = {
14        fuel    = { label = 'Gasoline', outputMult = 1.00, burnMult = 1.00 },
15        diesel  = { label = 'Diesel',   outputMult = 1.15, burnMult = 0.80 },
16        biofuel = { label = 'Biofuel',  outputMult = 0.90, burnMult = 1.10 },
17    },
18    useMlFuelJerryCans = true,
19    jerryCanPerAction  = 25.0,
20    useMlFuelInterface = true,
21    cableTypes = {
22        basic = { item = 'electric_cable', maxThroughput = 5000,  perMeter = 0.2 },
23        heavy = { item = 'heavy_cable',    maxThroughput = 20000, perMeter = 0.4 },
24    },
25    distanceLossPerMeter = 0,
26    breakerTripTicks = 2,
27    generatorAuto = {
28        enabled      = true,
29        autoStartSoC = 0.20,
30        autoStopSoC  = 0.85,
31    },
32}

• lightsRequirePower: lights glow only on a powered circuit
• cableItem, cablePerMeter, maxCableLength: cable consumed per meter and the longest single run
• circuitLimits: most generators, batteries, consumers and distributors per circuit, and its largest span
• fuelTypes: output and burn rate of each generator fuel
• useMlFuelJerryCans, jerryCanPerAction, useMlFuelInterface: refuel generators with ML Fuel cans and its interface
• cableTypes: basic and heavy cable, with the load each carries before it overloads
• distanceLossPerMeter: power lost over long cables. 0 turns it off
• breakerTripTicks: overloaded ticks before a breaker trips. A tripped breaker needs a fuse
• generatorAuto: generators in AUTO start when batteries fall below 20% and stop above 85%

solarByHour and solarByWeather set solar output by game hour and weather. windNative reads the game wind through players within 150 m of a turbine; with nobody near it produces nothing, or a fixed share with offlinePolicy = 'fixed'. A server hook can supply wind instead, see Developer. cableRopes, cableSag and statusLed set how cables and status lights look.

Defenses, Elevator, Beds and Generators

1Config.Defence = {
2    enabled       = true,
3    tickMs        = 1000,
4    hitCooldownMs = 800,
5    contactRange  = 2.0,
6    contactDamage = 10,
7}
8
9Config.MannedTurret = {
10    enabled         = true,
11    publicByDefault = false,
12    mountDistance   = 2.5,
13    reloadTime      = 3000,
14    reloadPerItem   = 1,
15    traverseDeg     = 120,
16}
17
18Config.Elevator = {
19    enabled       = true,
20    requiresPower = true,
21    powerUse      = 500,
22    speed         = 1.2,
23    speedDown     = 0.85,
24    floorHeight   = 3.0,
25    maxSegments   = 40,
26    callDistance  = 4.0,
27    carryVehicles = true,
28}
29
30Config.Beds = {
31    respawnEnabled  = false,
32    deadThresholdMs = 3000,
33}
34
35Config.Generator = {
36    noiseEnabled    = false,
37    noiseRadius     = 60.0,
38    noiseIntervalMs = 15000,
39}

• Defence: electric fences and spike barriers hurt intruders who touch them, and the auto turret shoots the nearest intruder within 28 m. The fence and the turret work only when powered. Owner and crew are never hurt. The block sets the fallback range and damage for models that set none
• MannedTurret: turrets players climb into and fire. publicByDefault lets anyone use them, reloadPerItem sets rounds per ammo item, traverseDeg the swing arc
• Elevator: a powered cabin with stacked cage segments, one per floor. carryVehicles takes a driven vehicle along
• Beds.respawnEnabled: a player who set a bed as spawn is moved there after a revive from a death longer than deadThresholdMs. Off by default. A death script can take over with the ClaimRespawn export
• Generator.noiseEnabled: running generators fire a noise event that a zombie or AI resource can listen to, see Developer

Skills

1Config.Skills = {
2    enabled = true,
3    category = 'personal',
4    xpPerCost = 0.2,
5    xpMin = 1,
6    xpMax = 120,
7    upgradeXp = true,
8    debtOnDemolish = true,
9    hourlyCap = 1200,
10    requireByTier = {
11        [1] = { level = 0, skill = '' },
12        [2] = { level = 0, skill = '' },
13        [3] = { level = 0, skill = '' },
14    },
15    requireByModel = {},
16}

• category, xpPerCost, xpMin, xpMax: ml_skills category and XP per placed piece, from its cost
• upgradeXp: upgrades award XP too
• debtOnDemolish: demolishing a piece takes its XP back
• hourlyCap: most building XP per player per hour
• requireByTier, requireByModel: level or skill needed for wood, stone and metal, or for single models

Furniture Sets

Config.FurnitureSets groups furniture props into sets (living room, bedroom, outdoor, entertainment, workshop, garden). With Config.Donor.enabled, the sets in Config.TebexPackages are delivered through ml_tebex, and staff grant them with the set commands. Both ship off.

Other Options

• Config.Blips: map blips for owned, crew and other bases. Admins see every base
• Config.BaseRainBlock: no rain effect on players under a base roof
• Config.Blackout.enabled: world blackout, also switchable from the admin panel
• Config.Skins: paint variants of the building models

UI Theme

1Config.UITheme = {
2    preset = nil,
3    colors = {
4        primary = nil,
5        accent = nil,
6        background = nil,
7        surface = nil,
8        text = nil,
9    },
10}

• preset: theme preset of the panels. nil follows the shared theme set in ml_bridge
• colors: CSS hex values for single colors. Any nil value follows the shared theme

Server Configuration

1Config.Webhooks = {
2    placement = '',
3    raid      = '',
4    security  = '',
5    donor     = '',
6    admin     = '',
7    upkeep    = '',
8    crew      = '',
9    locks     = '',
10}
11
12Config.AdminAcePermissions = {
13    inspect     = 'ml_bb.admin.inspect',
14    forceRemove = 'ml_bb.admin.force_remove',
15    panel       = 'ml_bb.admin.panel',
16    destructive = 'ml_bb.admin.destructive',
17    donorGrant  = 'ml_bb.donor.grant',
18    donorRevoke = 'ml_bb.donor.revoke',
19    donorView   = 'ml_bb.donor.view',
20    donorGive   = 'ml_bb.donor.give',
21    donorAudit  = 'ml_bb.donor.audit',
22}
23Config.AdminDestructiveRole = 'admin'
24Config.Locks.codePepper = 'mlbb_v1_pepper_REPLACE_IN_PROD'

• Webhooks: one Discord webhook per log category. Leave one empty to skip it
• AdminAcePermissions: ACE node of each staff action. A framework admin also passes. panel opens the admin panel, destructive covers removing bases, resetting decay, setting health, owners and stock
• AdminDestructiveRole: framework role that grants destructive actions without the ACE
• Locks.codePepper: secret mixed into stored lock codes. Replace it before players set codes