> 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/configuration.md).

# ⚙️  Configuration

Main settings for iKCScripts Boombox

The main settings for **iKCScripts Boombox** are located in:

```
config.lua
```

This file allows server owners to configure the resource for their framework, inventory, interaction system, audio preferences, permissions, and other supported behavior.

{% hint style="info" %}
After changing configuration settings, restart `kc_boombox` and test the affected feature in-game.
{% endhint %}

***

### 📦 Inventory System

Select the inventory integration used by your server.

Supported inventory integrations include:

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

Only the inventory integration selected in your configuration needs to be installed.

{% hint style="warning" %}
Make sure the configured inventory system matches the inventory actually running on your server. An incorrect selection can prevent the `kc_boombox` item from being used, removed, or returned correctly.
{% endhint %}

***

### 🎯 Interaction System

Select how citizens interact with placed Boomboxes.

Supported interaction options include:

* **ox\_lib TextUI**
* **ox\_target**
* **qb-target**

#### ox\_lib TextUI

Uses ox\_lib's TextUI system and does not require a separate target resource.

Owners receive:

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

Other nearby citizens receive:

```
[E] Open Boombox
```

#### ox\_target

Uses exact-entity targeting through **ox\_target**.

#### qb-target

Uses exact-entity targeting through **qb-target**.

{% hint style="info" %}
Boombox interactions are associated with the specific placed entity. The resource does not automatically switch control to another nearby Boombox.
{% endhint %}

***

### 🔊 Audio Distance

Controls how far away Boombox music can be heard.

Default:

```lua
Config.AudioDistance = 25.0
```

Music fades naturally as the listener moves farther away from the physical Boombox.

A larger value increases the listening area.

A smaller value keeps the music more localized.

***

### 🎛️ Control Distance

Controls how close a citizen must be to operate a Boombox.

Default:

```lua
Config.ControlDistance = 10.0
```

Protected playback actions are validated by the server.

Being able to hear a Boombox does not automatically mean the citizen is close enough to control it.

***

### 🎯 Target Distance

Controls the interaction distance when using a supported target interaction system.

Default:

```lua
Config.TargetDistance = 2.0
```

This keeps physical interaction with the Boombox close and intentional.

***

### 📍 Placement Distance

Controls how far from their character an owner can position a Boombox while placement mode is active.

Default:

```lua
Config.PlacementDistance = 10.0
```

The placement system prevents confirmation when the requested position is outside the permitted placement range.

***

### 🔉 Default Volume

Controls the starting volume used by the Boombox.

Default:

```lua
Config.DefaultVolume = 0.20
```

The value uses a decimal volume scale.

For example:

```
0.20 = 20%
0.50 = 50%
0.75 = 75%
```

***

### 🔊 Maximum Volume

Controls the highest volume that can be selected.

Default:

```lua
Config.MaxVolume = 0.75
```

This means the maximum configured volume is **75%**.

{% hint style="warning" %}
Increasing the maximum volume can make positional audio excessively loud and may reduce the intended distance-based listening experience.
{% endhint %}

***

### ⌨️ Volume Keybinds

The currently selected and authorized Boombox can be adjusted using keyboard volume controls.

Default keys:

```lua
Config.VolumeUpKey = 'PAGEUP'
Config.VolumeDownKey = 'PAGEDOWN'
```

In-game:

```
PAGE UP     Volume Up
PAGE DOWN   Volume Down
```

These keybinds affect only the specific Boombox that was selected by the citizen.

They do not automatically control the nearest Boombox.

***

### 🔢 Volume Step

Controls how much the volume changes each time the volume keybind is pressed.

Default:

```lua
Config.VolumeKeyStep = 0.05
```

With the default setting, each adjustment changes the volume by **5%**.

***

### 👥 Others Around

Controls the default permission behavior for nearby citizens.

Default:

```lua
Config.AllowOthersDefault = false
```

With the default set to `false`, newly used Boomboxes do not automatically allow normal nearby citizens to control playback.

The owner can change **Others Around** from the Boombox interface.

#### Others Around OFF

Normal nearby citizens cannot perform protected playback actions.

#### Others Around ON

Nearby citizens can control supported playback functions while they remain within the configured control distance.

{% hint style="info" %}
Others Around does not provide ownership. Non-owners cannot pick up the Boombox.
{% endhint %}

***

### 👥 Trusted Friends

Trusted Friends provide persistent control access to specific friends chosen by the owner.

A Trusted Friend can control the owner's Boombox while nearby even when:

**Others Around = OFF**

Trusted Friends still need to remain within the configured control distance.

Trusted Friends cannot:

* Pick up the owner's Boombox
* Become the Boombox owner
* Manage the owner's Trusted Friends
* Bypass owner-only actions

The permission order is:

```
Owner
  ↓
Trusted Friend
  ↓
Others Around
  ↓
View Only
```

See:

→ **👥** [**Trusted Friends**](/docs/boombox/features/trusted-friends.md)

***

### 💾 Persistence

Placed Boomboxes are stored persistently by the server.

This allows physical Boomboxes to be restored after server or resource restarts.

Persistent data is handled automatically by the resource.

{% hint style="warning" %}
Do not manually delete or reset Boombox data files on a live server unless you intentionally want to remove the corresponding stored data.
{% endhint %}

***

### 🐞 Debug Mode

Debug functionality is available for troubleshooting.

Default:

```lua
Config.Debug = false
```

Leave Debug disabled on a normal production server.

Enable it temporarily when troubleshooting or when requested during support.

***

### 📋 Recommended Default Configuration

The standard configuration provides a balanced starting point:

```lua
Config = {}

Config.Item = 'kc_boombox'
Config.Prop = 'prop_boombox_01'

Config.AudioDistance = 25.0
Config.ControlDistance = 10.0
Config.TargetDistance = 2.0
Config.PlacementDistance = 10.0

Config.DefaultVolume = 0.20
Config.MaxVolume = 0.75

Config.VolumeUpKey = 'PAGEUP'
Config.VolumeDownKey = 'PAGEDOWN'
Config.VolumeKeyStep = 0.05

Config.AllowOthersDefault = false

Config.Debug = false
```

{% hint style="info" %}
Your complete `config.lua` may contain additional integration or resource settings. Use the configuration file included with your version of Boombox as the authoritative reference for available options.
{% endhint %}

***

### 🔄 Applying Changes

After editing `config.lua`, restart:

```
kc_boombox
```

Then test the setting you changed.

For changes involving the inventory or framework integration, a full server restart may be preferable to ensure all framework and shared-item data is loaded correctly.

***

### ✅ Configuration Complete

Once your settings are configured, continue to:

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

For individual music and permission systems, see:

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

For common problems, see:

→ **🧰** [**Troubleshooting**](/docs/boombox/help/troubleshooting.md)

{% hint style="success" %}
Keep a backup of your working `config.lua` before making significant configuration changes.
{% endhint %}