# nova\_radio

NOVA Framework in-game radio system. Provides frequency-based voice communication channels with an inventory item requirement and pma-voice integration.

## Features

* **Frequency Channels** — Join any frequency from 0 to 999.99
* **Volume Control** — Adjustable radio volume
* **Favorites** — Save up to 5 favorite frequencies
* **Radio Item** — Requires a `radio` item in inventory to use
* **PTT Animation** — Push-to-talk animation when speaking
* **Radio Animation** — Open/close radio animation with prop
* **Restricted Channels** — Job/gang-restricted frequencies
* **Channel Names** — Named channels for easy identification
* **Keybind Support** — Optional keybind to open radio

## Configuration

Edit `config.lua`:

```lua
RadioConfig = {
    MaxFrequency = 999.99,
    DefaultVolume = 50,
    MaxFavorites = 5,
    RadioItem = 'radio',            -- Required inventory item

    OpenWithKeybind = true,
    -- Keybind defined in client/main.lua

    RestrictedChannels = {
        { freq = 1.0, type = 'job', names = { 'policia' }, requireDuty = true },
        { freq = 2.0, type = 'job', names = { 'ambulancia' }, requireDuty = true },
        { freq = 3.0, type = 'job', names = { 'mecanico' }, requireDuty = false },
        -- More restricted channels...
    },

    ChannelNames = {
        [1.0] = 'Polícia',
        [2.0] = 'Ambulância',
        [3.0] = 'Mecânico',
    },
}
```

### Configuration Options

| Option               | Type    | Description                             |
| -------------------- | ------- | --------------------------------------- |
| `MaxFrequency`       | number  | Maximum frequency value                 |
| `DefaultVolume`      | number  | Default volume (0–100)                  |
| `MaxFavorites`       | number  | Max saved favorite frequencies          |
| `RadioItem`          | string  | Item name required in inventory         |
| `OpenWithKeybind`    | boolean | Allow opening via keybind               |
| `RestrictedChannels` | table   | Channels limited to specific jobs/gangs |
| `ChannelNames`       | table   | Display names for frequencies           |

### Restricted Channels

Channels can be restricted by job or gang:

```lua
{
    freq = 1.0,
    type = 'job',                   -- 'job' or 'gang'
    names = { 'policia' },          -- Allowed job/gang names
    requireDuty = true,             -- Must be on duty?
}
```

## How It Works

1. Player must have the `radio` item in their inventory
2. Open radio via keybind or using the item
3. Enter a frequency to join a channel
4. PTT (Push-to-Talk) activates voice transmission
5. Other players on the same frequency hear the transmission
6. Animations and prop are shown during use

## Dependencies

* **nova\_core** — Player data, job/gang checks
* **nova\_inventory** — Radio item requirement
* **nova\_notify** — Notifications
* **pma-voice** — Voice communication backend

## Notes

* The radio NUI displays current frequency, volume, and connected players
* If the radio item is removed from inventory, the player is disconnected
* pma-voice handles the actual voice transmission; this script manages channel logic
* PTT state is synced to pma-voice via `pma-voice:radioActive`
* The UI uses a dark theme consistent with other NOVA scripts

## Security

* All actions are validated server-side with permission checks
* Event names and internal implementation details are not disclosed in this documentation for security purposes
* Unauthorized access attempts are logged