# Developer

> Developer API reference for ML Radio

Category: RADIO · Source: https://miciomods.it/docs/ml-radio-developer · Last updated: 2026-07-28

## Overview

Integration runs through two layers: editable handler files in `open/` (called via pcall, fail-closed on error) and exports. Mutating server exports are allowlist-gated: `ml_*` resources are allowed automatically, anything else must be added to `Config.AllowedExportResources` in `server/config_server.lua`.

## Server Exports

### Broadcast

- `GetActiveBroadcast(frequency)`: Current broadcast data for a frequency, or `nil`.
- `IsFrequencyBroadcasting(frequency)`: `true` while a station or autoplay is live on that frequency.
- `CanTransmitOnFrequency(src, frequency)`: Whether the player may talk on that frequency.
- `BootstrapAutoplay(stationId)`: Starts a station's autoplay playlist. Allowlist-gated.
- `PauseAutoplay(stationId)` / `ResumeAutoplay(stationId)`: Suspend and resume autoplay. Allowlist-gated.

### Antennas

- `GetFixedAntennas()`: Table of fixed towers with their live state.
- `DamageFixedAntenna(id, amount)`: Applies damage to a fixed tower. Allowlist-gated.
- `GetDisruptors()`: Table of active jammers.

### Inventory

- `radio`: Registered as the `usingItem` hook for ox_inventory; other inventories route through `ml_bridge` item binds.

## Client Exports

### Interface

- `OpenRadioUI()` / `CloseRadioUI()`: Open or close the handset interface.
- `OpenStereoMenu()` / `CloseStereoMenu()`: Stereo control panel.
- `GetActiveTheme()`: Current interface theme name.

### Signal

- `CalculateSignal(playerCoords)`: Current signal value for the local player.
- `GetSignalQuality(value?)`: Quality tier for a signal value.
- `IsSignalLost()`: `true` while the player has no usable reception.
- `IsInsideDisruptor()`: `true` inside an active jammer radius.

### Broadcast Audio

- `IsBroadcastPlaying(frequency)`: Whether station audio is playing locally.
- `SetBroadcastVolume(volume)`: Local station audio volume.
- `StopAllBroadcasts()`: Stops all locally playing station audio.
- `IsInSpeakerZone()`: `true` inside a configured speaker zone.

### Battery

- `RechargeBattery()`: Consumes a battery item to recharge the held radio.

## Server Handlers

Located in `open/server.lua`. All handlers are called via pcall; an error counts as a deny.

### OnChannelJoin

**open/server.lua**

```lua
function OpenServer.OnChannelJoin(src, frequency)
    return true -- return false to block the join
end
```

Fires before a player joins a frequency. Blocking keeps them off the channel.

### OnChannelLeave

**open/server.lua**

```lua
function OpenServer.OnChannelLeave(src, frequency)
end
```

Notification only, fires after a player leaves a frequency.

### CanHack

**open/server.lua**

```lua
function OpenServer.CanHack(src, antenna, isFixed)
    return true -- or: return false, 'locale_key'
end
```

Authorizes an antenna hack attempt, after the built-in item, distance and `requireSkill` checks. Return `false` plus a locale key to deny with a custom message.

### OnHackStart

**open/server.lua**

```lua
function OpenServer.OnHackStart(src, antenna, isFixed, itemUsed)
end
```

Fires when the server commits to the attempt, before the progress bar runs. Useful for attempt logs or stat counters.

### OnHackSuccess

**open/server.lua**

```lua
function OpenServer.OnHackSuccess(src, antenna, isFixed, itemUsed)
end
```

Fires after a successful hack: the item is consumed, the lockout and hack damage are applied, and clients are updated.

## Examples

**Award ml_skills XP for hacking**

**open/server.lua**

```lua
function OpenServer.OnHackStart(src, antenna, isFixed, itemUsed)
    exports.ml_skills:AddXp('personal', 5, src)
end

function OpenServer.OnHackSuccess(src, antenna, isFixed, itemUsed)
    exports.ml_skills:AddXp('personal', 50, src)
end
```

**Lock hacking behind an unlocked skill**

**open/server.lua**

```lua
function OpenServer.CanHack(src, antenna, isFixed)
    if not exports.ml_skills:HasUnlockedSkill(nil, 'signals_mastery_3', src) then
        return false, 'hack_skill_missing'
    end
    return true
end
```

**Start a station playlist from another resource**

```lua
-- from an ml_* resource, or one added to Config.AllowedExportResources
exports.ml_radio:BootstrapAutoplay('radio_station')
```