> 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/jobs/cuxial-diving/configuration.md). # Configuration Every option of Cuxial Diving explained: config, regions, loot, market, gear and progression. Behaviour lives in `shared/config.lua`; regions, loot, prices, gear and levels live in the files of `data/`. Restart the resource after any change. {% hint style="info" %} Coordinates, the NPC, the regions, the items and the prices that come in these files are examples. Change them to fit your server. {% endhint %} ## General | Option | Type | Default | What it does | | ----------------- | ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | | `debug` | boolean | `false` | Prints traces to the console. Also enabled by setting the convar `cuxial_diving_debug` to `1`. | | `account` | string | `'bank'` | Account used for job payouts, daily rewards and the market. | | `job` | string \| string\[] | `'all'` | Who can do the job. `'all'` = everyone. A job name or a list of job names = only those jobs. | | `logs.convar` | string | `'cuxial_diving_webhook'` | Name of the convar that holds the Discord webhook. With the convar empty, nothing is sent. | | `admin.auditDays` | number | `60` | Days the audit rows are kept. Older rows are deleted once a day. Minimum 1. | ## Interface · `ui` | Option | Type | Default | What it does | | ----------------- | ------------ | ------------ | -------------------------------------------------------------------------- | | `accent` | string (hex) | configurable | Accent colour of the panel. | | `currency.symbol` | string | `'$'` | Currency symbol shown in the panel. | | `currency.locale` | string | `'en-US'` | Number format of the amounts, as a language tag (`'en-US'`, `'es-ES'`...). | ## Job NPC · `npc` The NPC opens the panel and the market. | Option | Type | Default | What it does | | ----------------------------------------- | ------- | ------------------ | --------------------------------------------------------- | | `coords` | vector4 | example | Position and heading of the NPC. | | `model` | string | `'a_m_y_beach_01'` | Ped model. | | `distance` | number | `2.0` | Metres from which the interaction is offered. | | `menuDistance` | number | `6.0` | Metres beyond which the server refuses to open the panel. | | `spawnDistance` | number | `60.0` | Metres within which the ped exists for a player. | | `blip.enabled` | boolean | `true` | `true` shows the job blip on the map. `false` hides it. | | `blip.sprite`, `blip.color`, `blip.scale` | number | `317`, `3`, `0.55` | Look of the blip. | ## Interaction · `target` | Option | Type | Default | What it does | | --------------- | --------- | -------------------- | ----------------------------------------------------------------------------------- | | `distance` | number | `3.0` | Metres from a piece to interact with it. | | `showDistance` | number | `35.0` | Metres within which a marker is drawn above each pending piece. `0` = no marker. | | `marker.type` | number | `2` | Marker type of the game. | | `marker.scale` | number | `0.5` | Size of the marker. | | `marker.height` | number | `0.8` | Metres above the top of the piece. | | `marker.color` | number\[] | configurable | Colour as `{ r, g, b, alpha }`. | | `marker.bob` | boolean | `true` | `true` makes the marker move up and down. | | `marker.rotate` | boolean | `true` | `true` makes the marker spin. | | `icons` | table | Font Awesome classes | Icon of each interaction: `menu`, `coral`, `trash`, `open`, `loot`, `bag`, `raise`. | ## Blips · `blips` | Option | Type | Default | What it does | | -------------- | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------ | | `boat` | table | `sprite 529`, `color 0`, `scale 0.8` | Blip of the work boat. | | `deliver` | table | `sprite 410`, `color 2`, `scale 0.9` | Blip of the drop-off point. | | `area` | table | `color 77`, `alpha 90` | Circle that marks the radius of each task zone. | | `tasks` | table | one entry per task | Blip of each task: `coral`, `trash`, `suitcase`, `box`, each with `sprite`, `color` and `scale`. | | `siteDistance` | number | `250.0` | Metres within which the pieces of a zone exist for a player. | ## Crew · `crew` | Option | Type | Default | What it does | | ------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `maxPlayers` | number | `4` | Maximum crew size. | | `inviteDistance` | number | `8.0` | Metres between the owner and the invited player. | | `inviteSeconds` | number | `60` | Seconds until an invite expires. Minimum 5. | | `reconnectSeconds` | number | `180` | Seconds a seat is kept for a player who disconnects during a job. `0` = removed from the crew at once. | | `splitRewards` | boolean | `true` | `true` lets the owner share the money by percentage from the panel. `false` hides that option. Experience is never shared this way. | ## Job · `run` | Option | Type | Default | What it does | | ------------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------- | | `cooldownHours` | number | `0` | Hours a player must wait between jobs, counted from the start of the last one. `0` = no wait. | | `soloHalf` | boolean | `true` | `true` halves the required tasks (corals and trash) for a crew of one. `false` keeps the full amount. | | `spawnFreeRadius` | number | `10.0` | Metres around a spawn point that must be free of vehicles for the boat to appear there. | | `exclusiveRegions` | boolean | `false` | `false` lets several crews work in the same region. `true` allows one crew per region. | ## Screen fade · `fade` Used when a player is moved to the boat or back to the NPC. | Option | Type | Default | What it does | | -------- | ------ | ------- | ------------------------------------------------------------ | | `outMs` | number | `600` | Milliseconds of fade out. | | `holdMs` | number | `1500` | Milliseconds the screen stays black. | | `inMs` | number | `800` | Milliseconds of fade in. | | `maxMs` | number | `15000` | Safety limit. The screen never stays black longer than this. | ## Boarding · `board` | Option | Type | Default | What it does | | ------------------- | ------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `seat` | boolean | `true` | `true` seats each member in a free seat, the owner at the wheel. `false` leaves them standing on deck. | | `deckOffset` | vector3 | `vec3(0.0, 0.0, 2.0)` | Position on deck, relative to the boat, when there is no free seat or `seat = false`. | | `timeoutMs` | number | `8000` | Maximum wait for the boat to exist for the player. Minimum 1000. | | `reconnectDistance` | number | `100.0` | A player who reconnects is placed on the boat only when farther than this, in metres. | | `returnToNpc` | boolean | `true` | `true` takes a player back to the NPC when the job ends while they are in the water or on the boat. `false` leaves them where they are. | | `npcOffset` | number | `1.5` | Metres in front of the NPC where the player is placed. | ## Work boat · `boat` | Option | Type | Default | What it does | | ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `model` | string | `'tug'` | Boat model. | | `plate` | string | `'DIVE'` | Plate prefix, up to four characters. The job number completes it. | | `fuel` | number | `100.0` | Fuel level set on the boat when it spawns. | | `keys` | boolean | `true` | `true` gives the keys to the crew through `cuxial_garages` when that resource is running. `false` never gives keys. | | `spawnTimeoutMs` | number | `5000` | Maximum wait for the boat to be created. | ## Dive site · `site` The pieces of a task are placed when a crew member gets close to it. | Option | Type | Default | What it does | | ------------------ | ------ | ------- | ----------------------------------------------------------------------------------- | | `spawnRadius` | number | `150.0` | Metres from the centre of a task at which its pieces are generated. | | `maxDepthDelta` | number | `40.0` | Metres below the centre of the task where pieces are still accepted. | | `surfaceZ` | number | `0.0` | Height of the sea surface. Pieces must be below it. | | `minSeparation` | number | `2.0` | Minimum metres between two pieces. | | `requestTimeoutMs` | number | `20000` | Milliseconds a player has to answer with the positions before another one is asked. | | `maxAttempts` | number | `3` | Failed attempts per player before the request goes to another crew member. | | `watchMs` | number | `1000` | Milliseconds between proximity checks. Minimum 250. | ## Collecting · `collect` | Option | Type | Default | What it does | | ------------- | ------ | ----------- | --------------------------------------------------------------------------------- | | `maxDistance` | number | `4.0` | Metres from the piece that the server accepts. | | `progressMs` | table | `2800` each | Duration in milliseconds of each action: `coral`, `trash`, `open`, `loot`, `bag`. | | `marginMs` | number | `500` | Tolerance in milliseconds when the server checks those durations. | | `beginTtlMs` | number | `15000` | Milliseconds after which a started action expires. | ## Suitcases · `suitcase` | Option | Type | Default | What it does | | -------- | ------ | ---------------- | ------------------------------------------------------------------------------------ | | `weapon` | string | `'WEAPON_KNIFE'` | Weapon the player must hold to open a suitcase. `'WEAPON_UNARMED'` = no requirement. | ## Boxes · `boxes` | Option | Type | Default | What it does | | ----------------- | ------ | ------------------------- | ------------------------------------------------ | | `liftbagItem` | string | `'liftbag'` | Item spent when a lift bag is attached to a box. | | `liftbagModel` | string | `'cuxial_diving_liftbag'` | Lift bag model, from `cuxial_diving_assets`. | | `liftbagFallback` | string | `'prop_byard_float_02'` | Model used when the main one is not available. | | `oxygenCost` | number | `2` | Oxygen points spent when attaching a lift bag. | | `surfaceZ` | number | `0.5` | Height at which a raised box floats. | | `deckSlots` | number | `48` | Boxes that fit on deck. | ## Rope · `tow` The player throws the rope from the boat, seated or standing on deck, with the anchor down. | Option | Type | Default | What it does | | ------------- | ------ | ------- | ------------------------------------------------------------- | | `maxDistance` | number | `40.0` | Maximum metres between the boat and the floating box. | | `deckRadius` | number | `7.0` | Metres from the boat within which a player counts as on deck. | | `speed` | number | `5.0` | Speed of the box while it is pulled, in metres per second. | | `ropeType` | number | `5` | Rope type of the game. | ## Delivery · `deliver` | Option | Type | Default | What it does | | -------- | ------ | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `radius` | number | `15.0` | Metres from the drop-off point of the region at which the boat can be delivered. The player must be seated in the boat. | ## Payout · `reward` and `loot` | Option | Type | Default | What it does | | ---------------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reward.mode` | string | `'full'` | How the money of the region is paid. `'full'` = the full reward to every member. `'split'` = the reward divided by the crew size. `'bonus'` = the full reward plus `bonusPerExtra` for each extra member. | | `reward.bonusPerExtra` | number | `0.25` | Extra share per additional member in `'bonus'` mode. `0.25` = +25 %. | | `loot.boxTo` | string | `'tower'` | Who receives the loot of a box. `'tower'` = the player who threw the rope. `'deliverer'` = the player who delivers the boat, all at once. `'rotate'` = connected members in turns. | The crew size counts every member, connected or not. Members who are disconnected at delivery receive nothing. Experience is always paid in full to each connected member. ## Gear · `gear` | Option | Type | Default | What it does | | ------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------- | | `consumeMask` | boolean | `false` | `false` keeps the mask in the inventory after using it. `true` removes it. Tanks are always spent. | | `requireRun` | boolean | `true` | `true` allows the gear only during a job. `false` allows it at any time. | | `confirmMs` | number | `10000` | Milliseconds the game has to finish putting the gear on. After that the item is returned. Minimum 1000. | ## Market · `market` | Option | Type | Default | What it does | | --------------- | ------- | ------- | -------------------------------------------------------------------------------------- | | `maxDistance` | number | `15.0` | Metres from the NPC within which buying and selling is accepted. | | `maxAmount` | number | `100` | Maximum units per operation. | | `sellValuables` | boolean | `true` | `false` removes from the sell list the entries marked `valuable` in `data/market.lua`. | ## Outfit · `outfit` | Option | Type | Default | What it does | | ------ | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | string | `'wetsuit'` | Clothes worn during the job, from `data/outfits.lua`. `'wetsuit'` = wetsuit. `'classic'` = the alternative set of that file. `'none'` = the player keeps their own clothes. | The outfit is applied when the job starts and the player's own clothes come back when it ends. It only applies to the freemode male and female models. ## Ranking, history and profile | Option | Type | Default | What it does | | -------------------------- | ------ | ------- | -------------------------------------------------------------------------------------------------------- | | `leaderboard.size` | number | `10` | Entries in each ranking. From 1 to 50. | | `leaderboard.cacheSeconds` | number | `60` | Seconds the ranking is kept before it is read again from the database. | | `history.size` | number | `10` | Jobs shown in a player's history. From 1 to 50. | | `profile.flushMs` | number | `30000` | Milliseconds between saves of experience and daily progress. Money is always paid at once. Minimum 5000. | ## Commands · `commands` | Option | Type | Default | What it does | | -------------------------------- | --------------- | -------------------------------- | ----------------------------------------------------------------------- | | `gear.name` | string \| false | `'divinggear'` | Name of the command that takes the gear off. `false` disables it. | | `reset.name` | string \| false | `'divingreset'` | Name of the command that resets the job. `false` disables it. | | `list.name`, `list.restricted` | string | `'divinglist'`, `'group.admin'` | Name of the command that lists crews and the group allowed to use it. | | `close.name`, `close.restricted` | string | `'divingclose'`, `'group.admin'` | Name of the command that closes a crew and the group allowed to use it. | | `fast.name`, `fast.restricted` | string | `'divingfast'`, `'group.admin'` | Name of the debug command and the group allowed to use it. | See [Commands & permissions](/scripts/jobs/cuxial-diving/commands.md) for what each one does. ## Keys and on-screen help | Option | Type | Default | What it does | | ---------------- | ------ | -------- | ---------------------------------------------------------------------------- | | `keys.anchor` | string | `'H'` | Default key to drop or raise the anchor. | | `keys.interact` | string | `'E'` | Default key to deliver the boat, throw the rope and close the final summary. | | `keys.accept` | string | `'Y'` | Default key to accept an invite. | | `keys.decline` | string | `'N'` | Default key to decline an invite. | | `keys.tipHide` | string | `'BACK'` | Default key to hide a tip. | | `tips.seconds` | number | `12` | Seconds a first-time tip stays on screen. Minimum 3. | | `finish.seconds` | number | `15` | Seconds the final summary stays on screen. Minimum 3. | {% hint style="info" %} These keys are only defaults. Each player can rebind them in the GTA settings, under key bindings for FiveM. {% endhint %} ## Regions · `data/regions.lua` Each entry is a region the crew can pick. | Field | Type | What it does | | ---------- | ---------- | -------------------------------------------------------------------------------------- | | `id` | number | Stable number of the region. It is saved in the database: do not reuse or renumber it. | | `label` | string | Locale key with the name of the region. It must start with `region_`. | | `minLevel` | number | Minimum level that every member of the crew must have. | | `reward` | table | `{ money, xp }` per member. `reward.mode` decides how the money is paid. | | `tasks` | table\[] | Tasks of the region. See below. | | `spawns` | vector4\[] | Spawn points of the boat. The first free one is used. | | `deliver` | vector3 | Drop-off point of the boat. | Fields of each task: | Field | Type | What it does | | --------- | ------- | ----------------------------------------------------------------------------------------- | | `kind` | string | `'coral'`, `'trash'`, `'suitcase'` or `'box'`. | | `amount` | number | Number of pieces. | | `radius` | number | Radius in metres of the zone where the pieces appear. | | `center` | vector3 | Centre of the zone, on the seabed. | | `counted` | boolean | `true` = the task must be completed to deliver the boat. Without it the task is optional. | {% code title="data/regions.lua" %} ```lua { id = 5, label = 'region_reef', minLevel = 15, reward = { money = 5000, xp = 900 }, tasks = { { kind = 'coral', amount = 25, radius = 40.0, center = vec3(0.0, 0.0, -30.0), counted = true }, { kind = 'trash', amount = 25, radius = 40.0, center = vec3(0.0, 0.0, -30.0), counted = true }, { kind = 'suitcase', amount = 10, radius = 40.0, center = vec3(0.0, 0.0, -30.0) }, }, spawns = { vec4(0.0, 0.0, 0.5, 90.0), }, deliver = vec3(0.0, 0.0, 0.5), }, ``` {% endcode %} Replace the coordinates with real ones and add the key of `label` to `locales/en.json` and to the other locale files you use. ## Loot · `data/loot.lua` Three tables: `coral` (each coral cut), `suitcase` (each suitcase looted) and `box` (each box loaded on the boat). | Field | Type | What it does | | ------------ | ------ | ---------------------------------------------------------- | | `item` | string | Item name in your inventory. | | `chance` | number | Relative weight. The weights do not need to add up to 100. | | `min`, `max` | number | Amount given, picked at random between both. | ## Market · `data/market.lua` | Field | Type | What it does | | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `buy` | table\[] | What the NPC sells: `{ item, price }`. | | `sell` | table\[] | What the NPC buys: `{ item, price, valuable }`. Entries with `valuable = true` disappear with `market.sellValuables = false`. | Prices are per unit, in the account set in `account`. The name and the picture of each item come from your inventory. ## Gear · `data/gear.lua` | Field | Type | Default | What it does | | -------------- | -------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `tubes` | table\[] | three tanks | Tanks, in level order. Each one has `item` (usable item), `model` (prop on the back) and `seconds` (seconds underwater per oxygen point). | | `oxygen` | number | `100` | Oxygen points of a full tank. | | `lowOxygen` | number | `20` | Percentage at which the low oxygen warning appears. | | `mask.item` | string | `'scuba_gear'` | Item of the mask. | | `mask.model` | string | `'p_d_scuba_mask_s'` | Prop of the mask. | | `tank`, `mask` | table | | Bone, `offset` and `rotation` of each prop on the player. | | `underwaterMs` | number | `50000` | Time the player can stay underwater with oxygen left, as used by the game. | | `emptyMs` | number | `10` | The same value once the oxygen runs out. | | `equipMs` | number | `2000` | Milliseconds of the animation when putting the gear on. | | `anim` | table | | Animation played while putting the gear on. | With the default values a full tank lasts 5:00, 8:20 and 11:40 minutes underwater. Oxygen is only spent while the player swims underwater. ## Daily tasks · `data/daily.lua` | Field | Type | Default | What it does | | ------------ | -------- | ----------- | ------------------------------------------------------------------------------------ | | `resetHours` | number | `24` | Hours after which a player's daily tasks start again, counted from their last reset. | | `tasks` | table\[] | three tasks | Daily tasks. Fields below. | | Field | Type | What it does | | ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Stable key of the task. It is saved in the database. | | `label` | string | Locale key with the name. | | `kind` | string | What it counts. `'coral'` = corals cut. `'trash'` = trash collected. `'runs'` = jobs delivered. `'money'` = money earned from jobs. `'team'` = jobs delivered with a crew of two or more. | | `goal` | number | Amount to reach. | | `xp`, `money` | number | Reward on completion. | ## Levels · `data/levels.lua` `required` is the list of experience needed to go from each level to the next. Players start at level 1 and the maximum level is the number of entries plus one: 71 with the default file. ## Outfits and props · `data/outfits.lua`, `data/pieces.lua` `data/outfits.lua` holds the clothes of each outfit mode, for male and female: `components` as `{ component, drawable, texture }` and `props` as `{ prop, drawable, texture }`, where a drawable of `-1` removes the prop. Adjust the numbers to the clothing of your server. `data/pieces.lua` holds the models of the corals, trash, suitcases and boxes, the animation of each action and the layout of the boxes on deck. Change it only if you want other props. ## Common changes ### Limit the job to certain jobs {% code title="shared/config.lua" %} ```lua job = { 'lifeguard', 'diver' }, ``` {% endcode %} ### Split the reward between the crew {% code title="shared/config.lua" %} ```lua reward = { mode = 'split', bonusPerExtra = 0.25 }, ``` {% endcode %} ### Open suitcases without a knife {% code title="shared/config.lua" %} ```lua suitcase = { weapon = 'WEAPON_UNARMED' }, ``` {% endcode %} ### Let players use the gear outside a job {% code title="shared/config.lua" %} ```lua gear = { consumeMask = false, requireRun = false, confirmMs = 10000, }, ``` {% endcode %} ### Add a wait between jobs {% code title="shared/config.lua" %} ```lua run = { cooldownHours = 2, soloHalf = true, spawnFreeRadius = 10.0, exclusiveRegions = false, }, ``` {% 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/jobs/cuxial-diving/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.