> For the complete documentation index, see [llms.txt](https://fb-scripts.gitbook.io/fb-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fb-scripts.gitbook.io/fb-scripts/scripts/fb-blackmarket/installation.md).

# Installation

{% stepper %}
{% step %}
Download and extract the `fb-blackmarket` folder.
{% endstep %}

{% step %}
Move the `fb-blackmarket`folder into your server's `resources` directory.
{% endstep %}

{% step %}
Open your `server.cfg` and add the following line:

<pre><code>ensure ox_lib
<strong>ensure fb-handling
</strong></code></pre>

{% hint style="warning" %}
Make sure `ox_lib` starts **before** `fb-blackmarket`.
{% endhint %}
{% endstep %}

{% step %}
Restart your server or type `refresh` and `ensure fb-blackmarket`in your server console
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**Important:** The resource folder **must** be named exactly `fb-blackmarket`. Renaming it will break the resource.
{% endhint %}

### Database Setup

#### Automatic Setup (Default)

FB-Blackmarket **automatically creates all required database tables** when the resource starts. No manual SQL import needed!

When you start your server, you'll see in console:

```
[FB-Blackmarket] Database tables verified successfully. (4/4 tables ready)
```

**How it works:**

* The file `server/db-init.lua` runs on resource start
* Uses `CREATE TABLE IF NOT EXISTS` — safe to run every restart
* Auto-detects your MySQL driver (oxmysql, mysql-async, or ghmattimysql)
* If no MySQL driver is found, it prints a warning and skips gracefully

**Supported MySQL Drivers:**

| Driver            | Detection Method                 | Status      |
| ----------------- | -------------------------------- | ----------- |
| **oxmysql**       | `exports.oxmysql:execute()`      | ✅ Supported |
| **mysql-async**   | `MySQL.Async.execute()`          | ✅ Supported |
| **ghmattimysql**  | `exports.ghmattimysql:execute()` | ✅ Supported |
| **ox\_lib MySQL** | `MySQL.query()`                  | ✅ Supported |

{% hint style="info" %}
You don't need to do anything — just `ensure fb-blackmarket` and the tables will be created automatically on first start.
{% endhint %}

#### Manual Setup (Alternative)

If you prefer to import the SQL file manually instead of using automatic setup, follow these steps:

{% stepper %}
{% step %}

#### **Locate the SQL File**

Find `blackmarket.sql` in your resource folder:

```
fb-blackmarket/blackmarket.sql
```

{% endstep %}

{% step %}

#### Connect to Your Database

You need access to your MySQL/MariaDB database. Use whichever method you prefer:

<details>

<summary>Option A: Command Line (SSH / Terminal)</summary>

1. Open your server terminal (SSH or local)
2. Run the following command:

```bash
mysql -u root -p your_database_name < /path/to/fb-blackmarket/blackmarket.sql
```

3. Enter your MySQL password when prompted
4. If successful, no output is shown (silence = success)

{% hint style="info" %}
Replace `root` with your MySQL username and `your_database_name` with your FiveM database name (usually found in `server.cfg` under `set mysql_connection_string`).
{% endhint %}

</details>

<details>

<summary>Option B: phpMyAdmin (Web Panel)</summary>

1. Log in to **phpMyAdmin** (usually at `http://your-server-ip/phpmyadmin`)
2. Select your FiveM database from the left sidebar
3. Click the **Import** tab at the top
4. Click **Choose File** and select `blackmarket.sql`
5. Leave all settings as default
6. Click **Go** at the bottom
7. You should see a green success message: *"Import has been successfully finished"*

</details>

<details>

<summary>Option C: HeidiSQL (Windows Desktop)</summary>

1. Open **HeidiSQL** and connect to your database server
2. Select your FiveM database from the left panel
3. Go to **File → Run SQL file...** (or press `Ctrl+Shift+O`)
4. Select `blackmarket.sql`
5. Click the **▶ Run** button (or press `F9`)
6. Check the **Messages** tab at the bottom — it should show `4 queries executed`

</details>

<details>

<summary>Option D: DBeaver / MySQL Workbench</summary>

1. Open your database client and connect to your server
2. Select your FiveM database
3. Open `blackmarket.sql` as a new SQL script
4. Execute all queries (usually `Ctrl+Enter` or the Run button)
5. Refresh the tables list to confirm creation

</details>
{% endstep %}
{% endstepper %}

#### Tables Created

| Table                       | Purpose                              | Required? |
| --------------------------- | ------------------------------------ | --------- |
| `player_blackmarket`        | Player level, XP, and purchase stats | Optional  |
| `player_blackmarket_tasks`  | Task progress per player             | Optional  |
| `blackmarket_stock`         | Global item stock                    | Optional  |
| `blackmarket_purchase_logs` | Full purchase audit trail            | Optional  |

{% hint style="success" %}
These tables are only used when specific features are enabled:

* `Config.StockManagement.SaveToDatabase = true` → uses `blackmarket_stock`
* Purchase logging → uses `blackmarket_purchase_logs`
* The script works **without any database** using framework metadata for player data
  {% endhint %}

### Tablet Items Setup

{% stepper %}
{% step %}

#### Copy Item Images

Copy the tablet images to your inventory's image folder:

| Inventory           | Copy To                        |
| ------------------- | ------------------------------ |
| **qb-inventory**    | `qb-inventory/html/images/`    |
| **ps-inventory**    | `ps-inventory/html/images/`    |
| **ox\_inventory**   | `ox_inventory/web/images/`     |
| **qs-inventory**    | `qs-inventory/html/images/`    |
| **codem-inventory** | `codem-inventory/html/images/` |

Files to copy from `item/` folder:

* `bmitemphoto.png` — Normal tablet image
* `vbmitemphoto.png` — VIP tablet image
  {% endstep %}

{% step %}

#### Register Items (Per Framework)

<details>

<summary>QBCore — qb-core/shared/items.lua</summary>

Add to `qb-core/shared/items.lua`:

```lua
bm_tablet = {
    name = 'bm_tablet',
    label = 'Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'bmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Encrypted device to access the underground market network'
},
vipbm_tablet = {
    name = 'vipbm_tablet',
    label = 'VIP Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'vbmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Highly encrypted device for exclusive smuggler access'
},
```

</details>

<details>

<summary>QBox (qbx_core) — qbx_core/shared/items.lua</summary>

Add to `qbx_core/shared/items.lua`:

```lua
bm_tablet = {
    name = 'bm_tablet',
    label = 'Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'bmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Encrypted device to access the underground market network'
},
vipbm_tablet = {
    name = 'vipbm_tablet',
    label = 'VIP Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'vbmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Highly encrypted device for exclusive smuggler access'
},
```

</details>

<details>

<summary>ESX — SQL Query (Database)</summary>

Run this SQL in your database:

```sql
INSERT INTO `items` (`name`, `label`, `weight`, `rare`, `can_remove`) VALUES
    ('bm_tablet', 'Blackmarket Tablet', 1500, 0, 1),
    ('vipbm_tablet', 'VIP Blackmarket Tablet', 1500, 1, 1);
```

If you use **ESX + ox\_inventory**, follow the ox\_inventory instructions below instead.

</details>

<details>

<summary>ox_inventory — ox_inventory/data/items.lua</summary>

Add to `ox_inventory/data/items.lua`:

```lua
['bm_tablet'] = {
    label = 'Blackmarket Tablet',
    weight = 1500,
    close = true,
    stack = false,
    description = 'Encrypted device to access the underground market network'
},

['vipbm_tablet'] = {
    label = 'VIP Blackmarket Tablet',
    weight = 1500,
    close = true,
    stack = false,
    description = 'Highly encrypted device for exclusive smuggler access'
},
```

</details>

<details>

<summary>qs-inventory — qs-inventory/shared/items.lua</summary>

Add to `qs-inventory/shared/items.lua`:

```lua
['bm_tablet'] = {
    name = 'bm_tablet',
    label = 'Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'bmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Encrypted device to access the underground market network'
},
['vipbm_tablet'] = {
    name = 'vipbm_tablet',
    label = 'VIP Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'vbmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Highly encrypted device for exclusive smuggler access'
},
```

</details>

<details>

<summary>codem-inventory — codem-inventory/shared/items.lua</summary>

Add to `codem-inventory/shared/items.lua`:

```lua
bm_tablet = {
    name = 'bm_tablet',
    label = 'Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'bmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Encrypted device to access the underground market network'
},
vipbm_tablet = {
    name = 'vipbm_tablet',
    label = 'VIP Blackmarket Tablet',
    weight = 1500,
    type = 'item',
    image = 'vbmitemphoto.png',
    unique = true,
    useable = true,
    shouldClose = true,
    description = 'Highly encrypted device for exclusive smuggler access'
},
```

</details>
{% endstep %}
{% endstepper %}