Frameworks

The utils.fw module is designed to abstract framework-specific functionality across multiple popular frameworks, like QBCore, ESX, and others. This makes scripts compatible with different server setups out of the box. By centralizing the framework-specific logic in one place, it becomes easier to support multiple frameworks without scattering compatibility code throughout every script.

As more frameworks are supported, this module can be extended to include those as well, ensuring that no matter which framework a server runs, any scripts can integrate seamlessly

Initialization

Initializing the framework core is critical because it establishes a reliable reference (fw) that we can use throughout the scripts. Without initializing this core object, the scripts would be unable to access the framework's functions, player data, or other utilities.

• Framework Detection: The script first checks which framework is active by querying the state of popular resources. Once the correct framework is identified, it sets a global variable (FRAMEWORK) to reference it.

• Ensuring Correct Data Access: The rest of the bridge functions rely on this initial setup to determine which framework-specific methods to call. For example, getting player data in QBCore is different from doing so in ESX, so we need to know which framework we’re working with.

CreateThread(function()
    if GetResourceState('boii_core') == 'started' then
        FRAMEWORK = 'boii_core'
    elseif GetResourceState('qb-core') == 'started' then
        FRAMEWORK = 'qb-core'
    elseif GetResourceState('es_extended') == 'started' then
        FRAMEWORK = 'es_extended'
    elseif GetResourceState('ox_core') == 'started' then
        FRAMEWORK = 'ox_core'
    end

    while not FRAMEWORK do
        Wait(500)
    end
    
    if FRAMEWORK == 'boii_core' then
        fw = exports.boii_core:get_object()
    elseif FRAMEWORK == 'qb-core' then
        fw = exports['qb-core']:GetCoreObject()
    elseif FRAMEWORK == 'es_extended' then
        fw = exports['es_extended']:getSharedObject()
    elseif FRAMEWORK == 'ox_core' then
        local file = ('imports/%s.lua'):format(IsDuplicityVersion() and 'server' or 'client')
        local import = LoadResourceFile('ox_core', file)
        local chunk = assert(load(import, ('@@ox_core/%s'):format(file)))
        chunk()
        fw = Ox
    elseif FRAMEWORK == 'custom' then
        --- Custom framework initialization
    end

    return
end)

Functions

ESX functionality is lacking, most of them could be improved. ESX is something that has not been used in house for quite some time, they will be improved on in due course.

OX Core functions were initially coded for the LUA base, these have not been tested with the new TS core, currently unsure if any of them still work, these will be updated in due course.

get_data()

Retrieves a players client side data based on active framework.

Function

local function get_data(key)
    local player_data
    if FRAMEWORK == 'boii_core' then
        player_data = fw.get_data(key)
    elseif FRAMEWORK == 'qb-core' then
        player_data = fw.Functions.GetPlayerData()
    elseif FRAMEWORK == 'es_extended' then
        player_data = fw.GetPlayerData()
    elseif FRAMEWORK == 'ox_core' then
        player_data = fw.GetPlayerData()
    elseif FRAMEWORK == 'custom' then
        --- Custom framework logic
    end

    if not player_data then
        print('No player data found in get_data()')
    end

    return player_data
end

exports('fw_get_data', get_data)
utils.fw.get_data = get_data

Example

--- Retreive the data.
local data = utils.fw.get_data()

--- Print data as json string.
print('Data:', json.encode(data))

get_identity()

Retrieves players identity information.

Function

local function get_identity()
    local player = get_data()
    if not player then return false end

    local player_data

    if FRAMEWORK == 'boii_core' then
        player_data = {
            first_name = player.identity.first_name,
            last_name = player.identity.last_name,
            dob = player.identity.dob,
            sex = player.identity.sex,
            nationality = player.identity.nationality
        }
    elseif FRAMEWORK == 'qb-core' then
        player_data = {
            first_name = player.charinfo.firstname,
            last_name = player.charinfo.lastname,
            dob = player.charinfo.birthdate,
            sex = player.charinfo.gender,
            nationality = player.charinfo.nationality
        }
    elseif FRAMEWORK == 'es_extended' then
        player_data = {
            first_name = fw.GetPlayerData().firstName or 'firstName missing',
            last_name = fw.GetPlayerData().lastName or 'lastName missing',
            dob = fw.GetPlayerData().dateofbirth or 'dateofbirth missing',
            sex = fw.GetPlayerData().sex or 'sex missing',
            nationality = 'LS, Los Santos'
        }
    elseif FRAMEWORK == 'ox_core' then
        player_data = {
            first_name = player.firstName,
            last_name = player.lastName,
            dob = player.dob,
            sex = player.gender,
            nationality = 'LS, Los Santos'
        }
    elseif FRAMEWORK == 'custom' then
        --- Custom framework logic
    end
    return player_data
end

exports('fw_get_identity', get_identity)
utils.fw.get_identity = get_identity

Example

--- Retrieve identity.
local identity = utils.fw.get_identity()

--- Print players first name.
print('First Name:', identity.first_name)

get_player_id()

Retrieves players unique ID.

Function

local function get_player_id()
    local player = get_data()
    if not player then
        print('No player data found')
        return false
    end
    local player_id

    if FRAMEWORK == 'boii_core' then
        player_id = player.passport
    elseif FRAMEWORK == 'qb-core' then 
        player_id = player.citizenid
    elseif FRAMEWORK == 'es_extended' then
        player_id = player.identifier
    elseif FRAMEWORK == 'ox_core' then
        player_id = player.stateId
    elseif FRAMEWORK == 'custom' then
        --- Custom framework logic
    end

    if not player_id then
        print('player_id is nil')
    end

    return player_id
end

exports('fw_get_player_id', get_player_id)
utils.fw.get_player_id = get_player_id

Example

--- Retreive players id.
local player_id = utils.fw.get_player_id()

--- Print players id.
print('Player ID:', player_id)

player_has_job()

Callback function to check if player has a required job.

Function

local function player_has_job(jobs, on_duty, cb)
    utils.callback.cb('boii_utils:sv:player_has_job', { jobs = jobs, on_duty = on_duty }, function(has_job)
        cb(has_job)
    end)
end

exports('fw_player_has_job', player_has_job)
utils.fw.player_has_job = player_has_job

Example

--- Define jobs list.
local job_list = { 'police', 'ems' }
--- Toggle if on duty is required.
local on_duty_only = true

--- Check if player has one of the jobs and is on duty.
utils.fw.player_has_job(job_list, on_duty_only, function(has_job)
    if not has_job then print('Player does not meet the job requirements.') return end
    print('Player has the required job and is on duty.')
end)

get_player_job_grade()

Retrieve players job grade.

Function

local function get_player_job_grade(job, cb)
    utils.callback.cb('boii_utils:sv:get_player_job_grade', { job = job }, function(players_grade)
        cb(players_grade)
    end)
end

exports('fw_get_player_job_grade', get_player_job_grade)
utils.fw.get_player_job_grade = get_player_job_grade

Example

--- Define job name.
local job_name = 'police'

--- Retreive job grade if found.
utils.fw.get_player_job_grade('police', function(grade)
    if not grade then print('Grade not found for job.') return end
    print('Player job grade:', grade)
end)

get_inventory()

Retrieve players inventory data.

Function

local function get_inventory(cb)
    utils.callback.cb('boii_utils:sv:get_inventory', {}, function(inventory)
        cb(inventory)
    end)
end

exports('fw_get_inventory', get_inventory)
utils.fw.get_inventory = get_inventory

Example

--- Retreive and print inventory if found.
utils.fw.get_inventory(function(inventory)
    if not inventory then print('Inventory not found.') return end
    print('Player inventory:', json.encode(inventory))
end)

get_item()

Get a specific item in players inventory.

Function

local function get_item(item, cb)
    local item = tostring(item)
    utils.callback.cb('boii_utils:sv:get_item', { item_name = item }, function(item)
        cb(item)
    end)
end

exports('fw_get_item', get_item)
utils.fw.get_item = get_item

Example

--- Define item.
local item_id = 'water'

--- Check if player has item.
utils.fw.get_item(item_id, function(item)
    if not item then print('Item not found.') return end
    print('Item found:', json.encode(item))
end)

has_item()

Check if player has required item and quantity.

Function

local function has_item(item, amount, cb)
    local item = tostring(item)
    local amount = tonumber(amount) or 1
    utils.callback.cb('boii_utils:sv:has_item', { item_name = item, item_amount = amount }, function(has_item)
        cb(has_item)
    end)
end

exports('fw_has_item', has_item)
utils.fw.has_item = has_item

Example

--- Define item.
local item_id = 'water'
--- Define quantity.
local required_quantity = 5

--- Check if player has required item and correct quantity.
utils.fw.has_item(item_id, required_quantity, function(has_item)
    if not has_item then print('Player does not have enough of the required item.') return end
    print('Player has enough of the required item.')
end)