# Callbacks

The callback system allows server scripts to handle requests from clients and vice versa.

## RegisterServerCallback

Register a callback handler on the server that clients can trigger.

```lua
KOJA.Server.RegisterServerCallback(key, handler)
```

| Parameter | Type                            | Description                            |
| --------- | ------------------------------- | -------------------------------------- |
| `key`     | `string`                        | Callback identifier                    |
| `handler` | `function(source, payload, cb)` | Handler — call `cb(result)` to respond |

**Example**

```lua
KOJA.Server.RegisterServerCallback('myScript:getShopItems', function(source, payload, cb)
    local items = MySQL.query.await('SELECT * FROM shop_items WHERE category = ?', { payload.category })
    cb(items)
end)
```

**Triggered from the client:**

```lua
KOJA.Client.TriggerServerCallback('myScript:getShopItems', { category = 'food' }, function(items)
    for _, item in ipairs(items) do
        print(item.name, item.price)
    end
end)
```

## TriggerClientCallback

Trigger a callback registered on a specific client from the server.

```lua
KOJA.Server.TriggerClientCallback(key, playerId, payload, callback)
```

| Parameter  | Type            | Description                       |
| ---------- | --------------- | --------------------------------- |
| `key`      | `string`        | Callback identifier               |
| `playerId` | `number`        | Target player server ID           |
| `payload`  | `any`           | Data to send                      |
| `callback` | `function(...)` | Called with the client's response |

**Example**

```lua
KOJA.Server.TriggerClientCallback('myScript:getLocalCoords', source, nil, function(coords)
    print('Player is at:', coords.x, coords.y, coords.z)
end)
```

**Registered on the client:**

```lua
KOJA.Client.RegisterClientCallback('myScript:getLocalCoords', function(payload, cb)
    local pos = GetEntityCoords(PlayerPedId())
    cb({ x = pos.x, y = pos.y, z = pos.z })
end)
```

## TriggerCallback (internal)

Manually trigger an already-registered server callback from another server script.

```lua
KOJA.Server.TriggerCallback(key, source, payload, cb)
```

> This is mainly for internal use. Prefer `RegisterServerCallback` + client triggers for the standard pattern.

## Related pages

- [Police](/koja-lib/api-reference/server-api/police) — Functions for checking how many police officers are online.
- [Licenses](/koja-lib/api-reference/server-api/licenses) — Check whether a player holds a specific driving or skill license.
- [Money](/koja-lib/api-reference/server-api/money) — Functions for reading and modifying a player's money on the server.
- [Inventory](/koja-lib/api-reference/server-api/inventory) — Server-side inventory functions.
- [Notifications](/koja-lib/api-reference/server-api/notifications) — Send notifications to a player from the server side.
- [Player](/koja-lib/api-reference/server-api/player) — Functions for reading player information on the server.
- [Server API](/koja-lib/api-reference/server-api) — back to the section overview