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

# 📥  Installation

Follow these steps to install iKCScripts Boombox on your FiveM server.

Boombox supports **ox\_inventory**, **QBCore / qb-inventory**, and **ESX inventory**, along with **ox\_lib TextUI**, **ox\_target**, and **qb-target** interaction options.

You only need to install and configure the integrations used by your server.

***

### 1. Install the Resource

Place the `kc_boombox` folder inside your FiveM resources directory.

Example:

```
resources/
└── [scripts]/
    └── kc_boombox/
```

{% hint style="warning" %}
Keep the resource folder named `kc_boombox`.
{% endhint %}

***

### 2. Review the Installation Files

Inside `kc_boombox`, locate:

```
[install first]/
```

The folder contains the inventory setup files and Boombox inventory image.

```
[install first]/
├── kc_boombox.png
├── ox_inventory/
│   └── items.lua
├── qb-items/
│   └── items.lua
└── esx/
    └── items.sql
```

Choose the installation instructions below that match your server.

***

### 3. Install the Inventory Item

#### ox\_inventory

Open:

```
[install first]/ox_inventory/items.lua
```

Add the provided `kc_boombox` item definition to your **ox\_inventory** items configuration.

Then copy:

```
[install first]/kc_boombox.png
```

to:

```
ox_inventory/web/images/kc_boombox.png
```

{% hint style="info" %}
If you already have an item named `kc_boombox`, do not create a duplicate entry.
{% endhint %}

***

#### QBCore / qb-inventory

Open:

```
[install first]/qb-items/items.lua
```

Copy the provided `kc_boombox` item entry into:

```
qb-core/shared/items.lua
```

Then copy:

```
[install first]/kc_boombox.png
```

to:

```
qb-inventory/html/images/kc_boombox.png
```

After changing QBCore shared items, restart the required resources or restart the server so the new item is loaded.

***

#### ESX

Open:

```
[install first]/esx/items.sql
```

Import the provided SQL into the database used by your ESX server.

This creates the required:

```
kc_boombox
```

inventory item.

The inventory image location can vary depending on the inventory interface installed on your ESX server.

{% hint style="warning" %}
Install only the inventory item definition that matches your configured inventory system. You do not need to install the OX, QBCore, and ESX item definitions together.
{% endhint %}

***

### 4. Configure the Inventory Integration

Open:

```
config.lua
```

Select the inventory system used by your server.

Supported inventory integrations are:

* **ox\_inventory**
* **QBCore / qb-inventory**
* **ESX inventory**

Make sure the configured option matches the inventory system actually running on your server.

{% hint style="info" %}
`ox_inventory` is not required when Boombox is configured to use QBCore or ESX inventory.
{% endhint %}

***

### 5. Configure the Interaction System

Boombox supports multiple ways to interact with placed Boomboxes.

Choose the interaction system appropriate for your server.

#### ox\_lib TextUI

Uses the built-in ox\_lib TextUI interaction system.

No additional target resource is required.

Owners will see:

```
[E] Open Boombox • [G] Pick Up
```

Other citizens will see:

```
[E] Open Boombox
```

#### ox\_target

Select this option if your server uses **ox\_target**.

Interactions are attached to the exact placed Boombox entity.

#### qb-target

Select this option if your server uses **qb-target**.

Interactions are attached to the exact placed Boombox entity.

{% hint style="info" %}
You only need one interaction system configured for Boombox.
{% endhint %}

***

### 6. Add Boombox to server.cfg

Make sure the core dependencies start before Boombox.

```
ensure ox_lib
ensure xsound
ensure kc_boombox
```

Your framework, inventory, and optional target resources should already be started according to their own installation requirements.

{% hint style="warning" %}
`ox_lib` and `xsound` are required core dependencies and must be available before `kc_boombox` starts.
{% endhint %}

***

### 7. Restart the Server

Restart your FiveM server after completing the installation.

Watch the server console for errors involving:

* `kc_boombox`
* `ox_lib`
* `xsound`
* Your selected inventory integration
* Your selected interaction system

If the resource starts without errors, continue with the in-game test.

***

### 8. Test the Boombox Item

Give yourself the following inventory item:

```
kc_boombox
```

Use the item from your inventory.

The Boombox placement system should begin.

***

### 9. Test Placement & Pickup

Confirm that you can:

* Start placement from the inventory item
* Position the Boombox
* Rotate the Boombox
* Confirm placement
* Cancel placement
* Interact with the placed Boombox
* Pick up the Boombox as its owner

{% hint style="success" %}
The inventory item is only removed after the server successfully creates the placed Boombox. Canceling placement should leave the item in your inventory.
{% endhint %}

***

### 10. Test Music Playback

Open the placed Boombox and test a supported music URL.

Confirm that:

* The interface opens correctly
* Music starts correctly
* Audio originates from the Boombox
* Audio fades naturally with distance
* Volume controls work
* Queue controls work
* The selected Boombox remains the one being controlled

***

### 11. Test Permissions

Test the Boombox with another citizen.

Confirm:

* The owner has full control
* **Others Around OFF** restricts normal nearby control
* **Others Around ON** allows nearby control
* Trusted Friends receive their intended control access
* Non-owners cannot pick up the Boombox

***

### 12. Test Persistence

Place a Boombox and perform your normal server restart test.

After the server is available again, confirm that the placed Boombox is restored.

{% hint style="info" %}
Placed Boomboxes are persistent across server restarts. Active music playback does not need to automatically resume after a full server restart.
{% endhint %}

***

### ✅ Installation Complete

Your **iKCScripts Boombox** installation is complete.

Continue to:

→ **⚙️** [**Configuration**](/docs/boombox/configuration.md)

Then review:

→ **📻** [**Using the Boombox**](/docs/boombox/using-the-boombox.md)

→ **🎵** [**Features**](/docs/boombox/features.md)

{% hint style="success" %}
Always complete an in-game test using the same inventory and interaction configuration your production server will use before making the resource available to your community.
{% endhint %}