Skip to content

Stats

Jump to bottom
Francisco Dias edited this page Jun 20, 2024 · 6 revisions

Stats

Epic Online Services Interface: Stats Interface

The Stats Interface provides the ability for developers to manage users' stats for an application, which can include any statistical data that a developer wishes to track, such as the number of items collected, the player's fastest completion time for a level, the total number of victories or losses, or the number of times that a user has performed a certain action. You can use stats to determine when to unlock Achievements and how to use rank users in Leaderboards.

Functions

These functions are provided for handling stats:

Structs

These are the structures used by this API:


Back To Top

EpicGames_Stats_CopyStatByIndex

Epic Online Services Function: EOS_Stats_CopyStatByIndex

This function fetches a stat from a given index.

Note

Requires a previous call to EpicGames_Stats_QueryStats to store values in cache.


Syntax:

EpicGames_Stats_CopyStatByIndex(userID_target, index)
Argument Type Description
userID_target String The Product User ID of the user who owns the stat
index Real Index of the stat to retrieve from the cache



Returns:

StatData


Example:

var _count = EpicGames_Stats_GetStatsCount(userID_target);
for(var i = 0 ; i < _count ; i ++)
{
    var _struct = EpicGames_Stats_CopyStatByIndex(userID_target, i);
    var Name = _struct.Name;
}

The above code shows an example of how the function should be used. The stats data is returned for the provided stat index.



Back To Top

EpicGames_Stats_CopyStatByName

Epic Online Services Function: EOS_Stats_CopyStatByName

This function fetches a stat from cached stats by name.

Note

Requires a previous call to EpicGames_Stats_QueryStats to store values in cache.


Syntax:

EpicGames_Stats_CopyStatByName(user_target, name)
Argument Type Description
user_target String The Product User ID of the user who owns the stat
name String Name of the stat to retrieve from the cache



Returns:

StatData


Example:

var _struct = EpicGames_Stats_CopyStatByName(userID_target, "MyStatName");
var _name = _struct.Name;

The above code shows an example of how the function should be used. The stats data is returned for the provided stat name.



Back To Top

EpicGames_Stats_GetStatsCount

Epic Online Services Function: EOS_Stats_GetStatsCount

This function fetches the number of stats that are cached locally.

Note

Requires a previous call to EpicGames_Stats_QueryStats to store values in cache.


Syntax:

EpicGames_Stats_GetStatsCount(userID_target)
Argument Type Description
userID_target String The Product User ID for the user whose stats are being counted



Returns:

Real


Example:

var _count = EpicGames_Stats_GetStatsCount(userID_target);
for(var i = 0 ; i < _count ; i ++)
{
    var _struct = EpicGames_Stats_CopyStatByIndex(userID_target, i);
    var _name = _struct.Name;
}

The above code shows an example of how the function should be used. After a successful call to EpicGames_Stats_QueryStats, the function EpicGames_Stats_GetStatsCount will return the number of entries in the query array which can then be accessed using the EpicGames_Stats_CopyStatByIndex function.



Back To Top

EpicGames_Stats_IngestStat

Epic Online Services Function: EOS_Stats_IngestStat

This function ingests a stat by the amount specified in Options.

When the operation is complete and the delegate is triggered the stat will be uploaded to the backend to be processed. The stat may not be updated immediately and an achievement using the stat may take a while to be unlocked once the stat has been uploaded.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Stats_IngestStat(userID, userID_target, statName, amount)
Argument Type Description
userID String The Product User ID of the local user requesting the ingest. Set to undefined for dedicated server.
userID_target String The Product User ID for the user whose stat is being ingested
statName String Name of the Stat to ingest
amount Real Amount of the Stat to ingest



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_Stats_IngestStat"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_Stats_IngestStat(userID, userID, "Leaderboard_Stat", 183);

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Stats_IngestStat")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

EpicGames_Stats_QueryStats

Epic Online Services Function: EOS_Stats_QueryStats

This function queries a list of stats for a specific player. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.


Syntax:

EpicGames_Stats_QueryStats(userID, userID_target, startTime=undefined, endTime=undefined)
Argument Type Description
userID String The Product User ID of the local user requesting the stats. Set to undefined for dedicated server.
userID_target String The Product User ID for the user whose stats are being retrieved
startTime Real The POSIX timestamp for start time
endTime Real The POSIX timestamp for end time



Returns:

Real


Triggers:

Social Async Event

Key Type Description
type String The string "EpicGames_Stats_QueryStats"
status EpicGames_Result The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message String Text representation of the status code
identifier Real The asynchronous listener ID.

Example:

identifier = EpicGames_Stats_QueryStats();

The code sample above saves the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Stats_QueryStats")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
        show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.



Back To Top

StatData

The stat data is represented by a struct and contains information for a specific stat.

This struct is referenced by the following functions:


Member Type Description
Name String The name of the stat.
StartTime Real If not EpicGames_STATS_TIME_UNDEFINED then this is the POSIX timestamp for start time.
EndTime Real If not EpicGames_STATS_TIME_UNDEFINED then this is the POSIX timestamp for end time.
Value Real The current value for the stat.

YoYoGames 2024

Clone this wiki locally