# Developer

> Developer API reference for ML Radiation

Category: RADIATION ZONES · Source: https://miciomods.it/docs/ml-radiation-developer · Last updated: 2026-07-05

## Overview

Integration uses server/client exports for radiation state, handler hooks in the `open/` folder for custom logic, and a StateBag for real-time client-side access. Radiation is server-authoritative, the server only accepts increases from clients and handles all decreases internally. The mutating exports (`SetRadiation`, `AddRadiation`, `RemoveRadiation`) only accept calls from resources listed in `Config.AdminExportResources` (default: ml_radiation, ml_healthsystem, ml_staff); add your resource there to call them. `GetPlayerRadiation` is read-only and always open.

## Server Exports

### Radiation State

```lua
local radiation = exports.ml_radiation:GetPlayerRadiation(source)
exports.ml_radiation:SetRadiation(source, 500)
exports.ml_radiation:AddRadiation(source, 100)
exports.ml_radiation:RemoveRadiation(source, 200)
exports.ml_radiation:RemoveRadiation(source) -- removes all
```

- `GetPlayerRadiation(source)`: Returns current radiation level (0.0-1000.0)
- `SetRadiation(source, level)`: Sets radiation to a specific value. Clamped between 0 and `MaxRadiation`
- `AddRadiation(source, amount)`: Adds radiation to the current level
- `RemoveRadiation(source, amount?)`: Removes radiation. If `amount` is omitted, removes all radiation

## Client Exports

```lua
local radiation = exports.ml_radiation:GetRadiation()
```

- `GetRadiation()`: Returns the local player's current radiation level

## State Bags

The player's radiation level is written to the player's own StateBag (server-side on change, client mirror every second). It is set with replication disabled, so each client reads only its own value:

```lua
local radiation = LocalPlayer.state.radiation
```

Readable from the local player's own client scripts without exports.

## Server Handlers

Located in `open/server.lua`.

### Item Control

**open/server.lua**

```lua
function OpenServer.BeforeGiveItem(src, item, amount)
    return true -- return false to block
end
```

Called before giving an item to the player (cure/immunity items). Return `false` to block.

### Action Lifecycle

**open/server.lua**

```lua
function OpenServer.OnActionComplete(src, actionType, data)
end
```

Fires after an action completes (e.g. using a cure or immunity item).

## Client Handlers

Located in `open/client.lua`.

### Interaction

**open/client.lua**

```lua
function OpenClient.BeforeOpenUI(data)
    return true -- return false to block
end
```

Called before the Geiger Counter UI opens. Return `false` to block.

### Notifications

**open/client.lua**

```lua
function OpenClient.Notify(message, type)
    Bridge.Notify(message, type)
end
```

Override to use a custom notification system.

## Shared Handlers

Located in `open/shared.lua`.

**open/shared.lua**

```lua
function OpenHandlers.OnPlayerAction(src, data)
    return true -- return false to block
end

function OpenHandlers.ValidateAction(src, actionType)
    return true -- return false to block
end
```

- `OnPlayerAction`: Global hook before any action. Return `false` to block.
- `ValidateAction`: Pre-flight validation before an action is dispatched.

## Commands

- `/movegeiger`: Enter UI repositioning mode (Geiger must be open)
- `/resetgeigerpos`: Reset Geiger UI position to defaults
- `/setradiation [level]`: Sets your own radiation to a specific value (0-1000). Only registered when Config.Debug = true; it is a debug helper, not an admin command. It does not read `ServerConfig.AdminPermissions`

## Examples

**Read radiation from another script**

```lua
-- Server
local rad = exports.ml_radiation:GetPlayerRadiation(source)
if rad > 500 then
    Bridge.NotifyPlayer(source, 'warning', 'High radiation detected!')
end

-- Client (via StateBag, no export needed)
CreateThread(function()
    while true do
        local rad = LocalPlayer.state.radiation or 0
        if rad > 750 then
            -- trigger custom warning
        end
        Wait(5000)
    end
end)
```

**Block Geiger in certain zones**

**open/client.lua**

```lua
function OpenClient.BeforeOpenUI(data)
    local zone = GetNameOfZone(GetEntityCoords(cache.ped))
    if zone == 'AIRP' then
        Bridge.Notify('Cannot use Geiger here', 'error')
        return false
    end
    return true
end
```

**Grant immunity from another script**

```lua
-- Server: remove all radiation and add immunity via item system
exports.ml_radiation:RemoveRadiation(source)
```