Callback Module Documentation

The Callback module provides a robust RPC (Remote Procedure Call) system for client-server communication in RedM scripts.

Getting Started

-- Client-side
local Callback = exports.bln_lib:callback()

-- Server-side
local Callback = exports.bln_lib:callback()

Server-Side Usage

Register a Callback

Callback.Register(name, callback)

Parameters

• name (string): Unique identifier for the callback
• callback (function): Function to handle the request
  • Parameters:
    • source (number): Player source
    • cb (function): Callback function to send response
    • ... (any): Additional parameters from client

Example

-- Register simple callback
Callback.Register('getPlayerMoney', function(source, cb)
    local money = 1000
    cb(money)
end)

-- Register callback with parameters
Callback.Register('checkPlayerCanBuy', function(source, cb, itemPrice)
    local playerMoney = 1000
    cb(playerMoney >= itemPrice)
end)

Trigger Client Callback

-- Async version
Callback.TriggerAsync(name, source, callback, ...)

-- Sync version (uses promises)
local result = Callback.TriggerAwait(name, source, ...)

Parameters

• name (string): Callback identifier
• source (number): Target player
• callback (function): Response handler (async only)
• ... (any): Additional parameters

Example

-- Async
Callback.TriggerAsync('getPlayerPosition', player, function(position)
    print(json.encode(position))
end)

-- Sync
local position = Callback.TriggerAwait('getPlayerPosition', player)
print(json.encode(position))

Client-Side Usage

Register a Callback

Callback.Register(name, callback)

Parameters

• name (string): Unique identifier for the callback
• callback (function): Function to handle the request
  • Parameters:
    • cb (function): Callback function to send response
    • ... (any): Additional parameters from server

Example

-- Register position callback
Callback.Register('getPlayerPosition', function(cb)
    local coords = GetEntityCoords(PlayerPedId())
    cb(coords)
end)

-- Register callback with parameters
Callback.Register('isPlayerNearCoords', function(cb, coords, distance)
    local playerCoords = GetEntityCoords(PlayerPedId())
    local isNear = #(playerCoords - coords) < distance
    cb(isNear)
end)

Trigger Server Callback

-- Async version
Callback.TriggerAsync(name, callback, ...)

-- Sync version (uses promises)
local result = Callback.TriggerAwait(name, ...)

Parameters

• name (string): Callback identifier
• callback (function): Response handler (async only)
• ... (any): Additional parameters

Example

-- Async usage
Callback.TriggerAsync('getPlayerMoney', function(money)
    print('Player has $' .. money)
end)

-- Sync usage
local money = Callback.TriggerAwait('getPlayerMoney')
print('Player has $' .. money)

Complete Examples

Inventory Check System

-- Server-side registration
Callback.Register('canPlayerCarryItem', function(source, cb, item, amount)
    local player = GetPlayer(source)
    local canCarry = player.inventory.canCarry(item, amount)
    cb(canCarry)
end)

-- Client-side usage
-- Async
Callback.TriggerAsync('canPlayerCarryItem', function(canCarry)
    if canCarry then
        print('Can carry item')
    else
        print('Cannot carry item')
    end
end, 'apple', 5)

-- Sync
local canCarry = Callback.TriggerAwait('canPlayerCarryItem', 'apple', 5)
if canCarry then
    print('Can carry item')
end

Player Position System

-- Client-side registration
Callback.Register('getDetailedPosition', function(cb)
    local ped = PlayerPedId()
    local coords = GetEntityCoords(ped)
    local heading = GetEntityHeading(ped)
    cb({
        pos = coords,
        heading = heading,
        ground = GetGroundZFor_3dCoord(coords.x, coords.y, coords.z)
    })
end)

-- Server-side usage
-- Async
Callback.TriggerAsync('getDetailedPosition', playerId, function(data)
    print(json.encode(data))
end)

-- Sync
local position = Callback.TriggerAwait('getDetailedPosition', playerId)
print(json.encode(position))

Best Practices

1. Use Meaningful Names

-- Good
Callback.Register('getPlayerInventory', ...)

-- Avoid
Callback.Register('gpi', ...)

2. Handle Errors

Callback.Register('sensitiveOperation', function(source, cb)
    if not IsPlayerAceAllowed(source, 'admin') then
        cb(false, 'Not authorized')
        return
    end
    -- Proceed with operation
    cb(true, 'Operation successful')
end)

3. Choose Async vs Sync Wisely

-- Use async for non-blocking operations
Callback.TriggerAsync('longOperation', function(result)
    -- Handle result
end)

-- Use sync for operations that need immediate results
local result = Callback.TriggerAwait('quickCheck')
if result then
    -- Proceed immediately
end

Performance Considerations

1. Avoid excessive callbacks for frequent operations
2. Use sync callbacks sparingly as they block execution
3. Consider batching multiple requests when possible
4. Clean up registered callbacks when no longer needed