> For the complete documentation index, see [llms.txt](https://docs.gunchi.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gunchi.dev/esx-qb-qbx-nd-standalone-script-documentation/metal-detecting/installation.md).

# Installation

### 🔧 1. Requirements

Before installing, ensure you have the following dependencies:

* [**gunchi-bridge**](https://github.com/Tomogunchi/gunchi-bridge) — free & open source. Handles framework, inventory, target and dispatch integration for **ESX, QBCore, QBox, ND Core and Standalone**.
* [**ox\_lib**](https://github.com/overextended/ox_lib)

No framework-specific edition needed — the bridge auto-detects your framework.

### 📥 2. Download & Extract

1. Download the latest release from your Keymaster.
2. Place the folder `gunchi-metaldetecting` into your server's resources directory.
3. If you don't already have it, download `gunchi-bridge` from GitHub and place it in resources too.

### 🗄️ 3. Metal Detector Weapon

The script is activated by equipping the `weapon_metaldetector` weapon (changeable via `Config.WeaponName`). Add it to your framework's items:

**QBox / ox\_inventory** — `ox_inventory/data/weapons.lua`:

```lua
['WEAPON_METALDETECTOR'] = {
    label = 'Metal Detector',
    weight = 250,
    durability = 0.1,
    ammoname = nil,
},
```

**QBCore** — `qb-core/shared/weapons.lua`:

```lua
['weapon_metaldetector'] = {
    ['name'] = 'weapon_metaldetector',
    ['label'] = 'Metal Detector',
    ['weapontype'] = 'Melee',
    ['ammotype'] = nil,
    ['damagereason'] = 'Detected.'
},
```

(and a matching entry in `qb-core/shared/items.lua` if your inventory requires it)

**ESX** — register the weapon the same way you add any custom weapon (e.g. via `ox_inventory/data/weapons.lua` or your weapons resource).

**Standalone** — give the weapon however you like (`give weapon_metaldetector`); no item registration is required.

> **Loot items:** the loot table in `config.lua` ships with placeholder items (`sandwich`, `water`). Replace them with items that exist in **your** inventory before going live. If you enable `Config.RequireShovel`, add the shovel item too.

### ⚙️ 4. Configuration

Everything is tuned in `config.lua`:

* Loot table (tiers, items, amounts, chances)
* Permitted zones & diggable surfaces
* Zone cooldowns & spawn distances
* Skill check on/off & difficulty
* Deep signals, streak bonuses
* Shovel requirement & break chance
* Police dispatch alerts

### ▶️ 5. Add to Server Config

Start order matters — the bridge must load first:

```cfg
ensure ox_lib
ensure gunchi-bridge
ensure gunchi-metaldetecting
```

### 🔐 6. Escrow & Customization

This script uses escrow protection, however the following files remain fully editable:

* `config.lua` — every gameplay tunable
* `locales.lua` — every player-facing string (translate freely)
* `editable/skillcheck.lua` — the dig minigame itself. Defaults to the ox\_lib skill check, with commented examples for ps-ui and SN-Hacking — or plug in any minigame that returns true/false.

### 🎮 7. Usage

Once installed:

1. Equip the metal detector
2. Follow the compass, distance readout and proximity beeps to locate a signal
3. Head to the dig spot and action the prompt
4. Pass the skill check (if enabled) — deep signals take several shovelfuls but guarantee higher-tier loot
5. Receive server-rolled loot; consecutive successful digs build a streak that boosts rare drop chances
6. Wait for the configured cooldown, then a new zone generates

### 🆘 8. Support

If you need help:

* Join my Discord server for support and updates
* Bridge issues (framework detection, inventory, dispatch) can also be reported on the [gunchi-bridge GitHub](https://github.com/Tomogunchi/gunchi-bridge)