> For the complete documentation index, see [llms.txt](https://rex-studio.gitbook.io/rex-studio-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rex-studio.gitbook.io/rex-studio-docs/fivem-script/metal-detector.md).

# METAL DETECTOR

### 📸 Screenshots

| ![Metal Detector Interface](https://site.redstartrp.fr/cloud/noxen/metaldetector_1.png) | ![Detection Process](https://site.redstartrp.fr/cloud/noxen/metaldetector_2.png) |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| ![Distance Guide](https://site.redstartrp.fr/cloud/noxen/metaldetector_3.png)           | ![Treasure Found](https://site.redstartrp.fr/cloud/noxen/metaldetector_4.png)    |

A comprehensive and realistic metal detector script for FiveM servers, featuring advanced detection mechanics, multiple digging tools, particle effects, and multi-language support.

### 📝 Configuration Overview

The `shared/config.lua` file contains all script configuration options. Here's a simple description of each section:

#### 🎯 Framework Configuration

* **`Config.core`** : Choose the framework to use (`"ESX"` or `"QBCore"`)

#### 🐛 Debug & Logging

* **`Config.debug`** : Enable debug messages in console (`true`/`false`)
* **`Config.log`** : Enable logging system (`true`/`false`)
* **`Config.webhook`** : Discord webhook URL for logs (leave empty to disable)

#### 📦 Item Configuration

* **`Config.removeItem`** : Remove metal detector item after use (`true`/`false`)
* **`Config.itemName`** : Item name in database/inventory
* **`Config.autoPickup`** : Auto pickup found items (`true` = automatic, `false` = press E to pickup)

#### 🗺️ Search Zones

* **`Config.maxDistanceFromZones`** : Maximum distance (in meters) to be considered "near" a zone
* **`Config.useOxZones`** : Use ox\_lib zones (`true` = specific zones, `false` = everywhere)
* **`Config.searchZones`** : List of search zones (box, poly, sphere) with their coordinates

#### 🌍 Language

* **`Config.Language`** : Interface language (`"fr"`, `"en"`, `"es"`)

#### ⌨️ Control Keys

* **`Config.stopKey`** : Key to stop detection (default 73 = X)
* **`Config.faqKey`** : Key to show help (default 104 = H)

#### 💎 Treasure Items

* **`Config.UseMultipleItems`** : Allow multiple items per dig (`true` = multiple, `false` = one random)
* **`Config.Items`** : List of findable items/money with their probability (`random` = chance percentage)

#### 📦 Treasure Props

* **`Config.Props`** : List of 3D models that appear when digging with their burial depth

#### 🔍 Metal Detector Model

* **`Config.ItemProp`** : 3D model of metal detector held in hand
* **`Config.bonesOffsets`** : Position and rotation of detector on player's hand

#### ⛏️ Digging Tools

* **`Config.propAttachments`** : Configuration of tools (shovel, pickaxe, trowel) with animations and sounds

#### ⚙️ Advanced Settings

* **`Config.targMin`** : Minimum distance to generate a target (in meters)
* **`Config.targMax`** : Maximum distance to generate a target (in meters)
* **`Config.volume`** : Metal detector beep volume (0.0 = mute, 1.0 = maximum)
* **`Config.maxMarkerSize`** : Maximum size of detection marker
* **`Config.minMarkerSize`** : Minimum size of detection marker

#### 🎨 Distance-Based Behavior

* **`Config.pulseAndSound`** : Configuration of visual and audio behavior based on distance to treasure
  * Each level defines: color, pulsation speed, beep frequency
  * 7 distance levels: very far → very close

#### 🏪 NPC Vendor Configuration

* `Config.NPC.enabled` : Enable/disable NPC vendor (true/false)
* `Config.NPC.allowSellItems` : Allow selling found items to NPC (true/false)
* `Config.NPC.model` : NPC ped model (FiveM ped model hash)
* `Config.NPC.blip.enabled` : Show blip on map (true/false)
* `Config.NPC.blip.sprite` : Blip sprite ID
* `Config.NPC.blip.color` : Blip color ID
* `Config.NPC.blip.scale` : Blip scale
* `Config.NPC.blip.name` : Blip name displayed on map
* `Config.NPC.locations` : Table of NPC spawn locations (coords, heading, scenario)
* `Config.NPC.detectorPrices.buyPrice` : Price to buy metal detector from NPC
* `Config.Items[].resell` : Resell price for found items (set to 0 or nil to disable selling)
* `Config.Items[].resellType` : Type of money for resell ("cleanmoney" or "dirtymoney")

### ✨ Features

#### 🎯 Core Features

* **Realistic Metal Detection**: Advanced proximity-based detection system with visual and audio feedback
* **Multiple Digging Tools**: Support for trowel, pickaxe, and shovel with unique animations and sounds
* **Framework Support**: Compatible with both ESX and QBCore frameworks
* **Multi-Language System**: JSON-based localization (French, English, Spanish included)
* **Zone-Based Detection**: Configurable search zones with ox\_lib integration
* **Particle Effects**: Realistic dirt particles synchronized with digging animations
* **Progressive Marker System**: Distance-based color-coded markers with pulsation effects

#### 🎨 Visual & Audio

* **Dynamic Markers**: Color-changing proximity markers (Gray → Green → Yellow → Orange → Red)
* **Synchronized Audio**: Tool-specific sound effects perfectly timed with animations
* **Particle System**: Realistic dirt-throwing effects during excavation
* **Modern UI**: Clean notification system with fade effects

#### 🛠️ Customization

* **Extensive Configuration**: Over 50+ configurable options
* **Custom Items**: Define your own discoverable items with rarity percentages
* **Zone Management**: Create custom search areas with specific boundaries
* **Tool Customization**: Modify digging tool properties and animations
* **Sound Control**: Adjust detection beeps, volumes, and frequencies

### 📋 Requirements

* **FiveM Server** (Latest version recommended)
* **ESX** or **QBCore** framework

### 🚀 Installation

#### 1. Framework Configuration

Edit `shared/config.lua` and set your framework:

```lua
Config.core = "ESX" -- or "QBCore"
```

#### 2. Server Configuration

Add to your `server.cfg`:

```
ensure metaldetector
```

#### 3. Item Configuration

Add the metal detector item to your shop or admin panel.

### ⚙️ Configuration

#### Basic Setup

```lua
-- Framework selection
Config.core = "ESX" -- ESX or QBCore

-- Detection settings
Config.targMin = 15 -- Minimum target distance
Config.targMax = 50 -- Maximum target distance
Config.volume = 0.3 -- Audio volume (0.0 - 1.0)

-- Visual settings
Config.maxMarkerSize = 1.5
Config.minMarkerSize = 0.3
```

#### Zone Configuration

```lua
Config.useOxZones = true -- Enable ox_lib zones

Config.searchZones = {
    {
        name = "Beach Area",
        coords = vector3(100.0, 200.0, 30.0),
        radius = 150.0,
        blip = true
    }
}
```

#### Item Configuration

```lua
Config.Items = {
    {
        object = "item",
        name = "goldbar",
        random = 5, -- 5% chance
        amount = 1,
        resell = 500, -- Price to sell to NPC (0 = cannot be sold)
        resellType = "cleanmoney" -- "cleanmoney" or "dirtymoney"
    },
    {
        object = "money",
        name = "cash",
        random = 15, -- 15% chance
        amount = 250
    }
}
```

#### NPC Vendor Configuration

```lua
Config.NPC = {
    enabled = true, -- Enable/disable NPC vendor
    allowSellItems = true, -- Allow selling found items to NPC
    model = "s_m_y_ammucity_01", -- NPC ped model
    blip = {
        enabled = true, -- Show blip on map
        sprite = 280, -- Blip sprite ID
        color = 5, -- Blip color ID
        scale = 0.8, -- Blip scale
        name = "Metal Detector Vendor" -- Blip name
    },
    locations = {
        {
            coords = vector4(-1296.4374, -1621.9232, 4.1195, 127.5017), -- x, y, z, heading
            scenario = "WORLD_HUMAN_CLIPBOARD" -- NPC scenario/animation
        },
        -- Add more locations here if needed
    },
    detectorPrices = {
        buyPrice = 10000, -- Price to buy metal detector from NPC
    }
}
```

<figure><img src="/files/GaQk2GObGNN8I2SZUte8" alt=""><figcaption></figcaption></figure>

### 🎮 How to Use

#### For Players

1. **Acquire Metal Detector**: Purchase or receive a metal detector item
2. **Find Search Zone**: Go to designated search areas (marked with blips)
3. **Activate Detector**: Use the metal detector item from inventory
4. **Follow Markers**: Watch for color-coded proximity markers:
   * 🔘 **Gray**: Very far from target
   * 🟢 **Green**: Getting closer
   * 🟡 **Yellow**: Close to target
   * 🟠 **Orange**: Very close
   * 🔴 **Red**: Target nearby
5. **Listen for Beeps**: Audio frequency increases as you get closer
6. **Dig**: Press **E** when markers turn red to start digging
7. **Collect Items**:
   * If `Config.autoPickup = true` : Items are automatically added to inventory
   * If `Config.autoPickup = false` : Press **E** near the treasure to collect it

#### Controls

* **E**: Start digging when close to target / Pick up found items (if `Config.autoPickup = false`) / Talk to NPC vendor
* **X**: Stop detection
* **H**: Toggle help information (FAQ)
* **Mouse**: Look around while detecting

**Note**: If `Config.autoPickup = true`, items are automatically added to inventory without pressing E.

### 🔧 Advanced Configuration

#### Custom Digging Tools

```lua
Config.propAttachments = {
    ["prop_cs_trowel"] = {
        bone = 28422,
        offset = vector3(0.0, 0.0, 0.0),
        rotation = vector3(0.0, 0.0, 0.0),
        animDict = "weapons@first_person@aim_rng@generic@projectile@thermal_charge@",
        animName = "plant_floor"
    }
}
```

#### Audio Customization

```lua
Config.pulseAndSound = {
    [1] = { -- Very far
        distanceToZone = 50,
        color = {128, 128, 128}, -- Gray
        frequency = 4000,
        sizeChangeRate = 0.005
    },
    [7] = { -- Very close
        distanceToZone = 2,
        color = {255, 0, 0}, -- Red
        frequency = 500,
        sizeChangeRate = 0.03
    }
}
```

#### Multi-Language Support

Edit `locales/translations.json`:

```json
{
    "fr": {
        "start_detection": "Détection activée",
        "stop_detection": "Détection arrêtée"
    },
    "en": {
        "start_detection": "Detection started",
        "stop_detection": "Detection stopped"
    }
}
```

### 🔄 API Events

#### Client Events

```lua
-- Start detection manually
TriggerEvent('metal_detector:start')

-- Stop detection
TriggerEvent('metal_detector:stop')

-- Object found
RegisterNetEvent('metal_detector:foundObject')
AddEventHandler('metal_detector:foundObject', function(prop, items)
    -- Handle found object
end)
```

#### Server Events

```lua
-- Add item to player
TriggerServerEvent('metal_detector:addItem', itemName, amount)

-- Add money to player
TriggerServerEvent('metal_detector:addMoney', amount)
```

### 🐛 Troubleshooting

#### Common Issues

**Metal detector doesn't start:**

* Check if player has the item in inventory
* Verify framework configuration
* Ensure player is in a valid search zone

**No sounds playing:**

* Check Config.volume setting
* Verify sound files are not corrupted
* Test with different audio settings

**Particles not showing:**

* Update graphics drivers
* Check FiveM graphics settings
* Verify particle system is enabled

**Zone detection not working:**

* Ensure ox\_lib is properly installed
* Check zone coordinates in config
* Verify Config.useOxZones is true

#### Debug Mode

Enable debug mode for troubleshooting:

```lua
Config.debug = true
```