# Smoke Bunker configuration

> Every option in Smoke Bunker's open config files, with its default and what it does.

The options live in four Lua files under `config`. Restart `smoke_bunker` after a change.

| File | Holds |
| --- | --- |
| `config/shared/config.lua` | Sites, interior positions, economy, missions, raids, storage, workshop. Client and server read it. |
| `config/shared/catalog.lua` | Workshop recipes, blueprint items. |
| `config/client/config.lua` | Interact, text UI and clothing providers, blips, hatch, drive-in, delivery ped, cutscene. |
| `config/server/config.lua` | Admin groups, command names, loop intervals, rate limit, terminal distance, logger. |

`bridge/**/*.lua`, `config/**/*.lua`, `types.lua` and `install/*.lua` (item files) are under `escrow_ignore`, so they stay editable under Cfx.re Asset Escrow. [Integrations](/bunker/integrations) covers the bridge files.

<Warning>

  Keep `debug` and `debugPrints` `false` on a live server. With `debug = true`, an admin can open any bunker's terminal as its owner with `/bunkerui`.

</Warning>

Positions are `vec3` or `vec4`. Distances are in metres, times in seconds unless the name ends in `Ms`, `Min`, `Minutes`, `Hours` or `Days`, money in dollars. Interior positions are GTA Online bunker coordinates, moved to every site; get them with `/bunkercoords` (admin) inside any bunker.

## Server config

`config/server/config.lua`

| Option | Default | What it does |
| --- | --- | --- |
| `adminGroups` | `{ 'admin', 'god' }` | Groups allowed to use `/bunkeradmin`, `/bunkerui`, `/bunkermission`, `/bunkercoords`. Framework group matching: [Commands](/bunker/commands). |
| `commands.admin` | `'bunkeradmin'` | Admin command name. |
| `commands.ui` | `'bunkerui'` | Debug screen command name. Only while `debug = true`. |
| `sim.tickSeconds` | `5` | Timer loop interval. |
| `sim.viewerPushSeconds` | `15` | Push interval to open terminals. |
| `sim.saveSeconds` | `30` | Save interval for changed bunkers. |
| `sim.pruneLogsOnStart` | `true` | Delete log rows older than `logs.retainDays` at start. |
| `rateLimit.windowMs` | `1000` | Rate-limit window, per player and request type. |
| `rateLimit.maxRequests` | `8` | Requests per window. |
| `terminal.requireNearChair` | `true` | Terminal actions need player near boss chair in their bunker. |
| `terminal.maxDistance` | `8.0` | Max chair distance, metres. |
| `logger.enabled` | `false` | Send logs to Discord webhook or ox_lib logger. |
| `logger.type` | `'discord'` | `'ox'` or `'discord'`; any other value warns and turns logging off. |
| `logger.discordWebhook` | `''` | Webhook URL used when category has none. |
| `logger.webhooks` | every key `''` | Optional URL per category: `MONEY`, `PRODUCTION`, `RESEARCH`, `SECURITY`, `RAID`, `STAFF`, `default`. Blank falls back to `default`, then `discordWebhook`. `STORAGE` has no key and uses that fallback. |

## Client config

`config/client/config.lua`

| Option | Default | What it does |
| --- | --- | --- |
| `commands.coords` | `'bunkercoords'` | Admin command name that copies your coordinates. |
| `interact` | `'auto'` | `'auto'`, `'ox_target'`, `'qb-target'` or `'textui'`. `'auto'` uses first running of `ox_target`, `qb-target`, else text prompt. |
| `textUI` | `'auto'` | Prompt resource. `'auto'` and `'ox_lib'` use ox_lib; `'qb'` uses `qb-core`, `'okok'` `okokTextUI`, `'jg'` `jg-textui`. |
| `clothing` | `'auto'` | Personal Quarters wardrobe resource: `'auto'` (first running of the rest, in order), `'illenium-appearance'`, `'fivem-appearance'`, `'qb-clothing'` or `'esx_skin'`. |
| `interactDistance` | `2.0` | Default interact point radius. |
| `blips.forSale` | `{ enabled = true, sprite = 557, color = 4, scale = 0.7, label = 'Bunker For Sale' }` | Blip of each bunker for sale. `enabled = false` hides it. |
| `blips.owned` | `{ enabled = true, sprite = 557, color = 2, scale = 0.8, label = 'Your Bunker' }` | Blip of your own bunker, same fields. |
| `door.renderDistance` | `150.0` | Hatch prop exists within this distance. |
| `door.openSeconds` | `6.5` | Hatch open and close time. |
| `door.easing` | `'smoothstep'` | `'smoothstep'` or `'linear'`. |
| `door.openDegrees` | `20` | Open pose: closed `rot.y` minus this. Negative tilts other way. |
| `door.sound` | `{ bank = 'DLC_GR_Bunker_Door_Sounds', open = 'Door_Open_Long', limit = 'Door_Open_Limit', hearDistance = 60.0 }` | Hatch sounds from `bank`, heard within `hearDistance`: `open` at start, `limit` at stop. |
| `driveIn` | `{ speed = 5.0, timeoutMs = 12000, stopDistance = 4.0 }` | Delivery trucks drive to `config.sites[].door` at `speed` until within `stopDistance` or after `timeoutMs`. |
| `deliveryPed` | `{ sale = 's_m_m_highsec_01', scenario = 'WORLD_HUMAN_CLIPBOARD', sideOffset = 4.0, spawnDistance = 80.0 }` | Ped at every sale drop-off, local and export. `scenario` is `nil` for none; stands `sideOffset` right of spot, spawns within `spawnDistance`. |
| `cutscene` | `{ name = 'BUNK_INT', flagsDefault = 501, flagsGunRange = 493, skipControl = 38, maxSeconds = 120 }` | First walk-in intro; needs `entry.introCutscene`. `flagsGunRange` replaces `flagsDefault` in bunkers with Shooting Range. `skipControl` skips it and sale cutscene (`38` is `E`); stops after `maxSeconds`. |
| `fadeMs` | `1200` | Screen fade length. |

Jobs in `blipRestrictions.hiddenForJobs` see neither blip.

## Shared config

`config/shared/config.lua`

### General

| Option | Default | What it does |
| --- | --- | --- |
| `debug` | `false` | Admin test tools: simulate-raid and breach buttons, `/bunkerui`. |
| `debugPrints` | `false` | Verbose console logs. Errors and warnings always print. |
| `language` | `'en'` | File name in `locales/`. See [Language](#language). |
| `inventoryImagePath` | `'nui://ox_inventory/web/images/%s.png'` | Item icon source; `%s` is item name. Copy `install/image/` PNGs into your inventory's image folder and, if not ox_inventory, point this path there. Missing icon shows label's first two letters. |

### Ownership and entry

| Option | Default | What it does |
| --- | --- | --- |
| `ownership.oneBunkerPerCharacter` | `true` | One bunker org per character. |
| `ownership.keypadDigits` | `4` | Keypad code length. |
| `ownership.keypadAttempts` | `3` | Wrong codes before lockout. |
| `ownership.keypadLockoutSeconds` | `60` | Lockout length. |
| `ownership.startingBalance` | `0` | Starting org funds. |
| `ownership.startingSupplies` | `50` | Starting supplies. |
| `entry.checkMs` | `1000` | Access check interval; anyone inside without access returns to entrance. |
| `entry.groupEnabled` | `true` | Offer solo or group entry when others are close. |
| `entry.groupRadius` | `8.0` | Players this close are offered group entry. |
| `entry.groupMax` | `8` | Max people per entry, you included. |
| `entry.groupConsent` | `true` | Nearby players must accept first. |
| `entry.groupConsentSeconds` | `15` | Seconds to answer. |
| `entry.passSeconds` | `120` | Seconds a guest or group member has to walk the tunnel. |
| `entry.doorOpenSeconds` | `90` | Hatch open time after keypad, raid breach or delivery truck opens it; new opening restarts it. |
| `entry.introCutscene` | `true` | Intro cutscene on first walk-in after buying. |
| `blipRestrictions.hiddenForJobs` | `{ 'police', 'sheriff', 'bcso', 'sasp', 'lspd', 'state', 'fib', 'ranger' }` | Jobs or groups that never see bunker blips. |
| `keypad.renderDistance` | `40.0` | Keypad prop spawn distance. |
| `keypad.useDistance` | `1.5` | Keypad use distance, also reach of its raid hack and C4 points. |
| `keypad.onOpen` | `nil` | Function run when keypad camera starts, e.g. to hide your HUD. |
| `keypad.onClose` | `nil` | Function run when keypad camera ends. |

### Gang mode and org

When a gang buys a bunker, every gang member is added and kept in sync.

| Option | Default | What it does |
| --- | --- | --- |
| `gangMode.enabled` | `false` | Turns gang purchases on. |
| `gangMode.minBuyGrade` | `3` | Lowest grade that can buy for gang. |
| `gangMode.resyncMinutes` | `10` | Minutes between full resyncs; gang changes and player loads also sync. |
| `gangMode.esxGangJobs` | `{}` | ESX job names that count as gangs, e.g. `{ 'vagos', 'ballas' }`. |
| `gangMode.defaultRole` | `'MEMBER'` | Role for grades below first `gradeRoles` entry. |
| `gangMode.gradeRoles` | `{ minGrade = 0, role = 'PROSPECT' }`, `{ minGrade = 1, role = 'MEMBER' }`, `{ minGrade = 3, role = 'OFFICER' }` | Grade to org role: highest `minGrade` at or below member's grade wins. Buyer is always `OWNER`. |
| `gangMode.rolePerms` | `OFFICER` has `SELL`, `RAID`, `RESEARCH`. `MEMBER` has `SELL`. `PROSPECT` has none. | Permissions a synced member gets when added and when a grade change gives another role. Owner can edit them in between. |
| `org.perms` | `{ 'SELL', 'RAID', 'RESEARCH', 'WITHDRAW' }` | Permissions that exist. `OWNER` always has all. |
| `org.rolePerms` | Same values as `gangMode.rolePerms` | Permissions for hand-assigned role, and for previous owner who becomes `OFFICER` on transfer. |
| `org.maxMembers` | `20` | Max org members. |
| `org.inviteDistance` | `5.0` | Max distance to player you invite. |

### Ownership lifecycle and police alerts

| Option | Default | What it does |
| --- | --- | --- |
| `lifecycle.sellRefundPct` | `60` | Percent of site price paid to owner on sale. |
| `lifecycle.payoutBalance` | `true` | Also pay org balance to owner on sale. |
| `lifecycle.requireEmptyStash` | `true` | Selling or abandoning needs empty stash. |
| `lifecycle.gangOwnerFallback` | `true` | Gang bunkers: ownership moves to best gang member when owner leaves gang. |
| `lifecycle.upkeep` | `{ enabled = true, perDay = 2000, graceDays = 3 }` | Daily org-funds fee: `perDay` plus each bought upgrade's `dailyFee`. Unpaid days past `graceDays` repossess bunker. |
| `dispatch.enabled` | `true` | Police alerts on. Sent to online players whose job is in `dispatch.jobs` and to `cd_dispatch` when running. |
| `dispatch.jobs` | `{ 'police', 'sheriff', 'bcso', 'sasp', 'lspd', 'state', 'fib', 'ranger' }` | Jobs that receive alerts. |
| `dispatch.blipSeconds` | `90` | Seconds the alert blip stays. |
| `dispatch.onRaidBreach` | `true` | Alert when raiders breach bunker. |
| `dispatch.onHighRiskMission` | `true` | Alert when high-risk mission becomes tracked. |
| `perks` | See below | What each feature needs. |

Each perk names the `upgrade` or `custom` it needs. Other scripts read `perks` with `exports.smoke_bunker:getPerks` and `hasPerk`.

| Perk | Needs | Unlocks |
| --- | --- | --- |
| `workshop`, `exportContracts`, `garage` | Equipment upgrade | Workshop, export contracts, armored sale vehicle |
| `blastDoors` | Security upgrade | Blast doors: officers seal or open them in terminal; they seal when raid is launched on bunker. |
| `range`, `locker`, `quarters`, `caddy` | Same-name customization | Shooting range, gun locker, Personal Quarters, caddy |

### Sites

`sites` has one entry per bunker (11):

| `key` | `label` | `price` | `style` |
| --- | --- | --- | --- |
| `chumash` | Chumash Facility | `1450000` | `Bunker_Style_A` |
| `senora_w` | Grand Senora West | `1050000` | `Bunker_Style_B` |
| `senora_e` | Grand Senora East | `1100000` | `Bunker_Style_C` |
| `harmony` | Harmony Facility | `1200000` | `Bunker_Style_A` |
| `route68` | Route 68 Facility | `950000` | `Bunker_Style_B` |
| `tongva` | Tongva Facility | `1350000` | `Bunker_Style_C` |
| `grapeseed` | Grapeseed Facility | `1000000` | `Bunker_Style_A` |
| `palmer` | Palmer-Taylor Facility | `1250000` | `Bunker_Style_B` |
| `paleto` | Paleto Facility | `1500000` | `Bunker_Style_C` |
| `zancudo_n` | Zancudo North Facility | `900000` | `Bunker_Style_A` |
| `zancudo_s` | Lago Zancudo Facility | `1150000` | `Bunker_Style_B` |

| Field | What it does |
| --- | --- |
| `key` | Site id, used in `/bunkeradmin site <key>`. |
| `label` | Site name in game. |
| `price` | Purchase price. |
| `style` | Interior look before purchase, and starting style after. |

Position fields, matching the map in `stream`:

| Field | What it is |
| --- | --- |
| `mlo` | Interior position and heading from its ymap. Do not change unless you edit the map. |
| `door` | Surface tunnel door. |
| `entrance` | Spot in front of door. |
| `hatch` | Moving hatch part: closed-pose `coords` and `rot`, and its `model`. |
| `keypad` | Outside wall keypad: prop `coords` and `rot`. Opens the hatch and walks you in. |
| `exitKeypad` | Inside keypad: `coords` and `rot`. Only opens the hatch. |
| `blip` | Blip position. |

<Note>

  `/bunkeradmin site <key> price <n>`, `enable` and `disable` save to the database. A saved price overrides this file; to go back to the file's price, set it again with the command.

</Note>

### Interior

Some positions are placeholders: check each in game with `/bunkercoords`.

| Option | Default | What it does |
| --- | --- | --- |
| `interior.reference` | `vec4(938.3077, -3196.1116, -100.0, 180.0)` | Placement of the GTA Online interior `gr_grdlc_int_02`. Do not change. |
| `interior.bounds` | `min = vec3(826.0, -3267.0, -104.0)`, `max = vec3(1039.0, -3064.0, -88.0)` | Inside-bunker box: hall, range, lower tunnel. |
| `interior.applyDistance` | `220.0` | Entity sets and props apply within this distance of interior. |
| `interior.coords` | `vec3(899.5518, -3246.038, -98.04907)` | Hall point used to find interior. |
| `interior.spawn` | `vec4(885.982, -3245.716, -98.278, 90.0)` | Spawn after the intro cutscene or waking up. |
| `interior.desk.chair` | `vec4(908.670, -3206.994, -97.500, 10.022)` | Boss chair: terminal opens here, raiders hack laptop here. |
| `interior.desk.chairModel` | `'sm_prop_smug_offchair_01a'` | Desk chair prop. |
| `interior.desk.animDict` | `'anim@amb@clubhouse@boss@male@'` | Sit and stand animations. |
| `interior.desk.maxDistance` | `6.0` | Terminal closes beyond this plus 2 m from chair; also chair range for stash. |
| `interior.gunLocker` | `vec3(896.60, -3217.40, -98.20)` | Personal weapon locker. |
| `interior.workshop` | `vec3(904.50, -3214.50, -98.28)` | Workshop machine. |
| `interior.workshopRadius` | `2.5` | Workshop machine radius; screen stays open up to this plus 1 m. |
| `interior.caddy` | `vec4(890.50, -3238.20, -98.28, 90.0)` | Shared caddy parking spot while anyone is inside. |
| `interior.caddyRespawnSeconds` | `30` | Seconds between caddy checks; wrecked or missing caddy respawns. |
| `interior.missionCab` | `vec4(878.00, -3245.50, -97.80, 270.0)` | Phantom cab wait spot for large supply runs. |
| `interior.supplyDrop` | `vec4(896.50, -3241.00, -98.28, 90.0)` | Supply run parking spot. |
| `interior.quarters` | `wardrobe = vec3(904.90, -3201.20, -97.20)`, `bed = vec3(906.70, -3198.80, -97.20)` | Personal Quarters wardrobe and bed. |
| `interior.camProp` | `'prop_cctv_cam_01a'` | Working camera prop; shooting it breaks camera. |
| `interior.camHits` | `3` | Weapon or melee hits that break camera prop. |
| `interior.camRepair` | `seconds = 8`, `distance = 3.0`, `anim = { dict = 'amb@prop_human_movie_bulb@idle_a', clip = 'idle_b', flag = 1 }` | Camera repair takes `seconds`, plays `anim`, uses one `storage.cameraPartItem` from you or the stash. `distance` includes height. |
| `interior.camView` | `{ sensitivity = 3.0, maxYaw = 60.0, maxPitch = 30.0 }` | Feed mouse look; `maxYaw` and `maxPitch` limit sideways and up/down turn. |
| `interior.cams` | Four cameras | `id` and `zone`: `CAM-01` ENTRY RAMP, `CAM-02` LOADING BAY, `CAM-03` LAB WING, `CAM-04` PERIMETER. `coords`, `rot`, `fov` set the view. Bunker has first `upgrades.security.baseCams` cameras, `upgrades.security.cams` with Security upgrade. |
| `interior.sets` | A list of rules | Entity set rules: `set` is active when its `when` is met (or absent) and its `unless` is not. A condition is upgrade, `{ upgrade = 'equipment', min = 2 }`, or customization, `{ custom = 'quarters' }`. |
| `interior.styles` | `{ 'Bunker_Style_A', 'Bunker_Style_B', 'Bunker_Style_C' }` | Interior looks. |

The shooting range is under `interior.range`:

| Option | Default | What it does |
| --- | --- | --- |
| `range.start` | `vec3(899.00, -3170.50, -97.10)` | Mode and shooting spot. Placeholder. |
| `range.radius` | `2.0` | Radius around start spot. |
| `range.board` | `vec3(901.50, -3170.50, -97.10)` | Scoreboard spot. |
| `range.boardSize` | `10` | Rows per leaderboard. |
| `range.keepPerPlayer` | `50` | Stored runs per player. Older runs are deleted. |
| `range.gapMs` | `400` | Pause between two targets of one lane. |
| `range.comboStep`, `range.comboMax` | `0.1`, `2.0` | Each consecutive hit adds `comboStep` to score multiplier, up to `comboMax`. No combo in `precision`. |
| `range.modes` | `popup` 60 s, `moving` 60 s, `precision` 45 s with 20 hits at most | Modes with `label` (`Pop-up`, `Moving`, `Precision`) and length in `seconds`. `shots` caps `precision` hits. |
| `range.difficulty` | See below | Four difficulty levels. |
| `range.popup` | Model `gr_prop_gr_target_04a` and 12 `points` | Where pop-up targets appear. |
| `range.rails` | Model `gr_prop_gr_target_04b` and 3 `lanes` | Moving targets slide between each lane's `from` and `to`. |
| `range.precision` | Model `prop_target_comp_wood` and 3 `points` | Bullseye spots. Heading `0` faces shooters for this model. |
| `range.zones` | `HEAD` 100, `TORSO` 50 and `LIMB` 25 for both box targets. Rings `R1` 10, `R2` 5 and `R3` 2 for the bullseye. | Hit zones per target model, in its own space, with `points`. First match wins. |
| `range.headZones` | `{ HEAD = true, R1 = true }` | Zones that count as headshots or bullseyes. |

Target positions and zone sizes are placeholders: shoot a target with `debug` on and tune them.

| Difficulty | `window` (ms a target stays up, moving targets x2) | `speed` (rail metres per second) | `mult` (score multiplier) |
| --- | --- | --- | --- |
| `easy` | `2000` | `1.0` | `1.0` |
| `normal` | `1200` | `1.8` | `1.5` |
| `hard` | `700` | `2.8` | `2.0` |
| `insane` | `350` | `4.0` | `3.0` |

Each level also has a `label` and an `order` (list position).

### Upgrades and customizations

Upgrades are bought once; effects add up. Decimal values are fractions: `0.30` is +30%. An optional `image = 'https://...'` (or `nui://` URL) on an upgrade or customization replaces the icon.

| Upgrade | `price` | `dailyFee` | Numbers |
| --- | --- | --- | --- |
| `upgrades.equipment` | `1155000` | `800` | `production = 0.30`, `research = 0.25`, `value = 0.10` (stock value), `drain = -0.25` (supply drain). |
| `upgrades.staff` | `598500` | `1000` | `production = 0.20`, `research = 0.25`, `value = 0.05` (stock value). |
| `upgrades.security` | `351000` | `700` | `hold = 0.25` (raid defence), `cams = 4` (with the upgrade), `baseCams = 2` (without). |

Each upgrade and customization also has an `effects` list (its card lines).

Customizations are bought one option at a time; switching pays that option's price. `set` is the interior style an option applies, `model` the caddy's vehicle.

| Customization | Options and `price` | What it gives |
| --- | --- | --- |
| `customizations.style` | `Style 1` `0` (`Bunker_Style_A`), `Style 2` `215000` (`Bunker_Style_B`), `Style 3` `290000` (`Bunker_Style_C`) | Interior look, changeable any time. |
| `customizations.quarters` | `265000` | Personal Quarters: office, sleeping area, wardrobe, bed. |
| `customizations.range` | `Black` `740000`, `White` `845000` | Firing range and target challenge with best score. |
| `customizations.locker` | `175000` | Personal weapon locker per member. |
| `customizations.caddy` | `Caddy` `85000` (`caddy2`), `Bunker Caddy` `120000` (`caddy3`) | Caddy to drive around bunker. |

### Supplies, stock and production

| Option | Default | What it does |
| --- | --- | --- |
| `supplies.max` | `100` | Max supplies held. |
| `supplies.drainPerHour` | `4.2` | Supplies used per hour while producing, times active line's `supplyMult`. |
| `supplies.researchDrainPerHour` | `1.8` | Extra supplies per hour per active research project. |
| `supplies.tiers` | `{ units = 25, price = 15000 }`, `{ units = 50, price = 28000 }`, `{ units = 100, price = 50000 }` | Supply orders: `units` delivered for `price`. |
| `stock.defaultLine` | `'ammo'` | Line new bunker produces. |
| `stock.order` | `{ 'ammo', 'parts', 'precision', 'heavy' }` | Terminal order of stock types. |
| `production.baseUnitsPerHour` | `2.0` | Units per hour with no Production staff. |
| `production.perStaffUnitsPerHour` | `2.4` | Units per hour per Production operative, scaled by their efficiency. |
| `production.localSeconds` | `30` | Timer-mode delivery time of local buyer sale. |
| `production.exportSeconds` | `45` | Timer-mode delivery time of export contract. |
| `production.exportMinOnline` | `2` | Org members who must be online to send export. |
| `production.exportHijackChance` | `0.18` | Chance export is hijacked in timer mode. |
| `production.maxCatchupHours` | Code default `168`. Not in the shipped file. | Max elapsed time worked out when nobody has touched bunker. Add key to change it. `0` removes limit. |

`stock.types` sets the four lines: `requires` is the upgrade a type needs, `speed` multiplies production, `supplyMult` supply drain, `cap` max units, `local` and `export` unit prices before reputation and upgrade bonuses, `cargo` max units per sale mission.

| Field | `ammo` | `parts` | `precision` | `heavy` |
| --- | --- | --- | --- | --- |
| `label` | Ammunition | Weapon Parts | Precision Components | Heavy Ordnance |
| `requires` | None | `equipment` | `staff` | `security` |
| `speed` | `1.2` | `1.0` | `0.8` | `0.6` |
| `supplyMult` | `0.8` | `1.0` | `1.3` | `1.6` |
| `cap` | `250` | `200` | `150` | `100` |
| `local` | `2400` | `3200` | `4400` | `6000` |
| `export` | `3100` | `4150` | `5700` | `7800` |
| `cargo` | `250` | `200` | `150` | `100` |

### Missions

The controller is the player who started a mission; if they go offline, another online participant takes over. Default coordinates are starting points: check them with `/bunkermission preview <zone|dropoff> <id|index> [spawnIndex]`.

| Option | Default | What it does |
| --- | --- | --- |
| `missions.mode` | `'world'` | `'world'` runs vehicle missions, `'timer'` countdown with no vehicle. |
| `missions.orderMode` | `'truck'` | `'truck'`: ordering supplies starts pickup mission. `'instant'`: supplies arrive at once. |
| `missions.externalRuns` | `false` | Timer mode only. `true`: timer never completes supply run itself; call `exports.smoke_bunker:finishSupplyRun`. |
| `missions.rerollCooldownSeconds` | `20` | Cooldown for showing next `missions.list` job. |
| `missions.blueprintDropChance` | `0.5` | Chance finished supply run adds `blueprintDrop` to bunker's blueprints. |
| `missions.blueprintDrop` | `'Turret Servo Schematic'` | Research blueprint supply run can drop. |
| `missions.blueprintItemDropChance` | `0.25` | Chance finished supply run or settled sale also drops `bp_*` item into main stash. |
| `missions.blueprintDropWeights` | `{ ammo = 0, parts = 50, precision = 35, heavy = 15 }` | Weights of stock tier dropped `bp_*` item comes from; only unlocked tiers count. |
| `missions.spawnDistance` | `250.0` | Vehicle and guards spawn when controller is this close. |
| `missions.approachEveryMs` | `2000` | Controller client's vehicle request interval near pickup. |
| `missions.foundDistance` | `90.0` | Distance at which `missions.list` job counts as found. |
| `missions.deadlineSeconds` | `{ order = 1200, source = 1800, sale = 1500 }` | Time limit per mission kind: `order` truck supply order, `source` `missions.list` job, `sale` sale. |
| `missions.controllerTimeoutSeconds` | `60` | Mission fails when controller is offline this long and nobody can take over. |
| `missions.abandonSeconds` | `150` | Mission fails when no participant is near vehicle this long. |
| `missions.abandonRadius` | `400.0` | Radius that counts as near vehicle. |
| `missions.deliver` | `{ radius = 12.0, maxSpeed = 4.0, driveInSeconds = 45, hitchDistance = 15.0, doorRadius = 30.0 }` | Delivered when truck is within `radius` of target and slower than `maxSpeed` (m/s). Trailer run also needs cab within `hitchDistance` of trailer. Hatch stays open while truck is within `doorRadius` of entrance. `driveInSeconds` ends unload when no client reports back. |
| `missions.refundOnFail` | `{ order = true }` | Failed supply order refunds its price. |
| `missions.orderVehicle` | `{ 'supply', 'supply', 'supplyTrailer' }` | Vehicle per supply tier: index matches `supplies.tiers`, value is `missions.vehicles` key. |
| `missions.orderZone` | `{ 'city', 'city', 'docks' }` | Zone per supply tier; random spot of it is pickup. |
| `missions.vehicles` | `supply = mule3`, `supplyTrailer = phantom with trailers2`, `sale = mule3`, `saleArmored = boxville5` | Vehicle models. `supplyTrailer` cab waits inside bunker (`cabInBunker = true`); `saleArmored` is for sales by bunkers with `garage` perk. |
| `missions.zones` | Pools `city`, `docks`, `guarded` | Spot pools with `id`, `label`, `spawns`. `city`: Mule pickups and sale drop-offs. `docks`: open lots for trailers. `guarded`: spots with their own guard positions (`peds`). One random spot per run. Map shows only `radius` circle with spot inside. |
| `missions.cutscene` | `{ name = 'hs4f_drp_off', entity = 'MP_1', maxSeconds = 90, skippable = true }` | Driver cutscene at sale's drop-off. `entity` is driver's role; stops after `maxSeconds`. `skippable = true` lets driver skip it with client `cutscene.skipControl` (`E`). Alternatives: `hs4f_drp_cel`, `hs4_bch_end`, `tunf_drp_hand`; preview with `/bunkermission cutscene <name>`. |

`missions.reveal` sets which missions are tracked:

| Option | Default | What it does |
| --- | --- | --- |
| `reveal.delaySeconds` | `30` | Seconds after start before tracking begins. |
| `reveal.intervalSeconds` | `5` | Seconds between blip updates. Sales use `saleCircle.intervalSeconds`. |
| `reveal.risks` | `{ HIGH = true }` | Risk levels that are tracked. |
| `reveal.jobs` | `{ 'police', 'sheriff', 'bcso', 'sasp', 'lspd', 'state', 'fib', 'ranger' }` | Jobs that see tracking. |
| `reveal.otherOrgs` | `true` | Members of other orgs see it too. |
| `reveal.saleCircle` | `{ radius = 300.0, intervalSeconds = 60 }` | Sales show `radius` search circle with truck somewhere inside, refreshed every `intervalSeconds` and moved only when truck leaves it. |

`missions.list` holds the three jobs:

| Field | Job 1 | Job 2 | Job 3 |
| --- | --- | --- | --- |
| `name` | `HIJACK CONVOY` | `RAID LOCKUP` | `SKIM AIRDROP` |
| `location` | `LOS SANTOS` | `LS PORT & AIRPORT` | `LOS SANTOS` |
| `risk` | `MED` | `HIGH` | `LOW` |
| `units` | `50` | `75` | `35` |
| `vehicle` | `supply` | `supplyTrailer` | `supply` |
| `zone` | `guarded` | `docks` | `city` |
| `crew` | `MULE / 2 CREW` | `PHANTOM + TRAILER / 3 CREW` | `MULE / SOLO` |
| `seconds` | `45` | `60` | `30` |

| Field | What it does |
| --- | --- |
| `name`, `location` | Job name and place in terminal. |
| `risk` | `LOW`, `MED` or `HIGH`. Sets the guards (`guards.byRisk`), reinforcement chance and map tracking (`reveal.risks`). |
| `units` | Supplies delivered. |
| `vehicle` | Key of `missions.vehicles`. |
| `zone` | `id` of `missions.zones` pool; random spot of it is pickup. |
| `crew` | Vehicle and crew text on job card. |
| `seconds` | Timer-mode countdown. |

`missions.guards` sets the NPC guards of a `missions.list` job:

| Option | Default | What it does |
| --- | --- | --- |
| `guards.models` | `'s_m_y_blackops_01'`, `'s_m_y_blackops_02'`, `'g_m_y_mexgoon_01'` | Ped models, one at random per guard. |
| `guards.weapons` | `'WEAPON_CARBINERIFLE'`, `'WEAPON_PISTOL'`, `'WEAPON_SMG'` | Weapons, one at random per guard. |
| `guards.byRisk` | `{ LOW = { 0, 0 }, MED = { 3, 5 }, HIGH = { 6, 9 } }` | Min and max guards per risk. |
| `guards.accuracy`, `guards.health`, `guards.armour` | `35`, `220`, `50` | Accuracy, health, armour of each guard. |
| `guards.alertDistance` | `40.0` | Distance at which guards notice you. |
| `guards.reinforcement` | `chance = { LOW = 0.0, MED = 0.25, HIGH = 0.6 }`, `vehicle = 'baller2'`, `peds = 3`, `spawnDistance = 250.0` | When first guard dies, `chance` (by risk) decides if `vehicle` with `peds` more guards arrives, on road about `spawnDistance` from spot. |

`missions.sale` sets sales:

| Option | Default | What it does |
| --- | --- | --- |
| `sale.minDistance` | `1200.0` | Drop-off is at least this far from bunker. |
| `sale.risk` | `{ ['local'] = 'LOW', export = 'HIGH' }` | Risk per kind of sale. |
| `sale.dropoffZone` | `'city'` | Random spot of this zone is drop-off. |
| `sale.dropoffRadius` | `14.0` | Drop-off area size. |
| `sale.chase` | `{ delaySeconds = 45, vehicles = { LOW = 0, MED = 1, HIGH = 2 }, model = 'baller2', pedsPerVehicle = 3 }` | Chase cars sent `delaySeconds` into delivery; `vehicles` sets how many by risk, each `model` car carries `pedsPerVehicle` peds. |
| `sale.hijackable` | `{ ['local'] = false, export = true }` | Which sales rival org can steal. Member of another org who drives truck into their own bunker banks cargo and takes `reputation.hijackDelta` from seller. Hijackable sale ignores `controllerTimeoutSeconds` and `abandonSeconds`; fails only on timeout or destroyed truck. |

### Crews

| Option | Default | What it does |
| --- | --- | --- |
| `group.requiredForMissions` | `false` | `true`: missions need crew. `false`: crew optional; without one every online org member takes part. |
| `group.maxMembers` | `6` | Max crew members. |
| `group.rejoinSeconds` | `300` | Disconnected member keeps their place this long. |
| `group.inviteSeconds` | `60` | Crew invite lifetime. |
| `group.command` | `'crew'` | Crew panel command. |
| `group.hudKey` | `'G'` | Key that shows or hides task list. |
| `group.hudModifier` | `19` | Control held with `hudKey`: `19` is left ALT, `false` the key alone. |
| `group.hudCommand` | `'taskhud'` | Command to move task list. |
| `group.key` | `nil` | e.g. `'F6'` adds crew panel key mapping players can rebind. |

### Research

| Option | Default | What it does |
| --- | --- | --- |
| `research.staffSpeedBonus` | `0.25` | Research speed added per Research operative. |
| `research.baseSlots` | `1` | Concurrent projects. |
| `research.staffSlots` | `2` | Slots with Staff upgrade. |
| `research.startingBlueprints` | `{ { name = 'MK2 Suppressor Schematic', qty = 1 } }` | Starting blueprints. |
| `research.projects` | Six projects | See below. |

`hours` is the duration with no Research staff. `fast` is the org-funds price to finish a running project at once. A `blueprint` project uses one of that blueprint when it starts. `startsDone = true`: a new bunker already has it. `unlocks` lists the items on its card; recipes open through their own `unlockedBy` or `blueprint`, not this list.

| `id` | `name` | `hours` | `fast` | `blueprint` | `unlocks` |
| --- | --- | --- | --- | --- | --- |
| `r1` | MK II Barrel Rifling | `36` | `0` | None | None. `startsDone`. |
| `r2` | Ballistic Armor Plating | `36` | `0` | None | `armor_plate`. `startsDone`. |
| `r3` | Explosive Rounds | `96` | `85000` | None | `ammo_explosive` |
| `r4` | MK2 Suppressor | `72` | `60000` | `MK2 Suppressor Schematic` | `suppressor` |
| `r5` | Turret Servo Mod | `72` | `70000` | `Turret Servo Schematic` | `turret_servo` |
| `r6` | Gas Mask Filter Variant | `48` | `45000` | `Filtration Schematic` | `gasmask` |

Each project also has `desc` and `enables` card lines.

### Staff

| Option | Default | What it does |
| --- | --- | --- |
| `staff.wageCycleMinutes` | `60` | Wage cycle length. Unpaid wages pause production and research. |
| `staff.severanceHours` | `8` | Dismissal costs hourly wage times this, from org funds. |
| `staff.maxStaff` | `8` | Max operatives per bunker. |
| `staff.rehireFeeHours` | `60` | Rehire fee: hourly wage times this. |
| `staff.feeHours` | `55` | Hire fee: hourly wage times this. |
| `staff.candidateCount` | `3` | Candidates offered at once. |
| `staff.candidateRefreshHours` | `6` | Hours between candidate refreshes. |
| `staff.roles` | `{ 'Production', 'Research', 'Guard' }` | Staff roles. |
| `staff.starting` | `STF-1042 Marcus Vela` (Production, `wage = 220`, `eff = 91`) and `STF-1188 Dana Roth` (Production, `wage = 180`, `eff = 84`) | Operatives every new bunker starts with. |
| `staff.firstNames`, `staff.lastNames` | Two lists of 16 names | Candidate name pools. |
| `staff.wageRange` | `{ Production = { 160, 260 }, Research = { 220, 340 }, Guard = { 120, 190 } }` | Candidate hourly wage by role. |
| `staff.effRange` | `{ 68, 99 }` | Candidate efficiency, percent. |
| `staff.renderDistance` | `40.0` | Staff peds exist within this distance of player inside. |
| `staff.models` | `Production = 'mp_m_waremech_01'`, `Research = 's_m_m_scientist_01'`, `Guard = 's_m_y_blackops_01'` | Ped model per role. |
| `staff.spots` | A list of positions for each role | Work spots, filled in hire order. A `machine` is `lathe`, `drill` or `mill` (bunker machine), `assemble_guns` or `load_clips` (office chair) or `weapon_test`; with none ped stands guard with rifle. Give every role `maxStaff` spots so every hire is on floor. |
| `staff.idleEverySeconds` | `{ 8, 20 }` | Random idle animation interval. |

`staff.guard` sets guard operatives, who fight from their post in a raid and never leave it.

| Option | Default | What it does |
| --- | --- | --- |
| `guard.postRadius` | `2.5` | Distance guard may leave post for cover. |
| `guard.engageRange` | `60.0` | Raiders this close are attacked. |
| `guard.accuracy`, `guard.health` | `45`, `200` | Accuracy and health of each guard operative. |
| `guard.grenadeEverySeconds` | `20` | Guard with grenades throws one this often. |
| `guard.grenadeRange` | `{ 8.0, 30.0 }` | Guard throws at raider in sight this far away. |
| `guard.kit` | Three tracks of three tiers | Raid kit, bought per guard tier by tier. Tier 1 is what every hire has. |

| Track | Tier 1 | Tier 2 | Tier 3 |
| --- | --- | --- | --- |
| `weapon` | Carbine Rifle, `0` | Special Carbine MK2, `45000` | Combat MG MK2, `95000` |
| `armor` | No Vest, `0` | Light Vest (armour 50), `20000` | Heavy Armor (armour 100), `50000` |
| `grenades` | No Grenades, `0` | 2 Grenades, `15000` | 4 Grenades, `30000` |

Each cell is the tier's `label` and `price`. `weapon` tiers set `weapon` (a ped weapon name), `armor` tiers `armour`, `grenades` tiers grenade `count`.

### Reputation

Reputation runs 0 to 100. A tier starts at `min`, `bonus` is the percent added to unit prices, `note` is its card line.

| `reputation.tiers` name | `min` | `bonus` | `note` |
| --- | --- | --- | --- |
| `UNKNOWN` | `0` | `0` | NO STANDING · BASE PRICES ONLY |
| `KNOWN` | `30` | `4` | BUYERS DEAL BUT HAGGLE |
| `TRUSTED` | `60` | `8` | BUYERS PAY A PREMIUM AND WAIT LONGER |
| `PREFERRED` | `85` | `12` | BUYERS CALL YOU FIRST · PRIORITY CONTRACTS |

| Option | Default | What it does |
| --- | --- | --- |
| `reputation.start` | `0` | Starting reputation. |
| `reputation.localDelta` | `4` | Change after clean local sale. |
| `reputation.exportDelta` | `6` | Change after clean export. |
| `reputation.hijackDelta` | `-10` | Change when sale is lost: full value for export, half for local sale. Rival who banks hijacked sale gains the same. |

### Raids

| Option | Default | What it does |
| --- | --- | --- |
| `raid.threshold` | `70` | Bunker shows on other orgs' radar only while stock is above this percent of cap. |
| `raid.minOnline` | `2` | Org members who must be online to launch raid. |
| `raid.gearCost` | `45000` | Org funds spent to launch raid; refunded if restart or error cancels it. |
| `raid.incomingSeconds` | `45` | Length of simulated inbound raid. Debug tools only. |
| `raid.cooldownSeconds` | `1800` | Cooldown per attacker and target pair after raid. |
| `raid.stolenFraction` | `0.35` | Share of every stock type taken in successful raid. |
| `raid.cashPerUnitMultiplier` | `3` | Haul cash: stolen units times their stock type's local price times this. |
| `raid.holdBase`, `raid.holdPerGuard`, `raid.holdBlastSealed`, `raid.holdPerCamDown` | `0.30`, `0.20`, `0.15`, `-0.05` | Defence rating on radar: `holdBase` plus `holdPerGuard` per Guard operative, `holdBlastSealed` while blast doors are sealed, `holdPerCamDown` per broken camera, plus `upgrades.security.hold`. |
| `raid.holdMin`, `raid.holdMax` | `0.10`, `0.90` | Defence rating limits. |
| `raid.defenceLabels` | `NONE` up to `0.30`, `LIGHT` up to `0.50`, `MODERATE` up to `0.70`, `HEAVY` up to `1.0` | Rating labels. |
| `raid.approachSeconds` | `900` | Time to reach and breach target after launch. |
| `raid.assaultSeconds` | `600` | Time from first breach to finish hack. |
| `raid.hackSeconds` | `45` | Seconds hacker must survive next to laptop without break. |
| `raid.hackRadius` | `3.0` | Max hacker distance from laptop. |
| `raid.deadHealth` | `105` | Health at or below this counts as dead; hack resets. |
| `raid.passSeconds` | `900` | Raider entry pass validity. |
| `raid.tileBase` | `'https://wasabirobby.github.io/MAP/GTA-MAP-PNG/SAT/{z}/{x}/{y}.webp'` | Map tile URL for Acquire and Raid Radar maps (zoom 2 to 5). Empty turns tiles off and shows map notice. |
| `raid.world` | `{ x1 = -5744.4, x2 = 6792.4, y1 = 8307.7, y2 = -4000.0 }` | World corners of tile set. |

`raid.breach` sets how raiders get through the entrance keypad:

| Option | Default | What it does |
| --- | --- | --- |
| `breach.hackItem` | `'bunker_hackdevice'` | Item needed to hack keypad. |
| `breach.consumeHackItem` | `false` | `true` uses device up on every attempt. |
| `breach.hackDifficulty` | `{ 'easy', 'easy', 'medium' }` | ox_lib skill check rounds. |
| `breach.hackSealedDifficulty` | `{ 'easy', 'medium', 'medium', 'hard' }` | Rounds when blast doors are sealed (Security upgrade). |
| `breach.hackKeys` | `{ 'w', 'a', 's', 'd' }` | Skill check keys. |
| `breach.hackMinSeconds` | `2` | Hack result reported faster than this is refused. |
| `breach.hackSecondsPerRound` | `1.5` | Result faster than this per round is refused too. |
| `breach.hackRetrySeconds` | `60` | Cooldown for player after failed hack; owners get alarm. |
| `breach.c4Item` | `'bunker_c4'` | Used up when planted. |
| `breach.c4FuseSeconds` | `10` | Charge fuse. |
| `breach.c4SealedExtraSeconds` | `5` | Extra fuse with sealed blast doors. |
| `breach.c4SafeRadius` | `6.0` | Planter is warned to get this far away. |

`raid.guards` sets the NPC guards inside a raided bunker, on top of the Guard operatives:

| Option | Default | What it does |
| --- | --- | --- |
| `guards.base` | `2` | NPC guards at start. |
| `guards.perGuardStaff` | `0` | Extra NPC guards per Guard operative; `0` because operatives fight in person. |
| `guards.perSecurityLevel` | `1` | Extra NPC guards with Security upgrade. |
| `guards.max` | `8` | Max NPC guards. |
| `guards.waveSeconds`, `guards.waveSize`, `guards.maxWaves` | `120`, `2`, `2` | Every `waveSeconds`, `waveSize` more guards spawn if few are left, up to `maxWaves` waves. |
| `guards.spawns` | Eight positions | Spawn points in reference coordinates. Placeholders: tune with `/bunkercoords`. |

### Marketplace and buyer terminals

| Option | Default | What it does |
| --- | --- | --- |
| `market.feePct` | `5` | Host fee percent, taken from seller's proceeds. |
| `market.minUnit`, `market.maxUnit` | `100`, `5000000` | Min and max unit price of listing. |
| `market.maxQty` | `500` | Max items per listing. |
| `market.maxListingsPerBunker` | `20` | Max active listings per bunker. |
| `market.qtyStep`, `market.unitStep` | `5`, `500` | Step of quantity and price buttons. |
| `buyer.account` | `'bank'` | Account dealer terminal buyer pays from: `'bank'`, `'cash'` or `'money'`. |
| `buyer.maxDistance` | `4.0` | Distance from terminal point to open it and buy. |
| `buyer.allowAnywhere` | `false` | `true` needs no terminal point; use command or `openBuyerTerminal` export. |
| `buyer.command` | `false` | e.g. `'bunkerbuyer'` opens dealer terminal anywhere. Also needs `allowAnywhere`. |
| `buyer.points` | `LEGION SQUARE DEALER` at `vec4(195.17, -933.77, 30.69, 150.0)`, `SANDY SHORES DEALER` at `vec4(1961.0, 3740.0, 32.34, 300.0)` | Dealer terminals. Positions are placeholders: check them in game. |

### Storage and placeable storage

| Option | Default | What it does |
| --- | --- | --- |
| `storage.slots` | `120` | Bunker stash slots. |
| `storage.weight` | `2000000` | Bunker stash capacity, grams. |
| `storage.categories` | `ammo_rifle` and `armor_plate` = `'MUNITIONS'`, `blueprint_mk2` = `'BLUEPRINT'`, `gasmask`, `thermite` and `lockpick_adv` = `'GEAR'`, `camera_part` = `'PARTS'`, `money_dirty` = `'CASH'`, `weaponPrefix = 'WEAPON_'` | Storage page category per item. Items starting with `weaponPrefix` are `WEAPON`, any other is `MISC`. |
| `storage.itemValues` | `{}` | Optional `[item] = value`: estimated unit value on Storage page. No value counts as 0. |
| `storage.cameraPartItem` | `'camera_part'` | Item used up to repair destroyed camera. |
| `storage.lockerSlots`, `storage.lockerWeight` | `30`, `150000` | Each member's personal gun locker. Needs Gun Locker customization. |
| `storage.ownUi` | `true` | `true`: resource stash screen with rank rules, kits and allowances. `false`: inventory stash screen, which needs `WITHDRAW` permission. |
| `storage.locker` | `vec3(905.2, -3210.4, -98.2)` | Stash point inside bunker. |
| `storage.uiDistance` | `3.0` | Distance to stash point to use it. At terminal, `interior.desk.maxDistance` applies. |
| `storage.playerMaxWeight` | `120000` | Grams player may carry when taking from stash. `false`: no limit beyond inventory's own check. |
| `storage.depositBlacklist` | `{}` | `[item] = true` bars item from bunker. |
| `storage.manageRole` | `'OFFICER'` | Lowest role that edits withdraw ranks, caps, kits and allowances. Managers can also lift their own limits. `'OWNER'` keeps officers limited. |

`storage.rules` holds defaults copied into a bunker on the first use of its stash:

| Option | Default | What it does |
| --- | --- | --- |
| `rules.defaultRole` | `'MEMBER'` | Lowest role that takes items of unlisted category freely. |
| `rules.categoryRole` | `{ WEAPON = 'OFFICER', BLUEPRINT = 'OFFICER', CASH = 'OFFICER' }` | Lowest role per category. |
| `rules.dailyCap` | `{ OFFICER = 100, MEMBER = 20, PROSPECT = 0 }` | Items role takes freely per day. `-1` is unlimited. Owner is always unlimited. |
| `rules.kits` | `GUARD KIT` (id `guard`): `minRole = 'MEMBER'`, `cooldownMin = 60`, 2 `armor_plate` and 2 `ammo_rifle` | Item kits taken in one go. `minRole` is lowest role that can take one, `cooldownMin` minutes before member can retake it. |
| `rules.allowances` | `{}` | `[identifier] = { { name, count } }`: what one player may take of item per day, before role and cap rules apply. Set on stash screen. |

`placeables` sets extra stashes bought on the terminal's Storage page. Each arrives in the main stash as an item that places the stash when used. The item names must exist in your inventory (see `install/items_*.lua`).

| Option | Default | What it does |
| --- | --- | --- |
| `placeables.deliverySeconds` | `600` | Time until bought item reaches main stash. |
| `placeables.maxPerBunker` | `8` | Placed stashes per bunker. |
| `placeables.minSpacing` | `1.0` | Min distance between placed stashes. |
| `placeables.buyRole`, `placeables.pickupRole` | `'OFFICER'`, `'OFFICER'` | Lowest role that buys one, and that picks one up. Contents go with item. |
| `placeables.placeDistance` | `10.0` | Max distance from player to placed spot. |
| `placeables.raidLootPct` | `{ 30, 60 }` | Raiders get each stack with chance in this range, rolled once per stash. Rest moves to main stash. |
| `placeables.types` | Four types | See below. |
| `placeables.rack` | `panel = { halfW, minZ, maxZ, faceY }`, `shelf = { halfW, yMin, yMax, z }`, `strips`, `spotBar` | Gun rack geometry in rack-local metres. Must match model. |
| `placeables.rack.gap`, `placeables.rack.overlapScale`, `placeables.rack.boundsScale` | `0.0`, `0.65`, `0.6` | Min weapon spacing; footprint scales for overlap (lower packs tighter) and for keeping weapon inside panel or shelf. |
| `placeables.rack.camera` | `{ dist = 3.1, z = 1.0, fov = 50.0 }` | Rack screen camera. |
| `placeables.rack.defaultLights` | `{ accentOn = true, color = { 255, 24, 16 }, brightness = 0.6, spot = 'warm' }` | Starting rack lights: accent strips on or off, RGB colour, brightness, spotlight (`'warm'`, `'led'` or `'off'`). |
| `placeables.rack.spotColors` | `warm = { 255, 186, 120 }`, `led = { 214, 230, 255 }` | RGB per spotlight type. |
| `placeables.rack.wallWeapons`, `placeables.rack.shelfWeapons` | 45 and 10 weapon item names | Weapons that hang on wall, and heavy weapons that go on shelf only. |

| `placeables.types` key | `label` | `price` | `slots` | `weight` | `max` |
| --- | --- | --- | --- | --- | --- |
| `crate_small` | Supply Crate | `25000` | `20` | `200000` | `4` |
| `gun_case` | Gun Case | `60000` | `15` | `150000` | `2` |
| `container` | Storage Container | `120000` | `50` | `800000` | `2` |
| `gun_rack` | Gun Rack | `90000` | None | None | `2` |

| Field | What it does |
| --- | --- |
| `item` | Inventory item it arrives as: `bunker_` plus type key (`bunker_crate_small`, `bunker_gun_case`, `bunker_container`, `bunker_gun_rack`). |
| `price` | Terminal price. |
| `slots`, `weight` | Stash size; `weight` is in grams. |
| `max` | Max of this type per bunker, counting ones not placed yet. |
| `model` | Placed prop. Models are placeholders. |

`defaultRole` is the lowest role that opens a newly placed stash, `MEMBER` when unset; `gun_case` sets `'OFFICER'`. `gun_rack` sets `rack = true`: a wall rack that shows its weapons, has no stash and can be picked up only when empty.

### Workshop and item names

| Option | Default | What it does |
| --- | --- | --- |
| `workshop.slots` | `{ equipment = 1, staff = 1 }` | Concurrent crafting jobs: Equipment upgrade opens workshop with one slot, Staff upgrade adds one. |
| `workshop.maxQty` | `10` | Max batches per job. |
| `workshop.cancelRefundPct` | `50` | Percent of inputs returned when running job is cancelled. |
| `workshop.maxCargo` | `250` | Max units of crafted good per sale mission. |
| `workshop.recipes` | Seven bunker specials | Custom items: `ammo_rifle`, `armor_plate`, `ammo_explosive`, `suppressor`, `turret_servo`, `gasmask`, `thermite`. Fields below. |
| `workshop.goods` | Seven goods | Items sellable through sale mission or listing, with `local` and `export` unit prices before reputation bonus. |

| Recipe field | What it does |
| --- | --- |
| `id` | Recipe id; replaces catalog recipe with same id. |
| `category` | Workshop filter it is listed under. |
| `stockType` | Stock type used: key of `stock.types`. |
| `inputs` | Cost of one batch: `stock` units, raw `items` from bunker stash, optional `money` from org account. |
| `output` | `item` and `count` one batch makes. |
| `seconds` | Crafting time of one batch. |
| `unlockedBy`, `blueprint` | Research id or `bp_*` item that unlocks it. With neither, no unlock is needed. |

Raw item names in `workshop.recipes` are QBCore and ESX style and must exist in your inventory. A recipe whose output, after `itemNames` mapping, does not exist there is skipped with a console warning.

`itemNames` maps the ox_inventory names recipes use to your inventory's names; names without an entry pass through. `lowerWeapons = true` lower-cases `WEAPON_` names.

| Table | Inventory | Default |
| --- | --- | --- |
| `itemNames.ox` | ox_inventory | `{}` |
| `itemNames.jaksam` | jaksam_inventory | `{}` |
| `itemNames.tgiann` | tgiann-inventory | `{ lowerWeapons = true }` |
| `itemNames.qb` | qb-inventory, ps-inventory and codem-inventory | `lowerWeapons = true` and a list mapping ammo names (`['ammo-9'] = 'pistol_ammo'`) and attachment names (`['at_suppressor_light'] = 'pistol_suppressor'`) |
| `itemNames.one` | one_inventory | `{ lowerWeapons = true }` |
| `itemNames.codemv2` | codem-inventoryv2 | `{}` |
| `itemNames.wasabi` | wasabi_inventory | `{}` |

### Logs

| Option | Default | What it does |
| --- | --- | --- |
| `logs.retainDays` | `14` | Log rows older than this are deleted at start if `sim.pruneLogsOnStart` is `true`. |

## Catalog

`config/shared/catalog.lua` lists a workshop recipe for every ox_inventory firearm (no melee or novelty weapons), attachment, skin, ammo and throwable, using the [recipe fields](#workshop-and-item-names). A recipe is open when it is a `starter` or its `blueprint` (a `bp_*` item learned at the workshop) is known. A `config.workshop.recipes` recipe with the same id wins.

`catalog.blueprints` lists each `bp_*` blueprint item with its label, `tier` (stock tier of its recipes) and `unlocks` (recipe ids). Learning a blueprint uses up the item.

## Language

To add a language, copy `locales/en.json` to `locales/<code>.json`, translate the values and set `language` to the code.

The locale file holds notifications, error messages, log lines, interact prompts and the terminal's `ui_` labels. Other terminal text, such as confirmation dialogs and the Upgrades, Workshop, Crew, Stash and Range screens, is English and not in the file.

`locales/en.json` is not under `escrow_ignore`.
