XblLeaderboardQuery
Represents the parameters for submitting a leaderboard query using event-based or title-based stats.Syntax
Members
xboxUserIdType: uint64_t Optional XBOX user ID of the requesting user. If doing a global leaderboard, then set to 0. scid
Type: char[XBL_SCID_LENGTH] The UTF-8 encoded service configuration ID (SCID) of the title. leaderboardName
Type: const char* Optional UTF-8 encoded leaderboard name to get a leaderboard for. Set to nullptr if querying a social leaderboard or a title managed stat backed leaderboard. statName
Type: const char* Optional UTF-8 encoded statistic name to get a leaderboard for. Used when querying a social leaderboard or title managed stat backed leaderboard. socialGroup
Type: XblSocialGroupType Optional the social group of users to get leaderboard results. For example, to get a “friends only” leaderboard. Set to XblSocialGroupType_None to get a global leaderboard. additionalColumnleaderboardNames
Type: const char** Optional UTF-8 encoded array of names of stats for the additional columns. additionalColumnleaderboardNamesCount
Type: size_t Optional count of additionalColumnleaderboardNames passed in. order
Type: XblLeaderboardSortOrder Set sort order for the resulting leaderboard. maxItems
Type: uint32_t Set the maximum number of items that the resulting leaderboard contains. Set to 0 to let the service return the default maximum number of items. skipToXboxUserId
Type: uint64_t Set which user the resulting leaderboard centers around. Set to 0 to not skip to a specific user. skipResultToRank
Type: uint32_t Set which rank the resulting leaderboard centers around. Set to 0 to not skip to a specific rank. continuationToken
Type: const char* The UTF-8 encoded continuationToken used to get the next set of leaderboard data. queryType
Type: XblLeaderboardQueryType The type of leaderboard to query for.
Member of
XblLeaderboardResultArgument of
XblLeaderboardGetLeaderboardAsyncRemarks
Event-based Stats
When using the statName member with event-based Stats, the value should coincide with a stat instance.Title-managed Stats
When using title-managed Stats for leaderboards, setting skipToXboxUserId to a nonzero value compares the given xboxUserId’s stored stat against the global leaderboard. Similarly, setting socialGroup to People or Favorites compares the stored stats of the given xboxUserId and the associated users. It doesn’t use values of the global leaderboard. Note that when a player’s stored stat and their score on the global leaderboard aren’t the same, this can result in mismatched outputs.For title-managed Stats, the global leaderboard entry for a player isn’t a direct projection of their current stored stat. The leaderboard service maintains only the highest recorded value for each player. As a result, writing a lower value to a stat doesn’t lower that player’s position on the global leaderboard; the leaderboard keeps reflecting the previously recorded high. The stored stat itself, queryable through
XblUserStatisticsGet* or XblTitleManagedStatsGetForUserAsync, reflects the value most recently written, which is why it can diverge from the leaderboard.If your title needs leaderboard positions to decrease, title-managed Stats aren’t suitable. Examples include a rating that goes up or down, or a score that resets on losses. Instead, consider event-based Stats with a Replace rule, or an external leaderboard service such as PlayFab Leaderboards v2. For more discussion of this behavior, see the LeaderboardsTitleManaged Microsoft Game Development Kit (GDK) sample’s Implementation Notes.Requirements
Header: leaderboard_c.hSee also
leaderboard_cEvent-based vs. title-managed Stats