ds-npclooter

# 🎒 ds-npclooter

**Advanced NPC Loot System with Per-Player Cooldown and Notifications**

## 📋 Description

**ds-npclooter** is an advanced NPC looting system for FiveM servers

that allows players to search dead NPCs, players, and animals for loot.

The script features per-player cooldowns, multiple framework support, and customizable loot tables.

## ✨ Features

- 🎯 **Multi-Framework Support** - Works with QBCore, QBox, and ESX

- 🔄 **Auto-Detection** - Automatically detects your framework and dependencies

- ⏱️ **Per-Player Cooldowns** - Prevents spam looting with configurable cooldowns

- 🎁 **Customizable Loot Tables** - Separate loot tables for NPCs, players, and animals

- 🚔 **Police Dispatch Integration** - Optional police alerts when looting

- 🎨 **Multiple UI Systems** - Supports ox_lib, ps-ui, qb-progressbar, mythic_progbar, and more

- 📦 **Inventory Compatibility** - Works with `ox_inventory`, `qb-inventory`, `lj-inventory`, `ps-inventory`, `qs-inventory`, or ESX inventory

- 🎯 **Target System Support** - Compatible with qb-target and ox_target

- 🔍 **Distance Validation** - Server-side distance checks to prevent exploits

- 🐛 **Debug Mode** - Built-in debug system for troubleshooting

## 🎮 Framework Support

| Framework | Status | Auto-Detect |

|-----------|--------|-------------|

| 🟢 **QBCore** | ✅ Supported | Yes |

| 🟡 **QBox** | ✅ Supported | Yes |

| 🔵 **ESX** | ✅ Supported | Yes |

### Optional (Auto-Detected)

- **Target System**: `qb-target` or `ox_target`

- **Progress Bar**: `ox_lib`, `ps-ui`, `progressbar`, `mythic_progbar`, or `rprogress`

- **Inventory**: `ox_inventory`, `qb-inventory`, `lj-inventory`, `ps-inventory`, `qs-inventory`, or ESX inventory

- **Notifications**: `ox_lib` (recommended), QBCore/QBox notifications, or ESX notifications

- **Dispatch**: `ps-dispatch`, `qb-dispatch`, `qb-policejob`, or `cd_dispatch` this can be disabled

## 🚀 Installation

1. **Download** the resource and place it in your `resources` folder

resources/

└── ds-npclooter/

2. **Add** to your `server.cfg`:

cfg

ensure ds-npclooter

3. **Configure** the script in `shared/config.lua` (see Configuration section)

4. **Restart** your server or start the resource:

restart ds-npclooter

## ⚙️ Configuration

- Framework Selection

Config.Framework = "auto" -- Options: "qbcore", "qbox", "esx", "auto"

- **`auto`** - Automatically detects your framework (recommended)

- **`qbcore`** - Force QBCore framework

- **`qbox`** - Force QBox framework

- **`esx`** - Force ESX framework

### System Configuration

Config.Inventory = "auto" -- Auto-detect inventory system

Config.Target = "auto" -- Auto-detect target system

Config.Progressbar = "auto" -- Auto-detect progress bar

Config.Notify = "auto" -- Auto-detect notification system

### Loot Settings

Config.SearchTime = 5000 -- Time in milliseconds to search

Config.MaxDistance = 3.0 -- Maximum distance to loot

Config.LootPlayers = false -- Allow looting dead players

Config.LootAnimals = false -- Allow looting dead animals

### Cooldown Settings

Config.CooldownEnabled = true -- Enable per-player cooldowns

Config.Cooldown = 30 -- Cooldown in seconds per ped

### Police Dispatch

Config.DispatchEnabled = true -- Enable police alerts

Config.Dispatch = "auto" -- Auto-detect dispatch system

Config.PoliceAlertChance = 30 -- Chance to alert police (1-100)

Config.DispatchCode = "10-31" -- Dispatch code

Config.DispatchMessage = "Suspicious activity reported"

### Loot Tables

Customize loot tables for different entity types:

-- NPC Loot Table

Config.PedLoot = {

{ item = "item_name", min = 1, max = 599, chance = 80 },

{ item = "item_name", min = 1, max = 2, chance = 15 },

}

-- Player Loot Table (if Config.LootPlayers = true)

Config.PlayerLoot = {

{ item = "item_name", min = 1, max = 900, chance = 40 },

{ item = "item_name", min = 1, max = 1, chance = 90 },

{ item = "item_name", min = 1, max = 1, chance = 50 },

}

-- Animal Loot Table (if Config.LootAnimals = true)

Config.AnimalsLoot = {

{ item = "item_name", min = 1, max = 200, chance = 60 },

{ item = "item_name", min = 1, max = 3, chance = 40 },

}

**Loot Table Format:**

- `item` - Item name in your inventory

- `min` - Minimum amount to give

- `max` - Maximum amount to give

- `chance` - Chance percentage (1-100) to receive this item

## 🎯 Usage

1. **Kill an NPC** (or player/animal if enabled)

2. **Approach the dead entity** (within configured distance)

3. **Use your target system** to interact (qb-target or ox_target)

4. **Select "Loot NPC"** option

5. **Wait for progress bar** to complete

6. **Receive loot** based on configured loot tables

### Player Looting

When looting a dead player, the script will:

- First try to loot from the player's inventory (random item)

- If no inventory items, fall back to `Config.PlayerLoot` table

- Limit maximum items to prevent abuse

## 🐛 Debug Mode

Enable debug mode to see detailed logs:

Config.Debug = {

Enabled = true, -- Enable debug mode

Client = true, -- Show client-side debug

Server = true, -- Show server-side debug

Prefix = "^5[ds-npclooter]^7"

}

## 📝 Supported Systems

- Target Systems

- ✅ qb-target

- ✅ ox_target

### Progress Bars

- ✅ ox_lib (lib.progressBar)

- ✅ ps-ui (Circle)

- ✅ progressbar

- ✅ mythic_progbar

- ✅ rprogress

- ✅ fallback (simple wait)

### Inventory Systems

- ✅ ox_inventory

- ✅ qb-inventory

- ✅ lj-inventory

- ✅ ps-inventory

- ✅ qs-inventory

- ✅ ESX inventory

### Notification Systems

- ✅ ox_lib (lib.notify)

- ✅ QBCore/QBox (QBCore.Functions.Notify)

- ✅ ESX (ESX.ShowNotification)

### Dispatch Systems

- ✅ ps-dispatch

- ✅ qb-dispatch

- ✅ qb-policejob

- ✅ cd_dispatch

## 🔧 Troubleshooting

- Script not detecting framework

- Make sure your framework resource is started before `ds-npclooter`

- Check console for framework detection messages

- Manually set `Config.Framework` to your framework name

### Items not being added

- Verify your inventory system is detected correctly

- Check item names match your inventory items exactly

- Enable debug mode to see what's happening

### Target not showing

- Ensure qb-target or ox_target is installed and started

- Check `Config.Target` setting

- Verify the entity is dead and within distance

### Progress bar not working

- Check which progress bar system you have installed

- Set `Config.Progressbar` to match your system

- Use "auto" to let it detect automatically