# FAQ

## General

<details>

<summary>Is the script compatible with my framework?</summary>

HZ-Television supports **QBCore**, **ESX** and **Standalone** mode. The script automatically detects your framework via the Bridge system. Manually configure in `config.lua` → `Config.Bridge.Framework` if necessary.

</details>

<details>

<summary>Can we have multiple TVs with different content at the same time?</summary>

Yes! This is one of the main features. Each TV can broadcast different content (YouTube, Twitch, Kick, etc.) and players can see them all simultaneously.

</details>

<details>

<summary>How many players can watch a TV at the same time?</summary>

Unlimited. Synchronization is managed via state bags (server side), so all players near the TV will see the same content at the same time.

</details>

<details>

<summary>Does the script use a lot of resources?</summary>

No. HZ-Television is optimized: **0.01 ms** idle on client side, **0.03 ms** peak. Video rendering is handled by `generic_texture_renderer_gfx` which is very performant.

</details>

<details>

<summary>Can I use this script with vSync or qb-weathersync?</summary>

Yes, HZ-Television does not interfere with weather or time scripts. It only uses textures for video rendering.

</details>

***

## Installation

<details>

<summary>Error "generic_texture_renderer_gfx not found"</summary>

`generic_texture_renderer_gfx` is **required** for video rendering. Download it from [GitHub](https://github.com/pongo1231/fivem-gfx-thing) and add it **before** HZ-Television in your `server.cfg`.

</details>

<details>

<summary>Error "Menu system not detected"</summary>

The script requires `ox_lib` (recommended) or `qb-menu + qb-input`. Install one of them and start it **before** HZ-Television.

</details>

<details>

<summary>TV items don't appear in my inventory</summary>

You must manually add the items to your inventory system. Pre-configured files are provided in `HZ-Television/items/` for:

* ox\_inventory
* qb-inventory
* qs-inventory
* ESX (SQL)

Copy the content to the corresponding file of your inventory and restart the server.

</details>

<details>

<summary>How do I update the script?</summary>

1. Download the latest version from Keymaster
2. Make a **backup** of your `config.lua`
3. Replace all files except `config.lua`
4. Check the [Changelog](https://hz-script.gitbook.io/hz-script-docs/scripts/hz-television/changelog) for any new parameters
5. Restart the server

</details>

***

## Usage

<details>

<summary>Screen is black or nothing displays</summary>

**Common causes:**

1. `generic_texture_renderer_gfx` is not installed or started
2. The TV is not calibrated correctly → Use `/tvcfg` to adjust
3. The URL is invalid or blocked (some YouTube videos are restricted)
4. The TV model is not in `Config.Models`

**Solution:** Use `/tvcfg` near the TV and adjust Scale/Offset/Rotation values until the screen appears.

</details>

<details>

<summary>Sound doesn't work / sound too low</summary>

**Causes:**

1. The TV is off (Power OFF) → Turn it on via the menu
2. You are too far → Get closer (max `Config.Display.MaxSoundDistance`)
3. Volume is at 0 → Increase it in the Smart TV menu

**Solution:** Increase `Config.Display.MaxSoundDistance` in `config.lua` to extend sound range.

</details>

<details>

<summary>YouTube/Twitch doesn't work</summary>

**YouTube:**

* Some videos are blocked (embed disabled, regional restrictions)
* Use public videos without restrictions
* URLs of type `youtu.be` and `youtube.com/watch?v=` work

**Twitch:**

* Only use live channels
* Format: `https://www.twitch.tv/channelname`

**Kick:**

* Same as Twitch, only live streams
* Format: `https://kick.com/channelname`

</details>

<details>

<summary>How do I place a TV from inventory?</summary>

1. Add TV items to your inventory (see [Installation](https://hz-script.gitbook.io/hz-script-docs/scripts/hz-television/installation))
2. Use the item `tv_flat_01` (or other)
3. A 3D placement mode activates:
   * **Q/E**: Rotate left/right
   * **Z/X**: Tilt forward/backward
   * **Arrow keys**: Fine adjustments
   * **Scroll**: Move up/down
   * **G**: Snap to ground
   * **Left click**: Place
   * **Right click**: Cancel

</details>

<details>

<summary>How do I pick up a placed TV?</summary>

1. Approach the TV
2. Use your target system (ox\_target/qb-target)
3. Select **Pick Up TV**
4. The TV returns to your inventory

{% hint style="warning" %}
By default, only the owner (or an admin) can pick up a TV. Modify `Config.Placer.OnlyOwnerPickup` to change this behavior.
{% endhint %}

</details>

***

## Configuration

<details>

<summary>How do I add a custom TV model?</summary>

1. Open `config.lua`
2. Add an entry in `Config.Models`:

```lua
{
    model = 'my_custom_tv',
    label = 'My Custom 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 },
},
```

3. Place the TV in-game
4. Use `/tvcfg` to calibrate Scale/Offset/Rotation values with the 3D gizmo
5. Copy the final values to `config.lua`

</details>

<details>

<summary>How do I disable TV placement?</summary>

In `config.lua`:

```lua
Config.Placer = {
    Enabled = false,  -- Completely disables the system
}
```

Or limit via permissions:

```lua
Config.Permissions = {
    PlaceTV = 'admin',  -- Only admins can place TVs
}
```

</details>

<details>

<summary>How do I limit the number of TVs per player?</summary>

In `config.lua`:

```lua
Config.Placer = {
    MaxPerPlayer = 3,  -- Max 3 TVs per player
}
```

</details>

<details>

<summary>Placed TVs disappear on restart</summary>

Enable database persistence:

```lua
Config.Placer = {
    Persistence = true,  -- Requires oxmysql
}
```

The `hz_television_placed` table will be created automatically on restart.

</details>

<details>

<summary>How do I add pre-recorded channels?</summary>

In `config.lua`, add entries in `Config.Channels`:

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

Players will be able to select these channels directly from the Smart TV menu.

</details>

***

## Permissions

<details>

<summary>How do I reserve TVs for admins only?</summary>

In `config.lua`:

```lua
Config.Permissions = {
    UseTV = 'admin',
    PlaceTV = 'admin',
}
```

</details>

<details>

<summary>How do I authorize only certain jobs?</summary>

```lua
Config.Permissions = {
    UseTV = 'job:police,ambulance',  -- Police and ambulance
    PlaceTV = 'job:estate',          -- Real estate agent
}
```

Format: `'job:jobname1,jobname2'`

</details>

<details>

<summary>How do I give configurator access to moderators?</summary>

```lua
Config.Permissions = {
    ConfiguratorCommand = 'admin',  -- Change to 'everyone' or 'job:moderator'
}
```

Or create a custom permission in `bridge/permissions.lua`.

</details>

***

## Advanced Issues

<details>

<summary>TVs don't synchronize between players</summary>

**Causes:**

1. OneSync is not enabled → Enable it in `server.cfg`
2. State bags are not working → Check your FiveM version (build 2802+ recommended)

**Solution:** Make sure `onesync on` or `onesync_enabled 1` is in your `server.cfg`.

</details>

<details>

<summary>Lag / freeze when a TV turns on</summary>

**Causes:**

1. Too many active TVs at the same time
2. RenderDistance too high

**Solution:** Reduce `Config.Display.RenderDistance` in `config.lua` (ex: 30.0 instead of 50.0).

</details>

<details>

<summary>Error "Failed to load video" in F8 console</summary>

**Causes:**

1. Invalid URL or deleted video
2. YouTube video with embed disabled
3. Regional or age restrictions

**Solution:** Test the URL in a normal web browser. If it doesn't work in "embed" mode, it won't work in-game.

</details>

<details>

<summary>How do I disable billboards?</summary>

In `config.lua`, remove models of type `'billboard'` from `Config.Models`:

```lua
-- Comment or delete these lines
-- {
--     model = 'prop_huge_display_01',
--     type = 'billboard',
--     ...
-- },
```

</details>

***

## Integration with Other Scripts

<details>

<summary>How do I integrate with esx_property / qb-houses?</summary>

Use server exports to check property:

```lua
-- Example with esx_property
AddEventHandler('hz-televisionplaceTV', function(model, coords, heading)
    local src = source
    local isInOwnedProperty = exports['esx_property']:IsPlayerInOwnedProperty(src)

    if not isInOwnedProperty then
        TriggerClientEvent('esx:showNotification', src, 'You must be in your property!')
        CancelEvent()
    end
end)
```

See [Exports & Events](https://hz-script.gitbook.io/hz-script-docs/scripts/hz-television/exports) for more examples.

</details>

<details>

<summary>How do I broadcast an emergency alert on all TVs?</summary>

Use the server export `BroadcastToTV`:

```lua
RegisterCommand('emergency', function(source)
    if IsPlayerAdmin(source) then
        exports['HZ-Television']:BroadcastToTV('https://i.imgur.com/alert.png')
    end
end)
```

</details>

***

{% hint style="info" %}
Can't find your answer? Join our [Discord](https://discord.gg/D2jMNswvBM) and open a ticket in #support!
{% endhint %}