nakama defold
v3.4.0
Cliente da Lua para o NAKAMA Server escrito em Lua 5.1.
Nakama é um servidor de código aberto projetado para alimentar jogos e aplicativos modernos. Os recursos incluem contas de usuário, bate -papo, social, casamenteiro, multiplayer em tempo real e muito mais.
Este cliente implementa as opções completas da API e o soquete com o servidor. Está escrito em Lua 5.1 para ser compatível com os mecanismos de jogo baseados em Lua.
A documentação completa está disponível aqui.
Você precisará configurar o servidor e o banco de dados antes de se conectar com o cliente. A maneira mais simples é usar o Docker, mas dê uma olhada na documentação do servidor para outras opções.
Instale e execute os servidores. Siga estas instruções.
Adicione o cliente ao seu projeto.
game.project . O cliente agora aparecerá na pasta nakama em seu projeto.Adicione dependências ao seu projeto. Em projetos definidos, você precisa adicionar uma das seguintes dependências ao jogo.project:
Use as credenciais de conexão para inicializar o cliente Nakama.
local defold = require " nakama.engine.defold "
local nakama = require " nakama.nakama "
local config = {
host = " 127.0.0.1 " ,
port = 7350 ,
use_ssl = false ,
username = " defaultkey " ,
password = " " ,
engine = defold ,
timeout = 10 , -- connection timeout in seconds
}
local client = nakama . create_client ( config )(Opcional) Nakama usa a decodificação Base64 para a sessão dos tokens de sessão e a codificação Base64 e a decodificação dos dados de correspondência. O codificador e decodificador Base64 padrão está escrito em Lua. Para aumentar o desempenho da codificação Base64 e decodificar etapas, é possível usar um codificador Base64 escrito em C. Em projetos definidos, você precisa adicionar a seguinte dependência ao jogo.project:
O cliente tem muitos métodos para executar vários recursos no servidor ou abrir conexões de soquete em tempo real com o servidor.
Há várias maneiras de autenticar com o servidor. A autenticação pode criar um usuário se ele ainda não existir com essas credenciais. Também é fácil de autenticar com um perfil social do Google Play Games, Facebook, Game Center etc.
local client = nakama . create_client ( config )
local email = " [email protected] "
local password = " batsignal "
local session = client . authenticate_email ( email , password )
pprint ( session )Nota : Consulte as solicitações da seção abaixo para executar este snippet (a) de maneira síncrona.
Quando autenticado, o servidor responde com um token de autenticação (JWT) que pode ser usado para autenticar solicitações de API. O token contém propriedades úteis e se desfaz em uma tabela session .
local client = nakama . create_client ( config )
local session = client . authenticate_email ( email , password )
print ( session . created )
print ( session . token ) -- raw JWT token
print ( session . expires )
print ( session . user_id )
print ( session . username )
print ( session . refresh_token ) -- raw JWT token for use when refreshing the session
print ( session . refresh_token_expires )
print ( session . refresh_token_user_id )
print ( session . refresh_token_username )
-- Use the token to authenticate future API requests
nakama . set_bearer_token ( client , session . token )
-- Use the refresh token to refresh the authentication token
nakama . session_refresh ( client , session . refresh_token ) Recomenda -se armazenar o token de autenticação a partir da sessão e verificar na inicialização, se expirou. Se o token expirou, você deve reautenticar. Se o token estiver prestes a expirar, ele deve ser atualizado. O tempo de validade do token pode ser alterado como uma configuração no servidor. Você pode armazenar a sessão usando session.store(session) e posteriormente restaurá -la usando session.restore() :
local nakama_session = require " nakama.session "
local client = nakama . create_client ( config )
-- restore a session
local session = nakama_session . restore ()
if session and nakama_session . is_token_expired_soon ( session ) and not nakama . is_refresh_token_expired ( session ) then
print ( " Session has expired or is about to expire. Refreshing. " )
session = nakama . session_refresh ( client , session . refresh_token )
nakama_session . store ( session )
elseif not session or nakama_session . is_refresh_token_expired ( session ) then
print ( " Session does not exist or it has expired. Must reauthenticate. " )
session = client . authenticate_email ( " [email protected] " , " foobar123 " , nil , true , " britzl " )
nakama_session . store ( session )
end
client . set_bearer_token ( session . token )O cliente inclui muitas APIs embutidas para vários recursos do servidor de jogos. Eles podem ser acessados com os métodos que usam uma função de retorno de chamada para retornar um resultado (ou seja, assíncrono) ou o rendimento até que o resultado seja recebido (ou seja, síncrono e deve ser executado dentro de uma coroutina Lua).
local client = nakama . create_client ( config )
-- using a callback
client . get_account ( function ( account )
print ( account . user . id );
print ( account . user . username );
print ( account . wallet );
end )
-- if run from within a coroutine
local account = client . get_account ()
print ( account . user . id );
print ( account . user . username );
print ( account . wallet );O cliente Nakama fornece uma função de conveniência para criar e iniciar uma coroutina para executar várias solicitações de maneira síncrona uma após a outra:
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakama possui uma configuração de tentativa global e por solicitação para controlar como as chamadas de API com falha são recontratadas.
local retries = require " nakama.util.retries "
-- use a global retry policy with 5 attempts with 1 second intervals
local config = {
host = " 127.0.0.1 " ,
port = 7350 ,
username = " defaultkey " ,
password = " " ,
retry_policy = retries . fixed ( 5 , 1 ),
engine = defold ,
}
local client = nakama . create_client ( config )
-- use a retry policy specifically for this request
-- 5 retries at intervals increasing by 1 second between attempts (eg 1s, 2s, 3s, 4s, 5s)
nakama . list_friends ( client , 10 , 0 , " " , retries . incremental ( 5 , 1 ))Crie um token de cancelamento e passe isso com uma solicitação para cancelar a solicitação antes de concluir.
-- use a global retry policy with 5 attempts with 1 second intervals
local config = {
host = " 127.0.0.1 " ,
port = 7350 ,
username = " defaultkey " ,
password = " " ,
retry_policy = retries . fixed ( 5 , 1 ),
engine = defold ,
}
local client = nakama . create_client ( config )
-- create a cancellation token
local token = nakama . cancellation_token ()
-- start a request and proivide the cancellation token
nakama . list_friends ( client , 10 , 0 , " " , nil , callback , token )
-- immediately cancel the request without waiting for the request callback to be invoked
nakama . cancel ( token )Você pode se conectar ao servidor em uma conexão WebSocket em tempo real para enviar e receber mensagens de bate -papo, obter notificações e entrar em fósforo em uma correspondência multiplayer.
Você primeiro precisa criar um soquete em tempo real para o servidor:
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )Em seguida, prossiga para participar de um canal de bate -papo e enviar uma mensagem:
-- send channel join message
local channel_id = " pineapple-pizza-lovers-room "
local result = socket . channel_join ( socket , 1 , channel_id , false , false )
-- send channel messages
local result = socket . channel_message_send ( channel_id , " Pineapple doesn't belong on a pizza! " )Um soquete do cliente possui ouvintes de eventos que são chamados em vários eventos recebidos do servidor. Exemplo:
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )Ouvintes disponíveis:
on_disconnect - lida com um evento para quando o cliente está desconectado do servidor.on_channel_presence_eventon_match_presence_eventon_match_dataon_matchon_matchmaker_matchedon_notificationson_party_presence_eventon_partyon_party_dataon_party_join_requeston_status_presence_eventon_statuson_stream_dataon_erroron_channel_messageon_channel_message Nakama suporta qualquer conteúdo binário no atributo data de uma mensagem de correspondência. Independentemente do seu tipo de dados, o servidor aceita apenas dados codificados por Base64 , portanto, não poste dados de texto simples ou mesmo JSON, ou o Nakama Server reivindicará os dados malformados e desconectará seu cliente (defina o log do servidor para debug para detectar esses eventos).
O Nakama será automaticamente base64 codificar seus dados de correspondência se a mensagem foi criada usando nakama.create_match_data_message() . Nakama também decodificará automaticamente os dados de correspondência recebidos antes de ligar para o ouvinte on_matchdata .
local json = require " nakama.util.json "
local match_id = " ... "
local op_code = 1
local data = json . encode ({
dest_x = 1.0 ,
dest_y = 0.1 ,
})
-- send a match data message. The data will be automatically base64 encoded.
socket . match_data ( match_id , op_code , data ) Em um multiplayer retransmitido, você receberá as mensagens de outros clientes. O cliente já decodificou os dados da mensagem antes de enviá -los para o ouvinte on_matchdata . Se os dados foram codificados, como no exemplo acima, você precisa decodificá -los:
socket . on_matchdata ( function ( message )
local match_data = message . match_data
local data = json . decode ( match_data . data )
pprint ( data ) -- gameplay coordinates from the example above
end )As mensagens iniciadas pelo servidor em uma correspondência autorizada virão como JSON válido por padrão.
Lua Client para Satori escrito em Lua 5.1.
O Satori é um servidor LiveOps para jogos que alimentam análises acionáveis, teste A/B e configuração remota. Use o cliente Satori DeFold para se comunicar com o Satori do seu jogo definido.
Crie um cliente Satori usando a tecla API no painel Satori.
local config = {
host = " myhost.com " ,
api_key = " my-api-key " ,
use_ssl = true ,
port = 443 ,
retry_policy = retries . incremental ( 5 , 1 ),
engine = defold ,
}
local client = satori . create_client ( config )Em seguida, autentique para obter sua sessão:
satori . sync ( function ()
local uuid = defold . uuid ()
local result = client . authenticate ( nil , nil , uuid )
if not result . token then
error ( " Unable to login " )
return
end
client . set_bearer_token ( result . token )
end )Usando o cliente em que você pode obter experimentos ou sinalizadores de recursos, o usuário pertence.
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )O Roteiro de Desenvolvimento é gerenciado como problemas do GitHub e solicitações de puxar são bem -vindas. Se você estiver interessado em aprimorar o código, abra um problema para discutir as alterações ou aparecer e discuti -lo no fórum da comunidade.
Os testes de unidade podem ser encontrados na pasta de tests . Execute -os usando o Telescope (Fork, que suporta Lua 5.3+):
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
Os documentos da API são gerados com LDOC e implantados nas páginas do GitHub.
Ao alterar os comentários da API, execute o Rerun LDOC e comprometa as alterações nos docs/* .
Nota: Comentários para nakama/nakama.lua devem ser feitos em codegen/main.go .
Para executar o LDOC:
# in the project root, generate nakama.lua
# requires go and https://github.com/heroiclabs/nakama to be checked out
go run codegen/main.go -output nakama/nakama.lua ../nakama/apigrpc/apigrpc.swagger.json
# install ldoc (mac)
brew install luarocks
luarocks install ldoc
# run ldoc
doc . -d docs
Consulte as instruções na pasta CodeGen.
A adaptação dos clientes Nakama e Satori defolou a outro mecanismo baseado em Lua deve ser tão fácil quanto fornecer outro módulo de motor ao configurar o cliente Nakama:
-- nakama
local myengine = require " nakama.engine.myengine "
local nakama = require " nakama.nakama "
local nakama_config = {
engine = myengine ,
}
local nakama_client = nakama . create_client ( nakama_config )
-- satori
local myengine = require " nakama.engine.myengine "
local satori = require " satori.satori "
local satori_config = {
engine = myengine ,
}
local satori_client = satori . create_client ( satori_config )O módulo do motor deve fornecer as seguintes funções:
http(config, url_path, query_params, method, post_data, cancellation_token, callback) - faça solicitação http.
config - tabela de configuração passada para nakama.create() ou satori.create()url_path - caminho para anexar ao URI basequery_params - pares de valor -chave para usar como parâmetros de consulta URLmethod - "Get", "Post"post_data - dados para postarcancellation_token - Verifique se cancellation_token.cancelled é verdadeirocallback - Função para ligar com o resultado (resposta) socket_create(config, on_message) - Crie soquete. Deve retornar a instância do soquete (tabela com estado de soquete específico do motor).
config - tabela de configuração passada para nakama.create() ou `satori.create ()on_message - Função para chamar quando uma mensagem é enviada do servidor socket_connect(socket, callback) - Connect Socket.
socket - Instância do soquete Retornado de socket_create()callback - Função para ligar com resultado (OK, ERR) socket_send(socket, message) - Envie a mensagem no soquete.
socket - Instância do soquete Retornado de socket_create()message - mensagem para enviar uuid() - crie um uuid
Este projeto está licenciado sob a licença Apache-2.
