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


---

# 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://rex-studio.gitbook.io/rex-studio-docs/fivem-script/metal-detector.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.