API

Keymapping

• F2: Opens the action menu.

• TAB: Opens player inventory.

• LEFTALT: Activates target.

Commands

Global

• /id: Sends a notification to player containing their current server ID.

• /logout: Logs out of the current character and returns to character selection.

Admin

All admins must be set within the user_accounts table created by boii_utils, you can use any rank names this does not matter.

• /tpm: Teleports the player to a marker if one is placed.

• /car [vehicle]: Spawns a vehicle if one is specified if not defaults to adder.

• /dv: Deletes the nearest vehicle or the vehicle you are inside.

• /repair: Repairs the nearest vehicle or the vehicle you are inside.

• /revive <id>: Revives a player by specifying their server ID.

• /adjust_balance <id> <type> <action> <amount>: Adjusts the players balance, you must specify their ID, the type of balance to adjust *(bank, cash, savings)*, specify the action to perform *(add, remove, set)*, and specify the amount.

• /setjob <id> <job_id> <grade_id> [old_job_id]: Sets a players job. If you wish to replace a secondary job with another secondary job you must declare the old job id to replace.

Core Functions

If you would like to use the core object functions externally you can do so by adding the following into the resource you are working on. This should be added into both server side and client if you are working with both sides, or placed into a shared location to allow both sides to have access.

local boii = exports.boii_core:get_object()

If the above line was added correctly you will then be able to directly access object functions.

Example

-- Retrieve the object
local boii = exports.boii_core:get_object()

-- Accessing the object functions
local player = boii.get_data()

Client

get_data

The following is used to retrieve a players data on the client. You can use either object functions or exports to do this.

You can choose to either get the entire data table or you can specify a key if you prefer.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the entire data table
local player_data = boii.get_data()

-- Print to display the players client data
print('Player Data: ' .. json.encode(player_data))

-- Retreiving a specific key from the table
local bank = boii.get_data('balances')

-- Print to display the players bank details
print('Bank Details: ' .. json.encode(bank))

Using Exports:

-- Retrieving the entire data table
local player_data = exports.boii_core:get_data()

-- Print to display the players client data
print('Player Data: ' .. json.encode(player_data))

-- Retreiving a specific key from the table
local bank = exports.boii_core:get_data('balances')

-- Print to display the players bank details
print('Bank Details: ' .. json.encode(bank))

Server

get_players

The following returns all current connected players. You can use either object functions or exports to do this.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the players table
local players = boii.get_players()

-- Print to display the players table
print('Players: ' .. json.encode(players))

Using Exports:

-- Retrieving the players table
local players = exports.boii_core:get_players()

-- Print to display the players table
print('Players: ' .. json.encode(players))

get_player

The following returns a specific player by searching through players for a matching source ID. You can use either object functions or exports to do this. Whenever you are using any object function you should be retrieving the player first using this.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the player
local _src = source
local player = boii.get_player(_src)

-- Print to display player object
print('Player: ' .. json.encode(player))

Using Exports:

-- Retrieving the player
local _src = source
local player = exports.boii_core:get_player(_src)

-- Print to display player object
print('Player: ' .. json.encode(player))

get_identifier

The following is used to retrieve a specified player identifier. You can use either object functions or exports to do this.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the player
local _src = source
local player_license = boii.get_identifier(_src, 'license')

-- Print to display players licence
print('Player License: ' .. json.encode(player_license ))

Using Exports:

-- Retrieving the player
local _src = source
local player = exports.boii_core:get_identifier(_src, 'license')

-- Print to display players licence
print('Player License: ' .. json.encode(player_license ))

get_unique_id

The following can be used to retrieve the players unique ID from the user_accounts table. This is retrieved by using the players license identifier type. You can use either object functions or exports to do this.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the player
local _src = source
local player_license = boii.get_identifier(_src, 'license')
local unique_id = boii.get_unique_id(player_license)

-- Print to display players unique id
print('Players Unique ID: ' .. json.encode(unique_id))

Using Exports:

-- Retrieving the player
local _src = source
local player = exports.boii_core:get_identifier(_src, 'license')
local unique_id = exports.boii_core:get_unique_id(player_license)

-- Print to display players unique id
print('Players Unique ID: ' .. json.encode(unique_id))

Shared

get_shared_data

The following is used to retrieve data from the shared data sets. However, all data in here is currently place holder, it is all subject to change and be replaced with standalone boii resources *(statuses, items for example)* so this is mostly redundant. You can use either object functions or exports to do this.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retreiving a specific data table
local gang_data = boii.shared.get_shared_data('gangs', 'ballas')

-- Print the shared data for the ballas gang
print('Ballas Gang: ' .. json.encode(gang_data))

Using Exports:

-- Retreiving a specific data table
local gang_data = exports.boii_core:get_shared_data('gangs', 'ballas')

-- Print the shared data for the ballas gang
print('Ballas Gang: ' .. json.encode(gang_data))

Player Object

The following functions can be used directly on the players object. In order to use any of these you first need to retrieve the correct player. You can do this using the server side function get_player.

Using Object Functions:

-- First retreive the object if you have not already added into your script
local boii = exports.boii_core:get_object()

-- Retrieving the player
local _src = source
local player = boii.get_player(_src)

-- Print to display player object
print('Player: ' .. json.encode(player))

Using Exports:

-- Retrieving the player
local _src = source
local player = exports.boii_core:get_player(_src)

-- Print to display player object
print('Player: ' .. json.encode(player))

add_method

The following can be used to add methods to the player object externally if required.

player.add_method('new_method_name', new_method)

Usage

-- Retrieve the player object
local _src = source
local player = boii.get_player(_src)
if not player then return print('Player not found') end

-- Define a new method
local function new_method(player, param1, param2)
    -- ... (implementation of the new method)
end

-- Add the new method to the player object
player.add_method('new_method_name', new_method)

-- Now you can call the new method like any other method of the player object
player.new_method_name(param1, param2)

Example

-- Let's say you want to add a method to set a player's job title
local function set_job_title(player, job_title)
    player.data.job_title = job_title
    print('Job title set to ' .. job_title .. ' for player ' .. player.source)
end

-- Add the new method
player.add_method('set_job_title', set_job_title)

-- Call the new method
player.set_job_title('Software Developer')

modify_balances

The following can be used to modify the players balances.

However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.adjust_balance() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.modify_balances(operations, reason, should_save)

Usage

-- Retrieve the player object
local _src = source
local player = boii.get_player(_src)

-- Define your operations
local operations = {
    { balance_type = 'bank', action = 'remove', amount = 1000 },
    { balance_type = 'savings', action = 'add', amount = 1000 }
}

-- Call the function
-- @param operations table: Table of operations to run
-- @param reason string: The reason the players balance was modified
-- @param should_save boolean: Toggle if modifications should be saved to database
player.modify_balances(operations, reason, should_save)

Core Example

-- Example function
local function test_function(_src)
    -- Retrieve the player object for incoming source id
    local player = boii.get_player(_src)
    if not player then print('Player not found') return end
    
    -- Define your operations
    local operations = {
        { balance_type = 'bank', action = 'remove', amount = 1000 },
        { balance_type = 'savings', action = 'add', amount = 1000 }
    }
    
    -- Call the function
    player.modify_balances(operations, 'Transfered money from bank to savings.', true)
end

Utils Example

-- Example function
local function test_function(_src)    
    -- Define your operations
    local operations = {
        {balance_type = 'bank', action = 'remove', amount = 1000},
        {balance_type = 'savings', action = 'add', amount = 1000}
    }
    
    -- Utils supports additional validation data, anyone not in range can be kicked for potential exploits
    local validation_data = { location = vector3(100.0, 100.0, 20.0), distance = 10.0, drop_player = true }
    
    -- Call utils function
    utils.fw.adjust_balance(_src, {
        operations = operations, 
        validation_data = validation_data, 
        reason = 'Transfer from bank to savings', 
        should_save = true
    })
end

set_job

The following function can be used to set or change a players job.

By default the core supports the use of multi jobs. This is done by giving players the following:

• 1 Primary Job: To be used by things like EMS, Police etc.

• Limited number of secondary jobs: To be used by things like farmer, miner etc. Default is 2 max secondary jobs, this can be adjusted in config.

The aim here is to keep core jobs specific to the main slot, but allow users of those jobs the opportunity to take on any other smaller jobs around the server.

player.set_job(job_id, grade_id, job_id_to_replace)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Set the players job
player.set_job(job_id, grade_id)
   
-- To replace a secondary job with another
player.set_job(job_id, grade_id, job_id_to_replace)

Example

-- Example function to set a job
local function test_function(_src)
    local player = boii.get_player(_src)
    if player then
        -- Setting a new primary job
        local job_assigned = player.set_job('police_officer', '1')
        if job_assigned then
            print('New primary job assigned successfully.')
        else
            print('Failed to assign new primary job.')
        end
    end
end

-- Example function to replace a secondary job
local function test_function(_src)
    local player = boii.get_player(_src)
    if player then
        -- Updating a secondary job and replacing old job
        local secondary_job_updated = player.set_job('security_guard', '2', 'parking_attendant')
        if secondary_job_updated then
            print('Secondary job updated successfully.')
        else
            print('Failed to update secondary job.')
        end
    end
end

get_inventory

The following function is used to retrieve the players inventory data. However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.get_inventory() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.get_inventory()

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Retreive the inventory data
local inventory = player.get_inventory()

-- Print the players inventory
print('Players Inventory: ' .. json.encode(inventory))

Object Example

-- Example function
local function test_function(_src)
    -- Retrieve the player
    local player = boii.get_player(_src)
    
    -- Retreive the inventory
    local inventory = player.get_inventory()
    
    -- Print the players current inventory data
    print('Players Items: ' .. json.encode(inventory))
end    

Utils Example

-- Example utils function
local function test_function(_src)
    -- Retreive the inventory
    local inventory = utils.fw.get_inventory(_src)
    
    -- Print the players current inventory data
    print('Players Items: ' .. json.encode(inventory))
end 

get_item

The following function can be used to retreive an items data from the players inventory. However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.get_item() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.get_item(item_name)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Get the item
local item = player.get_item(item_name)

-- Print the item data
print('Item: ' .. json.encode(item))

Object Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    -- Get the item
    local item = player.get_item('water')
    if item then
        -- Print the result
        print('Water found: ' .. json.encode(item))
    end
end

Utils Example

-- Example function
local function test_function(_src)
    -- Get the item
    local item = utils.fw.get_item(_src, 'water')
    if item then
        -- Print the result
        print('Water found: ' .. json.encode(item))
    end
end

has_item

The following function can be used to check if a player has an item and optionally check if they have enough of an item. However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.has_item() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.has_item(item_name, quantity)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Check if they have the item
local has_item = player.has_item(item_name, quantity)

-- Print the result
if has_item then
    print('Player has item')
else
    print('Player does not have the item')
end

Object Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    -- Check if they have the item
    local has_item = player.has_item('water', 2)
    
    -- Print result
    if has_item then
        print('Player has enough water to proceed.')
    else
        print('Player does not have enough water.')
    end
end

Utils Example

-- Example function
local function test_function(_src)
    -- Check if they have the item
    local has_item = utils.fw.has_item(_src, 'water', 2)
    
    -- Print result
    if has_item then
        print('Player has enough water to proceed.')
    else
        print('Player does not have enough water.')
    end
end

modify_inventory

The following function can be used to modify the players inventory. However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.adjust_inventory() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.modify_inventory(items, should_save)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Define items to add or remove
local items = {
    {item_id = 'burger', action = 'add', quantity = 3},
    {item_id = 'water', action = 'remove', quantity = 1},
}

-- Call the function
-- @param items table: Table of item to handle
-- @param reason string: The reason the players inventory was modified
-- @param should_save boolean: Toggle if modifications should be saved to database
player.modify_inventory(items, reason, should_save)

Object Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    
    -- Define items to add or remove
    local items = {
        {item_id = 'burger', action = 'add', quantity = 1}
    }
    
    -- Call the function
    player.modify_inventory(items, 'Ate a burger.', true)
end

Utils Example

-- Example utils function
local function test_function(_src)
    
    -- Define items to add or remove
    local items = {
        {item_id = 'burger', action = 'add', quantity = 1}
    }
    
    -- Utils supports additional validation data, anyone not in range can be kicked for potential exploits
    local validation_data = { location = vector3(100.0, 100.0, 20.0), distance = 10.0, drop_player = true }

    -- Call utils function
    utils.fw.adjust_inventory(_src, {
        items = items , 
        validation_data = validation_data, 
        reason = 'Ate a burger', 
        should_save = true
    })
end

update_item_data

The following can be used to update an items data section. However you will not see this commonly used throughout the framework, to keep additional framework resources as close to standalone as possible using utils.fw.update_item_data() is recommended, an example of how to use this has been provided below. Using the utils function instead allows for multi framework compatibility *(refer to utils/server/framework)* for more information on how utils bridge functions work.

player.update_item_data(item_id, updates, should_save)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Define updates
local updates = {
    ammo = 10,
    durability = 10
}

-- Call the function
-- @param item_id string: The item id to modify
-- @param updates table: Table of updates to apply to data section
-- @param should_save boolean: Toggle if modifications should be saved to database
player.update_item_data(item_id, updates, should_save)

Object Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    
    -- Define updates
    local updates = {
        ammo = 10,
        durability = 10
    }
    
    -- Call the function
    player.update_item_data('weapon_pistol', updates, true)
end

Utils Example

-- Example function
local function test_function(_src)
    -- Define updates
    local updates = {
        ammo = 10,
        durability = 10
    }
    
    -- Call the function
    utils.fw.update_item_data(_src, 'weapon_pistol', updates, true)
end

set_data

The following can be used to set a players data to their object, sync with the client and optionally save to database.

player.set_data(data_types, save_to_db)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Set the players data
player.set_data(data_types, save_to_db)

-- Addtional usage
player.set_data({}) -- Sets all data types; you can set false here if you like however it is not required. e.g, player.set_data({}, false)
player.set_data({ 'identity' }) -- Sets a specific data type
player.set_data({}, true) -- Sets all data types and then saves to the database
player.set_data({ 'identity' }, true) -- Sets a specific data type and saves to the database

Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    
    -- Set the players balances and inventory data
    player.set_data({ 'balances', 'inventory' }, true)
end

save_data

The following function can be used to save the players data manually, this also runs internally optionally whenever set_data is called is with should_save.

player.save_data(data_types)

Usage

-- Retreive the player
local _src = source
local player = boii.get_player(_src)

-- Save the players data
player.save_data(data_types)

-- Additional usage
player.save_data({}) -- Saves all player data to the database
player.save_data({ 'identity' }) -- Saves a specific player data type to the database

Example

-- Example function
local function test_function(_src)
    -- Retreive the player
    local player = boii.get_player(_src)
    
    -- Save the players balances and inventory data
    player.save_data({ 'balances', 'inventory' })
end