Features

Shift System

Players interact with a GoPostal supervisor NPC at depot locations to manage their shift. The NPC uses a clipboard scenario and opens a menu when interacted with via third-eye targeting.

Menu Styles

The supervisor 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 (same style as the landscaping job). No camera, no NUI frontend required. Shift summary displays as a notification on clock-out.

Both styles expose the same functionality: clock in/out, request new tasks, invite crew partners, accept/decline crew invites, toggle uniform, and view stats/progression. The bridge menu uses lib.inputDialog for the crew invite server ID input.

Shift State Machine

State	Description
IDLE	Not clocked in, no active shift
CLOCKED_IN	On shift, ready to request a task via the supervisor menu
LOADING	Picking up packages from a pallet or collecting a mail bag from a post box
DELIVERING	Actively delivering packages or letters to addresses

Flow: IDLE -> CLOCKED_IN -> LOADING -> DELIVERING -> CLOCKED_IN (batch complete, request another task) -> ... -> IDLE (clock out)

Slot Limits

Each depot 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.

Task Types

When requesting a new task from the supervisor menu, the server randomly assigns one of two task types:

Task Type	Pickup Source	Delivery Target	Carry Item
Packages	Pallet at depot pickup point	Customer doorstep (delivery zones)	Cardboard box prop
Letters	Post box (random from depot's post box list)	Residential letterbox	Envelope prop

The number of deliveries per batch scales with the player's progression level.

Loading Phase

Package Loading

1. A pallet with cardboard boxes spawns at one of the depot's pickup points
2. Player uses third-eye on individual boxes to pick them up (crouch animation, 3s)
3. Player carries the box to the GoPostal van's rear doors
4. Player uses third-eye on the van to load the box (rear doors must be open)
5. Box prop attaches inside the van at predefined offsets
6. Repeat until all boxes are loaded

Letter Loading

1. A GPS blip guides the player to a randomly selected post box
2. Player uses third-eye on the post box zone to collect the mail bag (crouch animation, 3s)
3. Player carries the mail bag to the van's rear doors
4. Player uses third-eye on the van to load the mail bag
5. Mail bag prop attaches inside the van

Once all items are loaded, the shift transitions to DELIVERING state automatically.

Delivery Phase

Package Delivery

1. A GPS blip and route appear for the next delivery address
2. A delivery timer starts based on distance from the player to the delivery point
3. Player drives to the delivery zone (marker visible within 20m)
4. Player opens the van's rear doors and uses third-eye to grab a package
5. Player carries the package to the delivery marker (within 3m) and presses E to deliver
6. A customer NPC spawns, walks toward the player, and a handoff animation plays
7. The box prop transfers from the player to the customer, who walks away and fades out
8. Payment notification appears with a breakdown of earnings

Letter Delivery

1. A GPS blip and route appear for the next letterbox location
2. A delivery timer starts based on distance
3. Player drives near the letterbox (marker visible within 20m)
4. Player exits the vehicle and uses third-eye on the letterbox zone to deliver
5. An envelope prop appears briefly during the delivery animation
6. Payment notification appears

After all deliveries in a batch are complete, the shift returns to CLOCKED_IN state. The player can request another task from the supervisor or clock out.

Route Intelligence

Delivery batches use two systems to create level-appropriate, logical routes.

Spread-Aware Zone Selection

When generating a delivery batch, zones are selected based on the player's level spreadFactor rather than pure randomness:

• High spread factor (low-level players) — deliveries are biased toward zones that are far apart, encouraging map exploration
• Low spread factor (high-level players) — deliveries cluster in a tight area for efficient grinding
• Selection uses nearest-selected distance scoring: each candidate zone is scored by its distance to the nearest already-selected zone, then split into near/far halves. The spread factor controls how often the algorithm picks from the far half vs the near half
• Random-within-half selection ensures variety — same player, same level still gets different routes each shift

Route Ordering

After zones are selected, orders are sorted into a logical driving loop using a greedy nearest-neighbor algorithm starting from the depot:

1. Start at the depot coordinates
2. Find the nearest unvisited delivery from the current position
3. Move to that delivery, repeat until all deliveries are ordered

This eliminates zigzag routes and creates a natural circuit. When crew extra orders are added to a fresh batch, the route is re-sorted to integrate them into the optimal sequence. Mid-shift partner joins do not re-sort to avoid disrupting an in-progress route.

Progression System

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

Levels

Level	Title	Required Deliveries	Max Packages	Max Letters	Pay Multiplier	Tip Chance	Tip Range	Spread Factor
1	Trainee	0	3	3	1.00x	10%	$5-15	1.0 (sparse)
2	Mail Carrier	20	4	4	1.00x	15%	$5-20	0.75
3	Senior Courier	50	5	4	1.15x	25%	$10-30	0.5 (balanced)
4	Route Manager	100	7	5	1.30x	30%	$10-40	0.25
5	Head Postman	200	9	6	1.50x	40%	$15-50	0.0 (clustered)

Daily Streak

Completing at least one delivery per consecutive real-world day builds a streak (max 7 days). Each streak day adds a bonus to delivery payments. 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 during shift	1

Each successful delivery 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 delivery and accumulated across the shift. The full payout is issued as a lump sum when the player clocks out.

Per-Delivery Formula

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

Component	Calculation	Default
Base Pay	Flat rate per delivery	$40
Distance Bonus	distance * distanceBonusPerUnit	$0.40/unit
Speed Bonus	Flat bonus for on-time delivery	$20
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 delivery totals + co-op bonus
Co-op Bonus	15% bonus on deliveries completed while in a crew
Early Finish Penalty	20% deduction if undelivered packages remain in current batch
Vehicle Damage Charge	Deducted based on van body health below threshold ($0.50 per health point below 950)
Vehicle Destroy Fine	$150 flat fine if the van was destroyed during shift
Net Pay	grossPay - penaltyAmount - damageCharge (minimum $0)

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

Crew System

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

Forming a Crew

1. The shift leader opens the supervisor 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 same supervisor NPC, the invite appears in their menu
4. Otherwise, a notification tells them to visit the supervisor
5. On accept, the partner joins the leader's shift and receives the leader's vehicle reference

Crew Mechanics

• Both players share the same delivery batch and vehicle
• Crew formation adds 2 extra deliveries to the current batch (if capacity allows)
• Either player can pick up boxes, load the van, grab packages, and deliver
• Only one player can hold a package per delivery point (server-enforced claim)
• Deliveries completed in a crew earn a 15% co-op bonus
• Both players receive per-delivery 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	Death cleanup for the dead member, partner notified

Headshot portraits of both crew members are displayed in the NUI for visual identification.

Customer Reactions

When delivering packages, a customer NPC spawns and reacts based on delivery timeliness:

Reaction	Trigger	Animation	Walk Speed
Good	On-time delivery	givetake1_a (accept gesture)	1.0
Poor	Late delivery	gesture_no_way (frustrated)	0.8

Late deliveries also display a complaint notification message.

Vehicle System

A GoPostal delivery van (boxville2) spawns at the depot's vehicle spawn point when a player clocks in.

Vehicle Features

• White primary and secondary color
• License plate set to GOPOST
• Vehicle keys provided via community_bridge
• Rear doors (indices 2, 3) must be opened for loading/unloading
• Box props attach at predefined offsets inside the cargo area
• Mail bag prop attaches in the center of the cargo area (letter tasks)
• Health monitored every 1 second

Vehicle Destruction

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

• Current deliveries are cancelled
• A complaint is added to the player's record
• A $150 vehicle destroy fine is applied to the shift payout
• Both crew members are notified and returned to CLOCKED_IN state

Crew Vehicle Sharing

When a crew is formed, the partner receives a reference to the leader's van. If the leader clocks out, ownership transfers to the partner.

HUD Overlay

A NUI delivery panel appears during the DELIVERING state showing:

• Current delivery timer (countdown)
• Late indicator when timer expires
• Delivery progress (e.g., "2/5")
• Context hints (e.g., "Deliver package", "Look for letterbox")

Waypoints

A 3D floating waypoint marker appears above the current delivery 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), SMS notifications are sent for key shift events:

• Shift start confirmation
• Delivery assignments
• Crew invites
• Vehicle destruction alerts

Messages appear from "GoPostal - [Location Name]" as a service message.

Bystander System

Players who are not on a shift can see visual-only pallets at depot locations when other players are actively loading. These bystander pallets:

• Spawn via GlobalState synchronization (postaljob:activePallets)
• Use non-networked, collision-disabled objects
• Update box count in real-time as shift players pick up boxes
• Despawn when the player moves out of range or starts their own shift
• Are reconciled on initial discovery via statebag change handler

Uniform System

Players can toggle a GoPostal uniform on/off through the supervisor menu. Separate outfits are configured for male and female character models. The uniform is automatically removed when clocking out.