🔍METAL DETECTOR

📸 Screenshots

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:

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

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

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

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

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
    }
}

🎮 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

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

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:

{
    "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

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

-- 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:

Config.debug = true