Configuration Reference

Config File Map

File	Purpose
shared/config.lua	General settings (debug, phone, menu style, slot limits, shift states, job types)
shared/config/job.lua	Crew, payment, complaints, timer, call dispatch settings
shared/config/levels.lua	Progression level definitions
shared/config/locations.lua	Tow yard locations with NPC and vehicle spawn positions
shared/config/events.lua	All 40 job events with coordinates, vehicle models, and mission times
shared/config/vehicles.lua	Tow truck model and health settings
shared/config/props.lua	Tool props, animations, jack mechanics
shared/config/visuals.lua	NPC models, blips, driver peds, stranded NPC behavior, breakdown visuals, safety zones, cone system, repair effects, waypoints
shared/config/tutorials.lua	Tutorial tooltip definitions
shared/init.lua	Bridge initialization, debug function
server/main.lua	Rate limit configuration

---

General Settings

File: shared/config.lua

Setting	Type	Default	Description
Config.Debug	boolean	false	Enable debug logging with [oxide-roadsideassistancejob] prefix
Config.usePhone	boolean	true	Send shift emails via phone instead of toast notifications
Config.shiftSummary	string	'text'	Shift summary display mode: 'nui' for popup summary screen, 'text' for email summary
Config.menuStyle	string	'nui'	Dispatcher menu style: 'nui' for Vue shift menu with cinematic camera, 'menu' for Bridge.Menu context menu
Config.MaxSlotsPerLocation	number	3	Maximum concurrent shift slots per tow yard location

---

Job Settings

File: shared/config/job.lua

Crew

Setting	Type	Default	Description
Config.Crew.maxSize	number	2	Maximum crew members (leader + partner)
Config.Crew.inviteTimeout	number	60	Seconds before a crew invite expires
Config.Crew.coopBonusPercent	number	0.15	Bonus percentage applied to jobs completed while in a crew (15%)

Payment

Setting	Type	Default	Description
Config.Payment.basePay	table	See below	Base pay per job type
Config.Payment.distanceBonusPerUnit	number	0.30	Bonus per distance unit from accept location to event
Config.Payment.speedBonusAmount	number	25	Flat bonus for completing a job before the timer expires
Config.Payment.vehicleDestroyFine	number	200	Flat fine when the tow truck is destroyed
Config.Payment.streakBonusPerDay	number	10	Bonus added per consecutive daily streak day
Config.Payment.maxStreakDays	number	7	Maximum streak days (caps the streak bonus)
Config.Payment.gasFeePercent	number	0.05	Gas fee as a percentage of gross pay (5%)
Config.Payment.taxPercent	number	0.10	Tax as a percentage of gross pay (10%)

Base Pay by Job Type

Job Type	Base Pay
Fuel Help	$60
Wheel Change	$80
Towing	$100
Battery Change	$70

Config.Payment.basePay = {
    [JobType.FUEL_HELP]      = 60,
    [JobType.CHANGE_WHEEL]   = 80,
    [JobType.TOWING]         = 100,
    [JobType.BATTERY_CHANGE] = 70,
}

Complaints

Setting	Type	Default	Description
Config.Complaints.maxComplaints	number	3	Complaints needed to trigger a suspension
Config.Complaints.timeoutMinutes	number	30	Suspension duration in minutes
Config.Complaints.vehicleDestroyPenalty	number	1	Complaints added when the tow truck is destroyed
Config.Complaints.deathPenalty	number	1	Complaints added when the player dies on shift
Config.Complaints.decayPerJob	number	1	Complaints removed per successful job completion

Timer

Setting	Type	Default	Description
Config.Timer.baseTime	number	90	Base timer in seconds (unused in current formula; events use missionTime)
Config.Timer.timePerDistanceUnit	number	0.20	Additional seconds per distance unit
Config.Timer.extraTime	number	120	Extra time buffer added to mission timer
Config.Timer.expiredPenalty	number	0.85	Payment multiplier when completing after the timer expires (15% penalty)

Calls

Setting	Type	Default	Description
Config.Calls.minIntervalSeconds	number	15	Minimum seconds between dispatch calls
Config.Calls.maxIntervalSeconds	number	45	Maximum seconds between dispatch calls
Config.Calls.responseTimeSeconds	number	30	Seconds to accept/decline a call before it counts as missed
Config.Calls.maxMissedCalls	number	3	Missed/declined calls before automatic clock-out

---

Levels

File: shared/config/levels.lua

Each level is defined as an entry in Config.Levels:

Field	Type	Description
title	string	Locale key for the level title
requiredJobs	number	Total jobs needed to reach this level
payMultiplier	number	Multiplier applied to base pay calculation
tipChance	number	Probability of receiving a tip (0.0–1.0)
tipRange	table	Min/max tip amount { min, max }

Default Levels

Config.Levels = {
    [1] = { title = 'level.trainee',      requiredJobs = 0,   payMultiplier = 1.0,  tipChance = 0.10, tipRange = { 5, 15 }  },
    [2] = { title = 'level.mechanic',     requiredJobs = 15,  payMultiplier = 1.1,  tipChance = 0.15, tipRange = { 5, 20 }  },
    [3] = { title = 'level.senior_tech',  requiredJobs = 40,  payMultiplier = 1.2,  tipChance = 0.25, tipRange = { 10, 30 } },
    [4] = { title = 'level.team_lead',    requiredJobs = 80,  payMultiplier = 1.35, tipChance = 0.30, tipRange = { 10, 40 } },
    [5] = { title = 'level.master_tech',  requiredJobs = 150, payMultiplier = 1.5,  tipChance = 0.40, tipRange = { 15, 50 } },
}

---

Locations

File: shared/config/locations.lua

Each location in Config.Locations defines a complete tow yard:

Field	Type	Description
name	string	Locale key for the location name
coords	vector3	Dispatcher NPC position
heading	number	NPC facing direction
vehicleSpawn	vector4	Tow truck spawn position and heading
menuCamera	table	Camera settings for NUI menu (coords, heading, rotation, fov)

Default Location

The resource ships with one tow yard location near the city.

Config.Locations = {
    {
        name = 'location.tow_yard',
        coords = vector3(2403.55, 3127.90, 48.15),
        heading = 251.85,
        vehicleSpawn = vector4(2394.27, 3120.37, 48.15, 71.61),
        menuCamera = {
            coords = vector3(2410.19, 3131.07, 50.63),
            heading = 150.41,
            rotation = vector3(-15.0, 0.0, 0.0),
            fov = 50.0,
        },
    },
}

---

Events

File: shared/config/events.lua

Each event in Config.Events defines a service call:

Field	Type	Description
type	string	Job type constant (JobType.FUEL_HELP, JobType.CHANGE_WHEEL, JobType.TOWING, JobType.BATTERY_CHANGE)
label	string	Locale key for the event label
missionTime	number	Mission timer in seconds
vehicle	string	GTA vehicle model name for the stranded vehicle
coords	vec4	Spawn position and heading for the stranded vehicle
fuelBone	number	(Fuel help only) Bone index for the fuel cap
deliveryCoords	vec3	(Towing only) Drop-off delivery coordinates
npcDriver	boolean	Whether to spawn an NPC driver in the vehicle

Event Count by Type

Job Type	Events	Mission Time
Fuel Help	10	7 minutes
Wheel Change	10	10 minutes
Battery Change	10	8 minutes
Towing	10	8 minutes

---

Vehicle

File: shared/config/vehicles.lua

Setting	Type	Default	Description
Config.Vehicle.model	string	'towtruck'	Tow truck model name
Config.Vehicle.spawnDistance	number	5.0	Distance threshold for spawn area clearing
Config.Vehicle.healthCheckInterval	number	1000	Milliseconds between health checks
Config.Vehicle.destroyedThreshold	number	150	Engine health below which the truck is considered destroyed
Config.Vehicle.damageChargeRate	number	0.50	Dollar charge per health point below damage threshold
Config.Vehicle.damageChargeThreshold	number	950	Body health below which damage charges apply

---

Props

File: shared/config/props.lua

Tool Props

Each prop in Config.Props defines a tool with vehicle and player attachment configurations:

Prop	Model	Vehicle Bone	Player Bone
jack	imp_prop_car_jack_01a	3 (chassis)	28422 (right hand)
spareWheel	imp_prop_impexp_tire_02c	3 (chassis)	28422 (right hand)
jerryCan	w_am_jerrycan	3 (chassis)	28422 (right hand)
battery	prop_car_battery_01	3 (chassis)	28422 (right hand)

Each prop has vehicleAttach (bone, offset, rotation) and playerAttach (bone, offset, rotation, animDict, animName) sub-tables.

Fuel Animation

Setting	Type	Default	Description
Config.FuelAnimation.duration	number	10000	Refuelling animation duration (ms)
Config.FuelAnimation.dict	string	'weapons@misc@jerrycan@'	Animation dictionary
Config.FuelAnimation.anim	string	'fire'	Animation clip name

Wheel Animation

Setting	Type	Default	Description
Config.WheelAnimation.duration	number	10000	Wheel change animation duration (ms)
Config.WheelAnimation.dict	string	'anim@amb@clubhouse@tutorial@bkr_tut_ig3@'	Animation dictionary
Config.WheelAnimation.anim	string	'machinic_loop_mechandplayer'	Animation clip name

Battery Animation

Setting	Type	Default	Description
Config.BatteryAnimation.duration	number	8000	Battery change animation duration (ms)
Config.BatteryAnimation.dict	string	'mini@repair'	Animation dictionary
Config.BatteryAnimation.anim	string	'fixing_a_player'	Animation clip name

Jack Attach

Setting	Type	Default	Description
Config.JackAttach.bone	string	'chassis'	Vehicle bone the jack attaches relative to
Config.JackAttach.raiseSteps	table	{ 0.01, 0.03, 0.06, 0.09, 0.12, 0.15 }	Incremental Z offsets for vehicle raise
Config.JackAttach.stepTime	number	800	Milliseconds per pump stroke

Wheel Bones

Config.WheelBones maps wheel bone names to GTA tire indices. One is randomly selected at runtime for wheel change jobs:

Bone Name	Tire Index
wheel_lf	0 (front-left)
wheel_rf	1 (front-right)
wheel_lr	2 (rear-left)
wheel_rr	3 (rear-right)

---

Visuals

File: shared/config/visuals.lua

NPC and Blip Settings

Setting	Type	Default	Description
Config.NpcModel	string	's_m_m_autoshop_01'	Ped model for the dispatcher NPC
Config.NpcScenario	string	'WORLD_HUMAN_CLIPBOARD'	Ambient scenario the NPC performs
Config.Blip.sprite	number	68	Map blip sprite ID
Config.Blip.color	number	36	Map blip color
Config.Blip.scale	number	0.8	Map blip scale
Config.Blip.label	string	'blip.tow_yard'	Locale key for blip label
Config.EventBlip.sprite	number	280	Blip sprite for job event locations
Config.EventBlip.color	number	33	Event blip color
Config.EventBlip.scale	number	1.5	Event blip scale
Config.DeliveryBlip.sprite	number	225	Blip sprite for towing delivery points
Config.DeliveryBlip.color	number	5	Delivery blip color
Config.DeliveryBlip.scale	number	1.0	Delivery blip scale

Driver Peds

Config.DriverPeds is an array of 16 ped model names used for spawning stranded NPC drivers. A random model is selected for each job.

Stranded NPC Behavior

Setting	Type	Default	Description
Config.StrandedNPC.standOffset	vec3	(2.5, 0.5, 0.0)	Offset from vehicle for NPC standing position
Config.StrandedNPC.animationDistance	number	40.0	Distance threshold for animation vs ambient scenario
Config.StrandedNPC.farScenario	string	'WORLD_HUMAN_STAND_MOBILE'	Ambient scenario when player is far away

Three reaction animations cycle when the player is nearby, plus an impatient animation when the timer is low.

Breakdown Visuals

Setting	Type	Default	Description
Config.BreakdownVisuals.engineHealth	number	100.0	Engine health for smoking effect
Config.BreakdownVisuals.alwaysHazards	boolean	true	Enable hazard lights on all breakdown types

Safety Zone

Setting	Type	Default	Description
Config.SafetyZone.enabled	boolean	true	Enable traffic safety zones around breakdown scenes
Config.SafetyZone.scenarioBlockRadius	number	20.0	Radius to block ambient ped scenarios
Config.SafetyZone.clearVehiclesRadius	number	10.0	Radius to clear parked vehicles on job start

Speed Zone Tiers

Tier	Radius	Speed
Inner	15m	4.0
Middle	30m	15.0
Outer	50m	25.0

Cones

Setting	Type	Default	Description
Config.Cones.enabled	boolean	true	Enable the cone placement system
Config.Cones.model	string	'prop_roadcone01a'	Road cone prop model
Config.Cones.maxCones	number	3	Maximum cones available per shift
Config.Cones.bonusPerCone	number	5	Bonus payment per cone placed when job completes
Config.Cones.placementRange	number	6.0	Max placement distance from player (meters)

Repair Effects

Setting	Type	Default	Description
Config.RepairEffects.enabled	boolean	true	Enable spark particle effects during repairs
Config.RepairEffects.spark.dict	string	'core'	Particle effect dictionary
Config.RepairEffects.spark.name	string	'ent_dst_elec_fire_sp'	Particle effect name
Config.RepairEffects.spark.scale	number	0.4	Particle scale
Config.RepairEffects.spark.duration	number	1500	Particle duration (ms)

Waypoints

Setting	Type	Default	Description
Config.Waypoints.heightOffset	number	5.0	Height above ground for waypoint marker
Config.Waypoints.updateInterval	number	0	Render thread sleep time (0 = every frame)
Config.Waypoints.scaleMin	number	0.5	Minimum scale at far distance
Config.Waypoints.scaleMax	number	1.0	Maximum scale at near distance
Config.Waypoints.scaleNearDist	number	30.0	Distance at which maximum scale is used
Config.Waypoints.scaleFarDist	number	300.0	Distance at which minimum scale is used

---

Tutorials

File: shared/config/tutorials.lua

Each entry in Config.Tutorials defines a tooltip:

Field	Type	Default	Description
icon	string	—	FontAwesome icon class
title	string	—	Locale key for the tooltip title
body	string	—	Locale key for the tooltip body text
position	string	'top-right'	Screen position (top-right, bottom-right, center-top, etc.)
duration	number	10	Auto-dismiss time in seconds

Tutorial Keys

Key	Trigger
first_clockin	First time clocking in
first_incoming_call	First dispatch call received
first_call_decline	First declined or missed call
first_fuel_job	First fuel help job
first_wheel_job	First wheel change job
first_battery_job	First battery replacement job
first_towing_job	First towing job
first_cone	First cone taken from truck
first_timer_expired	First late job finish
first_vehicle_damage	First vehicle destruction
first_job_complete	First job completed
first_crew	First crew formation
first_level_up	First level up

---

Enums

File: shared/config.lua

ShiftState

Value	Constant	Description
'idle'	ShiftState.IDLE	Not on shift
'waiting'	ShiftState.WAITING	On shift, waiting for dispatch
'on_call'	ShiftState.ON_CALL	Call accepted, driving to scene
'working'	ShiftState.WORKING	Performing service job

JobType

Value	Constant	Description
'fuel_help'	JobType.FUEL_HELP	Fuel refuelling job
'change_wheel'	JobType.CHANGE_WHEEL	Wheel change job
'towing'	JobType.TOWING	Vehicle towing job
'battery_change'	JobType.BATTERY_CHANGE	Battery replacement job

---

Rate Limits

File: server/main.lua

Server-side rate limiting prevents action spam. Each action has a cooldown period in milliseconds:

Action	Cooldown (ms)	Description
clockIn	2000	Clocking in to a shift
clockOut	2000	Clocking out of a shift
acceptCall	2000	Accepting a dispatch call
rejectCall	2000	Rejecting a dispatch call
completeJob	5000	Completing a service job
crewInvite	5000	Sending a crew invite
respondToInvite	2000	Accepting/declining a crew invite
propSync	500	Prop state sync to crew partner
coneSync	500	Cone state sync to crew partner
repairStepSync	1000	Repair step sync to crew partner
updateVehicle	2000	Tow truck network ID update
updateStrandedVehicle	5000	Stranded vehicle network ID update
vehicleDestroyed	10000	Vehicle destroyed event