Shared Configuration (`sh_config.lua`)

The config/sh_config.lua file is the central configuration file accessible by both the client and the server. It defines framework bridges, base locations, vehicles, route generation rules, progression levels, minigame rewards, and tool upgrades.

⚙️ Core Bridges & Settings

return {
  debug = false, -- Enable verbose color-coded console logs for development
  framework = 'qbx', -- Supported: 'qb', 'qbx', 'esx'
  notify = 'ox_lib', -- Supported: 'ox_lib', 'bs-advnotifications'
  interaction = 'ox_target', -- Supported: 'ox_target', 'qb-target', 'qbx-target'
  clothingBridge = 'illenium-appearance', -- Supported: 'illenium-appearance', 'qb-clothing', 'esx_skin', 'none'
  vehicleKeys = 'qbx_vehiclekeys', -- Supported: 'qb-vehiclekeys', 'qbx_vehiclekeys', 'qs-vehiclekeys'
 
  jobName = false, -- false for open public job, or string like 'oilworker' to restrict to hired players

debug: When true, prints detailed logs with step indices and state changes ([OIL-DEBUG]). Set to false in production.
framework: Determines which framework bridge from bridge/framework/ to load.
clothingBridge: Dictates how workwear outfits are applied when clocking in and restored upon route completion.
vehicleKeys: Automatically distributes vehicle keys to all active lobby members when the work truck is spawned.
jobName: If false, any player can access the job base NPC and open the dashboard. If set to a string (e.g., 'oilworker'), only players with that job role can start routes.

⌨️ Commands & Keybinds

  commands = {
    taskManager = 'oiltaskmanager',   -- In-game site & task creator tool (requires admin ACE)
    bonusManager = 'oilbonusmanager', -- In-game multiplier event manager (requires admin ACE)
  },
 
  binds = {
    dashboard = {
      key = 'F9',
      label = 'Open Job Dashboard',
    },
    toggleTasks = {
      key = 'F6',
      label = 'Toggle Oil Field Tasks',
    },
  },

commands.taskManager: Command to open the administrative site management menu.
commands.bonusManager: Command to manage instant or scheduled global payout bonus multipliers.
binds.dashboard: Default key to toggle the comprehensive NUI job tablet/dashboard.
binds.toggleTasks: Default key to toggle the active task checklist HUD during an active route.

🏢 Base Headquarters & Work Vehicle

  base = {
    ped = {
      model = `s_m_y_construct_01`,
      coords = vec4(1714.21, -1598.33, 112.81, 279.76),
      scenario = 'WORLD_HUMAN_CLIPBOARD',
    },
 
    blip = {
      enable = true,
      sprite = 436,
      color = 5,
      scale = 0.8,
      label = 'Oil Field Job',
      display = 4,
    },
 
    vehicle = {
      model = `nsandstorm2`, -- Or `bscaracara` for default
      colors = {
        primary = 105,
        secondary = 105,
      },
      livery = 3,
      mods = {
        [0] = 21, [1] = 25, [2] = 3, [10] = 0,
        [42] = 0, [44] = 1, [47] = 0, [48] = 3,
      },
      spawnPoints = {
        vec4(1711.18, -1580.68, 111.29, 279.87),
        vec4(1710.41, -1576.29, 111.3, 279.87),
        vec4(1709.47, -1571.63, 111.33, 279.87),
        vec4(1711.0, -1566.21, 111.34, 279.87),
      },
    },
  },

Vehicle Comparison: `bscaracara` vs `nsandstorm2`

Setting	Bundled Default (`bscaracara`)	Custom Modded (`nsandstorm2`)
Model	`bscaracara`	`nsandstorm2`
Primary Color	`105`	`105`
Secondary Color	`105`	`105`
Livery	`0`	`3`
Mods Table	`[0] = 5, [1] = 6, [2] = 1, [48] = 0`	`[0] = 21, [1] = 25, [2] = 3, [10] = 0, [42] = 0, [44] = 1, [47] = 0, [48] = 3`
Source	Included in resource stream files	Download from GTA5-Mods (opens in a new tab) and replace `nsandstorm_livery7.yft`

spawnPoints: Coordinates checked sequentially when spawning the crew vehicle. The script tests each coordinate against job.spawnClearRadius to avoid vehicles spawning on top of each other.

📋 Job Route & Lobby Rules

  job = {
    sitesPerJob = { min = 4, max = 6 }, -- Random number of sites picked per shift
    spawnClearRadius = 3.5,              -- Radius around spawn points checked for obstructions
    taskLoadDistance = 150.0,            -- Distance to stream and cull task props dynamically
  },
 
  lobby = {
    maxMembers = 4,                      -- Maximum workers allowed in a single crew
    inviteCooldown = 5,                  -- Cooldown in seconds between sending lobby invites
  },

sitesPerJob: Specifies how many distinct oilfield sites will be assigned for each route. Can be a table { min = X, max = Y } or a fixed integer.
taskLoadDistance: Culling distance. Objects, sounds, and target zones for a site only spawn when players are within 150m, maximizing client FPS.

🎨 Outlines & Visual Highlights

Configures the engine outline shader used to highlight uncompleted oilfield tasks:

  outlines = {
    color = { r = 255, g = 140, b = 0, a = 200 }, -- Amber / Orange industrial glow
    shader = 1,                                    -- FiveM outline shader ID
    distance = 30.0,                               -- Distance in meters within which outlines activate
  },

🛠️ Tasks & Minigame Rewards

Configure individual base payouts, EXP rewards, and on-screen tutorial/control prompts for each of the 6 minigames:

  tasks = {
    ['drive_bolt']   = { exp = 60, payment = 150, ... }, -- Pipeline Flange Assembly
    ['grind_rust']   = { exp = 50, payment = 120, ... }, -- Rust Removal
    ['turn_valve']   = { exp = 40, payment = 100, ... }, -- Valve Regulation
    ['weld_pipe']    = { exp = 75, payment = 180, ... }, -- Pipeline Welding
    ['cut_pipe']     = { exp = 70, payment = 170, ... }, -- Pipeline Cutting
    ['technicalbox'] = { exp = 90, payment = 220, ... }, -- Technical Box Repair
  },

For each task, you can customize:

exp: Raw EXP granted to the player's account upon completion.
payment: Cash added to the lobby's pending payout pool.
blip: Map icon styling (sprite, color, scale).
ui.tutorial: Text displayed on the NUI help screen.
ui.controls: Keyboard and mouse legends rendered on the screen.

⚡ Tool Upgrades

Players can spend their accumulated character XP and cash in the dashboard's Upgrades tab to permanently improve tool speeds:

Tool Upgrade ID	In-Game Name	Associated Task	Level Multipliers
`grind_rust`	Grinder	Rust Removal	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`
`drive_bolt`	Impact Wrench	Flange Bolt Assembly	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`
`weld_pipe`	Welder	Pipeline Welding	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`
`turn_valve`	Valve Wrench	Valve Regulation	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`
`cut_pipe`	Gas Torch Cutter	Pipeline Cutting	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`
`technicalbox_oil_refill`	Oil Refill Kit	Technical Box Oil Refill	`L1: 1.25x` / `L2: 1.50x` / `L3: 1.75x`

Default Costs per Level:

Level 1: 100 XP + $1,000 Cash (+25% speed)
Level 2: 300 XP + $2,500 Cash (+50% speed)
Level 3: 600 XP + $5,000 Cash (+75% speed)

Configuration Client Configuration

Shared Configuration (sh_config.lua)