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

Funções de membro

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

ClearUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja proeza alcançada se pretende reverter.
pchName	const char *	O "Nome na API" da proeza alcançada que se pretende reverter.

Reverte o estado de uma proeza alcançada do utilizador especificado.

Esta função é principalmente usada para testes.

Deve chamar RequestUserStats e o respetivo callback deve ser bem-sucedido antes de chamar esta função!

Esta chamada apenas modifica o estado do Steam na memória e consome poucos recursos. De modo a enviar as estatísticas para o servidor, deve chamar a função StoreUserStats.

ATENÇÃO: esta função apenas irá funcionar em proezas que podem ser definidas por servidores. Se o campo "Definida por" da proeza especificada for "Servidor oficial", apenas servidores declarados como controlados oficialmente por si poderão defini-la. Para tal, terá de definir o intervalo de endereços IP dos seus servidores oficiais na secção Servidores dedicados do painel de administração da aplicação.

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• O "Nome na API" especificado da proeza existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.
  
• A chamada à função RequestUserStats foi concluída e o respetivo callback foi enviado para o utilizador especificado.
  
• A estatística tem de poder ser definida por servidores.

GetUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja proeza se pretende obter.
pchName	const char *	O "Nome na API" da proeza.
pbAchieved	bool *	Retorna o estado da proeza (se já foi alcançada ou não).

Obtém o estado de uma proeza especificada (se já foi alcançada ou não).

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• A chamada à função RequestUserStats foi concluída e o respetivo callback ocorreu.
  
• O "Nome na API" especificado da proeza existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.

Se a chamada for bem-sucedida, o estado é retornado através do parâmetro pbAchieved.

GetUserStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja estatística se pretende obter.
pchName	const char *	O "Nome na API" da estatística. Não deve ser mais longo do que o especificado em k_cchStatNameMax.
pData	int32 * / float *	A variável onde será retornado o valor da estatística.

Obtém o valor atual de uma estatística do utilizador especificado.

Deve chamar RequestUserStats e o respetivo callback deve ser bem-sucedido antes de chamar esta função.

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• A estatística especificada existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.
  
• A chamada à função RequestUserStats foi concluída e o respetivo callback ocorreu.
  
• O tipo passado para esta função deve ser igual ao tipo listado no painel de administração da aplicação no site do Steamworks.

RequestUserStats

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cujas estatísticas se pretende requisitar.

Descarrega estatísticas e proezas do utilizador especificado a partir do servidor, de modo assíncrono.

Estas estatísticas apenas serão atualizadas automaticamente para clientes que estejam a jogar no servidor. Para outros utilizadores, terá de chamar esta função de novo para atualizar os dados.

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

SetUserAchievement

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja proeza se pretende desbloquear.
pchName	const char *	O "Nome na API" da proeza que se pretende desbloquear.

Desbloqueia uma proeza do utilizador especificado.

Deve chamar RequestUserStats e o respetivo callback deve ser bem-sucedido antes de chamar esta função!

Esta chamada apenas modifica o estado do Steam na memória e consome poucos recursos. De modo a enviar as estatísticas para o servidor, deve chamar a função StoreUserStats.

ATENÇÃO: esta função apenas irá funcionar em proezas que podem ser definidas por servidores. Se o campo "Definida por" da proeza especificada for "Servidor oficial", apenas servidores declarados como controlados oficialmente por si poderão defini-la. Para tal, terá de definir o intervalo de endereços IP dos seus servidores oficiais na secção Servidores dedicados do painel de administração da aplicação.

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• O "Nome na API" especificado da proeza existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.
  
• A chamada à função RequestUserStats foi concluída e o respetivo callback foi enviado para o utilizador especificado.
  
• A estatística tem de poder ser definida por servidores.

SetUserStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja estatística se pretende definir.
pchName	const char *	O "Nome na API" da estatística. Não deve ser mais longo do que o especificado em k_cchStatNameMax.
nData	int32 / float	O novo valor da estatística. Tem de ser um valor absoluto, não o valor que deve ser somado ou subtraído.

Define/atualiza o valor de uma determinada estatística do utilizador especificado.

Deve chamar RequestUserStats e o respetivo callback deve ser bem-sucedido antes de chamar esta função!

Esta chamada apenas modifica o estado do Steam na memória e consome poucos recursos. De modo a enviar as estatísticas para o servidor, deve chamar a função StoreUserStats.

ATENÇÃO: estas atualizações apenas irão funcionar em estatísticas que podem ser editadas por servidores. Se o campo "Definida por" da estatística especificada for "Servidor oficial", apenas servidores declarados como controlados oficialmente por si poderão defini-la. Para tal, terá de definir o intervalo de endereços IP dos seus servidores oficiais na secção Servidores dedicados do painel de administração da aplicação.

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• A estatística especificada existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.
  
• A chamada à função RequestUserStats foi concluída e o respetivo callback foi enviado para o utilizador especificado.
  
• O tipo passado para esta função deve ser igual ao tipo listado no painel de administração da aplicação no site do Steamworks.
  
• A estatística tem de poder ser definida por servidores.

StoreUserStats

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cujas estatísticas se pretende armazenar.

Envia os dados das estatísticas e proezas alteradas do utilizador especificado ao servidor para armazenamento permanente.

Se este processo falhar, não serão enviados dados ao servidor. Recomendamos continuar a tentar até que a chamada seja bem-sucedida.

Podem ser impostos limites de frequência nesta chamada. A frequência deve ser uma questão de minutos e não de segundos. Chame esta função apenas durante grandes alterações de estado, como quando uma ronda termina, o mapa muda ou o utilizador sai do servidor.

Se tiver estatísticas ou proezas guardadas localmente (mas que não foram enviadas com esta função) no momento em que o processo da sua aplicação for encerrado, esta função será chamada de modo automático.

Informações de depuração adicionais são gravadas no ficheiro %steam_install%\logs\stats_log.txt.

Retorna: SteamAPICall_t, a ser usado com um resultado de chamada GSStatsStored_t.
Se m_eResult tiver k_EResultInvalidParam como resultado, isso deve-se a uma ou mais estatísticas enviadas terem sido rejeitadas por terem ultrapassado limites ou por estarem desatualizadas. Neste caso, o servidor retorna valores atualizados e as estatísticas devem ser atualizadas localmente para que se mantenham sincronizadas.

UpdateUserAvgRateStat

Nome	Tipo	Descrição
steamIDUser	CSteamID	O SteamID do utilizador cuja estatística AVGRATE se pretende atualizar.
pchName	const char *	O "Nome na API" da estatística. Não deve ser mais longo do que o especificado em 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 do utilizador especificado com novos valores.

Deve chamar RequestUserStats e o respetivo callback deve ser bem-sucedido antes de chamar esta função!

Esta chamada apenas modifica o estado do Steam na memória e consome poucos recursos. De modo a enviar as estatísticas para o servidor, deve chamar a função StoreUserStats.

ATENÇÃO: estas atualizações apenas irão funcionar em estatísticas que podem ser editadas por servidores. Se o campo "Definida por" da estatística especificada for "Servidor oficial", apenas servidores declarados como controlados oficialmente por si poderão defini-la. Para tal, terá de definir o intervalo de endereços IP dos seus servidores oficiais na secção Servidores dedicados do painel de administração da aplicação.

Retorna: bool
Esta função retorna true se for bem-sucedida e se todas as seguintes condições forem cumpridas; caso contrário, irá retornar false.

• A estatística especificada existe no painel de administração da aplicação no site do Steamworks e as alterações foram publicadas.
  
• A chamada à função RequestUserStats foi concluída e o respetivo callback foi enviado para o utilizador especificado.
  
• O tipo deve ser AVGRATE no backend de parceiro Steamworks.
  
• A estatística tem de poder ser definida por servidores.

Callbacks

Estes são os callbacks que podem ocorrer ao chamar SteamAPI_RunCallbacks. Muitos destes callbacks irão ocorrer diretamente como resposta às funções de membro de ISteamGameServerStats.

GSStatsReceived_t

O resultado ao obter do servidor as estatísticas e proezas mais recentes de um utilizador.

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

Funções associadas: RequestUserStats

GSStatsStored_t

O resultado de um pedido para armazenar as estatísticas de um utilizador.

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

Funções associadas: StoreUserStats

GSStatsUnloaded_t

Um callback que indica que as estatísticas de um utilizador foram desalocadas.

Chame RequestUserStats novamente para aceder às estatísticas deste utilizador.

Nome	Tipo	Descrição
m_steamIDUser	CSteamID	O utilizador cujas estatísticas foram desalocadas.

Constantes

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

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