Nomad Trader

Overview

The Nomad Trader System is a dynamic FiveM resource that spawns temporary traders at random locations across the map. These traders offer various items for sale and create an immersive trading experience for players.

Key Features

• Dynamic Spawn System: Traders spawn at random locations with configurable intervals

• Multiple Trader Types: Different trader personalities (Weapons Dealer, Supply Trader, Tech Specialist, etc.)

• Vehicle & Guard System: Traders can spawn with vehicles and armed guards

• Target System Integration: Supports qb-target, ox_target, and qtarget

• Framework Support: Compatible with ESX and QBCore frameworks

• Radio Notifications: Immersive radio-style notifications for trader events

• Trader Escape System: Traders can escape if threatened

• Dynamic Stock: Randomized stock amounts for each trader

System Requirements

• ESX or QBCore framework

• Optional: Target system (qb-target, ox_target, or qtarget)

• Optional: Core inventory for item images

Configuration Guide

Framework Settings

Config.Framework = "qbcore" -- 'esx' or 'qbcore'
Config.Locale = "en" -- Language option: "en", "tr", "de"
Config.Debug = false -- Enable debug messages

Currency Settings

Config.UseItemAsMoney = true -- Use items as currency instead of cash
Config.MoneyItem = "cigarette" -- Currency item name
Config.CurrencySymbol = "⚡ " -- Symbol for cash transactions

Trader System Settings

Config.EnableNomadTraders = true -- Enable/disable the system
Config.MaxActiveTraders = 1 -- Maximum concurrent traders
Config.TraderActiveTime = 30 -- Minutes trader stays active
Config.SpawnInterval = 10 -- Minutes between spawn attempts
Config.MarkerVisibleTime = 5 -- Minutes marker is visible

Vehicle & Guard System

Config.SpawnVehicle = true -- Spawn vehicles with traders
Config.SpawnGuards = true -- Spawn armed guards
Config.MaxGuards = 4 -- Maximum guards per trader
Config.GuardDetectionRange = 25.0 -- Weapon detection range

Target System Integration

Config.UseTarget = true -- Enable target system
Config.Target = {
    System = "qb-target", -- "qb-target", "ox_target", "qtarget"
    Icon = "fas fa-shopping-basket",
    Label = "Trade with Nomad",
    Distance = 2.0
}

Trader Types

1. Weapons Dealer (25% spawn chance)

• Model: s_m_y_dealer_01

• Items: Weapons, ammunition, grenades

• Specialty: Military-grade equipment

2. Supply Trader (30% spawn chance)

• Model: s_m_m_doctor_01

• Items: Food, drinks, medical supplies

• Specialty: Survival essentials

3. Tech Specialist (20% spawn chance)

• Model: s_m_y_construct_02

• Items: Electronics, tools, equipment

• Specialty: Technical equipment

4. Rare Items Merchant (15% spawn chance)

• Model: s_m_y_warehouse_01

• Items: Valuable materials, blueprints

• Specialty: Hard-to-find items

5. Survival Expert (10% spawn chance)

• Model: s_m_y_construct_01

• Items: Camping gear, survival tools

• Specialty: Outdoor equipment

System Workflow

1. Trader Spawning

1. System checks if maximum traders limit is reached

2. Random location is selected from Config.SpawnLocations

3. Random trader type is chosen based on spawn chances

4. Unique trader ID is generated

5. Stock is randomly generated (30-100% of max stock)

6. Vehicle and guards are spawned (if enabled)

7. Blip and marker are created

8. Radio notification is sent to nearby players

2. Trader Lifecycle

• Spawn: Trader appears with full visibility

• Marker Hidden: After MarkerVisibleTime, marker disappears but blip remains

• Warning: 5 minutes before despawn, warning is broadcast

• Despawn: After TraderActiveTime, trader is removed

3. Trading Process

1. Player approaches trader and uses interaction (target system or proximity)

2. Server validates trader existence and sends trader data

3. UI opens with available items and player currency

4. Player selects items and quantities

5. Server validates transaction (money, stock, inventory space)

6. Transaction is processed and UI is updated

4. Guard System

• Guards patrol around trader and vehicle

• Detect when players aim weapons

• Become hostile if player poses threat

• Different relationship groups for proper AI behavior

5. Escape System

• Activated when player aims weapon at trader

• Trader and guards get in vehicle and drive away

• UI is closed and blip is removed

• Radio notification informs of escape

Item Categories

The system supports 10 item categories:

• Weapons: Firearms and melee weapons

• Ammunition: Various ammo types

• Armor: Protective equipment

• Food: Food and beverages

• Medical: Health items and supplies

• Electronics: Tech equipment

• Tools: Utility items

• Valuables: Rare materials

• Blueprints: Crafting recipes

• Camping: Outdoor gear

Commands

Admin Commands

• nomadspawn - Force spawn trader (admin only)

• nomadclear - Remove all traders (admin only)

Troubleshooting

Common Issues

1. Traders not spawning: Check EnableNomadTraders and framework compatibility

2. Target system not working: Verify target system export and configuration

3. Items not appearing: Check inventory integration and item names

4. Guards not working: Verify model and weapon hashes

Debug Mode

Enable Config.Debug = true to see detailed console output:

• Trader spawn/despawn events

• Transaction processing

• Guard behavior

• System timers

Performance Considerations

• Maximum active traders limit prevents server overload

• Guards and vehicles are properly cleaned up when trader despawns

• Timers are optimized to reduce server load

• Client-side distance checks minimize unnecessary processing

Customization Tips

1. Add new trader types: Extend Config.TraderTypes with new personalities

2. Custom spawn locations: Add coordinates to Config.SpawnLocations

3. Modify items: Update trader inventories in config

4. Adjust timers: Fine-tune spawn intervals and active times

5. Custom notifications: Modify radio notification system

Dependencies

• Core framework (ESX/QBCore)

• Target system (optional)

• Inventory system for item handling

---