Troubleshooting

Solutions for common issues with oxide-blackmarket.

---

Dealer Issues

Dealer Not Spawning

Symptoms:

• No dealer visible anywhere
• /dealerstatus shows "No dealer currently active"

Solutions:

1. Check console for errors

   Look for: [oxide-blackmarket] ERROR: Failed to create dealer ped

2. Verify dependencies are running

   # server.cfg - Ensure correct order
   ensure community_bridge
   ensure oxide-blackmarket

3. Check OneSync is enabled

   set onesync on

4. Force respawn

   /relocatedealer

5. Enable debug mode to see startup messages

   Config.Debug = true

---

Dealer Not Visible to Players

Symptoms:

• Dealer spawns but some players can't see it
• /godealer works but dealer invisible

Solutions:

1. Verify OneSync culling radius

   • The resource sets 50km culling radius automatically
   • Ensure no other scripts are modifying entity culling

2. Check network sync

   -- Debug: Enable in config
   Config.Debug = true
   -- Look for: Notifying all clients of dealer spawn

3. Player may need to re-stream

   • Have player move closer to spawn location
   • Or restart their game

---

Dealer Gets Stuck

Symptoms:

• Dealer doesn't wander
• Dealer stuck in geometry

Solutions:

1. Force relocation

   /relocatedealer

2. Adjust spawn locations

   • Check Config.Locations for problematic spots
   • Ensure locations are in open areas
   • Test each location manually

3. Check for pathfinding issues

   • Avoid indoor locations
   • Avoid areas with complex geometry

---

Shop Issues

Shop Not Opening

Symptoms:

• Target shows interaction but nothing happens
• No shop UI appears

Solutions:

1. Check your target system is working

   • Test other target interactions in your server
   • Restart the target resource

2. Verify dealer is tradable

   • Dealer becomes untradable if damaged
   • Use /relocatedealer to reset

3. Check NUI

   • Press F8 and check for JavaScript errors
   • Verify html/ folder exists with all files

4. Check debug output

   -- Enable debug and look for:
   -- 'Requesting shop from server'
   -- 'Shop request from player X'

---

Transaction Failing

Symptoms:

• Buy/sell button doesn't work
• "Transaction failed" message

Solutions:

1. Check player has enough money/items

   • Verify cash for purchases
   • Verify item exists in inventory for sales

2. Check dealer still exists

   • Dealer may have been killed/relocated mid-transaction
   • Close shop and re-open

3. Check stock availability

   • Item may be out of stock
   • Stock resets on relocation

4. Check inventory space

   • Player may have full inventory
   • Make room and try again

---

Items Not Appearing in Shop

Symptoms:

• Shop opens but items are missing
• Only some tiers showing

Solutions:

1. Check player reputation tier

   /checkblackmarketrep [playerID]

   • Items only show for current tier and below

2. Verify item definitions

   • Check shared/items.lua for correct format
   • Ensure items exist in your framework's item registry

3. Check tier configuration

   -- Verify Config.ShopInventory[tier] exists
   -- Verify items have all required fields

---

Police Mechanic Issues

Dealer Not Surrendering

Symptoms:

• Aiming at dealer does nothing
• Dealer doesn't put hands up

Solutions:

1. Verify player has a police job

   • Your job name must be in Config.PoliceJobs
   • Default: { 'police', 'sheriff', 'bcso', 'sast', 'sasp' }
   • Add your custom police jobs to the config if needed

2. Check aim distance

   • Must be within 10m (Config.AimSurrenderDistance)
   • Must be actively aiming (not just holding weapon)

3. Dealer already broken out

   • If dealer broke free once, they won't surrender again
   • Wait for relocation or use /relocatedealer

4. Dealer already dead or damaged

   • Damaged dealers fight, don't surrender

---

Arrest Not Working

Symptoms:

• [E] prompt appears but arrest fails
• Arrest animation plays but nothing happens

Solutions:

1. Verify dealer is surrendered

   • Dealer must have hands up
   • Must be within 10-second window

2. Check distance

   • Must be within 3m (Config.ArrestDistance)

3. Dealer broke free

   • If 10-second timer expired, dealer attacks
   • Cannot arrest hostile dealer

4. Check police job

   • Your job name must be in Config.PoliceJobs

---

Dealer Fleeing Too Often

Symptoms:

• Dealer keeps running away
• Can't complete arrest

Solutions:

1. Stay close to dealer

   • Stay within 8m (Config.FleeDistanceThreshold)
   • Don't back away while dealer is surrendered

2. Adjust flee settings

   -- Reduce flee chance
   Config.FleeChance = 0.20  -- 20% instead of 35%
   
   -- Or increase threshold
   Config.FleeDistanceThreshold = 12.0

---

Hit Squad Issues

Hit Squad Not Spawning

Symptoms:

• Kill dealer but no retaliation
• No vehicle spawns

Solutions:

1. Verify hit squad is enabled

   Config.HitSquadEnabled = true

2. Check if player damaged dealer

   • Hit squad only targets player who damaged/killed
   • Other players won't trigger squad

3. Check debug output

   Look for: 'Spawning hit squad...'
   Look for: 'No ideal node found'

4. Check spawn location

   • May fail in remote areas with no road nodes
   • Try in city areas

---

Hit Squad AI Issues

Symptoms:

• Squad spawns but doesn't attack
• Squad gets stuck

Solutions:

1. Check difficulty settings

   Config.HitSquadDifficulty = 'medium'
   -- Try 'easy' for testing

2. Verify vehicle spawned

   • Vehicle may have failed to spawn
   • Check if model exists

3. Check combat ability

   Config.HitSquadCombatAbility = {
       easy = 50,
       medium = 75,
       hard = 100,
   }

---

Pager Issues

Pager Not Working

Symptoms:

• Use pager, nothing happens
• No notification

Solutions:

1. Check tier requirement

   • Must be Tier 2 or higher

   /checkblackmarketrep [playerID]

2. Check cooldown

   • 5-minute cooldown between uses
   • Wait and try again

3. Verify item exists

   • Ensure blackmarket_pager is registered in your framework's item system
   • Verify item is marked as useable

4. Check dealer exists

   • Pager fails if no dealer active

   /dealerstatus

---

Pager Email Not Received (Tier 4)

Symptoms:

• Pager works but no email
• Only get notification, no waypoint

Solutions:

1. Verify phone system is installed

   • Email feature requires a supported phone resource (lb-phone, qb-phone, etc.)
   • Community Bridge handles the abstraction automatically

2. Check phone resource is running

   • Ensure your phone resource is started before oxide-blackmarket

3. Verify Tier 4

   • Email only sent at Tier 4 (1000+ rep)
   • Lower tiers get area name only

4. Waypoint still works

   • Even if email fails, the waypoint is still set on the map
   • You'll see "Intel received. Location marked on your GPS."

---

Blip Issues

Blips Not Appearing

Symptoms:

• Get close to dealer but no blip
• Blip system seems broken

Solutions:

1. Check detection range

   • Must be within 200m (Config.BlipDetectionRange)

2. Check cooldown

   • 2-minute cooldown between flashes
   • Wait and approach again

3. Verify blips.lua is loaded

   • Check fxmanifest.lua includes blips.lua
   • Check for errors in console

4. Check debug output

   Look for: [oxide-blackmarket] messages related to blip detection

---

Loot Issues

Loot Bag Not Appearing

Symptoms:

• Dealer dies but no loot bag
• Can't find loot

Solutions:

1. Verify loot is enabled

   Config.LootDropEnabled = true

2. Check model loading

   Look for: 'Failed to load loot bag model'

3. Check death coords

   Look for: 'Death coords missing or invalid'

---

Can't Collect Loot

Symptoms:

• Loot bag visible but can't interact
• Search animation plays but nothing received

Solutions:

1. Check target interaction

   • Verify bag is targetable
   • Try from different angle

2. Loot already collected

   • First-come-first-served
   • Another player may have collected

3. Check proximity

   • Must be within 5m of bag
   • Move closer and try again

4. Check debug output

   Look for: 'CollectLoot: Player X too far'

---

Performance Issues

High CPU Usage

Solutions:

1. Reduce check intervals

   Config.FleeCheckInterval = 2000       -- 2 sec instead of 1
   Config.HitSquadCheckInterval = 2000   -- 2 sec instead of 1

2. Reduce detection range

   Config.BlipDetectionRange = 150.0     -- 150m instead of 200

3. Disable debug mode

   Config.Debug = false

---

Network Desync

Solutions:

1. Check server tick rate

   • Ensure adequate server performance

2. Reduce culling radius (not recommended)

   • Currently set to 50km for visibility
   • Only reduce if necessary

---

Debug Mode

Enable comprehensive logging:

-- shared/config.lua
Config.Debug = true

Console output includes:

• Dealer spawn/despawn events
• Shop requests and transactions
• Reputation changes
• Hit squad spawning
• Loot generation
• Pager usage

Log prefix: [oxide-blackmarket]

Disable in production to reduce console spam.

---

Getting Help

If issues persist:

1. Enable debug mode and collect console output
2. Check server console for errors during the issue
3. Check client console (F8) for JavaScript errors
4. Verify community_bridge is running and up to date
5. Test with minimal resources to isolate conflicts