Configuration

All gameplay tuning lives in config.lua. The file is listed under escrow_ignore in fxmanifest.lua, so it remains fully editable on escrow-protected builds.

Oxygen

Config.Oxygen controls the surface/dive economy:

Config.Oxygen = {
    drainInterval   = 5000,   -- ms between drain ticks underwater
    drainAmount     = 2,      -- oxygen lost per tick (out of maxOxygen)
    warningThreshold = 25,    -- % at which the low-oxygen toast fires
    damageInterval  = 3000,   -- ms between health-damage ticks at 0 oxygen
    damageAmount    = 10,     -- HP lost per damage tick
    refillTime      = 20000,  -- ms duration of the refill / equip progress bar
    maxOxygen       = 200,    -- ceiling for tank oxygen
}

Tank durability

Config.Tank controls how many refills a tank can take before it breaks, plus the scuba clothing visual.

Config.Tank = {
    maxDurability = 10,             -- refills before the tank breaks
    itemName      = 'scuba_tank',   -- ox_inventory item name
    refillItem    = 'tank_refill',  -- ox_inventory refill cartridge
    clothing = {
        component = 8,              -- ped component slot (8 = undershirt)
        male   = { drawable = 151, texture = 0 },
        female = { drawable = 187, texture = 0 },
    },
}

The defaults assume a vanilla GTA V ped clothing index. If your server uses a custom clothing system (illenium-appearance, fivem-appearance, qb-clothing), repoint component, drawable, and texture to whichever slot/asset shows the scuba harness on your peds.

Crates

Config.Crates controls density, the four crate tiers, the lockpick minigame, and the loot tables.

Config.Crates = {
    respawnTimer = 3600,    -- seconds; armed when first crate in a zone is searched
    minPerZone   = 35,
    maxPerZone   = 50,
    minDepth     = -5.0,    -- only spawn at this depth or deeper
    types        = { ... }, -- 4 tiers (regular / medical / locked / rare)
    lockpickMinigame = { ... },
    lootTables       = { ... },
}

Crate types

Tier	Model	Required item	Open mechanic	Spawn weight	Loot count
Regular	`sm_prop_smug_crate_s_bones`	—	Free open	40	2–4
Medical	`sm_prop_smug_crate_s_medical`	`WEAPON_CROWBAR`	Crowbar pry	25	2–3
Locked	`sm_prop_smug_crate_s_jewellery`	`diving_pick`	Lockpick + minigame (`easy, easy, medium`)	20	3–5
Rare	`sm_prop_smug_crate_s_tobacco`	`diving_pick`	Lockpick + minigame (`medium, medium, hard`) — failure destroys the crate	15	3–6

The lockpickMinigame table maps each tier to an ox_lib skill check. Adjust difficulty arrays or key sets per tier:

lockpickMinigame = {
    medical = { difficulty = { 'easy', 'easy' },                keys = { 'w', 'a', 's', 'd' } },
    locked  = { difficulty = { 'easy', 'easy', 'medium' },      keys = { 'w', 'a', 's', 'd' } },
    rare    = { difficulty = { 'medium', 'medium', 'hard' },    keys = { 'w', 'a', 's', 'd' } },
}

Loot tables

lootTables has one entry per tier. Each entry is a list of { item, min, max, chance } rolls, evaluated independently — so multiple lines can hit on a single crate. Default tables ship items from the bundled items.lua (jewelry, medical, crafting materials, drugs, heist tools). Replace freely if you swap or rebrand items.

Zones

Config.Zones ships seven pre-scouted dive zones. Each zone has a center, blip settings, and a list of pre-recorded ocean-floor spawnPoints (35–50 each).

Name	Label	Center
Paleto Wreck	Paleto Bay Shipwreck	`-1259.05, 6109.2, -13.59`
Procopio Beach	Procopio Beach Diving	`1189.39, 6782.99, -9.6`
Chumash Reef	Chumash Reef	`-2967.19, 2455.11, -7.01`
East Deep	Eastern Deep Waters	`3631.4, 5272.73, -4.16`
Vespucci Shallows	Vespucci Beach Waters	`-2000.0, -1200.0, -18.0`
Pacific South	Pacific Ocean South	`1750.95, -3013.3, -46.67`
Pacific East	Pacific Ocean East	`2872.13, -1799.35, -3.13`

⚠️

These coordinates target the standard GTA V coastline. If you run a custom map (LS Tuners shoreline, modded islands, or a non-Los Santos map), re-scout each zone — the script ships a /divinggenerate debug command that auto-samples the ocean floor and a /divingmark / /divingdump workflow for hand-picking points. See Troubleshooting.

Each zone takes the shape:

{
    name        = 'Paleto Wreck',
    label       = 'Paleto Bay Shipwreck',
    center      = vec3(-1259.05, 6109.2, -13.59),
    radius      = 120.0,
    blipSprite  = 478,
    blipColor   = 3,
    spawnPoints = { vector3(...), vector3(...), ... },
}

Boat rental

Config.Boat plus Config.DiveNPC define the rental NPC, the boat model, the spawn/return points, and persistence.

Config.Boat = {
    model       = 'dinghy',
    price       = 500,
    spawnPoint  = vec4(-800.43, -1499.13, -0.88, 113.16), -- in water
    returnPoint = vec3(-805.13, -1499.93, 0.12),
    returnRadius = 15.0,
 
    persistence = {
        enabled      = true,
        saveInterval = 30,    -- seconds between auto-saves of boat position
        maxAge       = 7200,  -- seconds before an abandoned boat is auto-deleted
    },
}

With persistence.enabled = true boats survive disconnects and full server restarts, and the player keeps the same boat. After maxAge seconds without the owning player online, the boat is reaped from diving_boats and deleted.

Shop and dive NPC

Config.Shop is registered as a standard Ox Inventory shop. Config.DiveNPC defines the single ped that exposes the shop and the boat rental via ox_target.

Config.Shop = {
    name  = 'diving_shop',
    label = 'Dive Shop',
    items = {
        { name = 'scuba_tank',     price = 2500 },
        { name = 'tank_refill',    price = 250 },
        { name = 'WEAPON_CROWBAR', price = 500 },
        { name = 'diving_pick',    price = 750 },
    },
}
 
Config.DiveNPC = {
    ped = {
        model    = 's_m_y_dockwork_01',
        coords   = vec4(-807.24, -1497.67, 0.6, 291.0),
        scenario = 'WORLD_HUMAN_CLIPBOARD',
    },
}

Hazards

Config.Hazards ships three hazard types. All are tunable per-zone.

Hazard	Effect	Default count
Currents	Push the diver in a direction; multiply oxygen drain when swimming against them	2 zones
Low visibility	Apply fog density to a sphere underwater	2 zones
Sharks	Spawn `a_c_sharktiger` / `a_c_sharkhammer` patrols that aggro and attack	2 zones, disabled by default

Config.Hazards = {
    currents = {
        { center = vector3(-1380.0, 6530.0, -28.0), radius = 40.0,
          direction = vector3(1.0, 0.0, 0.0), strength = 2.0,
          oxygenDrainMultiplier = 1.5 },
        ...
    },
    lowVisibility = {
        { center = vector3(3176.0, -1920.0, -60.0), radius = 80.0, fogDensity = 0.5 },
        ...
    },
    sharks = {
        enabled        = false,
        aggroRange     = 15.0,
        attackDamage   = 25,
        attackCooldown = 5000,
        scareItem      = 'WEAPON_CROWBAR',
        zones          = { ... },
    },
}

Set Config.Hazards.sharks.enabled = true to arm shark patrols. The scareItem is the hand-equipped weapon that, when used to hit a shark, drives it off instead of escalating.

Notifications

Every player-facing toast routes through Config.Notifications and uses ox_lib. Edit titles, descriptions, and durations in place — the keys (oxygenLow, tankBroken, crateDestroyed, boatReturned, etc.) are referenced throughout the client and server scripts and must stay intact.

Debug

Set Config.Debug = true to unlock the in-game debug commands. See Troubleshooting for the full list, including /divinggenerate (auto-sample ocean floor for a zone) and /divingmark / /divingdump (record points and copy them to clipboard in vector3(...) format).

Installation Gameplay