nakama defold
v3.4.0
Client LUA pour le serveur Nakama écrit dans LUA 5.1.
Nakama est un serveur open source conçu pour alimenter les jeux et les applications modernes. Les fonctionnalités incluent les comptes d'utilisateurs, le chat, le social, le matchmaker, le multijoueur en temps réel et bien plus encore.
Ce client implémente les options API et socket complètes avec le serveur. Il est écrit dans LUA 5.1 pour être compatible avec les moteurs de jeu basés sur LUA.
Une documentation complète est disponible ici.
Vous devrez configurer le serveur et la base de données avant de pouvoir vous connecter avec le client. Le moyen le plus simple consiste à utiliser Docker mais jetez un œil à la documentation du serveur pour d'autres options.
Installez et exécutez les serveurs. Suivez ces instructions.
Ajoutez le client à votre projet.
game.project . Le client se présentera désormais dans le dossier nakama dans votre projet.Ajoutez des dépendances à votre projet. Dans les projets défillés, vous devez ajouter l'une des dépendances suivantes à Game.project:
Utilisez les informations d'identification de connexion pour initialiser le client 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 )(Facultatif) Nakama utilise le décodage Base64 pour la session les jetons de session et le codage Base64 et le décodage des données de correspondance. L'encodeur et décodeur de base64 par défaut est écrit en Lua. Pour augmenter les performances des étapes d'encodage et de décodage de base64, il est possible d'utiliser un encodeur Base64 écrit en C. Dans les projets défillés, vous devez ajouter la dépendance suivante à Game.Project:
Le client dispose de nombreuses méthodes pour exécuter diverses fonctionnalités du serveur ou ouvrir des connexions de socket en temps réel avec le serveur.
Il existe une variété de façons de s'authentifier avec le serveur. L'authentification peut créer un utilisateur s'il n'existe pas déjà avec ces informations d'identification. Il est également facile d'authentifier avec un profil social de 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 )Remarque : Voir la section des demandes ci-dessous pour exécuter cet extrait (a) de manière synchrone.
Lorsqu'il est authentifié, le serveur répond avec un token Auth (JWT) qui peut être utilisé pour authentifier les demandes d'API. Le jeton contient des propriétés utiles et est désérialisé dans une table 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 ) Il est recommandé de stocker le jeton AUTH à partir de la session et de vérifier au démarrage s'il a expiré. Si le jeton a expiré, vous devez vous réautoriser. Si le jeton est sur le point d'expirer, il doit être rafraîchi. Le temps d'expiration du jeton peut être modifié en tant que paramètre dans le serveur. Vous pouvez stocker la session en utilisant session.store(session) et la restaurer plus tard à l'aide de 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 )Le client comprend de nombreuses API intégrées pour diverses fonctionnalités du serveur de jeux. Ceux-ci sont accessibles avec les méthodes qui utilisent une fonction de rappel pour renvoyer un résultat (c.-à-d. Asynchrones) ou un rendement jusqu'à ce qu'un résultat soit reçu (c'est-à-dire synchrone et doit être exécuté dans une coroutine 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 );Le client Nakama offre une fonction de commodité pour créer et démarrer une coroutine pour exécuter plusieurs demandes de manière synchrone l'une après l'autre:
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakama a une configuration de réchauffement globale et par la demande pour contrôler comment les appels API défaillants sont réduits.
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 ))Créez un jeton d'annulation et passez-le avec une demande d'annuler la demande avant sa fin.
-- 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 )Vous pouvez vous connecter au serveur via une connexion WebSocket en temps réel pour envoyer et recevoir des messages de chat, obtenir des notifications et faire du match dans une correspondance multijoueur.
Vous devez d'abord créer une prise en temps réel sur le serveur:
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )Ensuite, procédez à un canal de chat et envoyez un message:
-- 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! " )Un socket client a des auditeurs d'événements qui sont appelés sur divers événements reçus du serveur. Exemple:
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )Écouteurs disponibles:
on_disconnect - gère un événement pour le moment où le client est déconnecté du serveur.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 prend en charge tout contenu binaire dans l'attribut data d'un message de correspondance. Quel que soit votre type de données, le serveur accepte uniquement les données codées Base64 , alors assurez-vous de ne pas publier de données en texte clair ou même JSON, ou Nakama Server réclamera les données mal formées et déconnectez votre client (définissez la journalisation du serveur pour debug pour détecter ces événements).
Nakama sera automatiquement Base64 codez vos données de correspondance si le message a été créé à l'aide de nakama.create_match_data_message() . NAKAMA sera également automatiquement Base64 décoder toutes les données de correspondance reçues avant d'appeler l'auditeur 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 ) Dans un multijoueur relayé, vous recevrez les messages des autres clients. Le client a déjà Base64 a décodé les données du message avant de les envoyer à l'auditeur on_matchdata . Si les données étaient encodées JSON, comme dans l'exemple ci-dessus, vous devez le décoder vous-même:
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 )Les messages initiés par le serveur dans une correspondance faisant autorité viendront en tant que JSON valide par défaut.
Client Lua pour Satori écrit dans LUA 5.1.
Satori est un serveur LIVEOPS pour les jeux qui alimente l'analyse exploitable, les tests A / B et la configuration distante. Utilisez le client Satori Defold pour communiquer avec Satori à partir de votre jeu Defold.
Créez un client Satori à l'aide de la touche API à partir du tableau de bord 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 )Puis authentifiez-vous pour obtenir votre session:
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 )En utilisant le client, vous pouvez obtenir des expériences ou des indicateurs de fonctionnalité, l'utilisateur appartient.
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )La feuille de route de développement est gérée car les problèmes de github et les demandes de traction sont les bienvenus. Si vous souhaitez améliorer le code, veuillez ouvrir un problème pour discuter des modifications ou passer et en discuter dans le forum communautaire.
Des tests unitaires peuvent être trouvés dans le dossier tests . Exécutez-les à l'aide du télescope (fourche qui prend en charge Lua 5.3+):
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
Les documents API sont générés avec LDOC et déployés sur les pages GitHub.
Lorsque vous modifiez les commentaires de l'API, relancez LDOC et engagez les changements dans docs/* .
Remarque: Les commentaires pour nakama/nakama.lua doivent être faits dans codegen/main.go
Pour exécuter 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
Reportez-vous aux instructions dans le dossier Codegen.
L'adaptation des clients Nakama et Satori Defold à un autre moteur basé sur LUA devrait être aussi simple que de fournir un autre module de moteur lors de la configuration du client 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 )Le module du moteur doit fournir les fonctions suivantes:
http(config, url_path, query_params, method, post_data, cancellation_token, callback) - faites la demande http.
config - Tableau de configuration transmis à nakama.create() ou satori.create()url_path - Chemin vers l'ajout vers l'URI de basequery_params - paires de valeurs clés à utiliser comme paramètres de requête URLmethod - "Get", "Post"post_data - données à publiercancellation_token - Vérifiez si cancellation_token.cancelled est vraicallback - fonction à appeler avec le résultat (réponse) socket_create(config, on_message) - Créer un socket. Doit retourner l'instance de socket (table avec un état de prise spécifique au moteur).
config - Tableau de configuration transmis à nakama.create() ou `satori.create ()on_message - fonction à appeler lorsqu'un message est envoyé à partir du serveur socket_connect(socket, callback) - Connectez la prise.
socket - instance de socket renvoyée de socket_create()callback - fonction à appeler avec le résultat (ok, err) socket_send(socket, message) - Envoyer un message sur socket.
socket - instance de socket renvoyée de socket_create()message - Message à envoyer uuid() - Créer un uuid
Ce projet est concédé sous licence Apache-2.
