> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/gangs/cuxial-gang/configuration.md). # Configuration Every option of Cuxial Gang: shared/config.lua block by block and the files in data/. Cuxial Gang is configured in three places: `shared/config.lua` for general behaviour, one file per activity in `data/`, and the staff panel for everything that lives in the database. Restart the resource after editing a file. {% hint style="info" %} Locations, organizations, the vehicle catalogue, upgrade prices, season pass rewards, turf zones, racketeering points, favelas and airdrop sites are not in any file. Staff edit them in game with `/crimeadmin`. {% endhint %} ## shared/config.lua ### General | Option | Type | Default | What it does | | ----------------- | ------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `debug` | boolean | `false` | Debug traces in the console. Also enabled with `setr cuxial_gang_debug 1`. | | `ui.accent` | string | configurable | Accent colour of the staff panel and the HUDs, in hex. The boss menu and the tablet use the colour of each organization. | | `admin.ace` | string | `'mod'` | ACE that opens the staff panel and allows its commands. Checked on the server every time. | | `live.enabled` | boolean | `true` | Open windows refresh on their own when their data changes. | | `live.debounceMs` | number | `400` | Changes to the same block inside this window, in milliseconds, are announced once. | | `timeZone` | string | `'America/New_York'` | Time zone of the server, as an IANA name such as `Europe/Madrid`. Used by schedules and the season pass. | | `timeApi` | string | a public time API | URL asked for the real time of `timeZone` on start; `%s` is replaced by the zone. It must return JSON with `dateTime` or `datetime` in ISO format. Empty string = use the machine clock. | | `currency` | table | `{ currency = 'USD', style = 'currency', format = 'en-US' }` | Money format in the interface. `currency` is the ISO code and `format` the locale. | ### commands Each entry is `{ name = '...', restricted = '...' }`. | Option | Type | Default | What it does | | ------------ | --------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | `name` | string \| false | see [Commands](/scripts/gangs/cuxial-gang/commands.md) | Name of the command. `false` removes the command. | | `restricted` | string \| false | `'group.mod'` or `'group.admin'` | Group that sees and can run the command. The ACE in `admin.ace` is checked on top of it. | The entries are `panel`, `resetStats`, `addVehicle`, `fireMember` and `setGang`. ### org | Option | Type | Default | What it does | | ------------------------- | ------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `accessMethod` | string | `'none'` | `'none'`: headquarters are in the open world. | | `markerSize` | number | `1.2` | Size of the headquarters markers. | | `markerColor` | table | `{ r, g, b }` | Colour of the headquarters markers. | | `defaultSlots` | number | `2` | Rank and member slots of a new organization. | | `ranksLimit` | number | `5` | Maximum ranks reachable with upgrades. | | `membersLimit` | number | `20` | Maximum members reachable with upgrades. | | `defaultStashWeight` | number | `2` | Stash capacity of a new organization, in kg. | | `stashCapacityUpgradePer` | number | `5` | Kg added by each stash upgrade. | | `limitBossMenu` | boolean | `false` | `true`: only one member at a time inside the boss menu of an organization. | | `useDirtyMoneyInBossMenu` | boolean | `false` | `true`: upgrades are paid with dirty money instead of the clean balance. The premium season pass is always paid from the clean balance. | ### garage | Option | Type | Default | What it does | | --------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `disabled` | boolean | `false` | `true`: no organization garage at all. | | `hideMarker` | boolean | `false` | `true`: hides the garage marker at the headquarters. | | `sellPercentage` | number | `20` | Percentage lost when an organization sells a vehicle. | | `nearbyMembersRadius` | number | `30.0` | Metres. With a member closer than this, the tow truck does not take the vehicle. | | `idleMinutes` | number | `5` | Minutes a vehicle must be empty before it can be towed. | | `noticeSeconds` | number | `60` | Warning to the last driver before the tow. If someone gets in, the tow is cancelled. | | `maxTowSpeed` | number | `1.0` | Speed in m/s above which the vehicle counts as moving and is not towed. | | `recover.cost` | number | `5000` | Price to get back a destroyed or missing vehicle at once. | | `recover.payFrom` | string | `'org'` | Who pays: `'org'` (the organization's balance) or `'player'` (whoever asks). | | `returnOnRestart` | boolean | `true` | `true`: vehicles that were out when the server restarted go back to the garage for free. `false`: they show as destroyed and are recovered by paying. | ### tablet and seasonPass | Option | Type | Default | What it does | | -------------------------------- | ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tablet.asItem` | boolean | `false` | `true`: the tablet opens with the item and the command does not exist. `false`: it opens with the command. | | `tablet.command` | string | `'crimetablet'` | Command that opens the tablet. | | `tablet.item` | string | `'crime_tablet'` | Item that opens the tablet. | | `tablet.missionsPerRestart` | number | `8` | Missions drawn on each restart. | | `tablet.disableSeasonPass` | boolean | `false` | Hides the season pass. | | `tablet.disableRanking` | boolean | `false` | Hides the ranking. | | `tablet.disableDarkChat` | boolean | `false` | Turns the dark chat off. | | `seasonPass.customCurrency` | boolean | `false` | `false`: the premium track is bought with the clean balance of the organization. `true`: the pass shows its own currency instead of money and the premium track is not on sale. | | `seasonPass.customCurrencyLabel` | string | `'CT'` | Name of that currency. | ### blips | Option | Type | Default | What it does | | ------------------------------------------------------------------------------------------- | ------- | -------------------------- | ------------------------------------------------------------------------ | | `scale` | number | `0.8` | Size of the blips. | | `showOnMap` | boolean | `true` | Shows the blips of headquarters, garages, medic, laundering and favelas. | | `showZonesOnMap` | boolean | `true` | Shows the blips of the capture zones. | | `medic`, `organisation`, `zone`, `garage`, `port`, `helipad`, `moneyLaundry`, `laundryStop` | table | `{ id, color }` | Sprite and colour of each kind of blip. | | `laundryRadius` | table | `{ color, alpha, radius }` | Area drawn around a laundering stop. | ### zones | Option | Type | Default | What it does | | ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `disabled` | boolean | `false` | `true`: no capture zones. | | `tickSeconds` | number | `1` | How often the server counts who is inside each zone. | | `cooldownMinutes` | number | `15` | Minutes until a captured zone can be contested again. | | `captureExp` | number | `150` | Experience for capturing a zone. | | `list` | table | examples | The zones: `label`, a unique `index`, `coords` for the blip and the `points` of the polygon. The two included are examples to replace. | ### turf | Option | Type | Default | What it does | | ---------------------------------- | ------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `disabled` | boolean | `false` | `true`: no turf zones. | | `disableEnterNotifications` | boolean | `true` | `false`: notifies the player on entering and leaving a turf zone. | | `activityWindow` | table | `{ enabled = false, start = '23:00', finish = '11:00' }` | Hours in which turf activities count, in server time. It may cross midnight. | | `rivalry.disabled` | boolean | `false` | `true`: organizations cannot declare wars. | | `rivalry.startPrice` | number | `5000` | Price of declaring a war. | | `rivalry.durationHours` | number | `1` | Hours a declared war lasts. | | `rivalry.ownershipHours` | number | `24` | Hours the ownership lasts, only with `control.enabled = false`. | | `rivalry.winExp` | number | `250` | Experience for winning a war. | | `rivalry.bonusMultiplier` | number | `0.5` | During a war, this fraction of the price of each sale is added to the war score of the seller's organization. | | `drugSelling.expPerSale` | number | `15` | Experience per sale. | | `drugSelling.loyaltyPerSale` | number | `50` | Loyalty gained per sale in the zone. | | `drugSelling.loyaltyLossForOthers` | number | `15` | Loyalty the other organizations lose per sale. | ### turf.control Zone control decided by sales. With `enabled = false`, ownership simply expires after `rivalry.ownershipHours`. | Option | Type | Default | What it does | | ---------------------- | ------- | ---------------- | ------------------------------------------------------------------------- | | `enabled` | boolean | `true` | Turns zone control on. | | `windowDays` | number | `3` | Moving window, in days, used to decide owner and conflict level. | | `claimUnits` | number | `40` | Units an organization must sell to take a zone with no owner. | | `disputedUnits` | number | `15` | Units from a rival that make the zone disputed (level 1). | | `hotRatio` | number | `0.6` | Level 2: the rival reaches this fraction of the owner's sales. | | `takeoverMargin` | number | `0.15` | Level 3: the rival beats the owner by this margin and a war opens. | | `warHours` | number | `2` | Hours of a war opened by zone control. | | `abandonDays` | number | `7` | Days with no sales after which the zone loses its owner. | | `minOwnerOnline` | number | `1` | Members of the owner online for a war to start. | | `sweepCron` | string | `'*/10 * * * *'` | Cron of the periodic review that lowers levels as sales leave the window. | | `rankingPointsPerZone` | number | `50` | Ranking points per controlled zone. | ### turf.sales | Option | Type | Default | What it does | | -------------------------- | ------ | ------- | ----------------------------------------------------------------------------------- | | `maxUnitsPerHour` | number | `40` | Units that score per character and hour. Anything above is sold but does not count. | | `ownZoneMultiplier` | number | `1.0` | Price multiplier in your own zone. | | `enemyZoneMultiplier` | number | `1.2` | Price multiplier in an enemy zone. | | `disputedMultiplier` | number | `1.1` | Price multiplier in a disputed zone. | | `graffitiPointsMultiplier` | number | `1.5` | Points bonus with your own graffiti nearby. | | `graffitiPriceMultiplier` | number | `1.1` | Price bonus with your own graffiti nearby. | | `taxPercent` | number | `10` | Percentage of each foreign sale generated as dirty money for the owner. | | `hotAlertMultiplier` | number | `1.5` | From level 2, multiplies the chance of a police alert. | | `hotRejectMultiplier` | number | `1.5` | From level 2, multiplies the chance of the buyer backing out. | | `alertWindowMinutes` | number | `30` | Window used to count a seller's streak in a zone. | | `alertRadiusAfter` | number | `3` | Sales in a row after which the owner gets an area on the map. | | `alertPreciseAfter` | number | `5` | Sales in a row after which the area becomes precise. | | `alertRadius` | number | `300.0` | Radius of the wide area, in metres. | | `alertPreciseRadius` | number | `70.0` | Radius of the precise area, in metres. | | `alertBlipSeconds` | number | `90` | Seconds the area stays on the map. | ### rope, logs, steam, retention | Option | Type | Default | What it does | | ----------------------------------- | ------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `rope.enabled` | boolean | `true` | Turns the interaction menu on players on. | | `rope.keybind.enabled` | boolean | `true` | Registers a key for the menu. | | `rope.keybind.key` | string | `'F6'` | Default key. Each player can rebind it. | | `logs.general` | string | `'cuxial_gang_webhook'` | Name of the convar with the webhook for player actions. | | `logs.admin` | string | `'cuxial_gang_webhook_admin'` | Name of the convar with the webhook for staff actions. | | `steam.convar` | string | `'cuxial_gang_steam_key'` | Name of the convar with the Steam Web API key, for staff avatars. | | `retention.playerActionsDays` | number | `30` | Days member history is kept. `0` = never purge. | | `retention.adminLogsDays` | number | `90` | Days staff logs are kept. `0` = never purge. | | `retention.extortionMessagesDays` | number | `30` | Days phone extortion messages are kept. `0` = never purge. | | `additionalScripts.kq_shellcreator` | boolean | `false` | `true`: waits for the collision around the player to load when the organization loads. For headquarters inside generated interiors. | ## Files in data/ Each file configures one activity and starts with a comment describing every option. Coordinates, item names, models and prices inside them are examples to adapt. | File | What it configures | Main switch (default) | | --------------------- | ---------------------------------------------------------------------------------------- | ------------------------ | | `airdrop.lua` | Schedule, phases, guards, tiers, default sites and loot | `enabled = true` | | `arsenal.lua` | Bench type, levels, weekly quotas, recipes created on first start, parts and the dealer | `enabled = true` | | `blackMedic.lua` | Clandestine medic: healing time, cooldown, price and NPC | `Disable = false` | | `clothing.lua` | Cloakroom and the outfit worn on the laundering route | `Clothing.enable = true` | | `drugselling.lua` | Sellable drugs and prices, buyers, cooldown, police alert, rejection chance, burner item | — | | `extortion.lua` | Phone extortion of civilians: victims, keywords and replies | — | | `extortionFixers.lua` | Intermediaries who sell hostages: prices, delivery points and replies | — | | `favelas.lua` | Capture times, ownership, limits, bench type and blip | `enabled = true` | | `graffiti.lua` | Items, cooldowns, lifetime, loyalty, experience, size and forbidden surfaces | `disabled = false` | | `helipad.lua` | Helipads | `Disable = false` | | `hostageControl.lua` | NPC hostage menu, follow behaviour and animations | — | | `interactionMenu.lua` | Ranges of each action on a player, blocked controls and handcuff presets | — | | `missions.lua` | Mission catalogue: text, experience, reward and conditions | — | | `moneyLaundry.lua` | Office, van, stops, amount per stop and commission | `Disable = false` | | `mulas.lua` | Mule slots, recruiting, trust, contract limits and step command | `Disable = false` | | `ports.lua` | Ports and their NPC | `Disable = false` | | `racketeering.lua` | Cooldown, experience and blip of collection points | — | | `raids.lua` | Police raids: jobs, schedule, cooldowns, what can be seized | `enable = false` | | `supply.lua` | Cartel supply points: stock, passive sales, robbery and seizure | `enabled = true` | In `airdrop.lua`, `startCommand` and `testCommand` are `{ enabled, name, permission }`. `permission` is the framework permission each command requires, `'admin'` by default, checked through `cuxial_bridge`. {% hint style="warning" %} In `drugselling.lua` the `drugs` table is an allow-list: an item that is not in it cannot be sold, and its price always comes from that table. {% endhint %} ## Common changes ### Open the tablet with an item {% code title="shared/config.lua" %} ```lua tablet = { asItem = true, item = 'crime_tablet', -- ... }, ``` {% endcode %} The command stops existing. Add the item to your inventory as shown in [Installation](/scripts/gangs/cuxial-gang/installation.md). ### Enable police raids {% code title="data/raids.lua" %} ```lua enable = true, allowedJobs = { police = { minimumGradeToStart = 2 }, }, requireDuty = true, ``` {% endcode %} ### Change the staff permission {% code title="shared/config.lua" %} ```lua admin = { ace = 'gangadmin', }, ``` {% endcode %} {% code title="server.cfg" %} ```cfg add_ace group.admin gangadmin allow ``` {% endcode %} Also review `commands.*.restricted` so the group that sees each command matches. ### Set the drugs and prices of your server {% code title="data/drugselling.lua" %} ```lua drugs = { joint = 35, weed_brick = 60, }, ``` {% endcode %} ### Change the money format {% code title="shared/config.lua" %} ```lua currency = { currency = 'EUR', style = 'currency', format = 'es-ES' }, ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cuxial.com/scripts/gangs/cuxial-gang/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.