API

Statuses Initialization

Add the following export into your framework.

Typically you would want to add this into your server side. You can use your frameworks player joined event if applicable. If you are using the statuses system standalone you could use the playerSpawned event handler.

Export

exports.boii_statuses:init(source)

Example

RegisterNetEvent('boii:player_joined', function(player)
    exports.boii_statuses:init(player.source)
end)

If this has been added correctly a status object will be created on players when they join the server.

Client Exports

You can use the following exports to interact with the statuses system from the client side.

get_data

The following is used to retreive the players statuses data. You can either get the entire data table or you can specifiy a key.

Export

-- Gets the entire data table
exports.boii_statuses:get_data()

-- Gets a specific key in the data table
exports.boii_statuses:get_data('statuses')

Example

-- Getting all data
local player_data = exports.boii_statuses:get_data()
if player_data and player_data.statuses then
    player_data.statuses.health = player_data.statuses.health / 2
    print('players current health: ' .. player_data.statuses.health)
end

-- Getting a specific key
local player_statuses = exports.boii_statuses:get_data('statuses')
if player_statuses and player_statuses.health then
    player_statuses.health = player_statuses.health / 2
    print('players current health: ' .. player_statuses.health)
end

set_data

The following is used to set data to the client side statuses data. Typically you would not want to do this client side, this will be done automatically from the server when required.

Export

exports.boii_statuses:set_data(data)

Example

-- First we get the players statuses data
local health = exports.boii_statuses:get_data('statuses').health

-- Then modify
health = health - 10

-- Then set the data
exports.boii_status:set_data({ 'statuses' })

Server Exports

You can use the following exports to interact with the server side of the statuses system.

get_player

This is used to retrieve the statuses object for use or manipulation within other resources.

Export

exports.boii_statuses:get_player(source)

Example

local _src = source
local player = exports.boii_statuses:get_player(_src)
if player then
    print('statuses object found for player: ' .. _src)
end

Object Functions

You can use any of the following functions to directly interact with a players statuses object.

All of these functions MUST be used on the server side, and you MUST get the players object before attempting to use them.

apply_effect

This function can be used to apply effects to the player. Currently this covers buffs & debuffs however it will cover additional effects as the resource is improve upon.

Function

player.apply_effect(effect_type, effect_id)

Examples

-- Applying a buff
local player = exports.boii_statuses:get_player(source)
if player then
    player.apply_effect('buffs', 'stamina')
else
    print("Player object not found for source: "..tostring(source))
end

-- Applying a debuff
local player = exports.boii_statuses:get_player(source)
if player then
    player.apply_effect('debuffs', 'stamina')
else
    print("Player object not found for source: "..tostring(source))
end

remove_effect

The following function can be used to remove effects from the player.

Function

player.remove_effect(effect_type, effect_id)

Examples

-- Removing a buff
local player = exports.boii_statuses:get_player(source)
if player then
    player.remove_effect('buffs', 'stamina')
else
    print("Player object not found for source: "..tostring(source))
end

-- Removing a debuff
local player = exports.boii_statuses:get_player(source)
if player then
    player.remove_effect('debuffs', 'stamina')
else
    print("Player object not found for source: "..tostring(source))
end

apply_injury

The following function can be used to apply an injury to a players body part.

Function

player.apply_injury(body_part, damage)

Example

-- Applying a injury to a player
local player = exports.boii_statuses:get_player(source)
if player and config.injuries[body_part] then
    player.apply_injury('head', 50) -- Adds 50% damage from players head
else
    print("Invalid body part or damage, or player object not found for source: "..tostring(source))
end

heal_injury

The following function can be used to remove an injury to a players body part.

Function

player.heal_injury(body_part, damage)

Example

-- Removing a injury from a player
local player = exports.boii_statuses:get_player(source)
if player and config.injuries[body_part] then
    player.heal_injury('head', 50) -- Removes 50% damage from players head
else
    print("Invalid body part or damage, or player object not found for source: "..tostring(source))
end

set_data

The following function can be used to set a players data and optionally save. Any data set will be synced back to the client. This is primarily used internally by the other functions however if you wish to use this externally you can.

Function

-- If you do not declare any data types all data will be set
player.set_data({ }, should_save)

-- Declaring data types will only set specific data
player.set_data({ data_types }, should_save)

Example

-- Setting and saving a players updatated data
local player = exports.boii_statuses:get_player(source)
if player then
    player.statuses.health = 0
    player.flags.dead = true
    player.set_data({ 'statuses' , 'flags' }, true) -- Sets and saves the players updated statuses and flags
else
    print("Player object not found for source: "..tostring(source))
end

save_data

The following function can be used to save the players statuses data externally.

This runs internally through the set_data function if boolean is true. However if you wish to save manually from an external resource you can.

Function

-- Not declaring data types will save all data
player.save_data({ })

 -- Not declaring data types will save all data
player.save_data({ data_types })

Example

-- Setting and saving a players updatated data
local player = exports.boii_statuses:get_player(source)
if player then
    player.save_data() -- Sets and saves the players updated statuses and flags
else
    print("Player object not found for source: "..tostring(source))
end