供游戏服务器设置玩家统计与成就的函数。

成员函数

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

ClearUserAchievement

名称	类型	描述
steamIDUser	CSteamID	要清空其成就的用户的 Steam ID。
pchName	const char *	要解锁的成就的“API 名称”。

重置指定用户某一成就的解锁状态。

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

必须先调用 RequestUserStats，且须通过回调返回成功后，方可调用此函数！

此调用只修改 Steam 的内存状态，因此开销较小。 要将统计提交给服务器，则需调用 StoreUserStats。

注意： 此函数只能在允许游戏服务器设置的成就上生效。 如果此成就的“Set By”字段为“Official GS”，那么只有您宣布正式控制的服务器能够进行设置。 为此，您必须在“应用管理员”中的专用服务器项目下设置您的官方服务器的 IP 范围。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”，且更改已发布。
  
• RequestUserStats 已完成，且成功返回指定用户的回调。
  
• 必须允许游戏服务器设置统计。

GetUserAchievement

名称	类型	描述
steamIDUser	CSteamID	要为其获取成就的用户的 Steam ID。
pchName	const char *	成就的“API 名称”。
pbAchieved	bool *	返回成就的解锁状态。

获取成就的解锁状态。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• RequestUserStats 已完成，且成功返回回调。
  
• 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”，且更改已发布。

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

GetUserStat

名称	类型	描述
steamIDUser	CSteamID	要获得其统计的用户的 Steam ID。
pchName	const char *	统计的“API 名称”， 不得比 k_cchStatNameMax 中规定的长。
pData	int32 * / float *	要返回统计值至的变量。

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

必须先调用 RequestUserStats，且须通过回调返回成功后，方可调用此函数。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• 在 Steamworks 网站的“应用管理员”中存在指定统计，且更改已发布。
  
• RequestUserStats 已完成，且成功返回回调。
  
• 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。

RequestUserStats

名称	类型	描述
steamIDUser	CSteamID	要请求其统计的用户的 Steam ID。

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

只有目前正在服务器上进行游戏的客户端才会自动更新统计。 如需其他用户的数据，则需再次调用此函数才能更新。

返回： 返回：SteamAPICall_t，与 GSStatsReceived_t 调用结果一起使用。

SetUserAchievement

名称	类型	描述
steamIDUser	CSteamID	要为其解锁成就的用户的 Steam ID。
pchName	const char *	要解锁的成就的“API 名称”。

为指定用户解锁一项成就。

必须先调用 RequestUserStats，且须通过回调返回成功后，方可调用此函数！

此调用只修改 Steam 的内存状态，因此开销较小。 要将统计提交给服务器，则需调用 StoreUserStats。

注意： 此函数只能在允许游戏服务器设置的成就上生效。 如果此成就的“Set By”字段为“Official GS”，那么只有您宣布正式控制的服务器能够进行设置。 为此，您必须在“应用管理员”中的专用服务器项目下设置您的官方服务器的 IP 范围。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• 在 Steamworks 网站的“应用管理员”中存在指定成就的“API 名称”，且更改已发布。
  
• RequestUserStats 已完成，且成功返回指定用户的回调。
  
• 必须允许游戏服务器设置统计。

SetUserStat

名称	类型	描述
steamIDUser	CSteamID	要设置统计的用户的 Steam ID。
pchName	const char *	统计的“API 名称”， 不得比 k_cchStatNameMax 中规定的长。
nData	int32 / float	统计的新值。 统计的新值，必须为绝对值，不会为您递增或递减。

为指定用户设置或更新某一给定统计的值。

必须先调用 RequestUserStats，且须通过回调返回成功后，方可调用此函数！

此调用仅修改 Steam 的内存状态，因此消耗开销较小。 要将统计提交给服务器，则需调用 StoreUserStats。

注意： 此更新只能在允许游戏服务器编辑的统计上生效。 如果此统计的“Set By”字段为“Official GS”，那么只有您宣布正式控制的服务器能够进行设置。 为此，您必须在“应用管理员”中的专用服务器项目下设置您的官方服务器的 IP 范围。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• 在 Steamworks 网站的“应用管理员”中存在指定统计，且更改已发布。
  
• RequestUserStats 已完成，且成功返回指定用户的回调。
  
• 传入此函数的类型必须与 Steamworks 网站的“应用管理员”中列出的类型一致。
  
• 必须允许游戏服务器设置统计。

StoreUserStats

名称	类型	描述
steamIDUser	CSteamID	要存储其统计的用户的 Steam ID。

将指定用户已变更的统计与成就数据发送至服务器永久保存。

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

此调用会受到速率限制。 调用频率应该以分钟计，而非秒计。 您应只在重大状态更改时调用此函数，比如回合结束、地图更改或用户离开服务器时。

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

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

返回： SteamAPICall_t，与 GSStatsStored_t 调用结果一起使用。
如果 m_eResult 的结果为 k_EResultInvalidParam，那么有一项或多项统计因突破限制或过期而遭到拒绝。 这种情况下，服务器发回更新值，统计应在本地更新以保持同步。

UpdateUserAvgRateStat

名称	类型	描述
steamIDUser	CSteamID	要为其更新 AVGRATE 统计的用户的 Steam ID。
pchName	const char *	统计的“API 名称”， 不得比 k_cchStatNameMax 中规定的长。
flCountThisSession	float	自从上一次调用此函数后的累计值。
dSessionLength	double	自从上一次调用此函数后的时间，以秒数表示。

使用新值为指定用户更新 AVGRATE 统计。

必须先调用 ISteamGameServerStats::RequestUserStats，且须通过回调返回成功后，方可调用此函数！

此调用仅修改 Steam 的内存状态，因此消耗开销较小。 要将统计提交给服务器，则需调用 StoreUserStats。

注意： 此更新只能在允许游戏服务器编辑的统计上生效。 如果此统计的“Set By”字段为“Official GS”，那么只有您宣布正式控制的服务器能够进行设置。 为此，您必须在“应用管理员”中的专用服务器项目下设置您的官方服务器的 IP 范围。

返回： bool
如果下列所有条件都满足，此函数返回 true；否则返回 false。

• 在 Steamworks 网站的“应用管理员”中存在指定统计，且更改已发布。
  
• RequestUserStats 已完成，且成功返回指定用户的回调。
  
• Steamworks 合作伙伴后端中的类型须为 AVGRATE。
  
• 必须允许游戏服务器设置统计。

回调

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

GSStatsReceived_t

从服务器获取用户最新的统计和成就的结果。

名称	类型	描述
m_eResult	EResult	返回调用是否成功。 如果用户无统计，这将设置至 k_EResultFail。
m_steamIDUser	CSteamID	获取统计的用户。

关联函数： RequestUserStats

GSStatsStored_t

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

名称	类型	描述
m_eResult	EResult	返回调用是否成功。
m_steamIDUser	CSteamID	已存储其统计的用户。

关联函数： StoreUserStats

GSStatsUnloaded_t

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

再次调用 RequestUserStats 以访问此用户的统计。

名称	类型	描述
m_steamIDUser	CSteamID	已被卸载统计的用户。

常量

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

名称	类型	值	描述
STEAMGAMESERVERSTATS_INTERFACE_VERSION	const char *	"SteamGameServerStats001"