Features

Comprehensive documentation of all oxide-blackmarket features.

---

Dealer System

The black market dealer is a single NPC that spawns at random locations throughout the map.

Spawning

• Single Instance: Only one dealer exists at any time
• Random Location: Spawns at a random location from Config.Locations
• Network Synced: Visible to all players through OneSync

Relocation

The dealer relocates to a new random location periodically:

Setting	Default	Description
Config.RelocationInterval	45 minutes	Time between relocations

When relocating:

1. All clients are notified of despawn
2. Dealer entity is deleted
3. After 3-second cleanup delay, new dealer spawns
4. All clients are notified of new location

Wandering Behavior

When idle and tradable:

• Dealer walks around the spawn area
• Stops wandering when player initiates interaction
• Faces the player during trade
• Resumes wandering after interaction ends

Combat Behavior

When damaged by a player:

• Dealer becomes hostile and untradable
• Attacks the player who damaged them
• Armed with default weapon (pistol)

---

Reputation System

Players build reputation by selling items to the dealer, unlocking better inventory tiers.

Tiers

Tier	Name	Rep Required	Description
0	Unknown	0	New to the black market
1	Street	100	Recognized street dealer
2	Connected	300	Has established connections
3	Trusted	600	Trusted supplier
4	Inner Circle	1000	Part of the inner circle

Gaining Reputation

Reputation is gained by selling items to the dealer:

-- Example from shared/items.lua
Config.SellableItems = {
    cokebaggy = { price = 150, rep = 5 },    -- +5 rep per sale
    goldbar = { price = 2500, rep = 25 },    -- +25 rep per sale
}

Losing Reputation

Action	Rep Loss
Killing the dealer	-500 rep

Tier Notifications

Players receive notifications when their tier changes:

• Tier Up: "Your reputation has increased! You are now [Tier Name]."
• Tier Down: "Your reputation has decreased. You are now [Tier Name]."

Storage

Reputation is stored in player metadata:

Player.PlayerData.metadata['blackmarket_rep']

---

Shop System

The dealer offers a buy/sell shop with tier-locked inventory.

Opening the Shop

1. Approach the dealer (within target distance)
2. Use qb-target to select "Trade with Dealer"
3. Shop UI opens with your available inventory

Buying Items

• Only items at or below your tier are available
• Each item has limited stock
• Stock decreases with purchases
• Prices are fixed per item

Selling Items

• Sell contraband for cash and reputation
• Only items in Config.SellableItems can be sold
• Each item has a fixed price and rep reward

Stock Management

Event	Stock Effect
Player purchase	Stock decreases
Dealer relocation	Stock fully resets
Dealer death	Stock lost (drops as loot)

Shop UI

The shop features a modern glassmorphism design:

• Buy Tab: Browse available items by tier
• Sell Tab: View sellable items from inventory
• Player Info: Shows current cash and reputation
• Quantity Controls: +/- buttons for bulk transactions

---

Police Interactions

Officers can engage with the dealer through a unique surrender/arrest system.

Dispatch Alert

When a police officer gets within range of the dealer:

• Automatic dispatch alert is triggered
• Alert: "Suspicious Activity - Black Market Dealer"
• Only triggers once per dealer spawn

Setting	Default
Config.PoliceDetectionRange	150m

Surrender Mechanic

When a police officer aims at the dealer:

1. Detection: Officer aims weapon at dealer within 15m
2. Surrender: Dealer stops all actions, raises hands
3. Timer Start: 10-second arrest window begins
4. Animation: Dealer plays surrender animation

Arrest Sequence

While dealer is surrendered:

1. Approach dealer within arrest distance (5m)
2. Press [E] or use qb-target "Arrest Dealer"
3. Officer plays cuffing animation (~3.5 seconds)
4. Arrest completes if dealer hasn't escaped

Rewards:

Reward	Amount
Officer Cash	$5,000
Police Society Fund	$2,500

Escape Mechanics

The dealer may attempt to escape:

Flee Chance: If police back away while dealer is surrendered

• Distance threshold: 8m (officer must be farther)
• Flee chance: 35% per check
• Check interval: Every 1 second

Break Free: If not arrested within 10 seconds

• Dealer stops surrendering
• Re-arms with weapon
• Becomes hostile to the officer
• Hit squad spawns as backup

Respawn Delays

Scenario	Respawn Delay
Dealer killed	10 minutes
Dealer arrested	15 minutes

---

Hit Squad Retaliation

Killing or damaging the dealer triggers a hit squad response.

Trigger Conditions

A hit squad spawns when:

• Player damages the dealer (any amount)
• Player kills the dealer

Only the player who damaged/killed triggers the squad.

Squad Composition

• 4 NPCs in business/suit attire
• 1 Vehicle (4-door sedan)
• Armed based on difficulty setting

Difficulty Levels

Difficulty	Weapons	Combat Ability
Easy	4x Pistol	50
Medium	Pistol50, 2x SMG, Pump Shotgun	75
Hard	Combat Pistol, 2x Assault Rifle, Carbine	100

AI Behavior

The hit squad has dynamic AI that adapts:

Driving Mode:

• Driver chases player vehicle
• Passengers perform drive-by shooting

On-Foot Mode (when player on foot within 50m):

• Exit vehicle
• Engage player in combat
• Use cover and combat movement

Re-entry Mode:

• If player escapes in vehicle, squad re-enters car
• Resumes vehicle chase

Escape Condition

To escape the hit squad:

• Reach 500m distance from the squad vehicle
• Notification: "You lost them."
• Squad becomes ambient (stops tracking)

Death/Elimination

If all squad members are killed:

• Squad is released
• No escape required

---

Loot Drop System

When the dealer dies, they drop loot that players can collect.

Loot Generation

Component	Range/Amount
Cash	$500 - $2,500
Items	30% of remaining stock
Max Item Types	5 different items

Loot Bag

• Appears at dealer's death location
• Uses prop_cs_heist_bag_01 model
• Targetable with qb-target

Collection Process

1. Approach loot bag
2. Use qb-target "Search Bag"
3. 8-second search animation plays
4. Loot is given to player

Security Features

Server-Side Storage:

• Loot contents stored on server only
• Clients never receive loot data
• Prevents exploitation/manipulation

First-Come-First-Served:

• Only one player can collect each loot bag
• Once collected, bag despawns for all players

Proximity Check:

• Player must be within 5m to collect
• Prevents remote collection exploits

Despawn

Uncollected loot despawns after 5 minutes.

---

Blip Discovery System

Players can discover the dealer through proximity-based flash blips.

Detection

When a player gets within 200m of the dealer:

• A temporary blip appears on the map
• Blip flashes briefly then disappears
• Cooldown prevents spam

Tier-Based Duration

Higher reputation = longer blip visibility:

Tier	Blip Duration
0	3 seconds
1	4 seconds
2	5 seconds
3	6 seconds
4	10 seconds

Blip Appearance

Setting	Value
Sprite	140 (dollar sign)
Color	Red
Cooldown	2 minutes

---

Pager System

The burner pager item allows players to request dealer location information.

Requirements

• Must have blackmarket_pager item
• Must be Tier 2 or higher
• Must not be on cooldown

Success Rates

Success chance varies by tier:

Tier	Success Rate
2	40%
3	70%
4	100%

Usage Flow

1. Use pager item from inventory
2. "Sending message..." notification
3. 3-6 second response delay
4. Result notification

Results

Success (Tier 2-3):

• Receive general area name
• "Word on the street... dealer spotted near [Area Name]."

Success (Tier 4):

• Receive exact coordinates
• Email sent with waypoint button
• "Intel received. Check your emails."

Failure:

• "No response..."
• Cooldown still applied

Cooldown

Setting	Default
Config.PagerCooldown	5 minutes

Cooldown applies regardless of success or failure.