Skip to content

Using the plugin interface

Michael Rittenhouse edited this page Aug 20, 2017 · 27 revisions

AGS2Client isn't a plugin itself, but it does provide a common interface between plugins such as AGSteam and AGSGalaxy. The AGS2Client interface provides the following functions and properties for all supported game clients. (Note that for disjoint builds, AGS2Client will be replaced with the name of the plugin.)

Table of Contents

Functions

GetAverageRateStat

float AGS2Client.GetAverageRateStat(const string name)

Returns the value of the average rate stat with the specified name.

GetCurrentGameLanguage

String AGS2Client.GetCurrentGameLanguage()

Returns the current game language from the client.

GetFloatStat

float AGS2Client.GetFloatStat(const string name)

Returns the value of the float stat with the specified name.

GetIntStat

int AGS2Client.GetIntStat(const string name)

Returns the value of the int stat with the specified name.

GetUserName

String AGS2Client.GetUserName()

Returns the user name registered by the client. May return a null String.

IsAchievementAchieved

bool AGS2Client.IsAchievementAchieved(const string name)

Returns whether the achievement with the specified name has been achieved.

RequestLeaderboard

void AGS2Client.RequestLeaderboard(const string leaderboardName, AGS2ClientScoresRequestType, int limit)

Requests for the client to load leaderboard data (asynchronously) for the leaderboard with the specified name. AGS2ClientScoresRequestType may be one of eAGS2ClientScoresRequestGlobal, eAGS2ClientScoresRequestAroundUser, or eAGS2ClientScoresRequestFriends.

NOTE: This call is asynchronous, so you probably won't be able to use the results right away. You can check the CurrentLeaderboardName to see if the leaderboard has been loaded (possibly from repeatedly_execute, if you need to know as soon as it's loaded to populate a GUI).

NOTE: The enum AGS2ClientScoresRequestType and its values may be named differently on disjoint plugin builds. Autocomplete should provide you with an appropriate list of values based on your choice of plugin.

ResetAchievement

bool AGS2Client.ResetAchievement(const string name)

Resets the achievement with the specified name. Returns false if there was an error returned by the client.

ResetStatsAndAchievements

void AGS2Client.ResetStatsAndAchievements()

Resets all stats and achievements for the currently logged in user. Be sure to take care if using this function, as it cannot be undone without manually setting the stats and achievements again.

SetAchievementAchieved

bool AGS2Client.SetAchievementAchieved(const string name)

Sets the achievement with the specified name as "achieved". Returns false if there was an error returned by the client.

SetFloatStat

bool AGS2Client.SetFloatStat(const string name, float value)

Sets the value of the float stat with the specified name. Returns false if there was an error returned by the client.

SetIntStat

bool AGS2Client.SetIntStat(const string name, int value)

Sets the value of the int stat with the specified name. Returns false if there was an error returned by the client.

UpdateAverageRateStat

bool AGS2Client.UpdateAverageRateStat(const string name, float countThisSession, float sessionLength)

Updates the average rate stat with the specified name with the specified session data. Returns false if there was an error returned by the client.

UploadScore

bool AGS2Client.UploadScore(int score)

Uploads the specified score to your game's leaderboards. Returns false if there was an error returned by the client.

Properties

CurrentLeaderboardName

readonly String AGS2Client.CurrentLeaderboardName

Returns the name of the currently loaded leaderboard, or null if no leaderboard has been loaded.

NOTE: You must call RequestLeaderboard to populate leaderboard data first.

NOTE: Do not confuse this with the LeaderboardNames array. This property refers to the name of the leaderboard itself.

Initialized

readonly bool AGS2Client.Initialized

Returns whether the client is properly initialized. No other functions will work if the client has failed to initialize.

NOTE: Some clients require explicit initialization, while others do not. See Client-specific functions and properties below for any special instructions on connecting to the client.

LeaderboardCount

readonly int AGS2Client.LeaderboardCount

Returns the number of entries populated in the current leaderboard. The maximum index to LeaderboardNames and LeaderboardScores is one less than LeaderboardCount.

NOTE: You must call RequestLeaderboard to populate leaderboard data first.

LeaderboardNames

readonly String AGS2Client.LeaderboardNames[int index]

Returns the name of the specified entry from the leaderboard. Indexes are from zero to LeaderboardCount - 1.

NOTE: You must call RequestLeaderboard to populate leaderboard data first.

NOTE: Do not confuse this with the CurrentLeaderboardName property. This array refers to the names that appear as entries in the leaderboard, as associated with the LeaderboardScores.

LeaderboardScores

readonly int AGS2Client.LeaderboardScores[int index]

Returns the score of the specified entry from the leaderboard. Indexes are from zero to LeaderboardCount - 1.

NOTE: You must call RequestLeaderboard to populate leaderboard data first.

Client-specific functions and properties

The following functions and properties apply only to specific plugins. Consider using #ifdef around these in your game script to avoid having to change the scripts if disabling the plugin. (NOTE: These functions are always available to ags2clientstub, which ensures it works with all AGS2Client plugins.)

GOG Galaxy

Initialize

bool AGS2Client.Initialize(const string galaxyClientID, const string galaxyClientSecret)

Initializes the GOG Galaxy client with the client ID and client secret (given to you on the GOG Galaxy backend website). This must be called before you can use any other AGS2Client functions, so consider calling it in game_start or the room_FirstLoad of your first room that needs the plugin to be loaded.