Frameworks

CLIENT & SERVER

The Framework Bridge abstracts framework-specific logic into a common, easy-to-use API, allowing seamless interaction with multiple frameworks such as boii_core, qb-core, es_extended, and ox_core.

By consolidating functionality into a single bridge, developers can write framework-independent code, improving maintainability and scalability.

Addtional default support will be added for other frameworks as time progresses. If your framework is not currently covered and you would like it to be, reach out through discord.

Client Functions

get_data

Use the following function to retrieve the players client side across any covered framework.

--- Utils object
local player_data = utils.fw.get_data()

print('Player Data:', json.encode(player_data))

--- Direct export
local player_data = exports.boii_utils:get_data()

print('Player Data:', json.encode(player_data))

get_identity

Use the following function to retrieve the players identity information.

--- Utils object
local identity = utils.fw.get_identity()

print('Identity:', json.encode(identity))

--- Direct export
local identity = exports.boii_utils:get_identity()

print('Identity:', json.encode(identity))

get_player_id

Use the following function to return the player characters unique identifier. ('passport', 'citizenid', 'stateId', 'identifier', ... )

--- Utils object
local unique_id = utils.fw.get_player_id()

print('Unique ID:', unique_id)

--- Direct export
local unique_id = exports.boii_utils:get_player_id()

print('Unique ID:', unique_id)

player_has_job

Use the following function to check if a player has a specific job with an optional on duty check.

 --- Specify job/s
local jobs = { 'police', 'fib' }
--- If true player must be on duty to pass job check
local require_on_duty = true

--- Utils object
utils.fw.player_has_job(jobs, require_on_duty, function(has_job)
    if has_job then
        print('Player has job.')
    else
        print('Player does not have job.')
    end
end)

--- Direct export
exports.boii_utils:player_has_job(jobs, require_on_duty, function(has_job)
    if has_job then
        print('Player has job.')
    else
        print('Player does not have job.')
    end
end)

get_player_job_grade

Use the following function to return the players grade for a specific job.

--- Specify job
local job = 'police'

--- Utils object
utils.fw.get_player_job_grade(job, function(job_grade)
    if job_grade then
        print('Players job grade: ', job_grade)
    else
        print('No grade found.')
    end
end)

--- Direct export
exports.boii_utils:get_player_job_grade(job, function(job_grade)
    if job_grade then
        print('Players job grade: ', job_grade)
    else
        print('No grade found.')
    end
end)

get_inventory

Use the following function to retrieve the players inventory data.

--- Utils object
utils.fw.get_inventory(function(inventory)
    if inventory then
        print('Players Inventory: ', json.encode(inventory))
    else
        print('No inventory found.')
    end
end)

--- Direct export
exports.boii_utils:get_inventory(function(inventory)
    if inventory then
        print('Players Inventory: ', json.encode(inventory))
    else
        print('No inventory found.')
    end
end)

get_item

Use the following function to retrieve data for a specific item in the players inventory.

--- Specify item
local item = 'lockpick'

--- Utils object
utils.fw.get_item(item, function(inv_item)
    if inv_item then
        print('Item:', json.encode(inv_item))
    else
        print('No item found.')
    end    
end)

--- Direct export
exports.boii_utils:get_item(item, function(inv_item)
    if inv_item then
        print('Item:', json.encode(inv_item))
    else
        print('No item found.')
    end    
end)

has_item

Use the following function to check if a player has a specified item and quantity.

--- Specify item
local item = 'lockpick'
--- Specify quantity
local quantity = 1

--- Utils export
utils.fw.has_item(item, quantity, function(has_item)
    if has_item then
        print('Player has item.')
    else
        print('Player does not have item.')
    end    
end)

--- Direct export
exports.boii_utils:has_item(item, quantity, function(has_item)
    if has_item then
        print('Player has item.')
    else
        print('Player does not have item.')
    end    
end)

Server Functions

get_players

Use the following to retrieve all framework players currently connected.

--- Utils object
local players = utils.fw.get_players()

print('Players:', json.encode(players)

--- Direct export
local players = exports.boii_utils:get_players()

get_player

Use the following to retrieve a players object.

--- Utils object
local player = utils.fw.get_player(source)

if player then print('Player exists!') end

--- Direct export
local player = exports.boii_utils:get_player(source)

get_player_id

Use the following to retrieve the unique id for the character the player is using. The unique id is the characters citizenidfor qb, stateIdfor ox, identifierfor esx and so on.

--- Utils object
local player_id = utils.fw.get_player_id(source)

print('Player ID:', player_id)

--- Direct export
local player_id = exports.boii_utils:get_player_id(source)

get_id_params

Use the following to get required player parameters for database entries.

--- Utils object
local query, params = utils.fw.get_id_params(source)

print('Query:', query)
print('Params:', json.encode(params))

--- Direct export
local query, params = exports.boii_utils:get_id_params(source)

get_insert_params

Use the following to get prepared database insert data.

--- Utils object
local columns, values, params = utils.fw.get_insert_params(source)

print('Columns:', json.encode(columns))
print('Values:', values)
print('Params:', json.encode(params))

--- Direct export
local columns, values, params = exports.boii_utils:get_insert_params(source)

get_identity

Use the following to retrieve the players current character identity data, e.g. first name, last name etc.

--- Utils object
local identity = utils.fw.get_identity(source)

print('Identity:', json.encode(identity))

--- Direct export
local identity = exports.boii_utils:get_identity(source)

has_item

Use the following to check if a player has a specific item in their inventory and the correct quantity.

--- Utils object
local has_item = utils.fw.has_item(source, 'water', 2)

if has_item then print('Player has enough water!') end

--- Direct export
local has_item = exports.boii_utils:has_item(source, 'water', 2)

get_item

Use the following to get a specified item from a players inventory.

--- Utils object
local item = utils.fw.get_item(source, 'water')

print('Item:', json.encode(item))

--- Direct export
local item = exports.boii_utils:get_item(source, 'water')

get_inventory

Use the following to retrieve the players inventory.

--- Utils object
local inventory = utils.fw.get_inventory(source)

print('Inventory:', json.encode(inventory))

--- Direct export
local inventory = exports.boii_utils:get_inventory(source)

adjust_inventory

Use the following to adjust a players inventory. This is a little different to the normal but allows for batch updating if required and saves some space when coding for multiple item transactions within a script. The code example below has been commented to help guide this a little better.

--- Utils object
utils.fw.adjust_inventory(source, {
    items = { -- Items
        { 
            item_id = 'burger', -- Unique ID for the item
            action = 'add', -- Action to perform 'add' or 'remove'
            quantity = 3, -- Quantity to remove or add
            data = { quality = 100 } -- Optional additional data if required
        },
        { item_id = 'water', action = 'remove', quantity = 1 },
    }, 
    validation_data = { -- Valdation data is optional this can be removed if not used
        location = vector3(100.0, 100.0, 20.0), -- Coordinates for the action e.g. shopkeeper
        distance = 10.0, -- The distance player can be from the location
        drop_player = true -- Enable/disable kicking player if they are out of range
    },
    note = 'Received items.', -- Note if required for logging
    should_save = true -- Only relevant to boii_core as data can be force saved if required
})

--- Direct export
exports.boii_utils:adjust_inventory(source, {
    items = { { item_id = 'burger', action = 'add', quantity = 3 } },
    note = 'Received items.', -- Note if required for logging
    should_save = true -- Only relevant to boii_core as data can be force saved if required
})

update_item_data

Use the following to update the metadata of an item.

--- Utils object
utils.fw.update_item_data(source, 'water', { quality = 50 })

--- Direct exports
exports.boii_utils:update_item_data(source, 'water', { quality = 50 })

get_balances

Use the following to retrieve all balances a player has.

--- Utils object
local balances = utils.fw.get_balances(source)

print('Balances:', json.encode(balances))

--- Direct export
local balances = exports.boii_utils:get_balance(source)

get_balance_by_type

Use the following to retrieve a specific balance by type.

--- Utils object
local balance = utils.fw.get_balance_by_type(source, 'bank')

print('Balance:', tonumber(balance))

--- Direct exports
local balance = exports.boii_utils:get_balance_by_type(source, 'bank')

adjust_balance

Use the following to adjust a players balances. This is a little different to the normal but allows for batch updating if required and saves some space when coding for multiple balance transactions within a script. The code example below has been commented to help guide this a little better.

--- Utils object
utils.fw.adjust_balance(source, {
    operations = { -- Operations
        { 
            balance_type = 'bank', -- Balance type to adjust
            action = 'remove', -- Action to perform 'add' or 'remove'
            amount = 1000 -- Amount to add or remove
        },
        { balance_type = 'savings', action = 'add', amount = 1000 }
    }, 
    validation_data = { -- Valdation data is optional this can be removed if not used
        location = vector3(100.0, 100.0, 20.0), -- Coordinates for the action e.g. shopkeeper
        distance = 10.0, -- The distance player can be from the location
        drop_player = true -- Enable/disable kicking player if they are out of range
    },
    note = 'Made a transfer..', -- Note if required for logging
    should_save = true -- Only relevant to boii_core as data can be force saved if required

})

--- Direct export
exports.boii_utils:adjust_balance(source, {
    operations = { -- Operations
        { balance_type = 'bank', action = 'remove', amount = 1000 },
        { balance_type = 'savings', action = 'add', amount = 1000 }
    }, 
    note = 'Made a transfer..', -- Note if required for logging
    should_save = true -- Only relevant to boii_core as data can be force saved if required
})

get_player_jobs

Use the following to retrieve the players jobs. This includes boii_core's roles & ox_core's groups.

--- Utils object
local player_jobs = utils.fw.get_player_jobs(source)

print('Player jobs:', json.encode(player_jobs))

--- Direct exports
local player_jobs = exports.boii_utils:get_player_jobs(source)

player_has_job

Use the following to check if the player has one of the jobs specified. You can specify as many different jobs you want, along with an optional on duty check.

--- Specify jobs
local jobs = { 'police', 'fib' }
--- Specify if players should be on duty to count
local on_duty_required = true

--- Utils object
local has_job = utils.fw.player_has_job(source, jobs, on_duty_required)

if has_job then print('Player has job!') end

--- Direct export
local has_job = exports.boii_utils:player_has_job(source, jobs, on_duty_required)

get_player_job_grade

Use the following to retrieve the players grade/rank for a specified job.

--- Utils object
local job_grade = utils.fw.get_player_job_grade(source, 'police')

print('Job grade:', job_grade)

--- Direct exports
local job_grade = exports.boii_utils:get_player_job_grade(source, 'police')

count_players_by_job

Use the following to retrieve a count of players by specified job names. This is useful for returning police counts, can optionally only check for players on duty.

--- Specify jobs
local jobs = { 'police', 'fib' }
--- Specify if players should be on duty to count
local on_duty_required = true

--- Utils object
local total_with_job, total_on_duty = utils.fw.count_player_with_job(jobs, on_duty_required)

--- Direct export
local total_with_job, total_on_duty = exports.boii_utils:count_player_with_job(jobs, on_duty_required)

get_player_job_name

Use the following to the first job name found for a player.

--- Utils object
local job_name = utils.fw.get_player_job_name(source)

print('Job name:', job_name)

--- Direct export
local job_name = exports.boii_utils:get_player_job_name(source)

adjust_statuses

Use the following to adjust a players statuses.

--- Specify statuses
local statuses = {
    health = 100,
    armour = 50,
    thirst = 100
}

--- Utils object
utils.fw.adjust_statuses(source, statuses)

--- Direct export
exports.boii_utils:adjust_statuses(source, statuses)

register_item

Use the following to register an item.

--- Utils object
utils.fw.register_item('water', function() 
    print('Used water.')
end)

--- Direct export
exports.boii_utils:register_item('water', function() 
    print('Used water.')
end)