# 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

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

### Currency Settings

```lua
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

```lua
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

```lua
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

```lua
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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hate-development.gitbook.io/hate-development-docs/nomad-trader.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.