提供访问并提交统计、成就与排行榜的函数。
成员函数
ISteamUserStats
的成员函数通过全局访问器函数
SteamUserStats()
调用。
AttachLeaderboardUGC
SteamAPICall_t AttachLeaderboardUGC( SteamLeaderboard_t hSteamLeaderboard, UGCHandle_t hUGC );
在排行榜的当前用户条目上添加一项用户生成内容。
此内容可以是该用户达到一定分数的回放,或是和用户竞技的 AI。 附加的句柄在获取到条目时可用,使用包含
LeaderboardEntry_t.m_hUGC
的
GetDownloadedLeaderboardEntry 的其他玩家可以访问。 要创建和下载用户生成内容,请参见 Steam 创意工坊文档。
内容一经添加后,即使基础云文件有更改或被用户删除,内容仍将可用。
您必须先调用
FindLeaderboard 或
FindOrCreateLeaderboard 以获取
SteamLeaderboard_t,然后才能调用此函数。
返回: SteamAPICall_t,与
LeaderboardUGCSet_t 调用结果一起使用。
ClearAchievement
bool ClearAchievement( const char *pchName );
名称 | 类型 | 描述 |
pchName | const char * | 要重置的成就的 "API 名称"。 |
重置一项成就的解锁状态。
此函数主要仅用于测试目的。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
此调用只修改 Steam 的内存状态,因此开销较小。 要向服务器发送解锁状态,触发 Steam 界面通知,您必须调用
StoreStats。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
另见: ResetAllStats、
GetAchievementAndUnlockTime、
GetAchievement、
SetAchievementDownloadLeaderboardEntries
SteamAPICall_t DownloadLeaderboardEntries( SteamLeaderboard_t hSteamLeaderboard, ELeaderboardDataRequest eLeaderboardDataRequest, int nRangeStart, int nRangeEnd );
为指定排行榜获取一系列排行榜条目。
您可以请求多于既有数量的条目,然后此函数将返回所有既有的条目。
如果您想要为任意一组用户下载条目,比如一个服务器上的所有用户,您可以使用
DownloadLeaderboardEntriesForUsers,这能接受一组 Steam ID。
您必须先调用
FindLeaderboard 或
FindOrCreateLeaderboard 以获取
SteamLeaderboard_t,然后才能调用此函数。
返回: SteamAPICall_t 与
LeaderboardScoresDownloaded_t 调用结果一起使用。
另见: GetDownloadedLeaderboardEntry、
UploadLeaderboardScoreDownloadLeaderboardEntriesForUsers
SteamAPICall_t DownloadLeaderboardEntriesForUsers( SteamLeaderboard_t hSteamLeaderboard, CSteamID *prgUsers, int cUsers );
为指定排行榜上的任何一组用户获取一系列排行榜条目。
一次只能有一个未处理调用,可下载最多 100 个用户。 如果一个用户在指定排行榜上没有条目,则结果中将不包含该用户。
如果您希望按用户排名或当前用户的好友为顺序下载条目,您应该使用
DownloadLeaderboardEntries。
您必须先调用
FindLeaderboard 或
FindOrCreateLeaderboard 以获取
SteamLeaderboard_t,然后才能调用此函数。
返回: SteamAPICall_t,与
LeaderboardScoresDownloaded_t 调用结果一起使用。
如果用户数量大于 100 或 Steam ID 无效,则返回
k_uAPICallInvalid,表示错误。
另见: GetDownloadedLeaderboardEntry、
UploadLeaderboardScoreFindLeaderboard
SteamAPICall_t FindLeaderboard( const char *pchLeaderboardName );
通过名称获取排行榜。
您必须先调用此函数或
FindOrCreateLeaderboard,获取对您想访问的各排行榜的游戏会话有效的排行榜句柄,然后才能调用其他任何排行榜函数。
返回: SteamAPICall_t,与
LeaderboardFindResult_t 调用结果一起使用。
另见: GetLeaderboardEntryCount、
DownloadLeaderboardEntries、
UploadLeaderboardScoreFindOrCreateLeaderboard
SteamAPICall_t FindOrCreateLeaderboard( const char *pchLeaderboardName, ELeaderboardSortMethod eLeaderboardSortMethod, ELeaderboardDisplayType eLeaderboardDisplayType );
通过名称获取排行榜。若该排行榜尚未创建,该函数将创建一个。
您必须对您想访问的各排行榜先调用此函数或
FindLeaderboard,获取对游戏会话有效的排行榜句柄,然后才能调用其他任何排行榜函数。
此函数创建的排行榜将不会自动显示在 Steam 社区中。 您必须在 Steamworks 网站的“应用管理员”面板中的“社区名称”中进行手动设置。 因此,我们通常建议在 Steamworks 网站的“应用管理员”面板中创建排行榜,并使用
FindLeaderboard,除非您预计会有大量动态创建的排行榜。
切勿向
eLeaderboardSortMethod
传入
k_ELeaderboardSortMethodNone 或向
eLeaderboardDisplayType
传入
k_ELeaderboardDisplayTypeNone,因为这是未定义的行为。
返回: SteamAPICall_t,与
LeaderboardFindResult_t 调用结果一起使用。
另见: GetLeaderboardEntryCount、
DownloadLeaderboardEntries、
UploadLeaderboardScoreGetAchievement
bool GetAchievement( const char *pchName, bool *pbAchieved );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
pbAchieved | bool * | 返回成就的解锁状态。 |
获取成就的解锁状态。
针对其他用户的等效函数为:
GetUserAchievement。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
如果调用成功, 则通过
pbAchieved
参数返回解锁状态。
另见: GetAchievementDisplayAttribute、
GetAchievementName、
GetAchievementIcon、
GetAchievementAndUnlockTime、
GetAchievementAchievedPercentGetAchievementAchievedPercent
bool GetAchievementAchievedPercent( const char *pchName, float *pflPercent );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
pflPercent | float * | 从 0 到 100 的变量,返回解锁此成就的人数百分比。 |
返回已解锁指定成就的用户的百分比。
您必须先调用
RequestGlobalAchievementPercentages,且须通过其回调返回成功之后,才能调用此函数。
返回: bool
若成功,返回
true;否则,如果
RequestGlobalAchievementPercentages 未被调用,或如果指定的“API 名称”在全局成就百分比中不存在时,返回
false。
另见: GetMostAchievedAchievementInfo、
GetNextMostAchievedAchievementInfoGetAchievementAndUnlockTime
bool GetAchievementAndUnlockTime( const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
pbAchieved | bool * | 返回是否当前用户已解锁此成就。 |
punUnlockTime | uint32 * | 如果 pbAchieved 为 true,返回成就解锁的时间。 |
获取成就状态,以及,如果已解锁,其解锁时间。
如果返回值为 true,但解锁时间为零,则表示该成就在 Steam 开始记录成就解锁时间(2009 年 12 月)之前解锁。 此时间用 Unix 时间戳表示为从 1970 年 1 月 1 日(UTC)起的秒数。
针对其他用户的等效函数为:
GetUserAchievementAndUnlockTime。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
如果调用成功,则通过
pbAchieved
和
punUnlockTime
返回解锁状态和成就解锁的时间。
另见: GetAchievement、
GetAchievementDisplayAttribute、
GetAchievementName、
GetAchievementIconGetAchievementDisplayAttribute
const char * GetAchievementDisplayAttribute( const char *pchName, const char *pchKey );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
pchKey | const char * | 要获取值的“键”。 |
获取一个成就的常规属性。 目前提供名称、描述与隐藏状态。
此函数从字典/地图键值库获取值,因此您必须提供下列键之一。
- 通过“name”获取 UTF8 本地化的成就名。
- 通过“desc”获取 UTF8 本地化的成就说明。
- 通过“hidden”获取成就的隐藏状态。 若未隐藏,返回“0”,若隐藏,返回“1”。
若设置了游戏语言,按游戏语言提供此本地化内容;否则,将查看是否有用户 Steam UI 语言的本地化内容。 如果此方法也失败,则提供英语。
返回: const char *
此函数若达成所有下列条件,则以字符串返回值,否则返回空白字符串:
""。
另见: GetAchievement、
GetAchievementName、
GetAchievementIcon、
GetAchievementAndUnlockTimeGetAchievementIcon
int GetAchievementIcon( const char *pchName );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
获取一个成就的图标。
返回: int
触发
UserAchievementIconFetched_t 回调。
图像以句柄形式返回,需和
ISteamUtils::GetImageRGBA 配合使用,以获取实际的图像数据。
满足下列条件会返回无效句柄
0:
另见: GetAchievement、
GetAchievementName、
GetAchievementAndUnlockTime、
GetAchievementAchievedPercent、
GetAchievementDisplayAttributeGetAchievementName
const char * GetAchievementName( uint32 iAchievement );
名称 | 类型 | 描述 |
iAchievement | uint32 | 成就索引。 |
获取一个索引为 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 );
为排行榜的单个条目获取数据。
您应该用一个 0 到
LeaderboardScoresDownloaded_t.m_cEntryCount
的循环来获取全部的下载条目。 一旦您访问了所有条目,数据将被释放,
SteamLeaderboardEntries_t 句柄变成无效。
此外,可选择通过
pDetails
返回条目详细信息。 如果返回 NULL,
cDetailsMax
必须是
0。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
如果调用成功,则本条目会通过
pLeaderboardEntry
参数返回,如果
cDetailsMax
不为 0, 则
pDetails
将以解锁详情填充。
另见: DownloadLeaderboardEntries、
UploadLeaderboardScore示例: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 );
名称 | 类型 | 描述 |
pchStatName | const char * | 统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。 |
pData | int64 * / double * | 要返回统计值至的变量。 |
获得聚合统计的所有时间的总量。
您必须先调用
RequestGlobalStats,且须通过其回调返回成功之后,才能调用此函数。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
- 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
- RequestGlobalStats 已完成且回调返回成功。
- 类型与 Steamworks 网站的“应用管理员”中列出的类型一致。
另见: GetGlobalStatHistoryGetGlobalStatHistory
int32 GetGlobalStatHistory( const char *pchStatName, int64 *pData, uint32 cubData );
int32 GetGlobalStatHistory( const char *pchStatName, double *pData, uint32 cubData );
名称 | 类型 | 描述 |
pchStatName | const char * | 统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。 |
pData | double * | 每日历史记录将返回至的数组。 |
cubData | uint32 | pData 数组的总文件大小,以字节计。 |
获得聚合统计的每日历史。
pData 将以每日的值填充,以今天为起始。
所以调用的时候,pData[0] 是今天,pData[1] 是昨天,pData[2] 是两天前,以此类推。
您必须先调用
RequestGlobalStats,且须通过其回调返回成功之后,才能调用此函数。
返回: int32The number of elements returned in the
pData
数组返回的元素数量。
数值为
0 时表明发生了错误,原因为下列情况之一:
- 在 Steamworks 网站的“应用管理员”中不存在指定统计,或者更改尚未发布。
- RequestGlobalStats 尚未被调用,或者未返回有至少一天的历史记录的回调。
- 类型与 Steamworks 网站的“应用管理员”中列出的类型不一致。
- 无历史记录可用。
另见: GetGlobalStatGetLeaderboardDisplayType
ELeaderboardDisplayType GetLeaderboardDisplayType( SteamLeaderboard_t hSteamLeaderboard );
返回一个排行榜句柄的显示类型。
返回: ELeaderboardDisplayType排行榜的显示类型。 如果排行榜句柄无效,返回
k_ELeaderboardDisplayTypeNone。
另见: GetLeaderboardName、
GetLeaderboardSortMethod、
GetLeaderboardEntryCountGetLeaderboardEntryCount
int GetLeaderboardEntryCount( SteamLeaderboard_t hSteamLeaderboard );
返回一个排行榜中的条目总数。
从对
FindLeaderboard 或
FindOrCreateLeaderboard 的第一次调用起,按各排行榜进行缓存;并且
DownloadLeaderboardEntries、
DownloadLeaderboardEntriesForUsers 及
UploadLeaderboardScore 每次成功调用时,都将更新。
返回: int
排行榜的条目数。 若排行榜句柄无效,返回 0。
另见: GetLeaderboardName、
GetLeaderboardSortMethod、
GetLeaderboardDisplayTypeGetLeaderboardName
const char * GetLeaderboardName( SteamLeaderboard_t hSteamLeaderboard );
返回排行榜句柄名称。
返回: const char *
排行榜的名字。 若排行榜句柄无效,返回空字符串。
另见: GetLeaderboardEntryCount、
GetLeaderboardSortMethod、
GetLeaderboardDisplayTypeGetLeaderboardSortMethod
ELeaderboardSortMethod GetLeaderboardSortMethod( SteamLeaderboard_t hSteamLeaderboard );
返回排行榜句柄的排序顺序。
返回: ELeaderboardSortMethod排行榜的排序方式。 若排行榜句柄无效,返回
k_ELeaderboardSortMethodNone。
另见: GetLeaderboardName、
GetLeaderboardDisplayType、
GetLeaderboardEntryCountGetMostAchievedAchievementInfo
int GetMostAchievedAchievementInfo( char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved );
名称 | 类型 | 描述 |
pchName | char * | 返回成就“API 名称”至的字符串缓冲区。 |
unNameBufLen | uint32 | pchName 的字节大小,最短应与您最长的成就“API 名称”长度一致。 |
pflPercent | float * | 从 0 到 100 的变量,返回解锁此成就的人数百分比。 |
pbAchieved | bool * | 变量,返回是否当前用户已解锁此成就。 |
获取此游戏中最常达成的成就的信息。
您必须先调用
RequestGlobalAchievementPercentages,且须通过其回调返回成功之后,才能调用此函数。
返回: int
如果
RequestGlobalAchievementPercentages 未被调用,或如果指定的“API 名称”在全局成就百分比中不存在时,返回
-1。
如果调用成功,则返回一个应与
GetNextMostAchievedAchievementInfo 一起使用的迭代器。
另见: RequestCurrentStats、
RequestGlobalAchievementPercentages、
GetNextMostAchievedAchievementInfo、
GetAchievementAchievedPercent示例: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 );
名称 | 类型 | 描述 |
iIteratorPrevious | int | 从上一次调用此函数或者调用 GetMostAchievedAchievementInfo 返回的迭代器。 |
pchName | char * | 返回成就“API 名称”至的字符串缓冲区。 |
unNameBufLen | uint32 | pchName 的字节大小,最短应与您最长的成就“API 名称”长度一致。 |
pflPercent | float * | 从 0 到 100 的变量,返回解锁此成就的人数百分比。 |
pbAchieved | bool * | 变量,返回是否当前用户已解锁此成就。 |
获取此游戏中排在下一位的最常达成的成就的信息。
您必须先调用
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。
另见: RequestCurrentStats、
GetAchievementName示例: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 );
获取当前用户的当前统计值。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
使用
GetUserStat 为其他用户获取统计。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
- 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
- RequestCurrentStats 已完成且回调返回成功。
- 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。
另见: RequestCurrentStats、
SetStat、
UpdateAvgRateStat、
StoreStats、
ResetAllStatsGetTrophySpaceRequiredBeforeInstall
uint64 GetTrophySpaceRequiredBeforeInstall();
弃用。
返回: uint64GetUserAchievement
bool GetUserAchievement( CSteamID steamIDUser, const char *pchName, bool *pbAchieved );
名称 | 类型 | 描述 |
steamIDUser | CSteamID | 要获取成就的用户的 Steam ID。 |
pchName | const char * | 成就的“API 名称”。 |
pbAchieved | bool * | 返回成就的解锁状态。 |
获取成就的解锁状态。
针对本地用户的等效函数为
GetAchievement,针对游戏服务器的等效函数为
ISteamGameServerStats::GetUserAchievement。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
如果调用成功, 则通过
pbAchieved
参数返回解锁状态。
另见: RequestUserStats、
GetUserStat、
GetUserAchievementAndUnlockTimeGetUserAchievementAndUnlockTime
bool GetUserAchievementAndUnlockTime( CSteamID steamIDUser, const char *pchName, bool *pbAchieved, uint32 *punUnlockTime );
名称 | 类型 | 描述 |
steamIDUser | CSteamID | 要获取成就的用户的 Steam ID。 |
pchName | const char * | 成就的“API 名称”。 |
pbAchieved | bool * | 返回是否当前用户已解锁此成就。 |
punUnlockTime | uint32 * | 如果 pbAchieved 为 true,返回成就解锁的时间。 |
获取成就状态,以及,如果已解锁,其解锁时间。
如果返回值为 true,但解锁时间为零,则表示该成就在 Steam 开始记录成就解锁时间(2009 年 12 月)之前解锁。 此时间用 Unix 时间戳表示为从 1970 年 1 月 1 日(UTC)起的秒数。
针对本地用户的等效函数为
GetAchievementAndUnlockTime。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
如果调用成功,则通过
pbAchieved
和
punUnlockTime
返回解锁状态和成就解锁的时间。
另见: RequestUserStats、
GetUserAchievement、
GetUserStatGetUserStat
bool GetUserStat( CSteamID steamIDUser, const char *pchName, int32 *pData );
bool GetUserStat( CSteamID steamIDUser, const char *pchName, float *pData );
获取指定用户的一个当前统计值。
您必须先调用
RequestUserStats,且须通过其回调返回成功之后,才能调用此函数。
针对本地用户的等效函数为
GetStat;针对游戏服务器的等效函数为
ISteamGameServerStats::GetUserStat。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
- 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
- RequestUserStats 已完成且回调返回成功。
- 类型与 Steamworks 网站的“应用管理员”中列出的类型不一致。
另见: GetUserAchievement、
GetUserAchievementAndUnlockTimeGetUserStatsData
bool GetUserStatsData( void *pvData, uint32 cubData, uint32 *pcubWritten );
弃用。
返回: bool
IndicateAchievementProgress
bool IndicateAchievementProgress( const char *pchName, uint32 nCurProgress, uint32 nMaxProgress );
名称 | 类型 | 描述 |
pchName | const char * | 成就的“API 名称”。 |
nCurProgress | uint32 | 当前进度。 |
nMaxProgress | uint32 | 要解锁成就所需的进度。 |
向用户显示成就当前进度的弹出通知。
游戏必须调用
SetStat 进行手动设置!
通知格式如下:
返回: bool
触发
UserStatsStored_t 回调。
触发
UserAchievementStored_t 回调。
此函数若达成所有下列条件,则返回
true;否则返回
false。
- RequestCurrentStats 已完成且回调返回成功。
- 在 Steanworks 网站的“应用管理员”中存在指定的成就,且更改已发布。
- 指定的成就尚未解锁。
-
nCurProgress
小于 nMaxProgress
。
另见: RequestCurrentStats、
SetAchievement、
SetStat、
StoreStats、
ISteamUtils::SetOverlayNotificationPosition、
ISteamUtils::SetOverlayNotificationInsetInstallPS3Trophies
bool InstallPS3Trophies();
弃用。
返回: bool
RequestCurrentStats
bool RequestCurrentStats();
向服务器异步请求用户的当前统计与成就。
必须先调用本函数以获取统计及成就的初始状态。
结果回调返回后才能开始调用当前用户剩下的统计及成就函数。
针对其他用户的等效函数为:
RequestUserStats。
返回: bool
触发一个
UserStatsReceived_t 回调。
如果没有登录的用户,返回
false,否则返回
true。
另见: GetStat、
SetStat、
SetAchievement、
StoreStatsRequestGlobalAchievementPercentages
SteamAPICall_t RequestGlobalAchievementPercentages();
异步获取全球获得该游戏各个成就的玩家百分比数据。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
返回: SteamAPICall_t,与
GlobalAchievementPercentagesReady_t 调用结果一起使用。
另见: GetMostAchievedAchievementInfo、
GetNextMostAchievedAchievementInfo、
GetAchievementAchievedPercentRequestGlobalStats
SteamAPICall_t RequestGlobalStats( int nHistoryDays );
名称 | 类型 | 描述 |
nHistoryDays | int | 除了统计总计之外,还需要获取多少天的每日历史记录。 最多不超过 60 天。 |
异步获取全局统计数据,该数据对 Steamworks 网站的“应用管理员”中标记为“聚合”的统计可用。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
返回: SteamAPICall_t,与
GlobalStatsReceived_t 调用结果一起使用。
另见: GetGlobalStat、
GetGlobalStatHistoryRequestUserStats
SteamAPICall_t RequestUserStats( CSteamID steamIDUser );
名称 | 类型 | 描述 |
steamIDUser | CSteamID | 请求其统计的用户的 Steam ID。 |
为指定用户从服务器异步下载统计与成就。
这些统计无法自动更新。您需要再次调用此函数,以更新可能变动的数据。
为了防止使用过多内存,会维持一个最近最少使用的缓存(LRU),其他用户的统计将偶尔卸载。 卸载时将发送
UserStatsUnloaded_t 回调。 收到此回调后,用户的统计将不可使用,直至此函数重新调用后为止。
针对本地用户的等效函数为
RequestCurrentStats;针对游戏服务器的等效函数为
ISteamGameServerStats::RequestUserStats。
返回: SteamAPICall_t,与
UserStatsReceived_t 调用结果一起使用。
另见: GetUserAchievement、
GetUserAchievementAndUnlockTime、
GetUserStatResetAllStats
bool ResetAllStats( bool bAchievementsToo );
名称 | 类型 | 描述 |
bAchievementsToo | bool | 是否也重置用户的成就? |
重置当前用户的统计,且可选择是否重置成就。
此函数自动调用
StoreStats,以持久保留对服务器的更改。 这通常应只用于开发时的测试目的。 在调用此函数之后,调用
RequestCurrentStats,确认您与 Steam 提供的新默认值同步了您的统计。
返回: bool
true 表示
RequestCurrentStats 已调用且成功地返回了其回调,也即成功;否则返回
false。
SetAchievement
bool SetAchievement( const char *pchName );
名称 | 类型 | 描述 |
pchName | const char * | 要解锁的成就的“API 名称”。 |
解锁一项成就。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
您可以多次解锁一项成就,而无需担心只设置尚未设置的成就。 此调用只修改 Steam 的内存状态,因此开销较小。 要向服务器发送解锁状态,触发 Steam 界面通知,您必须调用
StoreStats。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
另见: RequestCurrentStats、
StoreStats、
ResetAllStats、
GetAchievementAndUnlockTime、
GetAchievementSetStat
bool SetStat( const char *pchName, int32 nData );
bool SetStat( const char *pchName, float fData );
名称 | 类型 | 描述 |
pchName | const char * | 统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。 |
nData | int32 / float | 统计的新值。 统计的新值,必须为绝对值,不会为您递增或递减。 |
为当前用户设置/更新给定统计的值。
您必须先调用
RequestCurrentStats,且须通过其回调返回成功之后,才能调用此函数。
此调用只修改 Steam 的内存状态,因此开销较小。 这样做使 Steam 在游戏崩溃或意外关闭时能存留更改。
要将统计提交至服务器,必须调用
StoreStats。
如果返回 false,但一切似乎都正确,请检查确定您在 Steamworks 网站的“应用管理员”中已发布更改。
返回: bool
此函数若达成所有下列条件,返回
true;否则返回
false。
- 在 Steamworks 网站的“应用管理员”中存在指定统计,且更改已发布。
- RequestCurrentStats 已完成且回调返回成功。
- 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。
另见: GetStat、
UpdateAvgRateStat、
ResetAllStatsSetUserStatsData
bool SetUserStatsData( const void *pvData, uint32 cubData );
名称 | 类型 | 描述 |
pvData | const void * | |
cubData | uint32 | |
弃用。
返回: bool
StoreStats
bool StoreStats();
将变动的统计与成就数据发送至服务器进行持久保存。
若失败,则不会发送任何数据至服务器。 建议不断重试,直至调用成功。
此调用会受到速率限制。 调用频率应该以分钟计,而非秒计。 您应只在重大状态更改时调用此函数,比如回合结束、地图更改或用户离开服务器时。 不过,这调用要求显示成就解锁通知对话框,因此如果您已调用了
SetAchievement,那么建议您随后立即调用此函数。
如果在您的应用程序进程结束时,您在本地保存有统计或成就,且尚未使用此函数上传,那么此函数将自动调用。
您可以在
%steam_install%\logs\stats_log.txt
文件中找到更多调试信息。
返回: bool
触发
UserStatsStored_t 回调。
触发
UserAchievementStored_t 回调。
此函数若达成所有下列条件,则返回
true;否则返回
false。
如果调用成功,您将收到
UserStatsStored_t 回调。
如果
m_eResult
得到
k_EResultInvalidParam 的结果,那么有一个或多个统计因破坏约束或过期而遭到拒绝。 这种情况下,服务器发回更新值,统计应在本地更新以保持同步。 此时您无需再次调用 RequestCurrentStats。
如果已有一个或更多成就解锁,则这也将触发一个
UserAchievementStored_t 回调。
另见: SetStat、
SetAchievementUpdateAvgRateStat
bool UpdateAvgRateStat( const char *pchName, float flCountThisSession, double dSessionLength );
名称 | 类型 | 描述 |
pchName | const char * | 统计的“API 名称”, 必须不超过 k_cchStatNameMax 的规定。 |
flCountThisSession | float | 自从上一次调用此函数后的累计值。 |
dSessionLength | double | 自从上一次调用此函数后的时间秒数。 |
使用新值更新 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 );
向指定的排行榜上传用户得分。
详细信息为可选的由游戏定义的信息,描述了用户如何获得此得分。 例如,如果为计时竞速的排行榜,您可以在玩家到达每个检查点时记录时间戳。 如果沿路有收集品,您可以使用位域作为 boolean 集合保存玩家在玩时收集的物品。
将得分上传至 Steam 有速率限制,为每 10 分钟上传10 次,每次对此函数只能有一个未处理调用。
返回: SteamAPICall_t 与
LeaderboardScoresDownloaded_t 调用结果一起使用。
另见: DownloadLeaderboardEntries、
AttachLeaderboardUGC回调
以下是可以通过调用
SteamAPI_RunCallbacks 触发的回调。 其中许多将响应
ISteamUserStats
的成员函数直接触发。
GlobalAchievementPercentagesReady_t
当从服务器获得全局成就百分比时调用。
关联函数: RequestGlobalAchievementPercentagesGlobalStatsReceived_t
当从服务器获得全局统计时调用。
名称 | 类型 | 描述 |
m_nGameID | uint64 | 这些全局统计所针对的游戏 ID。 |
m_eResult | EResult | 请求的结果。 返回:
|
关联函数: RequestGlobalStatsLeaderboardFindResult_t
找到一个排行榜时出现结果。
名称 | 类型 | 描述 |
m_hSteamLeaderboard | SteamLeaderboard_t | 查询到的排行榜的句柄。 如果未找到排行榜,则为 0。 |
m_bLeaderboardFound | uint8 | 是否找到排行榜。 如果找到,则为 1,如果没找到,则为 0。 |
关联函数: FindOrCreateLeaderboard、
FindLeaderboardLeaderboardScoresDownloaded_t
当排行榜的得分已下载并可获取时调用。
调用后,您必须使用
GetDownloadedLeaderboardEntry,为各下载条目获取信息。
关联函数: DownloadLeaderboardEntries、
DownloadLeaderboardEntriesForUsersLeaderboardScoreUploaded_t
结果表示已上传一个排行榜得分。
名称 | 类型 | 描述 |
m_bSuccess | uint8 | 调用是否成功? 如果调用成功,则返回 1,失败则返回 0。 发送的详情数量超过了 k_cLeaderboardDetailsMax 的规定。 在 Steamworks 网站的应用管理员页面中,排行榜被设置为“受信任”,且将只接受从 Steam Web API 发送的得分。 |
m_hSteamLeaderboard | SteamLeaderboard_t | 此得分上传的排行榜的句柄。 |
m_nScore | int32 | 尝试设置的得分。 |
m_bScoreChanged | uint8 | 如果排行榜上的得分更改,为 true;否则,如果既有得分更高,则为 false。 |
m_nGlobalRankNew | int | 用户在此排行榜上的新全局排名。 |
m_nGlobalRankPrevious | int | 用户在此排行榜上的上次全局排名。如果用户在排行榜上无既有条目,则为 0。 |
关联函数: UploadLeaderboardScoreLeaderboardUGCSet_t
结果表示用户生成内容已附加到当前用户的排行榜的一个条目中。
关联函数: AttachLeaderboardUGCNumberOfCurrentPlayers_t
获得当前 AppId 的当前玩家数量。
名称 | 类型 | 描述 |
m_bSuccess | uint8 | 调用是否成功? 如果成功,返回 1,如果未成功,则返回 0。 |
m_cPlayers | int32 | 当前在玩的玩家数量。 |
关联函数: GetNumberOfCurrentPlayersPS3TrophiesInstalled_t
有 PS3 奖杯时调用。
UserAchievementIconFetched_t
已获取的成就图标的结果。
关联函数: GetAchievementIconUserAchievementStored_t
保存成就于服务器请求或“表示进度”调用的结果。 如果
m_nCurProgress
与
m_nMaxProgress
均为零,则说明成就已完全解锁。
关联函数: StoreStats、
IndicateAchievementProgressUserStatsReceived_t
当已从服务器收到指定用户(包括本地用户)的最新统计与成就时调用。
关联函数: RequestCurrentStats、
RequestUserStatsUserStatsStored_t
用户统计存储请求的结果。
关联函数: StoreStats、
IndicateAchievementProgressUserStatsUnloaded_t
表示用户统计已卸载的回调。
在访问该用户的统计之前,重新调用
RequestUserStats。
结构
以下是 ISteamUserStats 中的函数能够返回和/或与之交互的结构。
LeaderboardEntry_t
排行榜的单个条目,由
GetDownloadedLeaderboardEntry 返回。
枚举
以下是定义来与 ISteamUserStats 一起使用的枚举。
ELeaderboardDataRequest
数据请求类型,在下载排行榜条目时与
DownloadLeaderboardEntries 一起使用。
名称 | 值 | 描述 |
k_ELeaderboardDataRequestGlobal | 0 | 用于按排行榜排名查询排行榜条目的连续范围。 开始参数与结束参数控制请求的范围。 例如,您可以设置开始为 1,结束为 10,显示排行榜上的前 10 名。 |
k_ELeaderboardDataRequestGlobalAroundUser | 1 | 用于获取相对一个用户条目的排行榜条目。 开始参数为要获取的在当前用户条目之前的条目数量,结束参数为在当前用户条目之后的条目数量。 当前用户条目总是包含在内。 例如,如果当前用户在排行榜上排第 5 名,设置开始为 -2,结束为 2,则将返回 5 项,第 3 名至第 7 名。 如果在用户条目前面或后面没有足够条目,Steam 将调整范围,尝试返回请求的条目数量。 例如,如果用户在排行榜上排第 1 位,将开始设置为 -2,结束设置为 2,Steam 将返回排行榜上的前 5 位。 |
k_ELeaderboardDataRequestFriends | 2 | 用于获得当前用户的好友的所有排行榜项目。 忽略开始参数与结束参数。 |
k_ELeaderboardDataRequestUsers | 3 | 内部使用。切勿与 DownloadLeaderboardEntries 一起使用! 否则为未定义的行为。 |
ELeaderboardDisplayType
Steam 社区网站使用的显示类型,用于获知排行榜得分显示时的格式。 您可以在使用
FindOrCreateLeaderboard 创建排行榜是设置显示类型,或在 Steamworks 合作伙伴后端进行设置。 您可以使用
GetLeaderboardDisplayType 获取给定排行榜的显示类型。
名称 | 值 | 描述 |
k_ELeaderboardDisplayTypeNone | 0 | 此值只能在排行榜无效时使用。您绝不能自己设置此值。 |
k_ELeaderboardDisplayTypeNumeric | 1 | 得分只是简单的数字值。 |
k_ELeaderboardDisplayTypeTimeSeconds | 2 | 得分代表秒数表示的时间。 |
k_ELeaderboardDisplayTypeTimeMilliSeconds | 3 | 得分代表毫秒表示的时间。 |
ELeaderboardSortMethod
排序方法,用于设置是否更高分或更低分才更好。 您可以在使用
FindOrCreateLeaderboard 创建排行榜时设置排序方法,或者在 Steamworks 网站的“应用管理员”中进行设置。 您可以使用
GetLeaderboardSortMethod 获取给定排行榜的的排序方法。
名称 | 值 | 描述 |
k_ELeaderboardSortMethodNone | 0 | 只在排行榜无效时使用。绝不应自己设置此值。 |
k_ELeaderboardSortMethodAscending | 1 | 最高分为最小的数字。 |
k_ELeaderboardSortMethodDescending | 2 | 最高分为最大的数字。 |
ELeaderboardUploadScoreMethod
名称 | 值 | 描述 |
k_ELeaderboardUploadScoreMethodNone | 0 | |
k_ELeaderboardUploadScoreMethodKeepBest | 1 | 排行榜将保存用户的最高分。 |
k_ELeaderboardUploadScoreMethodForceUpdate | 2 | 排行榜将总是替换入指定得分。 |
Typedefs
以下是定义来与 ISteamUserStats 一起使用的 typedef。
常量
以下是定义来与 ISteamUserStats 一起使用的常量。
名称 | 类型 | 值 | 描述 |
k_cchLeaderboardNameMax | int | 128 | 排行榜名称(UTF-8)的最大字节数。 |
k_cchStatNameMax | int | 128 | 统计与成就名称(UTF-8)的最大字节数。 |
k_cLeaderboardDetailsMax | int | 64 | 您可以为单个排行榜条目存储的详情的最大数量。 |
STEAMUSERSTATS_INTERFACE_VERSION | const char * | "STEAMUSERSTATS_INTERFACE_VERSION011" | |