nakama defold
v3.4.0
LUA -Client für Nakama Server in Lua 5.1 geschrieben.
Nakama ist ein Open-Source-Server, der moderne Spiele und Apps mit Strom versorgt. Zu den Funktionen gehören Benutzerkonten, Chat, Social, Matchmaker, Echtzeitmultiplayer und vieles mehr.
Dieser Client implementiert die vollständige API- und Socket -Optionen mit dem Server. Es ist in Lua 5.1 geschrieben, um mit LUA -basierten Spielemotoren kompatibel zu sein.
Hier finden Sie eine vollständige Dokumentation.
Sie müssen den Server und die Datenbank einrichten, bevor Sie eine Verbindung mit dem Client herstellen können. Am einfachsten ist es, Docker zu verwenden, aber einen Blick auf die Serverdokumentation für andere Optionen.
Installieren und führen Sie die Server aus. Befolgen Sie diese Anweisungen.
Fügen Sie den Kunden Ihrem Projekt hinzu.
game.project hinzufügen. Der Kunde wird nun in Ihrem Projekt in nakama Ordner angezeigt.Fügen Sie Ihrem Projekt Abhängigkeiten hinzu. In Defold -Projekten müssen Sie Game eine der folgenden Abhängigkeiten hinzufügen.
Verwenden Sie die Verbindungsanmeldeinformationen, um den Nakama -Kunden zu initialisieren.
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 )(Optional) Nakama verwendet Base64 Decoding für Sitzungen Die Sitzungstoken sowie Basis64 -Codierung und Decodierung von Übereinstimmungsdaten. Der Standard -Base64 -Encoder und Decoder sind in Lua geschrieben. Um die Leistung des Base64 -Encodes zu erhöhen und Schritte zu dekodieren, können Sie einen Base64 -Encoder in C -Projekte verwenden. In den Entfaltungsprojekten müssen Sie die folgende Abhängigkeit zu Game hinzufügen. Project:
Der Client verfügt über viele Methoden, um verschiedene Funktionen auf dem Server auszuführen oder Echtzeit -Socket -Verbindungen mit dem Server zu öffnen.
Es gibt verschiedene Möglichkeiten, sich mit dem Server zu authentifizieren. Die Authentifizierung kann einen Benutzer erstellen, wenn er mit diesen Anmeldeinformationen noch nicht vorhanden ist. Es ist auch einfach, sich mit einem sozialen Profil von Google Play Games, Facebook, Game Center usw. zu authentifizieren.
local client = nakama . create_client ( config )
local email = " [email protected] "
local password = " batsignal "
local session = client . authenticate_email ( email , password )
pprint ( session )HINWEIS : Siehe Abschnitt Anfragen unten zum Ausführen dieses Snippets (a) synchron.
Wenn der Server authentifiziert wurde, antwortet der Server mit einem Auth -Token (JWT), mit dem API -Anforderungen authentifiziert werden können. Das Token enthält nützliche Eigenschaften und wird in eine session deserialisiert.
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 ) Es wird empfohlen, das Auth -Token aus der Sitzung zu speichern und beim Start zu überprüfen, ob es abgelaufen ist. Wenn das Token abgelaufen ist, müssen Sie erneut automatisch werden. Wenn das Token kurz vor dem Ablauf ist, muss es erfrischt werden. Die Ablaufzeit des Tokens kann als Einstellung im Server geändert werden. Sie können die Sitzung mit session.store(session) speichern und später mit session.restore() wiederhergestellt:
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 )Der Client enthält viele integrierte APIs für verschiedene Funktionen des Spielservers. Diese können mit den Methoden zugegriffen werden, die entweder eine Rückruffunktion verwenden, um ein Ergebnis (dh asynchron) zurückzugeben, oder ergeben, bis ein Ergebnis empfangen wird (dh synchron und muss innerhalb einer Lua -Coroutine ausgeführt werden).
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 );Der Nakama -Kunde bietet eine Komfortfunktion zum Erstellen und Starten einer Coroutine, um mehrere Anfragen synchron nacheinander auszuführen:
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakama verfügt über eine globale und request-Wiederholungskonfiguration, um zu steuern, wie fehlgeschlagene API-Aufrufe wiedergegeben werden.
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 ))Erstellen Sie einen Stornierungs -Token und geben Sie diese mit einer Anfrage zur Stornierung der Anfrage vor, bevor sie abgeschlossen ist.
-- 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 )Sie können eine Verbindung zum Server über eine Echtzeit -WebSocket -Verbindung herstellen, um Chat -Nachrichten zu senden und zu empfangen, Benachrichtigungen abzurufen und ein Multiplayer -Match zu MatchMake zu erreichen.
Sie müssen zunächst einen Echtzeit -Socket zum Server erstellen:
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )Treten Sie dann einem Chat -Kanal bei und senden Sie eine Nachricht:
-- 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! " )Eine Client -Socket hat Event -Hörer, die auf verschiedene vom Server empfangene Ereignisse aufgerufen werden. Beispiel:
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )Verfügbare Zuhörer:
on_disconnect - behandelt ein Ereignis, wenn der Client vom Server getrennt wird.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 unterstützt binäre Inhalte im data einer Match -Nachricht. Unabhängig von Ihrem Datentyp akzeptiert der Server nur Base64-kodierte Daten . Stellen Sie daher sicher, dass Sie keine Klartextdaten oder sogar JSON oder Nakama-Server veröffentlichen, oder die Daten behaupten, dass die Daten fehlformt und Ihren Client trennen (setzen Sie den Server- debug , um diese Ereignisse zu erkennen).
Nakama wird automatisch Basis64 codieren, wenn die Nachricht mit nakama.create_match_data_message() erstellt wurde. Nakama wird auch automatisch alle empfangenen Übereinstimmungsdaten dekodieren, bevor er den Listener on_matchdata aufruft.
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 ) In einem Staffel -Multiplayer erhalten Sie die Nachrichten anderer Kunden. Der Client hat die Nachrichtendaten bereits entschlüsselt, bevor er sie an den Listener on_matchdata gesendet hat. Wenn die Daten JSON codiert waren, wie im obigen Beispiel, müssen Sie sie selbst dekodieren:
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 )Nachrichten, die vom Server in einer maßgeblichen Übereinstimmung initiiert wurden, werden standardmäßig als gültiges JSON gelten.
Lua -Kunde für Satori in Lua 5.1 geschrieben.
Satori ist ein LiveOp -Server für Spiele, die verteilungsfähige Analysen, A/B -Tests und Remote -Konfiguration betreiben. Verwenden Sie den Satori -Def -Client, um mit Satori innerhalb Ihres Entfaltungsspiels mit Satori zu kommunizieren.
Erstellen Sie einen Satori -Client mit der API -Taste aus dem Satori -Dashboard.
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 )Dann authentifizieren Sie sich, um Ihre Sitzung zu erhalten:
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 )Mit dem Client können Sie alle Experimente oder Feature -Flags abrufen. Der Benutzer gehört zu.
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )Die Entwicklungs -Roadmap wird verwaltet, da Github -Probleme und Zuganfragen willkommen sind. Wenn Sie daran interessiert sind, den Code zu verbessern, öffnen Sie bitte ein Problem, um die Änderungen zu besprechen oder ihn im Community -Forum zu besprechen.
Unit -Tests finden Sie im Ordner tests . Führen Sie sie mit Teleskop aus (Fork, die LUA 5.3+ unterstützt):
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
API -Dokumente werden mit LDOC generiert und auf GitHub -Seiten bereitgestellt.
Wenn Sie die API -Kommentare ändern, können Sie LDOC LDOC erneut ausführen und die Änderungen in docs/* begehen.
Hinweis: Kommentare für nakama/nakama.lua müssen in codegen/main.go abgegeben werden.
LDOC ausführen:
# 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
Siehe Anweisungen im CodeGen -Ordner.
Die Anpassung des Nakama- und Satori -Defold -Kunden an eine andere Lua -basierte Engine sollte so einfach sein wie die Bereitstellung eines anderen Motormoduls bei der Konfiguration des Nakama -Kunden:
-- 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 )Das Motormodul muss die folgenden Funktionen bereitstellen:
http(config, url_path, query_params, method, post_data, cancellation_token, callback) - HTTP -Anforderung machen.
config - config -Tabelle übergeben an nakama.create() oder satori.create()url_path - Pfad zum Anhängen an den Basis -URIquery_params - Schlüsselwertpaare als URL -Abfrageparameter verwendetmethod - "Get", "Post"post_data - Daten zu postencancellation_token - prüfen Sie, ob cancellation_token.cancelled wahr istcallback - Funktion zum Ergebnis (Antwort) aufzurufen socket_create(config, on_message) - Socket erstellen. Muss eine Socket -Instanz zurückgeben (Tabelle mit motorspezifischem Sockelzustand).
config - config -Tabelle übergeben an nakama.create() oder `satori.create ()on_message - Funktion zum Aufrufen, wenn eine Nachricht vom Server gesendet wird socket_connect(socket, callback) - Steckdose anschließen.
socket - Socket -Instanz zurückgegeben von socket_create()callback - Funktion zum Ergebnis (OK, ERR) socket_send(socket, message) - Nachricht in Socket senden.
socket - Socket -Instanz zurückgegeben von socket_create()message - Nachricht zum Senden uuid() - Erstellen Sie eine UUID
Dieses Projekt ist unter der Apache-2-Lizenz lizenziert.
