# Configuration

> Configuration reference for Outpost

Category: OUTPOST · Source: https://miciomods.it/docs/ml-base-building-configuration · Last updated: 2026-10-21

## 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

**shared/config.lua**

```lua
Config.Language = 'en'
Config.Debug = false
Config.AdminFreeBuild = false
Config.AdminKey = 'F10'
Config.Admin.MinimizeKey = 'F9'
Config.DrawDistance = 300.0
Config.SyncDistance = 100.0
Config.UseRoutingBuckets = false
Config.MaxTotalProps = 50000
Config.MaxPropsPerOwner = 1500
Config.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

**shared/config.lua**

```lua
Config.Building = {
    maxPlaceDistance = 10.0,
    keepBuilding = true,
    targetStructures = true,
    manageStructureKey = 'J',
    showTutorial = true,
    foundationsAlwaysNeedGround = false,
    structuralCollapse = true,
    rotStep = 15.0,
    rotStepFine = 1.0,
    heightStep = 0.05,
    heightStepFine = 0.01,
    hingeMaxAngle = 150.0,
    controlsDisplay = 'dui',
    repeatBuild = true,
    undoWindow = 20,
    alignToSlope = true,
    maxSlopeTilt = 30.0,
    ceilingMinSupports = 2,
    blockUnderground = true,
    claimRadiusDefault = 40.0,
    maxFlagsPerOwner = 1,
    flagRelocateCooldown = 300000,
    disabledZones = {
        { coords = vec3(-47.51, -984.7, 29.32), radius = 3075.0, label = 'South City' },
        { coords = vec3(2198.0, 3181.37, 49.75), radius = 500.0,  label = 'Safe Zone' },
        { coords = vec3(1688.12, 2594.93, 45.56), radius = 300.0,  label = 'Prison' },
    },
}
```

- `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

**shared/config.lua**

```lua
Config.Bridge = {
    enabled = true,
    maxLength = 40.0,
    minLength = 3.0,
    costPerMeter = { wood = 2 },
}
```

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

## Surfaces

**shared/config.lua**

```lua
Config.SurfaceCheck = {
    enabled = true,
    mode    = 'blacklist',
    appliesTo = {
        foundation = true,
    },
}
```

- `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

**shared/config.lua**

```lua
Config.Materials = {
    returnMaxPercentage = 0.5,
    pickup = {
        enabled = true,
        minLifePct = 1.0,
    },
    items = {
        wood   = 'wood',
        stone  = 'stone',
        metal  = 'metal',
        scraps = 'metal_scrap',
    },
}

Config.Upkeep = {
    allowUpgradeAll = false,
    cupboardUseDistance = 10.0,
    orphanDecay = {
        enabled       = true,
        intervalMs    = 5 * 60 * 1000,
        damagePerTick = 15.0,
    },
}
```

- `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

**shared/config.lua**

```lua
Config.Locks = {
    autoInstall = false,
    installItem = 'lock_mechanism',
    lockPlacement = true,
    lockedByDefault = {
        doors    = false,
        storages = false,
    },
    lockpick = {
        enabled        = true,
        onlyDuringRaid = true,
        alertOwner     = true,
        tiers = {
            [1] = { item = 'lockpick_basic',      timeMs = 6000,  wear = 34 },
            [2] = { item = 'lockpick_reinforced', timeMs = 9000,  wear = 50 },
            [3] = { item = 'lockpick_hardened',   timeMs = 12000, wear = 50 },
        },
    },
}
```

- `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

**shared/config.lua**

```lua
Config.UI = {
    theme                  = 'default',
    enableRadialMenu       = true,
    buildWheelKeybind      = true,
    buildWheelKey          = 'B',
    buildWheelRequiresItem = true,
    buildWheelItem         = 'construction_hammer',
}
```

- `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

**shared/config.lua**

```lua
Config.Raid = {
    enabled = true,
    raidSlidingMinutes = 15,
    disableOfflineRaiding = true,
    offlineGraceMinutes = 15,
    raidWindowMinutes = 60,
    blockRepairDuringRaid = true,
    blockUpgradeDuringRaid = true,
    blockBuildingDuringRaid = true,
    notifyDiscord = true,
    notifyInGame = true,
    notifyAllCrew = true,
    notifyCooldownMinutes = 25,
    raidSchedule = false,
    lootBypassEnabled = true,
    lootBypassItems = { 'lock_picker' },
    lootBypassConsume = true,
    lootBypassTimeMs = 8000,
}
```

- `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

**shared/config.lua**

```lua
Config.Crew = {
    lockDuringRaid = true,
    raidLockMinutes = 10,
    raidLockAdminBypass = false,
    logActions = true,
}
```

- `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

**shared/config.lua**

```lua
Config.Electricity = {
    lightsRequirePower = true,
    cableItem = 'electric_cable',
    cablePerMeter = 0.2,
    maxCableLength = 30.0,
    circuitLimits = {
        maxGenerators        = 8,
        maxBatteries         = 6,
        maxPowerUsers        = 50,
        maxPowerDistributors = 25,
        maxCircuitSize       = 100,
    },
    fuelTypes = {
        fuel    = { label = 'Gasoline', outputMult = 1.00, burnMult = 1.00 },
        diesel  = { label = 'Diesel',   outputMult = 1.15, burnMult = 0.80 },
        biofuel = { label = 'Biofuel',  outputMult = 0.90, burnMult = 1.10 },
    },
    useMlFuelJerryCans = true,
    jerryCanPerAction  = 25.0,
    useMlFuelInterface = true,
    cableTypes = {
        basic = { item = 'electric_cable', maxThroughput = 5000,  perMeter = 0.2 },
        heavy = { item = 'heavy_cable',    maxThroughput = 20000, perMeter = 0.4 },
    },
    distanceLossPerMeter = 0,
    breakerTripTicks = 2,
    generatorAuto = {
        enabled      = true,
        autoStartSoC = 0.20,
        autoStopSoC  = 0.85,
    },
}
```

- `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

**shared/config.lua**

```lua
Config.Defence = {
    enabled       = true,
    tickMs        = 1000,
    hitCooldownMs = 800,
    contactRange  = 2.0,
    contactDamage = 10,
}

Config.MannedTurret = {
    enabled         = true,
    publicByDefault = false,
    mountDistance   = 2.5,
    reloadTime      = 3000,
    reloadPerItem   = 1,
    traverseDeg     = 120,
}

Config.Elevator = {
    enabled       = true,
    requiresPower = true,
    powerUse      = 500,
    speed         = 1.2,
    speedDown     = 0.85,
    floorHeight   = 3.0,
    maxSegments   = 40,
    callDistance  = 4.0,
    carryVehicles = true,
}

Config.Beds = {
    respawnEnabled  = false,
    deadThresholdMs = 3000,
}

Config.Generator = {
    noiseEnabled    = false,
    noiseRadius     = 60.0,
    noiseIntervalMs = 15000,
}
```

- `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

**shared/config.lua**

```lua
Config.Skills = {
    enabled = true,
    category = 'personal',
    xpPerCost = 0.2,
    xpMin = 1,
    xpMax = 120,
    upgradeXp = true,
    debtOnDemolish = true,
    hourlyCap = 1200,
    requireByTier = {
        [1] = { level = 0, skill = '' },
        [2] = { level = 0, skill = '' },
        [3] = { level = 0, skill = '' },
    },
    requireByModel = {},
}
```

- `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

**shared/config.lua**

```lua
Config.UITheme = {
    preset = nil,
    colors = {
        primary = nil,
        accent = nil,
        background = nil,
        surface = nil,
        text = nil,
    },
}
```

- `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

**server/config_server.lua**

```lua
Config.Webhooks = {
    placement = '',
    raid      = '',
    security  = '',
    donor     = '',
    admin     = '',
    upkeep    = '',
    crew      = '',
    locks     = '',
}

Config.AdminAcePermissions = {
    inspect     = 'ml_bb.admin.inspect',
    forceRemove = 'ml_bb.admin.force_remove',
    panel       = 'ml_bb.admin.panel',
    destructive = 'ml_bb.admin.destructive',
    donorGrant  = 'ml_bb.donor.grant',
    donorRevoke = 'ml_bb.donor.revoke',
    donorView   = 'ml_bb.donor.view',
    donorGive   = 'ml_bb.donor.give',
    donorAudit  = 'ml_bb.donor.audit',
}
Config.AdminDestructiveRole = 'admin'
Config.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