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, service fleet vehicles, distance-based payouts, leveling progression tiers, and the task minigame registry.

⚙️ Core Bridges & Settings

return {
  framework = 'qbx', -- Supported: 'qb', 'qbx', 'esx'
  notify = 'ox_lib', -- Supported: 'bs-advnotifications', 'esx', 'mythic_notify', 'okokNotify', 'ox_lib', 'pNotify', 'qb', 'qbx'
  interaction = 'ox_target', -- Supported: 'qb-target', 'ox_target'
  vehicleKeys = 'qb-vehiclekeys', -- Supported: 'qb-vehiclekeys', 'qbx_vehiclekeys', 'qs-vehiclekeys'
 
  jobName = false, -- false for open public job, or string like 'roadmaintenance' to restrict to hired players

framework: Determines which framework bridge from bridge/framework/ to initialize ('qbx', 'qb', or 'esx').
notify: Selects your server's notification system. Compatible with bs-advnotifications, ox_lib, esx, qb, qbx, mythic_notify, okokNotify, or pNotify.
interaction: Selects your target system ('ox_target' or 'qb-target').
vehicleKeys: Automatically distributes vehicle keys to all active lobby crew members when service vehicles are spawned.
jobName: If false, any citizen can access the base NPC and start working. If set to a job string (e.g. 'roadmaintenance'), only players with that job role can talk to the supervisor or open the job dashboard.

⌨️ Commands & Keybinds

  binds = {
    dashboard = {
      key = 'F7',
      label = 'Open Job Dashboard',
    },
    toggleTasks = {
      key = 'F6',
      label = 'Toggle Road Maintenance Tasks',
    },
  },
 
  areaManagerCommand = 'roadtaskmanager',
  bonusManagerCommand = 'roadbonusmanager',

binds.dashboard: Default key (default: F7) to toggle the NUI job dashboard tablet.
binds.toggleTasks: Default key (default: F6) to toggle the on-screen active task checklist HUD during an active route.
areaManagerCommand: Administrative command to manage work areas and launch the 3D Task Creator (default: /roadtaskmanager). Requires the roadmaintenancejob.admin ACE permission.
bonusManagerCommand: Administrative command to trigger instant or scheduled payout multipliers (default: /roadbonusmanager). Requires the roadmaintenancejob.admin ACE permission.

🏢 Base Headquarters

  base = {
    blip = {
      sprite = 801,
      color = 47,
      scale = 0.8,
      label = 'Road Maintenance'
    },
    ped = {
      model = 's_m_y_dockwork_01',
      coords = vector4(864.89, -2429.71, 27.13, 171.74),
    },

base.blip: Controls the map blip displayed for the headquarters (sprite 801, orange color 47).
base.ped: Controls the supervisor NPC spawned at the headquarters dockyard. Players target this NPC to open the dashboard or clock out to receive payouts.

🚚 Fleet Vehicles & Spawn Points

    vehicles = {
      models = {
        {
          model = 'boxville',
          label = 'Brute Boxville',
          requiredLevel = 1,
          colours = { primary = 111, secondary = 111 },
          livery = 2,
          extras = {},
        },
        {
          model = 'utillitruck3',
          label = 'Utility Truck',
          requiredLevel = 2,
          colours = { primary = 111, secondary = 111 },
          livery = 0,
          extras = {},
        },
        {
          model = 'bison3',
          label = 'Bravado Bison',
          requiredLevel = 3,
          colours = { primary = 111, secondary = 111 },
          livery = 0,
          extras = {},
        },
      },
      spawnCoords = {
        vec4(880.5, -2437.72, 27.13, 358.18),
        vec4(876.96, -2437.66, 27.28, 358.55),
        vec4(873.21, -2437.61, 27.24, 359.94),
        vec4(869.62, -2437.6, 27.13, 0.83),
      },
    },
  },

models: Defines the vehicle fleet unlocked by player/crew level. Includes bundled liveries streamed directly from the resource.
requiredLevel: Level required to spawn that vehicle model tier.
spawnCoords: List of parking bays at the base headquarters. The server checks clearance within spawnClearRadius (default: 2.5m) before spawning vehicles.
Multi-Vehicle Spawning: When a crew has 3 or more players, the server automatically spawns 2 service vehicles simultaneously.

👥 Lobby & Job Settings

  lobby = {
    inviteCooldown = 5, -- Cooldown in seconds between sending invites
  },
 
  job = {
    spawnClearRadius = 2.5, -- Radius to check if a vehicle parking spot is blocked
    distancePay = {
      enabled = true,
      minDistance = 250.0, -- Distance (m) where payout bonus starts
      maxDistance = 3500.0, -- Distance (m) where payout bonus reaches cap
      maxBonus = 0.45, -- Max extra payout from distance (0.45 = +45%)
    },
  },

lobby.inviteCooldown: Prevents invite spam by requiring 5 seconds between invitations.
job.spawnClearRadius: The radius around spawn points checked for obstructions (parked cars, props) before spawning work vehicles.

📍 Distance Pay Bonus

The Distance Pay System automatically rewards crews with higher payouts when assigned to remote work areas across San Andreas:

Parameter	Default	Description
`enabled`	`true`	Enables or disables the distance pay multiplier calculation
`minDistance`	`250.0`	Minimum distance in meters from base before distance bonus begins
`maxDistance`	`3500.0`	Distance in meters at which the distance bonus reaches its upper limit
`maxBonus`	`0.45`	Maximum bonus percentage added to the task payout (`0.45` = +45%)

Payout Calculation Formula:

Final Task Payout = basePayment * levelMultiplier * (1 + distanceBonus) * globalBonusMultiplier

📈 Levels & Multipliers

  levels = {
    {
      requiredExp = 0,
      payMultiplier = 1.0,
    },
    {
      requiredExp = 2200,
      payMultiplier = 1.1,
    },
    {
      requiredExp = 6000,
      payMultiplier = 1.22,
    },
  },

Level	Required XP	Pay Multiplier	Unlocked Vehicle
Level 1	`0 XP`	`1.00x`	Brute Boxville
Level 2	`2,200 XP`	`1.10x` (+10%)	Utility Truck
Level 3	`6,000 XP`	`1.22x` (+22%)	Bravado Bison

🛠️ Tasks Registry (`tasks`)

The tasks table defines the core parameters, rewards, UI texts, icons, controls, and tutorial videos for all 8 minigames:

  tasks = {
    ['replace_sign'] = {
      label = 'Replace Road Sign',
      description = 'Remove the damaged road sign and mount the replacement securely.',
      exp = 30,
      payment = 65,
      -- UI configuration, icons, steps, controls, and video tutorials...
    },
    ['paint_lines'] = {
      label = 'Paint Road Lines',
      description = 'Repaint faded lane markings to restore clear road guidance.',
      exp = 35,
      payment = 75,
    },
    ['repair_traffic_light'] = {
      label = 'Repair Traffic Light',
      description = 'Open the control panel, complete the repair sequence, and secure it again.',
      exp = 40,
      payment = 92,
    },
    ['clean_oil'] = {
      label = 'Clean Oil Spill',
      description = 'Use the broom to clean up the oil spills on the road.',
      exp = 25,
      payment = 58,
    },
    ['clean_graffiti'] = {
      label = 'Clean Graffiti',
      description = 'Move the sponge over the graffiti to clean it.',
      exp = 30,
      payment = 70,
    },
    ['clear_rocks'] = {
      label = 'Clear Rocks',
      description = 'Drag the rocks to the highlighted zone.',
      exp = 40,
      payment = 86,
    },
    ['scan_road'] = {
      label = 'Scan Road',
      description = 'Start the scanner in the service vehicle and detect road issues before time runs out.',
      exp = 45,
      payment = 104,
    },
    ['scan_bridge'] = {
      label = 'Scan Bridge Durability',
      description = 'Calibrate the scanner and complete each bridge integrity scan.',
      exp = 40,
      payment = 81,
    }
  }

Task Reward Defaults Summary:

Task Identifier	Display Label	Default EXP	Base Payout
`replace_sign`	Replace Road Sign	`30 XP`	`$65`
`paint_lines`	Paint Road Lines	`35 XP`	`$75`
`repair_traffic_light`	Repair Traffic Light	`40 XP`	`$92`
`clean_oil`	Clean Oil Spill	`25 XP`	`$58`
`clean_graffiti`	Clean Graffiti	`30 XP`	`$70`
`clear_rocks`	Clear Rockslide	`40 XP`	`$86`
`scan_road`	Scan Road Condition	`45 XP`	`$104`
`scan_bridge`	Scan Bridge Durability	`40 XP`	`$81`

BS Business Tablet

Shared Configuration (sh_config.lua)