> For the complete documentation index, see [llms.txt](https://docs.rainmad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainmad.com/resources/watch-admin-menu/reference/exports-and-events.md).

# Exports and events

For other scripts on your server. Everything a script does through rm\_watch goes through the same role check and staff log as the menu.

{% hint style="info" %}
**RedM:** the same exports and events exist under the resource name `rm_watch_redm`: `exports.rm_watch_redm:...` and `rm_watch_redm:server:...`.
{% endhint %}

## Server exports

### Staff and permissions

```lua
exports.rm_watch:hasPermission(source, 'ban', checkDuty)  -- true when that player's group may run the action
exports.rm_watch:getPlayerStaffGroup(source)              -- 'owner', 'admin', a custom group name, or false
exports.rm_watch:getPlayerStaffDutyState(source)          -- true or false
exports.rm_watch:setPlayerStaffDutyState(source, true)
exports.rm_watch:getStaffGroups()                         -- the three built-in roles with their ace
exports.rm_watch:getOnlineStaff(onlyOnDuty)               -- { { id, name, role, duty }, ... }
```

`checkDuty = true` also requires the player to be on duty when `cfg.admin.duty.required` is on.

### Punishments

The last argument is the name written in the staff log; it defaults to your resource's name.

```lua
exports.rm_watch:ban(source, hours, 'Reason', 'Anticheat')    -- hours 0 = permanent
exports.rm_watch:createBan({                                  -- a player who is not online
    name = 'John',
    identifiers = { 'license:abc...', 'discord:123...' },
    tokens = {},                                              -- optional hardware tokens
    reason = 'Ban evasion',
    hours = 0,
    staffName = 'Anticheat',
})
exports.rm_watch:removeBan(banId, 'Anticheat')
exports.rm_watch:warnPlayer(source, 'Reason', 'Anticheat')
exports.rm_watch:jail(source, minutes, 'Reason', 'Police')
exports.rm_watch:unjail(sourceOrIdentifier, 'Police')
exports.rm_watch:isMuted(source, 'chat')                      -- or 'voice'; true while muted
```

Use `isMuted` in your own chat commands (`/ooc`, `/me`, a phone) to refuse muted players.

### Vehicles

```lua
exports.rm_watch:keepVehicle(entity, true)   -- spare a server vehicle from the cleanup; false lets it go
```

### Queue

```lua
local function priority(source, identifiers)  -- identifiers: { license = '...', discord = '...' }
    if isBooster(identifiers.discord) then return 300, 'Booster' end
end
exports.rm_watch:registerQueuePriorityProvider(priority)
exports.rm_watch:unregisterQueuePriorityProvider(priority)
exports.rm_watch:getQueueSnapshot()  -- { enabled, max, players, entries = { { id, position, name, priority, staff, waited } } }
```

A provider returns a priority from 0 to 1000 and an optional label. The highest of `cfg.queue.priority` and all providers wins.

### Menu buttons

Add your own button to the menu, with its own role, run through the same check and log as the built-in ones:

```lua
exports.rm_watch:registerAction('starterpack', {
    label = 'Give starter pack',
    role = 'admin',          -- 'moderator' (default), 'admin' or 'owner'
    target = true,           -- acts on a player: shown in their profile's Tools tab
    quick = false,           -- true also offers it on the quick wheel as 'addon:starterpack'
    run = function(staffSrc, targetSrc, args)
        -- give the items
        return true          -- or false, 'message'
    end,
})
```

| Export                       | Draws                                                  | Your `run` gets                           |
| ---------------------------- | ------------------------------------------------------ | ----------------------------------------- |
| `registerAction(name, opts)` | A button                                               | `args`                                    |
| `registerSelect(name, opts)` | A dropdown, `opts.options = { { value, label }, ... }` | `args.option`                             |
| `registerToggle(name, opts)` | A switch                                               | `args.on`; return the state it settled on |

Without `target`, the control shows in the **Self** tab. The action is named `addon:<name>`, so it can be moved with `cfg.admin.permissions` and switched per group like any other.

### Dashboard numbers

```lua
exports.rm_watch:registerStatBlock('bank_total', {
    label = 'Money in banks',
    role = 'admin',                      -- who sees it, moderator by default
    get = function() return 123456 end,  -- a number or a string, read when the dashboard opens
})
```

### Staff chat

```lua
exports.rm_watch:chatPost('general', 'Anticheat', 'Possible speed hack: player 12')
```

Posts a line under the name you give. Channels: `'general'`, or `'g:<group>'` for a group's channel.

### Hooks

```lua
local stop = exports.rm_watch:registerHook('player_banned', function(data)
    print(data.playerName, data.reason)
end)
```

Every hook also fires as a server event, for scripts that prefer events:

```lua
AddEventHandler('rm_watch:server:player_banned', function(data) end)
```

| Hook                    | Data                                                                                                                   |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `player_banned`         | `banId`, `playerName`, `player`, `reason`, `identifiers`, `staffName`, `createdAt`, `expiresAt`                        |
| `player_unbanned`       | `banId`, `playerName`, `player`, `staffName`                                                                           |
| `player_kicked`         | `target`, `name`, `reason`, `staffName`, `staffId`                                                                     |
| `player_warned`         | `target`, `player`, `name`, `reason`, `staffName`, `staffId` (`offline = true` and no `target` for an offline warning) |
| `player_jailed`         | `target`, `player`, `name`, `duration` (minutes), `reason`, `staffName`, `staffId`                                     |
| `player_unjailed`       | `player`, `staffName` (`'time served'` when it ran out)                                                                |
| `player_muted`          | `target`, `player`, `name`, `kind`, `chat`, `voice`, `seconds`, `reason`, `staffName`, `staffId`                       |
| `player_unmuted`        | `player`, `name`, `staffName`                                                                                          |
| `player_commserv`       | `target`, `player`, `name`, `tasks`, `zone`, `reason`, `staffName`, `staffId`                                          |
| `player_commserv_done`  | `player`, `name`, `staffName`                                                                                          |
| `queue_player_admitted` | `name`, `waitedMs`, `priority`                                                                                         |
| `queue_player_removed`  | `name`, `reason`                                                                                                       |
| `report_created`        | `reportId`, `author_source`, `author_name`, `subject`, `category`, `priority`                                          |
| `report_closed`         | `reportId`, `closed_by`                                                                                                |
| `ticket_reply`          | `ticketId`, `author`, `staff`                                                                                          |
| `ticket_assigned`       | `ticketId`, `assignee`, `by`                                                                                           |
| `ticket_attachment`     | `ticketId`, `attachmentId`, `kind`, `mime`, `staff`                                                                    |
| `chat_message`          | `channel`, `id`, `author`, `body`, `web`                                                                               |
| `voice_note`            | `ref`, `channel` or `ticket`, `by`, `player`                                                                           |

`target` is the server id, `player` the primary identifier. `registerHook` returns a function that removes the hook.

## Client exports

```lua
exports.rm_watch:hideMenu()                    -- close the admin menu
exports.rm_watch:hasPermission('noclip')       -- what the menu allowed this player when it last opened

exports.rm_watch:registerZone('bank', {        -- an ox_lib zone rm_watch cleans up on restart
    kind = 'sphere',                           -- 'sphere', 'box' (size, rotation) or 'poly' (points, thickness)
    coords = vec3(150.0, -1040.0, 29.0),
    radius = 20.0,
    onEnter = function() end,
    onExit = function() end,
})
exports.rm_watch:removeZone('bank')
```

## Client events

Staff can draw named zones on the menu's map. Entering and leaving one fires:

```lua
AddEventHandler('rm_watch:client:zoneEnter', function(zone) print(zone.id, zone.label) end)
AddEventHandler('rm_watch:client:zoneExit', function(zone) end)
```
