Features

Shift System

Players interact with a dispatcher NPC at the tow yard to manage their shift. The NPC uses a clipboard scenario and opens a menu when interacted with via third-eye targeting.

Menu Styles

The dispatcher menu supports two display modes, controlled by Config.menuStyle:

Style	Setting	Description
NUI	'nui' (default)	Full-screen Vue menu with cinematic camera, crew headshot portraits, and a rich progression card. Shift summary displays as a NUI popup on clock-out.
Bridge Menu	'menu'	Lightweight ox_lib context menu. No camera, no NUI frontend required. Shift summary displays as a notification on clock-out.

Both styles expose the same functionality: clock in/out, invite crew partners, accept/decline crew invites, and view stats/progression.

Shift State Machine

State	Description
IDLE	Not clocked in, no active shift
WAITING	On shift, waiting for dispatch to send a service call
ON_CALL	Call accepted, driving to the stranded vehicle
WORKING	Actively performing the service job at the scene

Flow: IDLE → WAITING → (call arrives) → ON_CALL → WORKING → (job complete) → WAITING → ... → IDLE (clock out)

Slot Limits

Each tow yard location has a configurable maximum number of concurrent shift slots (default: 3). If all slots are full, new players cannot clock in at that location.

---

Call Dispatch System

After clocking in, dispatch automatically sends service calls at random intervals.

How It Works

1. A random delay between Config.Calls.minIntervalSeconds (15s) and Config.Calls.maxIntervalSeconds (45s) elapses
2. The server selects a random event from the pool (avoiding recently used events)
3. An incoming call notification appears with the job type, distance, and a response timer
4. The player presses E to accept or Backspace to decline within the response window

Call Behavior

Setting	Default	Description
Config.Calls.minIntervalSeconds	15	Minimum seconds between dispatch calls
Config.Calls.maxIntervalSeconds	45	Maximum seconds between dispatch calls
Config.Calls.responseTimeSeconds	30	Seconds to accept/decline before auto-miss
Config.Calls.maxMissedCalls	3	Missed/declined calls before automatic clock-out

Missed calls (unanswered within the response window) and declined calls both count toward the missed call limit. Reaching the maximum triggers an automatic clock-out for the player and their crew partner.

Event Pool

The dispatch system tracks which events have been used during the current shift to avoid repetition. Once all 40 events have been used, the pool resets.

---

Job Types

Four distinct service types, each with unique mechanics, props, and animations.

Fuel Help

Scenario: A stranded vehicle has run out of fuel. Refuel it using a jerry can.

Steps:

1. Drive to the stranded vehicle (NPC driver exits and waits nearby)
2. Take the jerry can from the tow truck via third-eye
3. Walk to the vehicle's fuel cap and interact to fill the tank
4. A 10-second refuelling animation plays with the jerry can prop
5. Return the jerry can to the truck

Setting	Value
Mission time	7 minutes
Base pay	$60
Events	10

Wheel Change

Scenario: A stranded vehicle has a flat tire. Change it using a jack and spare wheel.

Steps:

1. Drive to the stranded vehicle (NPC driver exits and waits nearby)
2. Take the car jack from the tow truck and place it under the vehicle
3. The vehicle raises incrementally over 6 pump strokes (800ms each)
4. Take the spare wheel from the truck and interact with the flat tire to swap it
5. A 10-second wheel change animation plays with spark effects
6. Remove the jack from under the vehicle
7. Return props to the truck

The flat tire is randomly selected at runtime from one of the 4 wheel positions (front-left, front-right, rear-left, rear-right).

Setting	Value
Mission time	10 minutes
Base pay	$80
Events	10

Battery Change

Scenario: A stranded vehicle has a dead battery. Replace it.

Steps:

1. Drive to the stranded vehicle (NPC driver exits and waits nearby)
2. Interact with the vehicle's engine bay to remove the dead battery (8-second animation)
3. Return to the tow truck and take the new battery
4. Carry the battery to the vehicle and install it in the engine bay (8-second animation with spark effects)

Setting	Value
Mission time	8 minutes
Base pay	$70
Events	10

Towing

Scenario: An abandoned vehicle needs to be towed to a drop-off point.

Steps:

1. Drive to the abandoned vehicle (no NPC driver)
2. Back the tow truck close to the vehicle and interact to attach it to the tow hook
3. A 5-second attaching animation plays
4. Drive to the delivery drop-off point (marked on map with a blip and waypoint)
5. At the drop-off, the vehicle auto-detaches and the job completes

A tow distance warning system monitors the separation between the tow truck and attached vehicle, alerting the player if they drive too far ahead.

Setting	Value
Mission time	8 minutes
Base pay	$100
Events	10
Delivery point	Shared drop-off at Grand Senora

---

Props System

Four physical props are attached to the tow truck bed at shift start and transfer between the truck, the player's hands, and the stranded vehicle during jobs.

Prop	Model	Used In	Carry Animation
Car Jack	imp_prop_car_jack_01a	Wheel change	Push/carry
Spare Wheel	imp_prop_impexp_tire_02c	Wheel change	Box carry
Jerry Can	w_am_jerrycan	Fuel help	Jerry can hold
Battery	prop_car_battery_01	Battery change	Box carry

Interaction Flow

1. Take from truck — Third-eye the tow truck to take a specific prop. The prop detaches from the truck and attaches to the player's hand with a carry animation.
2. Use at scene — Third-eye the stranded vehicle at the appropriate bone (fuel cap, tire, engine bay) to perform the repair action.
3. Return to truck — Third-eye the tow truck to re-attach the prop to the truck bed.

Props are only available for the job type that requires them.

---

Safety Cone System

Three safety cones are stored on the tow truck bed and can be placed around the work area for a payment bonus.

Placing Cones

1. Third-eye the tow truck and select "Take Safety Cone"
2. A cone attaches to the player's right hand
3. A ghost preview cone appears where the player aims (camera raycast)
4. Press E to place the cone at the ghost position, or Backspace to cancel
5. The ghost cone snaps to ground level within Config.Cones.placementRange (6m)

Speed Zones

Each placed cone creates tiered speed zones around its position:

Tier	Radius	Speed Limit
Inner	15m	4 mph
Middle	30m	15 mph
Outer	50m	25 mph

Speed zones slow down NPC traffic around the work area, enhancing immersion and safety.

Cone Bonus

Each cone placed when a job completes earns an additional Config.Cones.bonusPerCone ($5) added to the job payment.

---

Progression System

Players earn progression through completed jobs. Progression persists across sessions via database.

Levels

Level	Title	Required Jobs	Pay Multiplier	Tip Chance	Tip Range
1	Trainee	0	1.00x	10%	$5–15
2	Mechanic	15	1.10x	15%	$5–20
3	Senior Technician	40	1.20x	25%	$10–30
4	Team Lead	80	1.35x	30%	$10–40
5	Master Technician	150	1.50x	40%	$15–50

Daily Streak

Completing at least one job per consecutive real-world day builds a streak (max 7 days). Each streak day adds a bonus to job payments via Config.Payment.streakBonusPerDay ($10/day). Missing a day resets the streak to 1.

Complaint System

Certain actions add complaints to a player's record:

Action	Complaints Added
Vehicle destroyed during shift	1
Player dies or goes down during shift	1

Each successful job completion removes 1 complaint. Reaching the maximum complaints (default: 3) results in a temporary suspension (default: 30 minutes), after which complaints reset to 0.

---

Payment System

Payment is calculated per job and accumulated across the shift. The full payout is issued as a lump sum to the player's bank account when they clock out.

Per-Job Formula

subtotal = (basePay + distanceBonus + speedBonus + coneBonus) * levelMultiplier * timerMultiplier
total = subtotal + streakBonus + tip

Component	Calculation	Default
Base Pay	Flat rate per job type	$60–100
Distance Bonus	distance * distanceBonusPerUnit	$0.30/unit
Speed Bonus	Flat bonus for on-time completion	$25
Cone Bonus	conesPlaced * bonusPerCone	$5/cone
Level Multiplier	From progression level config	1.0x–1.5x
Timer Multiplier	1.0 if on-time, penalty if late	0.85x if late
Streak Bonus	dailyStreak * streakBonusPerDay	$10/day
Tip	Random chance based on level	Varies

End-of-Shift Payout

When clocking out, the system calculates a final payout:

Component	Description
Gross Pay	Sum of all job totals + co-op bonus
Co-op Bonus	15% bonus on jobs completed while in a crew
Vehicle Damage Charge	Deducted based on truck body health below threshold ($0.50 per health point below 950)
Vehicle Destroy Fine	$200 flat fine if the truck was destroyed during shift
Gas Fee	5% of gross pay
Taxes	10% of gross pay
Net Pay	grossPay - damageCharge - gasFee - taxes (minimum $0)

When using the NUI menu style, a shift summary screen displays the full breakdown. When using the bridge menu style, an email or notification is shown instead.

---

Crew System

Two players can work together as a crew, sharing a vehicle and service calls.

Forming a Crew

1. The shift leader opens the dispatcher menu and enters a partner's server ID
2. An invite is sent to the target player (expires after 60 seconds)
3. If the target is near the dispatcher NPC, the invite appears in their menu
4. Otherwise, a notification tells them to visit the dispatcher
5. On accept, the partner joins the leader's shift and receives the leader's vehicle reference

Crew Mechanics

• Both players share the same dispatch calls and tow truck
• Only the crew leader can accept or reject incoming calls
• Both players can interact with props, cones, and stranded vehicles
• Jobs completed in a crew earn a 15% co-op bonus
• Both players receive per-job payment notifications in real-time

Crew Dissolution

Scenario	Behavior
Leader clocks out	Vehicle and shift transfer to partner, who continues solo
Partner clocks out	Partner leaves, leader continues solo
Either disconnects	Remaining member continues solo, partner notified
Either dies/goes down	Death cleanup for affected member, crew disbanded, partner continues solo

---

Stranded NPC Behavior

For fuel help, wheel change, and battery change jobs, a random civilian NPC spawns inside the stranded vehicle and exhibits contextual behavior.

NPC Lifecycle

1. Vehicle spawns with the NPC in the driver seat
2. NPC exits the vehicle and walks to a standing position nearby
3. NPC cycles through reaction animations (beckoning, pleading) when the player is within 40m
4. When the player is far away (>40m), the NPC switches to an ambient phone scenario
5. NPC faces the player when approached
6. After job completion, the NPC and vehicle are cleaned up

A pool of 16 civilian ped models is used, with a random selection per job.

---

Breakdown Visuals

Stranded vehicles display visual effects to indicate the breakdown:

• Hazard lights enabled on all job types
• Cosmetic body damage (dents) applied to non-towing vehicles
• Engine smoke from low engine health
• Flat tire visually applied for wheel change jobs (randomly selected wheel)
• Engine fires are disabled for safety

For towing jobs, the vehicle spawns without an NPC driver and without damage effects, representing an abandoned vehicle.

---

Vehicle System

A tow truck (towtruck) spawns at the tow yard's vehicle spawn point when a player clocks in.

Vehicle Features

• License plate set to TOWSVC
• Vehicle keys provided via community_bridge
• Health monitored every 1 second
• Props (jack, spare wheel, jerry can, battery) attached to the truck bed
• Safety cones (3) attached to the truck bed
• Third-eye targets for taking/returning all props and cones

Vehicle Destruction

If the tow truck's engine health drops below the destroyed threshold (150):

• Current job is cancelled
• A complaint is added to the player's record
• A $200 vehicle destroy fine is deducted from cash immediately
• Dispatch stops and the player must wait
• Both crew members are notified

Vehicle Damage Charges

At clock-out, if the truck's body health is below 950, a damage charge is calculated at $0.50 per health point below the threshold and deducted from the shift payout.

---

HUD Overlay

A NUI panel appears during active jobs showing:

• Mission timer — Countdown to the job deadline. Shows "LATE" indicator when the timer expires.
• Job type label — The current service type being performed.
• Hint text — Context-sensitive instructions (e.g., "Release the vehicle to complete delivery", cone placement controls).

---

Waypoints

A 3D floating waypoint marker appears above the current job destination. The waypoint:

• Hovers at a configurable height offset (default: 5m above ground)
• Scales between 0.5x and 1.0x based on distance (30m to 300m range)
• Shows distance text (meters or kilometers)
• Toggles visibility by holding H (configurable keybind)

---

Phone Integration

If the player has a phone (via community_bridge phone support), email notifications are sent for key shift events:

• Shift start welcome message
• Vehicle destruction alerts
• Death/hospitalization notices
• End-of-shift summary with full payment breakdown

Messages appear from "Roadside Assistance — [Location Name]" as a service email.

---

Tutorial System

13 contextual tutorial tooltips guide new players through their first shift experience. Tutorials appear as positioned NUI overlays with icons, titles, and explanatory text.

Tutorial	Trigger	Description
First Clock In	Clocking in	Explains waiting for dispatch calls
Incoming Call	First call received	How to accept/reject calls
Call Declined	First declined/missed call	Warning about complaint accumulation
Fuel Job	First fuel help job	Jerry can refuelling instructions
Wheel Job	First wheel change job	Jack and spare wheel instructions
Battery Job	First battery job	Battery removal and installation
Towing Job	First towing job	Tow hook and delivery instructions
Safety Cones	First cone taken	Cone placement and bonus explanation
Timer Expired	First late finish	Pay penalty warning
Vehicle Damage	First vehicle destruction	Fine and complaint warning
Job Complete	First job completed	Pay and progression explanation
Crew Partner	First crew formation	Co-op bonus explanation
Level Up	First level up	Progression benefits explanation

Tutorials persist via KVP storage (client-side) and are only shown once per topic. Players can toggle tutorials on/off with /roadsidetutorials or reset all progress with /roadsidetutorialreset.