Integration

This page is for script developers and server maintainers who want to integrate rcore_stats into their scripts.

You do not need to do anything here to enjoy the full functionality of rcore_stats on your server.

Here you will find all the necessary information to integrate rcore_stats into your script.

Creating categories, stats and achievements

Everything related to creation is SERVER SIDE only.

Every event is "ensure" event, which means that it will create the category/stat/achievement only if it doesn't exist yet. That makes it easier for you as you can just call this event every time your resource starts and you don't have to worry about creating the same category/stat/achievement multiple times.

To create these data you should do it in a particular order, that's why we have prepared this part of documentation as step-by-step guide.

Step 1: Make sure the rcore_stats script is ready

rcore_stats emit an event when they are ready, but just in case your integration script is loaded before rcore_stats, you can check if the script is ready with this code:

👉 This part is required to detect if rcore_stats API is ready and to create all things needed.

local statsInited = false

local function setupStats() 
    if not statsInited then
        statsInited = true

        -- ❗❗❗ This is the place you will add the triggers to create categories, stats and achievements ❗❗❗
    end
end

AddEventHandler('rcore_stats:api:ready', setupStats)

CreateThread(function()
    if GetResourceState("rcore_stats") == "started" or GetResourceState("rcore_stats") == "starting" then
        while not statsInited do
            TriggerEvent('rcore_stats:api:isReady', function(isReady)
                if isReady then
                    setupStats()
                end
            end)
            Wait(1000)
        end
    end
end)

Step 2: Create a category or use existing one

Available categories by default: distance, finance, speed, favorite, combat, other

If your desired statistic doesn't fit into any of these categories, you can create your own category.

    -- @param key string - unique key of the category
    -- @param name string - name of the category displayed in the game
    -- @param cb function - callback function that will be called after the category is created, useful to then create stat types for this category
    TriggerEvent('rcore_stats:api:ensureCategory', key, name, cb)

    -- Example
    TriggerEvent('rcore_stats:api:ensureCategory', 'minigames', 'Minigames', nil)

Step 3: Create a stat type

You can create two types of stat types: player and server.

• player - this type of stat is calculated for each player separately

• server - the server stats are basically accumulators of player stats

  • for example, if you have a stat distance_car, you can create stat total_distance_car and the script will automatically sum all distance_car stats for all players so you can see the total distance traveled by all players

There are also unit types that can be used to display special stat types, like speed, distance etc.

Available unit types are:

• speed - the stat value should be in meters per second and it will be displayed in km/h or mph

• distance - the stat value should be in meters and it will be displayed in km or mi

• finance - this stat will be displayed as $xxx if not configured to something else in configs/config_units.lua

• time - this stat should be in minutes and will be displayed as 3h, 23m for example

• nil - if you use nil, no unit type will be used and stat will be displayed as is

Step 3.1: Create a player stat type

If you want to create a stat type with a custom category that you just created above, you need to create the category first and to be really sure, you can use the last parameter in create category event as a callback and then create the stat type in the callback.

-- @param key string - unique key of the stat type
-- @param name string - name of the stat type displayed in the game
-- @param type string - type of the stat type, can be "player" or "server", use player here as we are creating player stat type
-- @param unit_type string - unit type of the stat type, can be "speed", "distance", "finance", "time" or nil
-- @param category_key string - key of the category where the stat type should be placed
-- @param is_enabled boolean - if the stat type should be enabled by default
-- @param calculated_from string - does nothing for player stat types, set as nil
-- @param cb function - callback function that will be called after the stat type is created, useful to then create achievements for this stat type
TriggerEvent('rcore_stats:api:ensureStatType', key, name, type, unit_type, category_key, is_enabled, calculated_from, cb)

-- Example to create a stat type for basketball minigame
TriggerEvent('rcore_stats:api:ensureStatType', "basket_hoops", "Basketball - Points scored", "player", nil, "minigames", true, nil)

-- Example to create a stat type for measuring distance traveled by skateboard (notice the unit_type `distance`)
TriggerEvent('rcore_stats:api:ensureStatType', "distance_skateboard", "Distance on skateboard", "player", "distance", "other", true, nil)

Step 3.2: Create a server stat type

Server stats are accumulators of player stats, so you can see the total value of all player stats of the same type.

-- @param key string - unique key of the stat type
-- @param name string - name of the stat type displayed in the game
-- @param type string - type of the stat type, can be "player" or "server", use server here as we are creating server stat type
-- @param unit_type string - unit type of the stat type, can be "speed", "distance", "finance", "time" or nil
-- @param category_key string - key of the category where the stat type should be placed
-- @param is_enabled boolean - if the stat type should be enabled by default
-- @param calculated_from string - key of the player stat type that this server stat type should calculate from
-- @param cb function - not used for server stat types, set as nil
TriggerEvent('rcore_stats:api:ensureStatType', key, name, type, unit_type, category_key, is_enabled, calculated_from, cb)

-- Example to create a server stat type for basketball minigame
TriggerEvent('rcore_stats:api:ensureStatType', "total_basket_hoops", "Basketball - Total points scored", "server", nil, "minigames", true, "basket_hoops")

Step 4: Create an achievement

Achievements are a way to reward players for reaching a certain goal. You can create achievements for player stats only.

Each achievement has an icon, default is 🏆, but you can set any icon from https://lucide.dev/icons/. Simply go to the page, find the icon you like, click on it and copy the name, for example loader-pinwheel.

If you want to create an achievement for a stat type that you just created above, you need to create the stat type first and to be really sure, you can use the last parameter in create stat type event as a callback and then create the achievement in the callback.

-- @param key string - unique key of the achievement
-- @param name string - name of the achievement displayed in the game
-- @param description string - description of the achievement displayed in the game
-- @param icon string - icon of the achievement displayed in the game
-- @param stat_key string - key of the player stat type that this achievement should be calculated from
-- @param threshold number - value of the player stat type that player needs to reach to get this achievement
TriggerEvent('rcore_stats:api:ensureAchievement', key, name, description, icon, stat_key, threshold)

TriggerEvent('rcore_stats:api:ensureAchievement', "basket_hoops_1", "Basketball - 1 point", "Score 1 point in basketball", "loader-pinwheel", "basket_hoops", 1)

🥳 Congrats! You can now easily integrate statistics and achievements into your script!

But wait, you may ask, how can I change the stats of the player?

Changing stats

Changing stats is really easy, you just need to call an event and you're done!

Everything else will be handled for you, the script will increase/decrease/set the value of the stat type, check if the player has reached any achievements and save the data to the database.

All changes in stats are handled on CLIENT SIDE!!!

Increase stat value

Find the place in your script where you want to increase the value of the stat type and call this event:

-- @param statKey string - unique key of the stat type
-- @param value number - value by which the stat should be increased
TriggerEvent('rcore_stats:api:increaseStatValue', statKey, value)

-- Example to increase the value of the stat type "basket_hoops" by 1
TriggerEvent('rcore_stats:api:increaseStatValue', "basket_hoops", 1)

Decrease stat value

Find the place in your script where you want to decrease the value of the stat type and call this event:

-- @param key string - unique key of the stat type
-- @param value number - value by which the stat should be decreased
TriggerEvent('rcore_stats:api:decreaseStatValue', key, value)

-- Example to decrease the value of the stat type "basket_hoops" by 1
TriggerEvent('rcore_stats:api:decreaseStatValue', "basket_hoops", 1)

Set stat value

In some cases, you may want to set the value of the stat type to a specific value, for example if the value should not be a number, but a string (text). Or if you want to reset the value of the stat type to 0.

-- @param key string - unique key of the stat type
-- @param value number - value to which the stat should be set
TriggerEvent('rcore_stats:api:setStatValue', key, value)

-- Example to set the value of the stat type "basket_hoops" to 0
TriggerEvent('rcore_stats:api:setStatValue', "basket_hoops", 0)

🥳 Now your integration should be ready to go, enjoy!