Steamworks 文献库
ISteamUserStats 接口
提供访问并提交统计、成就与排行榜的函数。

成员函数

ISteamUserStats 的成员函数通过全局访问器函数 SteamUserStats() 调用。

AttachLeaderboardUGC

SteamAPICall_t AttachLeaderboardUGC( SteamLeaderboard_t hSteamLeaderboard, UGCHandle_t hUGC );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。
hUGCUGCHandle_t指向使用 ISteamRemoteStorage::FileShare 共享的一项用户生成内容的句柄。

在排行榜的当前用户条目上添加一项用户生成内容。

此内容可以是该用户达到一定分数的回放,或是和用户竞技的 AI。 附加的句柄在获取到条目时可用,使用包含 LeaderboardEntry_t.m_hUGCGetDownloadedLeaderboardEntry 的其他玩家可以访问。 要创建和下载用户生成内容,请参见 Steam 创意工坊文档。

内容一经添加后,即使基础云文件有更改或被用户删除,内容仍将可用。

您必须先调用 FindLeaderboardFindOrCreateLeaderboard 以获取 SteamLeaderboard_t,然后才能调用此函数。

返回: SteamAPICall_t,与 LeaderboardUGCSet_t 调用结果一起使用。

ClearAchievement

bool ClearAchievement( const char *pchName );
名称类型描述
pchNameconst char *要重置的成就的 "API 名称"。

重置一项成就的解锁状态。

此函数主要仅用于测试目的。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

此调用只修改 Steam 的内存状态,因此开销较小。 要向服务器发送解锁状态,触发 Steam 界面通知,您必须调用 StoreStats

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。
  • RequestCurrentStats 已完成且回调返回成功。

另见: ResetAllStatsGetAchievementAndUnlockTimeGetAchievementSetAchievement

DownloadLeaderboardEntries

SteamAPICall_t DownloadLeaderboardEntries( SteamLeaderboard_t hSteamLeaderboard, ELeaderboardDataRequest eLeaderboardDataRequest, int nRangeStart, int nRangeEnd );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。
eLeaderboardDataRequestELeaderboardDataRequest要生成的数据请求类型。
nRangeStartint开始下载 eLeaderboardDataRequest 条目的索引。
nRangeEndint下载的最后的 eLeaderboardDataRequest 条目的索引。

为指定排行榜获取一系列排行榜条目。

您可以请求多于既有数量的条目,然后此函数将返回所有既有的条目。

如果您想要为任意一组用户下载条目,比如一个服务器上的所有用户,您可以使用 DownloadLeaderboardEntriesForUsers,这能接受一组 Steam ID。

您必须先调用 FindLeaderboardFindOrCreateLeaderboard 以获取 SteamLeaderboard_t,然后才能调用此函数。

返回: SteamAPICall_tLeaderboardScoresDownloaded_t 调用结果一起使用。


另见: GetDownloadedLeaderboardEntryUploadLeaderboardScore

DownloadLeaderboardEntriesForUsers

SteamAPICall_t DownloadLeaderboardEntriesForUsers( SteamLeaderboard_t hSteamLeaderboard, CSteamID *prgUsers, int cUsers );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。
prgUsersCSteamID *要获得排行榜条目的一组 Steam ID。
cUsersintprgUsers 数组内的元素数量。

为指定排行榜上的任何一组用户获取一系列排行榜条目。

一次只能有一个未处理调用,可下载最多 100 个用户。 如果一个用户在指定排行榜上没有条目,则结果中将不包含该用户。

如果您希望按用户排名或当前用户的好友为顺序下载条目,您应该使用 DownloadLeaderboardEntries

您必须先调用 FindLeaderboardFindOrCreateLeaderboard 以获取 SteamLeaderboard_t,然后才能调用此函数。

返回: SteamAPICall_t,与 LeaderboardScoresDownloaded_t 调用结果一起使用。
如果用户数量大于 100 或 Steam ID 无效,则返回 k_uAPICallInvalid,表示错误。

另见: GetDownloadedLeaderboardEntryUploadLeaderboardScore

FindLeaderboard

SteamAPICall_t FindLeaderboard( const char *pchLeaderboardName );
名称类型描述
pchLeaderboardNameconst char *要寻找的排行榜的名称。 必须不超过 k_cchLeaderboardNameMax 的规定。

通过名称获取排行榜。

您必须先调用此函数或 FindOrCreateLeaderboard,获取对您想访问的各排行榜的游戏会话有效的排行榜句柄,然后才能调用其他任何排行榜函数。

返回: SteamAPICall_t,与 LeaderboardFindResult_t 调用结果一起使用。


另见: GetLeaderboardEntryCountDownloadLeaderboardEntriesUploadLeaderboardScore

FindOrCreateLeaderboard

SteamAPICall_t FindOrCreateLeaderboard( const char *pchLeaderboardName, ELeaderboardSortMethod eLeaderboardSortMethod, ELeaderboardDisplayType eLeaderboardDisplayType );
名称类型描述
pchLeaderboardNameconst char *要寻找或创建的排行榜的名称。 必须不超过 k_cchLeaderboardNameMax 的规定。
eLeaderboardSortMethodELeaderboardSortMethod若创建新排行榜,此为其排序顺序。
eLeaderboardDisplayTypeELeaderboardDisplayType若创建新排行榜,此为其显示类型(用于 Steam 社区网站)。

通过名称获取排行榜。若该排行榜尚未创建,该函数将创建一个。

您必须对您想访问的各排行榜先调用此函数或 FindLeaderboard,获取对游戏会话有效的排行榜句柄,然后才能调用其他任何排行榜函数。

此函数创建的排行榜将不会自动显示在 Steam 社区中。 您必须在 Steamworks 网站的“应用管理员”面板中的“社区名称”中进行手动设置。 因此,我们通常建议在 Steamworks 网站的“应用管理员”面板中创建排行榜,并使用 FindLeaderboard,除非您预计会有大量动态创建的排行榜。

切勿向 eLeaderboardSortMethod 传入 k_ELeaderboardSortMethodNone 或向 eLeaderboardDisplayType 传入 k_ELeaderboardDisplayTypeNone,因为这是未定义的行为。

返回: SteamAPICall_t,与 LeaderboardFindResult_t 调用结果一起使用。


另见: GetLeaderboardEntryCountDownloadLeaderboardEntriesUploadLeaderboardScore

GetAchievement

bool GetAchievement( const char *pchName, bool *pbAchieved );
名称类型描述
pchNameconst char *成就的“API 名称”。
pbAchievedbool *返回成就的解锁状态。

获取成就的解锁状态。

针对其他用户的等效函数为:GetUserAchievement

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • RequestCurrentStats 已完成且回调返回成功。
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。

如果调用成功, 则通过 pbAchieved 参数返回解锁状态。

另见: GetAchievementDisplayAttributeGetAchievementNameGetAchievementIconGetAchievementAndUnlockTimeGetAchievementAchievedPercent

GetAchievementAchievedPercent

bool GetAchievementAchievedPercent( const char *pchName, float *pflPercent );
名称类型描述
pchNameconst char *成就的“API 名称”。
pflPercentfloat *从 0 到 100 的变量,返回解锁此成就的人数百分比。

返回已解锁指定成就的用户的百分比。

您必须先调用 RequestGlobalAchievementPercentages,且须通过其回调返回成功之后,才能调用此函数。

返回: bool
若成功,返回 true;否则,如果 RequestGlobalAchievementPercentages 未被调用,或如果指定的“API 名称”在全局成就百分比中不存在时,返回 false

另见: GetMostAchievedAchievementInfoGetNextMostAchievedAchievementInfo

GetAchievementAndUnlockTime

bool GetAchievementAndUnlockTime( const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
名称类型描述
pchNameconst char *成就的“API 名称”。
pbAchievedbool *返回是否当前用户已解锁此成就。
punUnlockTimeuint32 *如果 pbAchieved 为 true,返回成就解锁的时间。

获取成就状态,以及,如果已解锁,其解锁时间。

如果返回值为 true,但解锁时间为零,则表示该成就在 Steam 开始记录成就解锁时间(2009 年 12 月)之前解锁。 此时间用 Unix 时间戳表示为从 1970 年 1 月 1 日(UTC)起的秒数。

针对其他用户的等效函数为:GetUserAchievementAndUnlockTime

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • RequestCurrentStats 已完成且回调返回成功。
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。

如果调用成功,则通过 pbAchievedpunUnlockTime 返回解锁状态和成就解锁的时间。

另见: GetAchievementGetAchievementDisplayAttributeGetAchievementNameGetAchievementIcon

GetAchievementDisplayAttribute

const char * GetAchievementDisplayAttribute( const char *pchName, const char *pchKey );
名称类型描述
pchNameconst char *成就的“API 名称”。
pchKeyconst char *要获取值的“键”。

获取一个成就的常规属性。 目前提供名称、描述与隐藏状态。

此函数从字典/地图键值库获取值,因此您必须提供下列键之一。
  • 通过“name”获取 UTF8 本地化的成就名。
  • 通过“desc”获取 UTF8 本地化的成就说明。
  • 通过“hidden”获取成就的隐藏状态。 若未隐藏,返回“0”,若隐藏,返回“1”。

若设置了游戏语言,按游戏语言提供此本地化内容;否则,将查看是否有用户 Steam UI 语言的本地化内容。 如果此方法也失败,则提供英语。

返回: const char *
此函数若达成所有下列条件,则以字符串返回值,否则返回空白字符串:""
  • RequestCurrentStats 已完成且回调返回成功。
  • 在 Steanworks 网站的“应用管理员”中存在指定的成就,且更改已发布。
  • 指定的 pchKey 有效。

另见: GetAchievementGetAchievementNameGetAchievementIconGetAchievementAndUnlockTime

GetAchievementIcon

int GetAchievementIcon( const char *pchName );
名称类型描述
pchNameconst char *成就的“API 名称”。

获取一个成就的图标。

返回: int
触发 UserAchievementIconFetched_t 回调。
图像以句柄形式返回,需和 ISteamUtils::GetImageRGBA 配合使用,以获取实际的图像数据。

满足下列条件会返回无效句柄 0
  • RequestCurrentStats 未完成且回调未返回成功。
  • Steamworks 网站的“应用管理员”中无指定的成就,或者更改未发布。
  • Steam 仍在从服务器获取图像数据。 这将触发 UserAchievementIconFetched_t 回调,会在图像数据准备好后通知您并给您一个新的句柄。 如果回调内的 m_nIconHandle 仍旧是 0,那说明指定的成就没有设置图像。

另见: GetAchievementGetAchievementNameGetAchievementAndUnlockTimeGetAchievementAchievedPercentGetAchievementDisplayAttribute

GetAchievementName

const char * GetAchievementName( uint32 iAchievement );
名称类型描述
iAchievementuint32成就索引。

获取一个索引为 0 到 GetNumAchievements 之间的成就“API 名称”。

此函数必须与 GetNumAchievements 一起使用,在成就列表中循环。

一般情况下,游戏中应已编译有成就列表,不需要使用这些函数。

返回: const char *
成就的“API 名称”,如果 iAchievement 不是有效的索引的话返回空字符串。 RequestCurrentStats 必须被调用并成功返回其回调,且当前 APP ID 必须有成就。

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

GetDownloadedLeaderboardEntry

bool GetDownloadedLeaderboardEntry( SteamLeaderboardEntries_t hSteamLeaderboardEntries, int index, LeaderboardEntry_t *pLeaderboardEntry, int32 *pDetails, int cDetailsMax );
名称类型描述
hSteamLeaderboardEntriesSteamLeaderboardEntries_t从最后一次获取的 LeaderboardScoresDownloaded_t 调用结果中取得的一个排行榜条目句柄。
indexint需要接收的排行榜条目索引,必须在 0 到 LeaderboardScoresDownloaded_t.m_cEntryCount 之间。
pLeaderboardEntryLeaderboardEntry_t *条目将返回至的变量。
pDetailsint32 *此条目的详情要返回至的预分配数组。
cDetailsMaxintpDetails 的缓冲区长度。

为排行榜的单个条目获取数据。

您应该用一个 0 到 LeaderboardScoresDownloaded_t.m_cEntryCount 的循环来获取全部的下载条目。 一旦您访问了所有条目,数据将被释放,SteamLeaderboardEntries_t 句柄变成无效。

此外,可选择通过 pDetails 返回条目详细信息。 如果返回 NULL, cDetailsMax 必须是 0

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • hSteamLeaderboardEntries 必须是上一次调用LeaderboardScoresDownloaded_t 结果中的有效句柄。
  • 索引必须在 0 到 LeaderboardScoresDownloaded_t.m_cEntryCount 之间。

如果调用成功,则本条目会通过 pLeaderboardEntry 参数返回,如果 cDetailsMax 不为 0, 则 pDetails 将以解锁详情填充。

另见: DownloadLeaderboardEntriesUploadLeaderboardScore

示例:
void OnLeaderboardScoresDownloaded( LeaderboardScoresDownloaded_t *pCallback ) { for ( int i = 0; i < pCallback->m_cEntryCount; i++ ) { LeaderboardEntry_t leaderboardEntry; int32 details[3]; // 我们知道最初存了这么多。 SteamUserStats()->GetDownloadedLeaderboardEntry( pCallback->m_hSteamLeaderboardEntries, i, &leaderboardEntry, details, 3 ); assert( leaderboardEntry.m_cDetails == 3 ); //... } }

GetGlobalStat

bool GetGlobalStat( const char *pchStatName, int64 *pData ); bool GetGlobalStat( const char *pchStatName, double *pData );
名称类型描述
pchStatNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
pDataint64 * / double *要返回统计值至的变量。

获得聚合统计的所有时间的总量。

您必须先调用 RequestGlobalStats,且须通过其回调返回成功之后,才能调用此函数。

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
  • RequestGlobalStats 已完成且回调返回成功。
  • 类型与 Steamworks 网站的“应用管理员”中列出的类型一致。

另见: GetGlobalStatHistory

GetGlobalStatHistory

int32 GetGlobalStatHistory( const char *pchStatName, int64 *pData, uint32 cubData ); int32 GetGlobalStatHistory( const char *pchStatName, double *pData, uint32 cubData );
名称类型描述
pchStatNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
pDatadouble *每日历史记录将返回至的数组。
cubDatauint32pData 数组的总文件大小,以字节计。

获得聚合统计的每日历史。

pData 将以每日的值填充,以今天为起始。
所以调用的时候,pData[0] 是今天,pData[1] 是昨天,pData[2] 是两天前,以此类推。

您必须先调用 RequestGlobalStats,且须通过其回调返回成功之后,才能调用此函数。

返回: int32
The number of elements returned in the pData 数组返回的元素数量。

数值为 0 时表明发生了错误,原因为下列情况之一:
  • 在 Steamworks 网站的“应用管理员”中不存在指定统计,或者更改尚未发布。
  • RequestGlobalStats 尚未被调用,或者未返回有至少一天的历史记录的回调。
  • 类型与 Steamworks 网站的“应用管理员”中列出的类型不一致。
  • 无历史记录可用。

另见: GetGlobalStat

GetLeaderboardDisplayType

ELeaderboardDisplayType GetLeaderboardDisplayType( SteamLeaderboard_t hSteamLeaderboard );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。

返回一个排行榜句柄的显示类型。

返回: ELeaderboardDisplayType
排行榜的显示类型。 如果排行榜句柄无效,返回 k_ELeaderboardDisplayTypeNone

另见: GetLeaderboardNameGetLeaderboardSortMethodGetLeaderboardEntryCount

GetLeaderboardEntryCount

int GetLeaderboardEntryCount( SteamLeaderboard_t hSteamLeaderboard );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。

返回一个排行榜中的条目总数。

从对 FindLeaderboardFindOrCreateLeaderboard 的第一次调用起,按各排行榜进行缓存;并且 DownloadLeaderboardEntriesDownloadLeaderboardEntriesForUsersUploadLeaderboardScore 每次成功调用时,都将更新。

返回: int
排行榜的条目数。 若排行榜句柄无效,返回 0。

另见: GetLeaderboardNameGetLeaderboardSortMethodGetLeaderboardDisplayType

GetLeaderboardName

const char * GetLeaderboardName( SteamLeaderboard_t hSteamLeaderboard );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。

返回排行榜句柄名称。

返回: const char *
排行榜的名字。 若排行榜句柄无效,返回空字符串。

另见: GetLeaderboardEntryCountGetLeaderboardSortMethodGetLeaderboardDisplayType

GetLeaderboardSortMethod

ELeaderboardSortMethod GetLeaderboardSortMethod( SteamLeaderboard_t hSteamLeaderboard );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。

返回排行榜句柄的排序顺序。

返回: ELeaderboardSortMethod
排行榜的排序方式。 若排行榜句柄无效,返回 k_ELeaderboardSortMethodNone

另见: GetLeaderboardNameGetLeaderboardDisplayTypeGetLeaderboardEntryCount

GetMostAchievedAchievementInfo

int GetMostAchievedAchievementInfo( char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );
名称类型描述
pchNamechar *返回成就“API 名称”至的字符串缓冲区。
unNameBufLenuint32pchName 的字节大小,最短应与您最长的成就“API 名称”长度一致。
pflPercentfloat *从 0 到 100 的变量,返回解锁此成就的人数百分比。
pbAchievedbool *变量,返回是否当前用户已解锁此成就。

获取此游戏中最常达成的成就的信息。

您必须先调用 RequestGlobalAchievementPercentages,且须通过其回调返回成功之后,才能调用此函数。

返回: int
如果 RequestGlobalAchievementPercentages 未被调用,或如果指定的“API 名称”在全局成就百分比中不存在时,返回 -1

如果调用成功,则返回一个应与 GetNextMostAchievedAchievementInfo 一起使用的迭代器。

另见: RequestCurrentStatsRequestGlobalAchievementPercentagesGetNextMostAchievedAchievementInfoGetAchievementAchievedPercent

示例:
const int ACH_NAME_MAX_LENGTH = 64; char[ACH_NAME_MAX_LENGTH] achName; float achPercent; float achUnlocked; int i = SteamUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); while ( i != -1 ) { printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked ); // 做出类似添加/更新本地成就对象或者将其向用户显示的举动。 i = SteamUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); }

GetNextMostAchievedAchievementInfo

int GetNextMostAchievedAchievementInfo( int iIteratorPrevious, char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );
名称类型描述
iIteratorPreviousint从上一次调用此函数或者调用 GetMostAchievedAchievementInfo 返回的迭代器。
pchNamechar *返回成就“API 名称”至的字符串缓冲区。
unNameBufLenuint32pchName 的字节大小,最短应与您最长的成就“API 名称”长度一致。
pflPercentfloat *从 0 到 100 的变量,返回解锁此成就的人数百分比。
pbAchievedbool *变量,返回是否当前用户已解锁此成就。

获取此游戏中排在下一位的最常达成的成就的信息。

您必须先调用 RequestGlobalAchievementPercentages,且须通过其回调返回成功之后,才能调用此函数。

返回: int
如果 RequestGlobalAchievementPercentages 未被调用,或如果指定的“API 名称”在全局成就百分比中不存在时,返回 -1

如果调用成功会返回一个迭代器,该迭代器应与对此函数的后续调用一起使用。

示例:
const int ACH_NAME_MAX_LENGTH = 64; char[ACH_NAME_MAX_LENGTH] achName; float achPercent; float achUnlocked; int i = SteamUserStats()->GetMostAchievedAchievementInfo( achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); while ( i != -1 ) { printf( "AchievementInfo - name: %s, percent: %f, unlocked: %d", achName, achPercent, achUnlocked ); // 做出类似添加/更新本地成就对象或者将其向用户显示的举动。 i = SteamUserStats()->GetNextMostAchievedAchievementInfo( i, achName, ACH_NAME_MAX_LENGTH, achPercent, achUnlocked ); }

GetNumAchievements

uint32 GetNumAchievements();
获取在 Steamworks 网站的“应用管理员”中定义的成就数量。

这用于遍历 GetAchievementName 的所有成就。

一般情况下,游戏中应已编译有成就列表,不需要使用这些函数。

返回: uint32
成就的数量。 如果 RequestCurrentStats 尚未被调用,或未成功返回其回调,或当前 APP ID 无成就,则返回 0

另见: RequestCurrentStatsGetAchievementName

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

GetNumberOfCurrentPlayers

SteamAPICall_t GetNumberOfCurrentPlayers();
异步取回正在玩本游戏的玩家总数。 包括在线与在离线模式下的玩家。

返回: SteamAPICall_t,与 NumberOfCurrentPlayers_t 调用结果一起使用。

GetStat

bool GetStat( const char *pchName, int32 *pData ); bool GetStat( const char *pchName, float *pData );
名称类型描述
pchNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
pDataint32 * / float *要返回统计值至的变量。

获取当前用户的当前统计值。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

使用 GetUserStat 为其他用户获取统计。

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
  • RequestCurrentStats 已完成且回调返回成功。
  • 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。

另见: RequestCurrentStatsSetStatUpdateAvgRateStatStoreStatsResetAllStats

GetTrophySpaceRequiredBeforeInstall

uint64 GetTrophySpaceRequiredBeforeInstall();
弃用。

返回: uint64

GetUserAchievement

bool GetUserAchievement( CSteamID steamIDUser, const char *pchName, bool *pbAchieved );
名称类型描述
steamIDUserCSteamID要获取成就的用户的 Steam ID。
pchNameconst char *成就的“API 名称”。
pbAchievedbool *返回成就的解锁状态。

获取成就的解锁状态。

针对本地用户的等效函数为 GetAchievement,针对游戏服务器的等效函数为 ISteamGameServerStats::GetUserAchievement

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • RequestUserStats 已完成且回调返回成功。
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。

如果调用成功, 则通过 pbAchieved 参数返回解锁状态。

另见: RequestUserStatsGetUserStatGetUserAchievementAndUnlockTime

GetUserAchievementAndUnlockTime

bool GetUserAchievementAndUnlockTime( CSteamID steamIDUser, const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
名称类型描述
steamIDUserCSteamID要获取成就的用户的 Steam ID。
pchNameconst char *成就的“API 名称”。
pbAchievedbool *返回是否当前用户已解锁此成就。
punUnlockTimeuint32 *如果 pbAchieved 为 true,返回成就解锁的时间。

获取成就状态,以及,如果已解锁,其解锁时间。

如果返回值为 true,但解锁时间为零,则表示该成就在 Steam 开始记录成就解锁时间(2009 年 12 月)之前解锁。 此时间用 Unix 时间戳表示为从 1970 年 1 月 1 日(UTC)起的秒数。

针对本地用户的等效函数为 GetAchievementAndUnlockTime

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • RequestUserStats 已完成且回调返回成功。
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。

如果调用成功,则通过 pbAchievedpunUnlockTime 返回解锁状态和成就解锁的时间。

另见: RequestUserStatsGetUserAchievementGetUserStat

GetUserStat

bool GetUserStat( CSteamID steamIDUser, const char *pchName, int32 *pData ); bool GetUserStat( CSteamID steamIDUser, const char *pchName, float *pData );
名称类型描述
steamIDUserCSteamID要获得其统计的用户的 Steam ID。
pchNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
pDataint32 * / float *要返回统计值至的变量。

获取指定用户的一个当前统计值。

您必须先调用 RequestUserStats,且须通过其回调返回成功之后,才能调用此函数。

针对本地用户的等效函数为 GetStat;针对游戏服务器的等效函数为 ISteamGameServerStats::GetUserStat

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
  • RequestUserStats 已完成且回调返回成功。
  • 类型与 Steamworks 网站的“应用管理员”中列出的类型不一致。

另见: GetUserAchievementGetUserAchievementAndUnlockTime

GetUserStatsData

bool GetUserStatsData( void *pvData, uint32 cubData, uint32 *pcubWritten );
名称类型描述
pvDatavoid *
cubDatauint32
pcubWrittenuint32 *

弃用。

返回: bool

IndicateAchievementProgress

bool IndicateAchievementProgress( const char *pchName, uint32 nCurProgress, uint32 nMaxProgress );
名称类型描述
pchNameconst char *成就的“API 名称”。
nCurProgressuint32当前进度。
nMaxProgressuint32要解锁成就所需的进度。

向用户显示成就当前进度的弹出通知。

游戏必须调用 SetStat 进行手动设置!

通知格式如下:
achievement_progress.png

返回: bool
触发 UserStatsStored_t 回调。
触发 UserAchievementStored_t 回调。
此函数若达成所有下列条件,则返回 true;否则返回 false
  • RequestCurrentStats 已完成且回调返回成功。
  • 在 Steanworks 网站的“应用管理员”中存在指定的成就,且更改已发布。
  • 指定的成就尚未解锁。
  • nCurProgress 小于 nMaxProgress

另见: RequestCurrentStatsSetAchievementSetStatStoreStatsISteamUtils::SetOverlayNotificationPositionISteamUtils::SetOverlayNotificationInset

InstallPS3Trophies

bool InstallPS3Trophies();
弃用。

返回: bool

RequestCurrentStats

bool RequestCurrentStats();
向服务器异步请求用户的当前统计与成就。

必须先调用本函数以获取统计及成就的初始状态。
结果回调返回后才能开始调用当前用户剩下的统计及成就函数。

针对其他用户的等效函数为:RequestUserStats

返回: bool
触发一个 UserStatsReceived_t 回调。
如果没有登录的用户,返回 false,否则返回 true

另见: GetStatSetStatSetAchievementStoreStats

RequestGlobalAchievementPercentages

SteamAPICall_t RequestGlobalAchievementPercentages();
异步获取全球获得该游戏各个成就的玩家百分比数据。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

返回: SteamAPICall_t,与 GlobalAchievementPercentagesReady_t 调用结果一起使用。


另见: GetMostAchievedAchievementInfoGetNextMostAchievedAchievementInfoGetAchievementAchievedPercent

RequestGlobalStats

SteamAPICall_t RequestGlobalStats( int nHistoryDays );
名称类型描述
nHistoryDaysint除了统计总计之外,还需要获取多少天的每日历史记录。 最多不超过 60 天。

异步获取全局统计数据,该数据对 Steamworks 网站的“应用管理员”中标记为“聚合”的统计可用。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

返回: SteamAPICall_t,与 GlobalStatsReceived_t 调用结果一起使用。


另见: GetGlobalStatGetGlobalStatHistory

RequestUserStats

SteamAPICall_t RequestUserStats( CSteamID steamIDUser );
名称类型描述
steamIDUserCSteamID请求其统计的用户的 Steam ID。

为指定用户从服务器异步下载统计与成就。

这些统计无法自动更新。您需要再次调用此函数,以更新可能变动的数据。

为了防止使用过多内存,会维持一个最近最少使用的缓存(LRU),其他用户的统计将偶尔卸载。 卸载时将发送 UserStatsUnloaded_t 回调。 收到此回调后,用户的统计将不可使用,直至此函数重新调用后为止。

针对本地用户的等效函数为 RequestCurrentStats;针对游戏服务器的等效函数为 ISteamGameServerStats::RequestUserStats

返回: SteamAPICall_t,与 UserStatsReceived_t 调用结果一起使用。


另见: GetUserAchievementGetUserAchievementAndUnlockTimeGetUserStat

ResetAllStats

bool ResetAllStats( bool bAchievementsToo );
名称类型描述
bAchievementsToobool是否也重置用户的成就?

重置当前用户的统计,且可选择是否重置成就。

此函数自动调用 StoreStats,以持久保留对服务器的更改。 这通常应只用于开发时的测试目的。 在调用此函数之后,调用 RequestCurrentStats,确认您与 Steam 提供的新默认值同步了您的统计。

返回: bool
true 表示 RequestCurrentStats 已调用且成功地返回了其回调,也即成功;否则返回 false

SetAchievement

bool SetAchievement( const char *pchName );
名称类型描述
pchNameconst char *要解锁的成就的“API 名称”。

解锁一项成就。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

您可以多次解锁一项成就,而无需担心只设置尚未设置的成就。 此调用只修改 Steam 的内存状态,因此开销较小。 要向服务器发送解锁状态,触发 Steam 界面通知,您必须调用 StoreStats

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”,且更改已发布。
  • RequestCurrentStats 已完成且回调返回成功。

另见: RequestCurrentStatsStoreStatsResetAllStatsGetAchievementAndUnlockTimeGetAchievement

SetStat

bool SetStat( const char *pchName, int32 nData ); bool SetStat( const char *pchName, float fData );
名称类型描述
pchNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
nDataint32 / float统计的新值。 统计的新值,必须为绝对值,不会为您递增或递减。

为当前用户设置/更新给定统计的值。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

此调用只修改 Steam 的内存状态,因此开销较小。 这样做使 Steam 在游戏崩溃或意外关闭时能存留更改。
要将统计提交至服务器,必须调用 StoreStats

如果返回 false,但一切似乎都正确,请检查确定您在 Steamworks 网站的“应用管理员”中已发布更改。

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
  • RequestCurrentStats 已完成且回调返回成功。
  • 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。

另见: GetStatUpdateAvgRateStatResetAllStats

SetUserStatsData

bool SetUserStatsData( const void *pvData, uint32 cubData );
名称类型描述
pvDataconst void *
cubDatauint32

弃用。

返回: bool

StoreStats

bool StoreStats();
将变动的统计与成就数据发送至服务器进行持久保存。

若失败,则不会发送任何数据至服务器。 建议不断重试,直至调用成功。

此调用会受到速率限制。 调用频率应该以分钟计,而非秒计。 您应只在重大状态更改时调用此函数,比如回合结束、地图更改或用户离开服务器时。 不过,这调用要求显示成就解锁通知对话框,因此如果您已调用了 SetAchievement,那么建议您随后立即调用此函数。

如果在您的应用程序进程结束时,您在本地保存有统计或成就,且尚未使用此函数上传,那么此函数将自动调用。

您可以在 %steam_install%\logs\stats_log.txt 文件中找到更多调试信息。

返回: bool
触发 UserStatsStored_t 回调。
触发 UserAchievementStored_t 回调。
此函数若达成所有下列条件,则返回 true;否则返回 false
  • RequestCurrentStats 已完成且回调返回成功。
  • 在 Steamworks 合作伙伴后端,当前游戏相关联的统计,这些统计已发布。

如果调用成功,您将收到 UserStatsStored_t 回调。

如果 m_eResult 得到 k_EResultInvalidParam 的结果,那么有一个或多个统计因破坏约束或过期而遭到拒绝。 这种情况下,服务器发回更新值,统计应在本地更新以保持同步。 此时您无需再次调用 RequestCurrentStats。

如果已有一个或更多成就解锁,则这也将触发一个 UserAchievementStored_t 回调。

另见: SetStatSetAchievement

UpdateAvgRateStat

bool UpdateAvgRateStat( const char *pchName, float flCountThisSession, double dSessionLength );
名称类型描述
pchNameconst char *统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。
flCountThisSessionfloat自从上一次调用此函数后的累计值。
dSessionLengthdouble自从上一次调用此函数后的时间秒数。

使用新值更新 AVGRATE 统计。

您必须先调用 RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。

此调用仅修改 Steam 的内存状态,因此消耗开销较小。 这样做使 Steam 在游戏崩溃或意外关闭时能存留更改。
要将统计提交至服务器,必须调用 StoreStats

如果返回 false,但一切似乎都正确,请检查确定您在 Steamworks 网站的“应用管理员”中已发布更改。

返回: bool
此函数若达成所有下列条件,返回 true;否则返回 false
  • 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
  • RequestCurrentStats 已完成且回调返回成功。
  • Steamworks 合作伙伴后端中的类型须为 AVGRATE。

UploadLeaderboardScore

SteamAPICall_t UploadLeaderboardScore( SteamLeaderboard_t hSteamLeaderboard, ELeaderboardUploadScoreMethod eLeaderboardUploadScoreMethod, int32 nScore, const int32 *pScoreDetails, int cScoreDetailsCount );
名称类型描述
hSteamLeaderboardSteamLeaderboard_tFindLeaderboardFindOrCreateLeaderboard 获取的排行榜句柄。
eLeaderboardUploadScoreMethodELeaderboardUploadScoreMethod您是否希望强制更改得分,或者如果之前的得分更好,将其保留?
nScoreint32要上传的得分。
pScoreDetailsconst int32 *可选:一组关于解锁此得分的详细信息。
cScoreDetailsCountintpScoreDetails 中的元素数量。 必须不超过 k_cLeaderboardDetailsMax 的规定。

向指定的排行榜上传用户得分。

详细信息为可选的由游戏定义的信息,描述了用户如何获得此得分。 例如,如果为计时竞速的排行榜,您可以在玩家到达每个检查点时记录时间戳。 如果沿路有收集品,您可以使用位域作为 boolean 集合保存玩家在玩时收集的物品。

将得分上传至 Steam 有速率限制,为每 10 分钟上传10 次,每次对此函数只能有一个未处理调用。

返回: SteamAPICall_tLeaderboardScoresDownloaded_t 调用结果一起使用。


另见: DownloadLeaderboardEntriesAttachLeaderboardUGC

回调

以下是可以通过调用 SteamAPI_RunCallbacks 触发的回调。 其中许多将响应 ISteamUserStats 的成员函数直接触发。

GlobalAchievementPercentagesReady_t

当从服务器获得全局成就百分比时调用。

名称类型描述
m_nGameIDuint64这些成就百分比所针对的游戏 ID。
m_eResultEResult请求的结果。 返回:
k_EResultOK 表示成功。
k_EResultInvalidState 表示统计尚未载入,调用 RequestCurrentStats
k_EResultFail 表示远程调用失败,或者此 AppId 无全局成就百分比。

关联函数: RequestGlobalAchievementPercentages

GlobalStatsReceived_t

当从服务器获得全局统计时调用。

名称类型描述
m_nGameIDuint64这些全局统计所针对的游戏 ID。
m_eResultEResult请求的结果。 返回:

关联函数: RequestGlobalStats

LeaderboardFindResult_t

找到一个排行榜时出现结果。

名称类型描述
m_hSteamLeaderboardSteamLeaderboard_t查询到的排行榜的句柄。 如果未找到排行榜,则为 0
m_bLeaderboardFounduint8是否找到排行榜。 如果找到,则为 1,如果没找到,则为 0

关联函数: FindOrCreateLeaderboardFindLeaderboard

LeaderboardScoresDownloaded_t

当排行榜的得分已下载并可获取时调用。
调用后,您必须使用 GetDownloadedLeaderboardEntry,为各下载条目获取信息。

名称类型描述
m_hSteamLeaderboardSteamLeaderboard_t这些条目所属的排行榜的句柄。
m_hSteamLeaderboardEntriesSteamLeaderboardEntries_t传入 GetDownloadedLeaderboardEntry 句柄以获取各下载条目的信息。
m_cEntryCountint下载条目的数量。

关联函数: DownloadLeaderboardEntriesDownloadLeaderboardEntriesForUsers

LeaderboardScoreUploaded_t

结果表示已上传一个排行榜得分。

名称类型描述
m_bSuccessuint8调用是否成功? 如果调用成功,则返回 1,失败则返回 0
发送的详情数量超过了 k_cLeaderboardDetailsMax 的规定。
在 Steamworks 网站的应用管理员页面中,排行榜被设置为“受信任”,且将只接受从 Steam Web API 发送的得分。
m_hSteamLeaderboardSteamLeaderboard_t此得分上传的排行榜的句柄。
m_nScoreint32尝试设置的得分。
m_bScoreChangeduint8如果排行榜上的得分更改,为 true;否则,如果既有得分更高,则为 false
m_nGlobalRankNewint用户在此排行榜上的新全局排名。
m_nGlobalRankPreviousint用户在此排行榜上的上次全局排名。如果用户在排行榜上无既有条目,则为 0

关联函数: UploadLeaderboardScore

LeaderboardUGCSet_t

结果表示用户生成内容已附加到当前用户的排行榜的一个条目中。

名称类型描述
m_eResultEResult操作结果。可能值为:
m_hSteamLeaderboardSteamLeaderboard_tUGC 附加至的排行榜的句柄。

关联函数: AttachLeaderboardUGC

NumberOfCurrentPlayers_t

获得当前 AppId 的当前玩家数量。

名称类型描述
m_bSuccessuint8调用是否成功? 如果成功,返回 1,如果未成功,则返回 0
m_cPlayersint32当前在玩的玩家数量。

关联函数: GetNumberOfCurrentPlayers

PS3TrophiesInstalled_t

有 PS3 奖杯时调用。

名称类型描述
m_nGameIDuint64这些统计所针对的游戏。
m_eResultEResult操作结果。
m_ulRequiredDiskSpaceuint64如果 m_eResultk_EResultDiskFull,则这将包含需要安装奖杯的空间。

UserAchievementIconFetched_t

已获取的成就图标的结果。

名称类型描述
m_nGameIDCGameID此成就的游戏 ID。
m_rgchAchievementNamechar[k_cchStatNameMax此回调针对成就的名称。
m_bAchievedbool返回图标是已达成(true)的版本,还是未达成(false)的版本。
m_nIconHandleint图像的句柄,可与 ISteamUtils::GetImageRGBA 一起使用,获取图像数据。 0 表示成就未设置图像。

关联函数: GetAchievementIcon

UserAchievementStored_t

保存成就于服务器请求或“表示进度”调用的结果。 如果 m_nCurProgressm_nMaxProgress 均为零,则说明成就已完全解锁。

名称类型描述
m_nGameIDuint64此成就的游戏 ID。
m_bGroupAchievementbool未使用。
m_rgchAchievementNamechar[k_cchStatNameMax成就名称。
m_nCurProgressuint32成就的当前进度。
m_nMaxProgressuint32解锁所需的总进度。

关联函数: StoreStatsIndicateAchievementProgress

UserStatsReceived_t

当已从服务器收到指定用户(包括本地用户)的最新统计与成就时调用。

名称类型描述
m_nGameIDuint64这些统计针对的游戏 ID。
m_eResultEResult返回调用是否成功。 如果用户无统计,这将设置为 k_EResultFail
m_steamIDUserCSteamID获取统计的用户。

关联函数: RequestCurrentStatsRequestUserStats

UserStatsStored_t

用户统计存储请求的结果。

名称类型描述
m_nGameIDuint64这些统计针对的游戏 ID。
m_eResultEResult返回调用是否成功。

关联函数: StoreStatsIndicateAchievementProgress

UserStatsUnloaded_t

表示用户统计已卸载的回调。

在访问该用户的统计之前,重新调用 RequestUserStats

名称类型描述
m_steamIDUserCSteamID统计已卸载的用户。

结构

以下是 ISteamUserStats 中的函数能够返回和/或与之交互的结构。

LeaderboardEntry_t

排行榜的单个条目,由 GetDownloadedLeaderboardEntry 返回。

名称类型描述
m_steamIDUserCSteamID此条目所属的用户。 您可以使用 ISteamFriends::GetFriendPersonaNameISteamFriends::GetSmallFriendAvatar 获取更多信息。
m_nGlobalRankint32以 [1..N] 为范围的此条目的全局排名,其中 N 为在排行榜中有条目的用户数量。
m_nScoreint32排行榜中设置的原始得分。
m_cDetailsint32此条目拥有的详情数量。
m_hUGCUGCHandle_t附加于此条目的 UGC 的句柄。 若无,为 k_UGCHandleInvalid

枚举

以下是定义来与 ISteamUserStats 一起使用的枚举。

ELeaderboardDataRequest

数据请求类型,在下载排行榜条目时与 DownloadLeaderboardEntries 一起使用。

名称描述
k_ELeaderboardDataRequestGlobal0用于按排行榜排名查询排行榜条目的连续范围。 开始参数与结束参数控制请求的范围。 例如,您可以设置开始为 1,结束为 10,显示排行榜上的前 10 名。
k_ELeaderboardDataRequestGlobalAroundUser1用于获取相对一个用户条目的排行榜条目。 开始参数为要获取的在当前用户条目之前的条目数量,结束参数为在当前用户条目之后的条目数量。 当前用户条目总是包含在内。 例如,如果当前用户在排行榜上排第 5 名,设置开始为 -2,结束为 2,则将返回 5 项,第 3 名至第 7 名。 如果在用户条目前面或后面没有足够条目,Steam 将调整范围,尝试返回请求的条目数量。 例如,如果用户在排行榜上排第 1 位,将开始设置为 -2,结束设置为 2,Steam 将返回排行榜上的前 5 位。
k_ELeaderboardDataRequestFriends2用于获得当前用户的好友的所有排行榜项目。 忽略开始参数与结束参数。
k_ELeaderboardDataRequestUsers3内部使用。切勿与 DownloadLeaderboardEntries 一起使用! 否则为未定义的行为。

ELeaderboardDisplayType

Steam 社区网站使用的显示类型,用于获知排行榜得分显示时的格式。 您可以在使用 FindOrCreateLeaderboard 创建排行榜是设置显示类型,或在 Steamworks 合作伙伴后端进行设置。 您可以使用 GetLeaderboardDisplayType 获取给定排行榜的显示类型。

名称描述
k_ELeaderboardDisplayTypeNone0此值只能在排行榜无效时使用。您绝不能自己设置此值。
k_ELeaderboardDisplayTypeNumeric1得分只是简单的数字值。
k_ELeaderboardDisplayTypeTimeSeconds2得分代表秒数表示的时间。
k_ELeaderboardDisplayTypeTimeMilliSeconds3得分代表毫秒表示的时间。

ELeaderboardSortMethod

排序方法,用于设置是否更高分或更低分才更好。 您可以在使用 FindOrCreateLeaderboard 创建排行榜时设置排序方法,或者在 Steamworks 网站的“应用管理员”中进行设置。 您可以使用 GetLeaderboardSortMethod 获取给定排行榜的的排序方法。

名称描述
k_ELeaderboardSortMethodNone0只在排行榜无效时使用。绝不应自己设置此值。
k_ELeaderboardSortMethodAscending1最高分为最小的数字。
k_ELeaderboardSortMethodDescending2最高分为最大的数字。

ELeaderboardUploadScoreMethod



名称描述
k_ELeaderboardUploadScoreMethodNone0
k_ELeaderboardUploadScoreMethodKeepBest1排行榜将保存用户的最高分。
k_ELeaderboardUploadScoreMethodForceUpdate2排行榜将总是替换入指定得分。

Typedefs

以下是定义来与 ISteamUserStats 一起使用的 typedef。

名称基类型描述
SteamLeaderboardEntries_tuint64排行榜的下载条目列表的句柄。 由 LeaderboardScoresDownloaded_t 返回,可以用于遍历 GetDownloadedLeaderboardEntry 的所有条目。
SteamLeaderboard_tuint64单个排行榜的句柄。

常量

以下是定义来与 ISteamUserStats 一起使用的常量。

名称类型描述
k_cchLeaderboardNameMaxint128排行榜名称(UTF-8)的最大字节数。
k_cchStatNameMaxint128统计与成就名称(UTF-8)的最大字节数。
k_cLeaderboardDetailsMaxint64您可以为单个排行榜条目存储的详情的最大数量。
STEAMUSERSTATS_INTERFACE_VERSIONconst char *"STEAMUSERSTATS_INTERFACE_VERSION011"