Funções para permitir que servidores definam estatísticas e conquistas para jogadores.

Funções de membro

Funções de membro de ISteamGameServerStats são chamadas por meio da função de acesso global SteamGameServerStats().

ClearUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cuja conquista reverter.
pchName	const char *	O "nome na API" da conquista a reverter.

Reverte uma conquista do usuário especificado.

Usada principalmente para testes.

Você deve chamar RequestUserStats, e o retorno de chamada deve receber um valor de sucesso antes de chamar esta função!

Esta chamada só modifica o estado do Steam na memória e não é custosa. Para enviar as estatísticas ao servidor, chame a função StoreUserStats.

AVISO: só funciona em conquistas que podem ser alteradas por servidores. Se o campo "Definida por" da conquista especificada for "Servidores oficiais", então apenas servidores declarados como controlados oficialmente por você poderão alterá-la. Para tal, será necessário definir o intervalo de endereços IP dos servidores oficiais na seção Servidores dedicados da administração de aplicativo.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• O "nome na API" especificado da conquista existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas;
  
• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado para o usuário especificado;
  
• A estatística pode ser alterada pelo servidor.

GetUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário do qual recuperar a conquista.
pchName	const char *	O "nome na API" da conquista.
pbAchieved	bool *	Retorna se a conquista já foi alcançada pelo usuário.

Recupera se a conquista já foi alcançada pelo usuário ou não.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado;
  
• O "nome na API" especificado da conquista existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas.

Se a chamada for bem-sucedida, então o resultado será retornado no parâmetro pbAchieved.

GetUserStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cuja estatística recuperar.
pchName	const char *	O "nome na API" da estatística. Não pode ultrapassar o tamanho definido pela constante k_cchStatNameMax.
pData	int32 * / float *	A variável que receberá o valor da estatística retornada.

Recupera o valor atual da estatística para o usuário especificado.

Você deve chamar RequestUserStats, e o retorno de chamada deve receber um valor de sucesso antes de chamar esta função.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• O nome na API especificado da estatística existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas;
  
• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado;
  
• O tipo passado para a função é igual ao tipo listado no painel de administração de aplicativo no site do Steamworks.

RequestUserStats

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cujas estatísticas requisitar.

Baixa estatísticas e conquistas do usuário especificado do servidor de forma assíncrona.

As estatísticas só serão atualizadas automaticamente para clientes que estejam jogando no servidor. Para outros usuários, será necessário chamar a função novamente para atualizar os dados.

Retorna: SteamAPICall_t, a ser usado com o resultado de chamada GSStatsReceived_t.

SetUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário do qual desbloquear/alcançar a conquista.
pchName	const char *	O "nome na API" da conquista a ser desbloqueada/alcançada.

Desbloqueia (ou, usando a terminologia usada no cliente, "alcança") uma conquista para o usuário especificado.

Você deve chamar RequestUserStats e o retorno de chamada deve receber um valor de sucesso antes de chamar esta função!

Esta chamada só modifica o estado do Steam na memória e não é custosa. Para enviar as estatísticas ao servidor, chame a função StoreUserStats.

AVISO: só funciona em conquistas que podem ser alteradas por servidores. Se o campo "Definida por" da conquista especificada for "Servidores oficiais", então apenas servidores declarados como controlados oficialmente por você poderão alterá-la. Para tal, será necessário definir o intervalo de endereços IP dos servidores oficiais na seção Servidores dedicados da administração de aplicativo.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• O "nome na API" especificado da conquista existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas;
  
• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado para o usuário especificado;
  
• A estatística pode ser alterada pelo servidor.

SetUserStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cuja estatística será definida.
pchName	const char *	O "nome na API" da estatística. Não pode ultrapassar o tamanho definido pela constante k_cchStatNameMax.
nData	int32 / float	O novo valor da estatística. Deve ser um valor absoluto, e não o valor que deve ser somado ou subtraído do valor atual.

Define/Atualiza o valor de uma dada estatística para o usuário especificado.

Você deve chamar RequestUserStats, e o retorno de chamada deve receber um valor de sucesso antes de chamar esta função!

Esta chamada só modifica o estado do Steam na memória e não é custosa. Para enviar as estatísticas ao servidor, chame a função StoreUserStats.

AVISO: só funciona em estatísticas que podem ser alteradas por servidores. Se o campo "Definida por" da estatística especificada for "Servidores oficiais", então apenas servidores declarados como controlados oficialmente por você poderão alterá-la. Para tal, será necessário definir o intervalo de endereços IP dos servidores oficiais na seção Servidores dedicados da administração de aplicativo.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• O nome na API especificado da estatística existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas;
  
• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado para o usuário especificado;
  
• O tipo passado para a função é igual ao tipo listado no painel de administração de aplicativo no site do Steamworks;
  
• A estatística pode ser alterada pelo servidor.

StoreUserStats

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cujas estatísticas serão armazenadas.

Envia as estatísticas e as conquistas alteradas ao servidor para armazenamento permanente para o usuário especificado.

Se falhar, nada é enviado ao servidor. É aconselhável continuar tentando até a chamada ser bem-sucedida.

Esta chamada pode ter limitações de frequência. A frequência deve ser na ordem de minutos, não segundos. Chame apenas durante grandes alterações de estado, como no final de uma rodada, troca de mapa ou desconexão de um usuário do servidor.

Se tiver estatísticas ou conquistas salvas localmente (mas ainda não enviadas com esta função) no momento do encerramento do processo do aplicativo, então esta função será chamada automaticamente.

Dados adicionais de depuração são gravados no arquivo %instalação_do_steam%\logs\stats_log.txt.

Retorna: SteamAPICall_t , a ser usado com o resultado de chamada GSStatsStored_t.
Se m_eResult tiver como resultado k_EResultInvalidParam], então uma ou mais estatísticas enviadas foram rejeitadas, seja por ultrapassarem limites ou estarem desatualizadas. Nesses casos, o servidor retorna valores atualizados, e as estatísticas devem ser atualizadas localmente para se manterem sincronizadas.

UpdateUserAvgRateStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O ID Steam do usuário cuja estatística AVGRATE será atualizada.
pchName	const char *	O "nome na API" da estatística. Não pode ultrapassar o tamanho definido pela constante k_cchStatNameMax.
flCountThisSession	float	O valor acumulado desde a última chamada a esta função.
dSessionLength	double	O tempo, em segundos, desde a última chamada a esta função.

Atualiza uma estatística AVGRATE com novos valores para o usuário especificado.

Você deve chamar RequestUserStats e o retorno de chamada deve receber um valor de sucesso antes de chamar esta função!

Esta chamada só modifica o estado do Steam na memória e não é custosa. Para enviar as estatísticas ao servidor, chame a função StoreUserStats.

AVISO: Só funciona em estatísticas que podem ser alteradas por servidores. Se o campo "Definida por" da estatística especificada for "Servidores oficiais", então apenas servidores declarados como controlados oficialmente por você poderão alterá-la. Para tal, será necessário definir o intervalo de endereços IP dos servidores oficiais na seção Servidores dedicados da administração de aplicativo.

Retorna: bool
Retorna true se todas as condições a seguir forem atendidas e a requisição for bem-sucedida; false caso contrário.

• O nome na API especificado da estatística existe na administração de aplicativo no site do Steamworks, e as alterações foram publicadas;
  
• A chamada à função RequestUserStats foi concluída, e o respectivo retorno de chamada foi disparado para o usuário especificado;
  
• O tipo deve ser AVGRATE no backend de parceiro Steamworks;
  
• A estatística pode ser alterada pelo servidor.

Retornos de chamada

Estes são os retornos de chamada (callbacks) que podem ser disparados ao chamar SteamAPI_RunCallbacks. Muitos podem ser disparados diretamente em resposta às funções de membro de ISteamGameServerStats.

GSStatsReceived_t

Resultado ao recuperar as estatísticas e conquistas mais recentes para um usuário do servidor.

Nome	Tipo	Descrição
m_eResult	EResult	Retorna se a chamada foi bem-sucedida ou não. Se o usuário não possuir estatísticas, o valor será k_EResultFail
m_steamIDUser	CSteamID	O usuário cujas estatísticas foram recuperadas.

Funções associadas: RequestUserStats

GSStatsStored_t

Resultado de uma solicitação de armazenamento de estatísticas de um usuário.

Nome	Tipo	Descrição
m_eResult	EResult	Retorna se a chamada foi bem-sucedida ou não.
m_steamIDUser	CSteamID	O usuário cujas estatísticas foram armazenadas.

Funções associadas: StoreUserStats

GSStatsUnloaded_t

Retorno de chamada que indica que as estatísticas de um usuário foram removidas da memória.

Chame RequestUserStats novamente para acessar as estatísticas do usuário.

Nome	Tipo	Descrição
m_steamIDUser	CSteamID	Usuário cujas estatísticas foram removidas da memória.

Constantes

Essas são as constantes definidas para uso com ISteamGameServerStats.

Nome	Tipo	Valor	Descrição
STEAMGAMESERVERSTATS_INTERFACE_VERSION	const char *	"SteamGameServerStats001"