ICircuitryUserStats Interface

This API provides functions for accessing and submitting statistics, achievements, and leaderboards.

Member Functions

The member functions for ICircuitryUserStats are accessed through the global function called CircuitryUserStats().

ClearAchievement

bool ClearAchievement( const char *pchName );

Name	Type	Description
pchName	const char *	This is the 'API Name' of the achievement to reset.

This function resets the unlock status of a particular achievement. Primarily used for testing.

You will have needed to call the RequestCurrentStats function and it needs to have returned successfully via a callback prior to calling this function.

This function call only modifies Circuitry's 'in-memory' state. To send the unlock status to the server (and to trigger the Circuitry overlay notification) you will need to call the StoreStats function.

Returns: bool
This function returns true if successful, if all of the following conditions are met; otherwise, false.

DownloadLeaderboardEntries

CircuitryAPICall_t DownloadLeaderboardEntries( CircuitryLeaderboard_t hCircuitryLeaderboard, ELeaderboardDataRequest eLeaderboardDataRequest, int nRangeStart, int nRangeEnd );

This function call returns a series of entries for a specified leaderboard. You can request for more entries than exist.

If you would like to download entries for an arbitrary set of users (i.e. all of the users on a server) then call the DownloadLeaderboardEntriesForUsers function which takes an array of Circuitry IDs.

You must call the FindLeaderboard function or the FindOrCreateLeaderboard function to get a CircuitryLeaderboard_t prior to calling this function.

Returns: CircuitryAPICall_t to be used with a LeaderboardScoresDownloaded_t call result.

DownloadLeaderboardEntriesForUsers

CircuitryAPICall_t DownloadLeaderboardEntriesForUsers( CircuitryLeaderboard_t hCircuitryLeaderboard, CCircuitryID *prgUsers, int cUsers );

This function call returns the leaderboard entries for an arbitrary set of users on a specific leaderboard.

A maximum of 100 users can be downloaded at a time (with only one outstanding call at a time). If a user does not have an entry on the specified leaderboard, they will not be included in the result.

If you wish to retrieve entries based on their ranking or friends of the current user then call the DownloadLeaderboardEntries function.

You must call the FindLeaderboard function or the FindOrCreateLeaderboard function to get a CircuitryLeaderboard_t prior to calling this function.

Returns: CircuitryAPICall_t to be used with a LeaderboardScoresDownloaded_t call result.
Returns k_uAPICallInvalid indicating an error if the number of users is greater than 100 or if one of the Circuitry IDs is invalid.

FindLeaderboard

CircuitryAPICall_t FindLeaderboard( const char *pchLeaderboardName );

Name	Type	Description
pchLeaderboardName	const char *	The name of the leaderboard you want to locate. Must not be longer than k_cchLeaderboardNameMax.

This function retrieves a leaderboard by name.

You will need to call either this or the FindOrCreateLeaderboard function to retrieve the leaderboard handle which is valid for the game session for each leaderboard you wish to access prior to calling any other Leaderboard functions.

Returns: CircuitryAPICall_t to be used with a LeaderboardFindResult_t call result.

FindOrCreateLeaderboard

CircuitryAPICall_t FindOrCreateLeaderboard( const char *pchLeaderboardName, ELeaderboardSortMethod eLeaderboardSortMethod, ELeaderboardDisplayType eLeaderboardDisplayType );

Name	Type	Description
pchLeaderboardName	const char *	The is the name of the leaderboard to locate or create. This should not be longer than k_cchLeaderboardNameMax.
eLeaderboardSortMethod	ELeaderboardSortMethod	The 'sort order' of the new leaderboard if it's created.
eLeaderboardDisplayType	ELeaderboardDisplayType	The display type of the new leaderboard if it's created.

This retrieves a leaderboard by its name. It will create it if it's has not yet been created.

You will need to call either this or the FindLeaderboard function to obtain the handle that is valid for the game session for each leaderboard you wish to access prior to calling any other Leaderboard functions.

Leaderboards created with this function will not automatically show up in the community. You must manually set the Community Name field in the Partner Portal of the Robot Cache website. It is recommended that you create the leaderboards in the Partner Portal anel on the Circuitry website using the FindLeaderboard function unless you're expected to have a large amount of dynamically created leaderboards.

NOTE: Do not pass k_ELeaderboardSortMethodNone for eLeaderboardSortMethod or k_ELeaderboardDisplayTypeNone for eLeaderboardDisplayType as this may cause unexpected results.

Returns: CircuitryAPICall_t to be used with a LeaderboardFindResult_t call result.

GetAchievement

bool GetAchievement( const char *pchName, bool *pbAchieved );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.
pbAchieved	bool *	This returns the unlock status of the achievement.

Retrieves the unlock status of the Achievement. The equivalent function for other users is the GetUserAchievement function.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

If the function call is successful then the 'unlock' status is returned via the pbAchieved parameter.

GetAchievementAchievedPercent

bool GetAchievementAchievedPercent( const char *pchName, float *pflPercent );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.
pflPercent	float *	This is the variable that returns the percentage of users that have unlocked this achievement from 0 to 100.

This function returns the percentage of users who have unlocked the specified achievement.

You must have called the RequestGlobalAchievementPercentages function and it needed to return successfully via a callback prior to calling this.

Returns: bool
Returns true upon success; otherwise false if RequestGlobalAchievementPercentages has not been called or if the specified 'API Name' does not exist in the global achievement percentages.

GetAchievementAndUnlockTime

bool GetAchievementAndUnlockTime( const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.
pbAchieved	bool *	This returns whether or not the current user has 'unlocked' the achievement.
punUnlockTime	uint32 *	This returns the time that the unchievement was unlocked; if pbAchieved is true.

Retrieves the achievement status as well as the time it was unlocked (and if it was unlocked).

If the return value is 'true' but the unlock time is zero, then it was unlocked before Circuitry started tracking achievement unlock times. The time is provided in UTC format.

The equivalent function for other users is GetUserAchievementAndUnlockTime.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

If the call is successful then the achieved 'status' and 'unlock time' are provided via the arguments pbAchieved and punUnlockTime.

GetAchievementDisplayAttribute

const char * GetAchievementDisplayAttribute( const char *pchName, const char *pchKey );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.
pchKey	const char *	The 'key' to get a value for.

This retrieves the general attributes for an achievement (i.e. Name, Description, and Hidden status).

This receives the value from a dictionary/map 'key/value' store. As a result, you will need to provide one of the following keys:

• "name" to retrive the localized achievement name in UTF8
• "desc" to retrive the localized achievement description in UTF8
• "hidden" for retrieving if an achievement is hidden. Returns "0" when not hidden, "1" when hidden

NOTE: The localization for this is provided based on the games language if it's set. Otherwise, it checks to see if a particular localization is available. If this fails, then it reverts back to English.

Returns: const char *
This function returns the value as a string upon 'success' if all of the following conditions are met. Othereise it returns an empty string: "".

• RequestCurrentStats has completed and successfully returned its callback.
• The specified pchKey is valid.

GetAchievementIcon

int GetAchievementIcon( const char *pchName );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.

This retrieves the icon for an achievement.

Returns: int
Triggers a UserAchievementIconFetched_t callback.
The image is returned as a 'handle' which is used with ICircuitryUtils::GetImageRGBA to get the actual image data.

An invalid handle of 0 will be returned under the following conditions:
RequestCurrentStats has not completed and successfully returned its callback.
The Circuitry API is retrieving the image data from the server resulting in a UserAchievementIconFetched_t callback which will notify you when the image data is ready (as well as provide a new handle). * If the m_nIconHandle in the callback is still 0, then there is no image set for the specified achievement.

GetAchievementName

const char * GetAchievementName( uint32 iAchievement );

Name	Type	Description
iAchievement	uint32	Index of the achievement.

This retrieves the 'API name' for an achievement index between 0 and GetNumAchievements.

This function needs to be used along with the GetNumAchievements function to loop through the list of achievements.

Returns: const char *
The 'API Name' of the achievement. This returns an empty string if iAchievement is not a valid index. RequestCurrentStats needs to have been called (and successfully returned its callback) and the current App ID MUST include achievements.

Example:

int numAchievements = CircuitryUserStats()->GetNumAchievements();
for ( int i = 0; i < numAchievements; ++i )
{
    const char *achName = CircuitryUserStats()->GetAchievementName( i );
    if ( achName )
    {
        printf( "%s", achName );
    }
}

GetDownloadedLeaderboardEntry

bool GetDownloadedLeaderboardEntry( CircuitryLeaderboardEntries_t hCircuitryLeaderboardEntries, int index, LeaderboardEntry_t *pLeaderboardEntry, int32 *pDetails, int cDetailsMax );

Name	Type	Description
hCircuitryLeaderboardEntries	CircuitryLeaderboardEntries_t	A handle that is obtained from the most recently received LeaderboardScoresDownloaded_t call result.
index	int	The index of the leaderboard entry to receive. Needs to be between 0 and LeaderboardScoresDownloaded_t.m_cEntryCount.
pLeaderboardEntry	LeaderboardEntry_t *	A variable where the entry will be returned to.
pDetails	int32 *	A preallocated array where the details of this entry get returned into.
cDetailsMax	int	The length of the pDetails array.

This function retrieves the data for a single leaderboard entry.

You should use a 'for' loop from 0 to LeaderboardScoresDownloaded_t.m_cEntryCount to return all of the downloaded entries. Once you've accessed all the entries, the data will be freed, and the CircuitryLeaderboardEntries_t handle will become invalid.

Optionally, details may be returned for the entry via pDetails. If this is NULL then cDetailsMax MUST be 0.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
hCircuitryLeaderboardEntries must be a valid handle from the last received LeaderboardScoresDownloaded_t call result.
index must be between 0 and LeaderboardScoresDownloaded_t.m_cEntryCount

If the function call is successful then the entry is returned via the parameter pLeaderboardEntry and if cDetailsMax is NOT 0 then pDetails is filled with the unlock details.

Example:

void OnLeaderboardScoresDownloaded( LeaderboardScoresDownloaded_t *pCallback )
{
    for ( int i = 0; i < pCallback->m_cEntryCount; i++ )
    {
        LeaderboardEntry_t leaderboardEntry;
        int32 details[3]; // We know that we store this many initially.
        CircuitryUserStats()->GetDownloadedLeaderboardEntry( pCallback->m_hCircuitryLeaderboardEntries, i, &leaderboardEntry, details, 3 );

        assert( leaderboardEntry.m_cDetails == 3 );
        //...
    }
}

GetGlobalStat

bool GetGlobalStat( const char *pchStatName, int64 *pData ); 
bool GetGlobalStat( const char *pchStatName, double *pData );

Name	Type	Description
pchStatName	const char *	The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pData	int64 * / double *	The variable to return the stat value into.

This function retrieves the lifetime totals for an aggregated statistic.

You must have previously called the RequestGlobalStats function and it needs to have returned successfully via its callback prior to calling this function.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false. * RequestGlobalStats has completed and successfully returned its callback.

GetGlobalStatHistory

int32 GetGlobalStatHistory( const char *pchStatName, int64 *pData, uint32 cubData ); 
int32 GetGlobalStatHistory( const char *pchStatName, double *pData, uint32 cubData );

Name	Type	Description
pchStatName	const char *	The 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pData	double *	The array that the daily history will be returned into.
cubData	uint32	The total size in bytes of the pData array.

This function retrieves the daily history for an aggregated statistic.

pData will be filled with daily values, starting with today.
When called, pData[0] will be today, pData1 will be yesterday, and pData2 will be two days ago, etc.

You will need to have called the RequestGlobalStats function and it needs to have been returned successfully via its callback prior to calling this function.

Returns: int32
The number of elements returned in the pData array.

A value of 0 indicates failure for one of the following reasons:
* RequestGlobalStats has not been called or returned its callback, with at least 1 day of history.

GetLeaderboardDisplayType

ELeaderboardDisplayType GetLeaderboardDisplayType( CircuitryLeaderboard_t hCircuitryLeaderboard );

This function returns the display type of a leaderboard handle.

Returns: ELeaderboardDisplayType
The display type of the leaderboard. Returns k_ELeaderboardDisplayTypeNone if the leaderboard handle is invalid.

GetLeaderboardEntryCount

int GetLeaderboardEntryCount( CircuitryLeaderboard_t hCircuitryLeaderboard );

This function returns the total number of entries in a leaderboard.

This data is cached on a 'per leaderboard basis' upon the first call to FindLeaderboard or FindOrCreateLeaderboard. It is refreshed on each successful call to DownloadLeaderboardEntries, DownloadLeaderboardEntriesForUsers, and UploadLeaderboardScore.

Returns: int
The number of entries in the leaderboard. Returns 0 if the leaderboard handle is invalid.

GetLeaderboardName

const char * GetLeaderboardName( CircuitryLeaderboard_t hCircuitryLeaderboard );

This function returns the name of a leaderboard handle.

Returns: const char *
Returns the name of the leaderboard or an empty string if the leaderboard handle is invalid.

GetLeaderboardSortMethod

ELeaderboardSortMethod GetLeaderboardSortMethod( CircuitryLeaderboard_t hCircuitryLeaderboard );

This function returns the sort order of a leaderboard handle.

Returns: ELeaderboardSortMethod
Returns the sort method of the leaderboard or returns k_ELeaderboardSortMethodNone if the leaderboard handle is invalid.

GetMostAchievedAchievementInfo

int GetMostAchievedAchievementInfo( char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );

Name	Type	Description
pchName	char *	String buffer that returns the 'API Name' of the achievement into.
unNameBufLen	uint32	The size in bytes of pchName. Should be at least as long as your longest achievement 'API Name'.
pflPercent	float *	Variable to return the percentage of the people that have unlocked this achievement from 0 to 100.
pbAchieved	bool *	Variable to return whether or not the current user has unlocked this achievement.

This function retrieves the info on the 'most achieved' achievement for the application.

You will need to have called the RequestGlobalAchievementPercentages function and it needed to have returned successfully via its callback prior to calling this function.

Returns: int
Returns -1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

If the function call is successful it returns an iterator which should be used with GetNextMostAchievedAchievementInfo.

Example:

const int ACH_NAME_MAX_LENGTH = 64;
char[ACH_NAME_MAX_LENGTH] achName;
float achPercent;
float achUnlocked;

int i = CircuitryUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked );
while ( i != -1 )
{
    printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked );

    i = CircuitryUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked );
}

GetNextMostAchievedAchievementInfo

int GetNextMostAchievedAchievementInfo( int iIteratorPrevious, char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );

Name	Type	Description
iIteratorPrevious	int	This is an iterator returned from the previous call to this function or from GetMostAchievedAchievementInfo
pchName	char *	A string buffer to return the 'API Name' of the achievement into.
unNameBufLen	uint32	The size in bytes of pchName, should be at least as long as your longest achievement 'API Name'.
pflPercent	float *	Variable that returns the percentage of people that have unlocked this achievement from 0 to 100.
pbAchieved	bool *	Variable that returns whether the current user has unlocked this achievement.

This function retrieves the information on the next most achieved 'achievement' for the game.

You must have previously called the RequestGlobalAchievementPercentages function and it needs to have returned successfully via its callback prior to calling.

Returns: int
Returns -1 if RequestGlobalAchievementPercentages has not been called or if there are no global achievement percentages for this app Id.

If the function call is successful it returns an 'iterator' which should be used with subsequent function calls to this function.

Example:

const int ACH_NAME_MAX_LENGTH = 64;
char[ACH_NAME_MAX_LENGTH] achName;
float achPercent;
float achUnlocked;

int i = CircuitryUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked );
while ( i != -1 )
{
    printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked );
    // Do something like add/update this info in your local achievement object or display it to the user.

    i = CircuitryUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked );
}

GetNumAchievements

uint32 GetNumAchievements();

Retrieves the number of achievements defined in the Partner Poortal of the Robot Cache website.

This function is used for iterating through all of the achievements with the GetAchievementName function.

Returns: uint32
The number of achievements. Returns 0 if RequestCurrentStats has not been called and successfully, returned its callback or the current App ID has no achievements.

Example:

int numAchievements = CircuitryUserStats()->GetNumAchievements();
for ( int i = 0; i < numAchievements; ++i )
{
    const char *achName = CircuitryUserStats()->GetAchievementName( i );
    if ( achName )
    {
        printf( "%s", achName );
    }
}

GetNumberOfCurrentPlayers

CircuitryAPICall_t GetNumberOfCurrentPlayers();

Retrieves the total number of players currently playing the game (both online and offline).

Returns: CircuitryAPICall_t to be used with a NumberOfCurrentPlayers_t call result.

GetStat

bool GetStat( const char *pchName, int32 *pData ); 
bool GetStat( const char *pchName, float *pData );

Name	Type	Description
pchName	const char *	This is the 'API Name' of the stat. Must not be longer than k_cchStatNameMax.
pData	int32 * / float *	This is the variable to return the stat value into.

This function retrieves the current value of the statistic for the current user.

You must have previously called the function RequestCurrentStats and it needs to return successfully via its callback prior to calling this.

To receive stats for other users use GetUserStat.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

GetUserAchievement

bool GetUserAchievement( CCircuitryID circuitryIDUser, const char *pchName, bool *pbAchieved );

Name	Type	Description
circuitryIDUser	CCircuitryID	The Circuitry ID of the user to get the achievement for.
pchName	const char *	The 'API Name' of the achievement.
pbAchieved	bool *	Returns the unlock status of the achievement.

Retrieves the unlock status of the Achievement.

The similar function for the local user is GetAchievement. The equivalent function for game servers is ICircuitryGameServerStats::GetUserAchievement.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestUserStats has completed and successfully returned a callback.

If the function call is successful then the unlock status is returned via the pbAchieved parameter.

GetUserAchievementAndUnlockTime

bool GetUserAchievementAndUnlockTime( CCircuitryID circuitryIDUser, const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );

Name	Type	Description
circuitryIDUser	CCircuitryID	The Circuitry ID of the user to retrieve the achievement for.
pchName	const char *	The 'API Name' of the achievement.
pbAchieved	bool *	This returns whether the current user has unlocked the achievement.
punUnlockTime	uint32 *	This returns the time that the unchievement was unlocked; if pbAchieved is true.

Retrieves the achievement status and the time it was unlocked (if unlocked).

The equivalent function for the local user is GetAchievementAndUnlockTime.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestUserStats has completed and successfully returned its callback.

If the call is successful then the achieved status and unlock time are provided via the arguments pbAchieved and punUnlockTime.

GetUserStat

bool GetUserStat( CCircuitryID circuitryIDUser, const char *pchName, int32 *pData ); 
bool GetUserStat( CCircuitryID circuitryIDUser, const char *pchName, float *pData );

Name	Type	Description
circuitryIDUser	CCircuitryID	The Circuitry ID of the user to get the stat for.
pchName	const char *	The 'API Name' of the statistic (cannot be longer than k_cchStatNameMax.)
pData	int32 * / float *	The variable to return the stat value into.

Retrieves the current value of the statistic for the specified user.

You must have previously called the function RequestUserStats and it needs to have returned successfully via its callback prior to calling this.

The equivalent function for the local user is GetStat. The equivalent function for game servers is ICircuitryGameServerStats::GetUserStat.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestUserStats has completed and successfully returned its callback.

IndicateAchievementProgress

bool IndicateAchievementProgress( const char *pchName, uint32 nCurProgress, uint32 nMaxProgress );

Name	Type	Description
pchName	const char *	The 'API Name' of the achievement.
nCurProgress	uint32	The current progress.
nMaxProgress	uint32	The progress required to unlock the achievement.

This function displays to the user a notification along with the current progress of an achievement.

Please note that when calling this function it will NOT set the progress or unlock the achievement. The application must do that manually by calling the SetStat function.

Returns: bool
Triggers a UserStatsStored_t callback.
Triggers a UserAchievementStored_t callback.
This function returns true upon success if all of the following conditions are met; otherwise, false.
RequestCurrentStats has completed and successfully returned its callback.
The specified achievement is not already unlocked.
* nCurProgress is less than nMaxProgress.

RequestCurrentStats

bool RequestCurrentStats();

This function asynchronously requests the user's current stats and achievements from the Robot Cache servers.

You will need to call this function first in order to get the initial status of statistics and achievements.
Only after the callback is returned can you begin calling the remaining statistics and achievement functions for the current user.

The equivalent function for other users is RequestUserStats.

Returns: bool
Triggers a UserStatsReceived_t callback.
Only returns false if there is no user logged in; otherwise, true.

RequestGlobalAchievementPercentages

CircuitryAPICall_t RequestGlobalAchievementPercentages();

This function asynchronously retrieves the data for the percentage of players who have received each achievement for the current game globally.

You must have previously called the function RequestCurrentStats and it needs to return successfully via its callback prior to calling.

Returns: CircuitryAPICall_t to be used with a GlobalAchievementPercentagesReady_t call result.

RequestGlobalStats

CircuitryAPICall_t RequestGlobalStats( int nHistoryDays );

Name	Type	Description
nHistoryDays	int	This is the number of days of day-by-day history to retrieve in addition to the overall totals.

This function asynchronously retrieves the global statistics which are available for statistics.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this.

Returns: CircuitryAPICall_t to be used with a GlobalStatsReceived_t call result.

RequestUserStats

CircuitryAPICall_t RequestUserStats( CCircuitryID circuitryIDUser );

Name	Type	Description
circuitryIDUser	CCircuitryID	The Circuitry ID of the user to request the statistics for.

This function asynchronously downloads the statistics and achievements for the specified user from the Robot Cache server.

Statistics are not updated automatically. You will need to call this function to refresh any data that may have changed.

NOTE: A 'least recently used' cache (or LRU) is maintained in order to minimize memory usage. User's statistics will occasionally be unloaded as well. When this happens a UserStatsUnloaded_t callback is sent. After this callback is returned, the user's statistics will not be available until this function is called again.

The equivalent function call for the local user is RequestCurrentStats. The equivalent function for game servers is ICircuitryGameServerStats::RequestUserStats.

Returns: CircuitryAPICall_t to be used with a UserStatsReceived_t call result.

ResetAllStats

bool ResetAllStats( bool bAchievementsToo );

Name	Type	Description
bAchievementsToo	bool	Also reset the user's achievements?

This function resets the current users statistics and can also reset achievements if you wish to do so.

This automatically calls StoreStats to committ the changes to the Robot Cache server. NOTE: This should only be used for testing purposes. Please insure that you sync your statistics with the new default values after calling this by calling RequestCurrentStats.

Returns: bool
true indicating success if RequestCurrentStats has been called and successfully returned its callback; otherwise false.

SetAchievement

bool SetAchievement( const char *pchName );

Name	Type	Description
pchName	const char *	The 'API Name' of the Achievement to unlock.

This function unlocks an achievement.

You must have previously called the function RequestCurrentStats and it needs to have returned successfully via its callback prior to calling the function.

You may unlock an achievement numerous times so you don't need to be concerned about only setting achievements that aren't already set. This function call only modifies Circuitry's in-memory state. You will need to call the StoreStats function to send the unlock status to the Robot Cache server and to trigger the Circuitry overlay notification.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

SetStat

bool SetStat( const char *pchName, int32 nData ); 
bool SetStat( const char *pchName, float fData );

Name	Type	Description
pchName	const char *	The 'API Name' of the statistic. This must not be longer than k_cchStatNameMax.
nData	int32 / float	The new value of the statistic. This needs to be an absolute value as it will not increment or decrement for you.

This function sets (or updates) the value of a given statistic for a current user.

You will have needed to call the RequestCurrentStats function and it needs to have returned successfully via its callback prior to calling this function.

This call only modifies Circuitry's in-memory state. Doing this allows Circuitry to persist the changes even in the event of an application crash or unexpected shutdown.
To submit the statistics to the server you must call StoreStats.

If it returns false (and everything appears correct) check to ensure that your changes in the Robot Cache Partner Portal are published.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

StoreStats

bool StoreStats();

This function sends the changed statistics and achievements data to the Robot Cache server.

If the function fails then no data is sent to the server.

This function call can be 'rate limited'. As a result, the call number of times you should make the call should be based on minutes, rather than seconds. Note: Use this function during major state changes. The call is required to display the achievement unlock notification dialog. If you have called the SetAchievement function then you should call this function shortly after.

Note: This function will be called automatically if you have statistics or achievements that you have saved locally but haven't uploaded with this function when your application process ends.

You can also locate additional debug information in the %circuitry_install%logsstats_log.txt file.

Returns: bool
Triggers a UserStatsStored_t callback.
Triggers a UserAchievementStored_t callback.
This function returns true upon success if all of the following conditions are met; otherwise, false.
* RequestCurrentStats has completed and successfully returned its callback.

If the function call is successful you will receive a UserStatsStored_t callback.

If m_eResult has a result of k_EResultInvalidParam, then one or more statistics that have been uploaded have been rejected. This is due to the constraints are broke or were out of date. In this case, the server will send back updated values and the stats should be updated locally to keep in sync.

If one or more of the achievements has been unlocked then this will also trigger a UserAchievementStored_t callback.

UpdateAvgRateStat

bool UpdateAvgRateStat( const char *pchName, float flCountThisSession, double dSessionLength );

Name	Type	Description
pchName	const char *	The 'API Name' of the statistic and must not be longer than k_cchStatNameMax.
flCountThisSession	float	The value accumulation since the last call to this function.
dSessionLength	double	The amount of time in seconds since the last call to this function.

Updates an AVGRATE stat with new values.

You must have called RequestCurrentStats and it needs to return successfully via its callback prior to calling this!

This call only modifies Circuitry's in-memory state and is very cheap. Doing so allows Circuitry to persist the changes even in the event of an application crash or unexpected shutdown.
To submit the stats to the server you must call StoreStats.

If this is returning false and everything appears correct, then check to ensure that your changes in the App Admin panel of the Circuitry website are published.

Returns: bool
This function returns true upon success if all of the following conditions are met; otherwise, false.
The specified stat exists in App Admin on the Circuitry website, and the changes are published.
RequestCurrentStats has completed and successfully returned its callback.
* The type must be AVGRATE in the Circuitry Partner backend.

UploadLeaderboardScore

CircuitryAPICall_t UploadLeaderboardScore( CircuitryLeaderboard_t hCircuitryLeaderboard, ELeaderboardUploadScoreMethod eLeaderboardUploadScoreMethod, int32 nScore, const int32 *pScoreDetails, int cScoreDetailsCount );

Name	Type	Description
hCircuitryLeaderboard	CircuitryLeaderboard_t	A leaderboard handle obtained from FindLeaderboard or FindOrCreateLeaderboard.
eLeaderboardUploadScoreMethod	ELeaderboardUploadScoreMethod	Do you want to force the score to change, or keep the previous score if it was better?
nScore	int32	The score to upload.
pScoreDetails	const int32 *	Optional: Array containing the details surrounding the unlocking of this score.
cScoreDetailsCount	int	The number of elements in pScoreDetails. Must not exceed k_cLeaderboardDetailsMax

This function uploads a user score to a specified leaderboard.

Details are optional application-defined information which outlines how the user got that score. In addition, you may use bit fields as booleans to store the items the player picked up while playing if you have collectible items.

Uploading scores to the Robot Cache servers is rate limited to 10 uploads per 10 minutes and you may only have one outstanding call to this function at a time.

Returns: CircuitryAPICall_t to be used with a LeaderboardScoreUploaded_t call result.

Callbacks

These are callbacks which can be executed by calling the CircuitryAPI_RunCallbacks function. Many of these will be called directly in response to the member functions of ICircuitryUserStats.

GlobalAchievementPercentagesReady_t

This is called when the global achievement percentages have been received from the server.

Name	Type	Description
m_nGameID	uint64	Application ID which these achievement percentages are for.
m_eResult	EResult	Result of the request.
Returns: k_EResultOk indicating success. k_EResultInvalidState indicating statistics haven't been set yet, then call RequestCurrentStats
k_EResultFail if the remote call fails or there are no global achievement percentages for the current Application Id.

GlobalStatsReceived_t

Called when the global stats have been received from the server.

Name	Type	Description
m_nGameID	uint64	Game ID which these global stats are for.
m_eResult	EResult	Result of the request.
Returns: k_EResultOk indicating success, k_EResultInvalidState if stats haven't been loaded yet, then callRequestCurrentStats.
k_EResultFail if the remote call fails or there are no global achievement percentages for the current Application Id.

LeaderboardFindResult_t

Result when finding a leaderboard.

Name	Type	Description
m_hCircuitryLeaderboard	CircuitryLeaderboard_t	This is a handle to the leaderboard that was searched for. Returns a 0 if no leaderboard was found.
m_bLeaderboardFound	uint8	Was the leaderboard found? 1 if it was, 0 if it wasn't.

LeaderboardScoresDownloaded_t

This is called when scores for a leaderboard have been downloaded and are ready to be retrieved.
NOTE: After calling you must use the GetDownloadedLeaderboardEntry function to retrieve data for each downloaded entry.

Name	Type	Description
m_hCircuitryLeaderboard	CircuitryLeaderboard_t	This ia a handle to the leaderboard that these entries belong to.
m_hCircuitryLeaderboardEntries	[CircuitryLeaderboardEntries_t]	The is the handle to pass into [GetDownloadedLeaderboardEntry] to retrieve the info for each downloaded entry.
m_cEntryCount	int	The number of entries downloaded.

LeaderboardScoreUploaded_t

Result indicating that a leaderboard score has been uploaded.

Name	Type	Description
m_bSuccess	uint8	Returns 1 if the call was successful, 0 on failure. The amount of details sent exceeds k_cLeaderboardDetailsMax. DEVELOPER REVIEW: The leaderboard is set to "Trusted" in Robot Cache Paetner portal and will only accept scores sent from the Circuitry Web API.
m_hCircuitryLeaderboard	CircuitryLeaderboard_t	Handle to the leaderboard that this score was uploaded to.
m_nScore	int32	The score that was attempted to be set.
m_bScoreChanged	uint8	true if the score on the leaderboard changed otherwise false if the existing score was better.
m_nGlobalRankNew	int	The new global rank of the user on this leaderboard.
m_nGlobalRankPrevious	int	The previous global rank of the user on this leaderboard; 0 if the user had no existing entry in the leaderboard.

NumberOfCurrentPlayers_t

Gets the current number of players for the current Application Id.

Name	Type	Description
m_bSuccess	uint8	Returns 1 if it was; otherwise, 0 on failure.
m_cPlayers	int32	Number of players currently playing.

UserAchievementIconFetched_t

The result of an achievement icon that has been fetched.

Name	Type	Description
m_nGameID	CGameID	The Game ID this achievement is for.
m_rgchAchievementName	char［k_cchStatNameMax］	The name of the achievement that this callback is for.
m_bAchieved	bool	Returns whether the icon is for the achieved (true) or unachieved (false) version.
m_nIconHandle	int	This is a handle to the image, which can be used with the ICircuitryUtils::GetImageRGBA function to get the image data. 0 means no image is set for the achievement.

UserAchievementStored_t

This is the result of a request to store the achievements on the Robot Cache server, or an "indicate progress" call. If both m_nCurProgress and m_nMaxProgress are zero, this means the achievement has been fully unlocked.

Name	Type	Description
m_nGameID	uint64	The game ID that this achievement is for.
m_rgchAchievementName	char［k_cchStatNameMax］	Name of the achievement.
m_nCurProgress	uint32	The current progress towards completing the achievement.
m_nMaxProgress	uint32	The total amount of progress required to unlock the achievement.

UserStatsReceived_t

Called when the latest statistics and achievements for a specific user (including the local user) have been received from the Robot Cache server.

Name	Type	Description
m_nGameID	uint64	The game ID that these statistics are for.
m_eResult	EResult	Returns whether the call was successful or not. If the user has no statistics, this will be set to k_EResultFail.
m_circuitryIDUser	CCircuitryID	The user whose stats were retrieved.

UserStatsStored_t

The result of a request to store the user statistics.

Name	Type	Description
m_nGameID	uint64	The game ID that these stats are for.
m_eResult	EResult	Returns whether the call was successful or not.

UserStatsUnloaded_t

A callback indicating that a user's statistics have been unloaded. NOTE: You need to have called the RequestUserStats again before accessing statistics for this user.

Name	Type	Description
m_circuitryIDUser	CCircuitryID	A user whose stats have been unloaded.

Structures

These are structures which functions in ICircuitryUserStats may return and/or interact with.

LeaderboardEntry_t

A single entry in a leaderboard, as returned by GetDownloadedLeaderboardEntry.

Name	Type	Description
m_circuitryIDUser	CCircuitryID	A user who this entry belongs to. You may use [ICircuitryFriends::GetFriendPersonaName] and [ICircuitryFriends::GetSmallFriendAvatar] to get more info.
m_nGlobalRank	uint32	The global rank of this entry ranging from [1..N], where N is the number of users with an entry in the leaderboard.
m_nScore	uint32	This is the raw score as set in the leaderboard.
m_cDetails	uint32	This is the number of details available for this entry.

Enumerators

These are enumerators which are defined for use with ICircuitryUserStats.

ELeaderboardDataRequest

Type of data request, used when downloading leaderboard entries with DownloadLeaderboardEntries.

Name	Value	Description
k_ELeaderboardDataRequestGlobal	0	Used to query for a range of leaderboard entries by rank. The start/end parameters control the requested range. For example, you can display the top 10 for your application by setting start to 1 and end to 10.
k_ELeaderboardDataRequestGlobalAroundUser	1	Used to retrieve leaderboard entries relative a user's entry. The start parameter is the number of entries to retrieve before the current user's entry, and the end parameter is the number of entries after the current user's entry. The current user's entry is always included. For example, if the current user is #5 on the leaderboard, setting start to -2 and end to 2 will return 5 entries: ranks #3 through #7. If there are not enough entries in the leaderboard before or after the user's entry, Circuitry will adjust the range to attempt to return the number of entries requested.
k_ELeaderboardDataRequestFriends	2	Used to retrieve all leaderboard entries for friends of the current user. The start and end parameters are ignored.

ELeaderboardDisplayType

The display type to know how to format the leaderboard scores when displayed. DEVELOPER REVIEW: You can set the display type when creating a leaderboard with FindOrCreateLeaderboard or in the Robot Cache Partner Portal backend. You can retrieve the display type for a given leaderboard with GetLeaderboardDisplayType.

Name	Value	Description
k_ELeaderboardDisplayTypeNone	0	Do not set this. This is only ever used when a leaderboard is invalid.
k_ELeaderboardDisplayTypeNumeric	1	The score is just a simple numerical value.
k_ELeaderboardDisplayTypeTimeSeconds	2	The score represents a time, in seconds.
k_ELeaderboardDisplayTypeTimeMilliSeconds	3	The score represents a time, in milliseconds.

ELeaderboardSortMethod

The sort method used to set whether a higher or lower score is better. DEVELOPER REVIEW: You can set the sort method when creating a leaderboard with FindOrCreateLeaderboard or in the Robot Cache Partner Portal. You can retrieve the sort method for a given leaderboard with GetLeaderboardSortMethod.

Name	Value	Description
k_ELeaderboardSortMethodNone	0	Do not set this. Only used when a leaderboard is invalid.
k_ELeaderboardSortMethodAscending	1	The top-score is the lowest number.
k_ELeaderboardSortMethodDescending	2	The top-score is the highest number.

ELeaderboardUploadScoreMethod

Name	Value	Description
k_ELeaderboardUploadScoreMethodNone	0
k_ELeaderboardUploadScoreMethodKeepBest	1	Leaderboard will keep user's best score
k_ELeaderboardUploadScoreMethodForceUpdate	2	Leaderboard will always replace score with specified

Type Definitions

These are type definitions which are defined for use with ICircuitryUserStats.

Name	Base type	Description
CircuitryLeaderboardEntries_t	uint64	Handle to a list of downloaded entries in a leaderboard. This is returned by [LeaderboardScoresDownloaded_t] and can be used to iterate through all of the entries with [GetDownloadedLeaderboardEntry]
CircuitryLeaderboard_t	uint64	Handle to a single leaderboard.

Constants

These are constants which are defined for use with ICircuitryUserStats.

Name	Type	Value	Description
k_cchLeaderboardNameMax	int	128	Maximum number of bytes for a leaderboard name (UTF-8 encoded).
k_cchStatNameMax	int	128	Maximum number of bytes for stat and achievement names (UTF-8 encoded).
k_cLeaderboardDetailsMax	int	64	Maximum number of details that you can store for a single leaderboard entry.
ROBOTUSERSTATS_INTERFACE_VERSION	const char *	"ROBOTUSERSTATS_INTERFACE_VERSION011"