# Configuration

All settings are found in `config.lua`. This guide explains each section in detail.

***

## General

```lua
Config.Locale = 'en'  -- 'en' or 'fr'
Config.Debug = false  -- Enable debug logs
```

| Parameter | Type    | Description                           |
| --------- | ------- | ------------------------------------- |
| `Locale`  | string  | Interface language (`'en'` or `'fr'`) |
| `Debug`   | boolean | Enables detailed logs in the console  |

***

## Bridge System (Multi-Framework)

{% hint style="info" %}
Framework, inventory, target, menu, and notification detection is now handled by **HZ-Bridge**. Configure these settings once in HZ-Bridge's `config.lua` and all Hz-Scripts inherit them automatically. See [HZ-Bridge Configuration](https://hz-script.gitbook.io/hz-script-docs/free-tools/hz-bridge/configuration).
{% endhint %}

***

## Permissions

```lua
Config.Permissions = {
    ConfiguratorCommand = 'admin',  -- Who can use /tvcfg
    BillboardCommand = 'admin',     -- Who can use /billboard
    UseTV = 'everyone',             -- Who can use TVs
    PlaceTV = 'everyone',           -- Who can place TVs
}
```

| Permission            | Options                                 | Description                 |
| --------------------- | --------------------------------------- | --------------------------- |
| `ConfiguratorCommand` | `'admin'`, `'everyone'`, `'job:police'` | Access to `/tvcfg`          |
| `BillboardCommand`    | `'admin'`, `'everyone'`, `'job:police'` | Access to `/billboard`      |
| `UseTV`               | `'admin'`, `'everyone'`, `'job:police'` | TV usage                    |
| `PlaceTV`             | `'admin'`, `'everyone'`, `'job:police'` | TV placement from inventory |

**Supported formats:**

* `'admin'`: Reserved for framework admins
* `'everyone'`: Accessible to all
* `'job:police'`: Reserved for `police` job
* `'job:ambulance,police'`: Multiple jobs (separated by `,`)

***

## Display & Audio

```lua
Config.Display = {
    MaxSoundDistance = 15.0,   -- Max distance to hear TV
    MinSoundDistance = 2.0,    -- Distance for max volume
    DefaultVolume = 0.5,       -- Default volume (0.0 - 1.0)
    RenderDistance = 50.0,     -- Screen render distance
}
```

| Parameter          | Type  | Description                                |
| ------------------ | ----- | ------------------------------------------ |
| `MaxSoundDistance` | float | Maximum distance to hear sound (in meters) |
| `MinSoundDistance` | float | Distance for maximum volume                |
| `DefaultVolume`    | float | Default volume (0.0 = muted, 1.0 = max)    |
| `RenderDistance`   | float | Video screen render distance               |

{% hint style="info" %}
Volume decreases progressively between `MinSoundDistance` and `MaxSoundDistance`.
{% endhint %}

***

## TV Placement

```lua
Config.Placer = {
    Enabled = true,           -- Enable placement system
    Persistence = false,      -- Database saving (requires oxmysql)
    MaxPerPlayer = 5,         -- Max TVs per player
    AllowPickup = true,       -- Allow picking up placed TVs
    OnlyOwnerPickup = true,   -- Only owner can pick up
}
```

| Parameter         | Type    | Description                               |
| ----------------- | ------- | ----------------------------------------- |
| `Enabled`         | boolean | Enable/disable TV placement               |
| `Persistence`     | boolean | Save placed TVs to database               |
| `MaxPerPlayer`    | integer | Limit of TVs placed per player            |
| `AllowPickup`     | boolean | Allow picking up placed TVs               |
| `OnlyOwnerPickup` | boolean | Only owner can pick up (admin can always) |

{% hint style="warning" %}
`Persistence = true` requires **oxmysql** and automatically creates the `hz_television_placed` table.
{% endhint %}

***

## Placement Controls

```lua
Config.PlacementControls = {
    RotateLeft = 'Q',         -- Rotate left
    RotateRight = 'E',        -- Rotate right
    TiltForward = 'Z',        -- Tilt forward
    TiltBackward = 'X',       -- Tilt backward
    MoveUp = 'SCROLLUP',      -- Move up
    MoveDown = 'SCROLLDOWN',  -- Move down
    SnapToGround = 'G',       -- Snap to ground
    Confirm = 'LEFTCLICK',    -- Place
    Cancel = 'RIGHTCLICK',    -- Cancel
}
```

All controls are customizable. See the [complete FiveM controls list](https://docs.fivem.net/docs/game-references/controls/).

***

## TV Models

```lua
Config.Models = {
    -- Classic TVs
    {
        model = 'prop_tv_flat_01',
        label = 'Flat Screen TV',
        type = 'tv',
        scale = { x = 0.5, y = 0.28 },
        offset = { x = 0.0, y = 0.0, z = 0.0 },
        rotation = { x = 0.0, y = 0.0, z = 0.0 },
    },
    {
        model = 'prop_tv_flat_02',
        label = 'Flat Screen TV (Large)',
        type = 'tv',
        scale = { x = 0.6, y = 0.35 },
        offset = { x = 0.0, y = 0.0, z = 0.0 },
        rotation = { x = 0.0, y = 0.0, z = 0.0 },
    },

    -- Billboards
    {
        model = 'prop_huge_display_01',
        label = 'Giant Billboard',
        type = 'billboard',
        scale = { x = 8.0, y = 4.5 },
        offset = { x = 0.0, y = 0.0, z = 2.0 },
        rotation = { x = 0.0, y = 0.0, z = 0.0 },
    },
}
```

### Adding a Custom Model

```lua
{
    model = 'my_custom_tv',           -- Model hash
    label = 'My Custom TV',           -- Display name
    type = 'tv',                      -- 'tv' or 'billboard'
    scale = { x = 0.5, y = 0.28 },   -- Screen size
    offset = { x = 0.0, y = 0.05, z = 0.0 },  -- Screen position
    rotation = { x = 0.0, y = 0.0, z = 0.0 }, -- Screen rotation
},
```

{% hint style="info" %}
Use `/tvcfg` in-game to easily calibrate `scale`, `offset` and `rotation` values with a 3D gizmo.
{% endhint %}

***

## Pre-recorded Channels

```lua
Config.Channels = {
    {
        name = 'Weazel News',
        url = 'https://www.youtube.com/watch?v=example',
        category = 'news',
    },
    {
        name = 'Music Radio',
        url = 'https://www.youtube.com/watch?v=example',
        category = 'music',
    },
}
```

| Parameter  | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `name`     | string | Channel name                     |
| `url`      | string | Video/stream URL                 |
| `category` | string | Category (optional, for sorting) |

Players can select these channels directly from the Smart TV menu.

***

## Commands

```lua
Config.Commands = {
    Configurator = 'tvcfg',    -- Open configurator
    Billboard = 'billboard',   -- Edit billboard
}
```

| Command      | Description                               |
| ------------ | ----------------------------------------- |
| `/tvcfg`     | Opens 3D configurator (must be near a TV) |
| `/billboard` | Edits nearby billboard content            |

***

## Inventory Items

```lua
Config.Items = {
    ['tv_flat_01'] = {
        model = 'prop_tv_flat_01',
        label = 'Flat Screen TV',
    },
    ['tv_flat_02'] = {
        model = 'prop_tv_flat_02',
        label = 'Flat Screen TV (Large)',
    },
    ['tv_monitor_01'] = {
        model = 'prop_monitor_02',
        label = 'PC Monitor',
    },
}
```

Add as many items as you want. Keys must match the items added to your inventory.

***

## Discord Webhooks (optional)

```lua
Config.Webhooks = {
    Enabled = false,
    PlaceTV = 'https://discord.com/api/webhooks/...',
    ConfigTV = 'https://discord.com/api/webhooks/...',
}
```

Enable Discord logs to track player actions.

***

## Advanced Configuration Examples

### "Strict Roleplay Server" Configuration

```lua
Config.Permissions = {
    ConfiguratorCommand = 'admin',
    BillboardCommand = 'job:police,admin',
    UseTV = 'everyone',
    PlaceTV = 'job:estate,admin',
}

Config.Placer = {
    Enabled = true,
    Persistence = true,
    MaxPerPlayer = 3,
    OnlyOwnerPickup = true,
}
```

### "Creative/Sandbox Server" Configuration

```lua
Config.Permissions = {
    ConfiguratorCommand = 'everyone',
    BillboardCommand = 'everyone',
    UseTV = 'everyone',
    PlaceTV = 'everyone',
}

Config.Placer = {
    Enabled = true,
    Persistence = true,
    MaxPerPlayer = 20,
    OnlyOwnerPickup = false,
}
```

***

{% hint style="success" %}
After modifying `config.lua`, restart the script with `ensure HZ-Television` or restart the server.
{% endhint %}