nakama defold
v3.4.0
LUA 5.1で書かれたNakama ServerのLUAクライアント。
Nakamaは、モダンなゲームやアプリを強化するために設計されたオープンソースサーバーです。機能には、ユーザーアカウント、チャット、ソーシャル、マッチメーカー、リアルタイムマルチプレイヤーなどが含まれます。
このクライアントは、サーバーを使用して完全なAPIおよびソケットオプションを実装します。 LUA 5.1で書かれており、LUAベースのゲームエンジンと互換性があります。
完全なドキュメントはこちらから入手できます。
クライアントに接続する前に、サーバーとデータベースをセットアップする必要があります。最も簡単な方法は、Dockerを使用することですが、他のオプションのサーバードキュメントをご覧ください。
サーバーをインストールして実行します。これらの指示に従ってください。
クライアントをプロジェクトに追加します。
game.projectへのライブラリ依存性として、安定したリリースまたは最新の開発バージョンのURLを追加する必要があります。クライアントは、プロジェクトのnakamaフォルダーに表示されます。プロジェクトに依存関係を追加します。 Defoldプロジェクトでは、以下の依存関係のいずれかをgame.projectに追加する必要があります。
接続資格情報を使用して、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 )（オプション）Nakamaは、セッションにBase64デコードを使用し、セッショントークンとMatchデータのベース64エンコードとデコードの両方を使用します。デフォルトのBase64エンコーダーとデコーダーはLUAで記述されています。 base64エンコードとデコード手順のパフォーマンスを向上させるには、Cで記述されたbase64エンコーダーを使用することができます。
クライアントには、サーバー内のさまざまな機能を実行したり、サーバーとのリアルタイムソケット接続を開いたりする多くの方法があります。
サーバーで認証するさまざまな方法があります。認証は、それらがそれらの資格情報にまだ存在しない場合、ユーザーを作成できます。また、Google Playゲーム、Facebook、ゲームセンターなどのソーシャルプロフィールで簡単に認証することもできます。
local client = nakama . create_client ( config )
local email = " [email protected] "
local password = " batsignal "
local session = client . authenticate_email ( email , password )
pprint ( session )注：このスニペット（a）を同期して実行するための以下のリクエストセクションを参照してください。
認証されると、サーバーはAUTHトークン（JWT）で応答します。これは、APIリクエストの認証に使用できます。トークンには便利なプロパティが含まれており、 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 ) AUTHトークンをセッションから保存し、起動時に有効期限が切れている場合はチェックすることをお勧めします。トークンの有効期限が切れている場合は、再認証する必要があります。トークンが期限切れになっている場合は、リフレッシュする必要があります。トークンの有効期限は、サーバーの設定として変更できます。 session.store(session)を使用してセッションを保存でき、後で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 )クライアントには、ゲームサーバーのさまざまな機能のための多くの組み込みAPIが含まれています。これらは、コールバック関数を使用して結果（つまり非同期）を返すか、結果が受信されるまで降伏する方法（つまり、同期し、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 );Nakamaクライアントは、複数のリクエストを次のように同期して実行するためのコルーチンを作成および起動するための利便性機能を提供します。
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakamaには、API呼び出しが再試行された方法を制御するために、グローバルおよびリクエストごとの再試行構成があります。
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 ))キャンセルトークンを作成し、完了する前にリクエストをキャンセルするリクエストでそれを渡します。
-- 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 )リアルタイムWebSocket Connectionを介してサーバーに接続して、チャットメッセージを送信および受信したり、通知を取得したり、マルチプレイヤーマッチに対応したりできます。
最初にサーバーにリアルタイムソケットを作成する必要があります。
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )次に、チャットチャネルに参加してメッセージを送信します。
-- 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! " )クライアントソケットには、サーバーから受け取ったさまざまなイベントで呼び出されるイベントリスナーがあります。例：
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )利用可能なリスナー：
on_disconnectクライアントがサーバーから切断されたときのイベントを処理します。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_messageNakamaは、一致メッセージのdata属性のバイナリコンテンツをサポートしています。データ型に関係なく、サーバーはbase64エンコードされたデータのみを受け入れるため、プレーンテキストデータやJSONさえ投稿しないようにしてください。または、nakamaサーバーは、データの奇形を請求し、クライアントを切断します（サーバーログをdebugしてこれらのイベントを検出します）。
nakama.create_match_data_message()を使用してメッセージが作成された場合、Nakamaは一致データを自動的にベースにします。また、nakamaは、 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 )中継されたマルチプレイヤーでは、他のクライアントのメッセージを受信します。クライアントは、 on_matchdataリスナーに送信する前に、メッセージデータを既にbase64にデコードしています。上記の例のように、データがJSONエンコードされている場合、自分でデコードする必要があります。
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 )信頼できる一致でサーバーによって開始されたメッセージは、デフォルトで有効なJSONとして提供されます。
Lua 5.1に書かれたSatoriのLuaクライアント。
Satoriは、実行可能な分析、A/Bテスト、リモート構成を強化するゲーム用のLiveOpsサーバーです。 Satori Defoldクライアントを使用して、Defoldゲーム内からSatoriと通信します。
SatoriダッシュボードからAPIキーを使用して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 )次に、認証してセッションを取得します。
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 )クライアントを使用すると、任意の実験や機能フラグを取得できます。ユーザーは属します。
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )開発ロードマップは、githubの問題として管理されており、プルリクエストを歓迎します。コードを強化することに興味がある場合は、問題を開いて変更について話し合うか、コミュニティフォーラムでドロップインして議論してください。
ユニットテストはtestsフォルダーにあります。望遠鏡（LUA 5.3+をサポートするフォーク）を使用してそれらを実行します。
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
APIドキュメントはLDOCで生成され、GitHubページに展開されます。
APIコメントを変更するとき、LDOCを再実行し、 docs/*の変更をコミットします。
注： nakama/nakama.luaのコメントはcodegen/main.goで作成する必要があります。
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
CodeGenフォルダーの手順を参照してください。
NakamaとSatoriのDefoldクライアントを別のLUAベースのエンジンに適応させることは、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 )エンジンモジュールは、次の機能を提供する必要があります。
http(config, url_path, query_params, method, post_data, cancellation_token, callback) -httpリクエストを作成します。
config -configテーブルnakama.create()またはsatori.create()に渡されますurl_pathベースURIに追加するパスquery_params -urlクエリパラメーターとして使用するキーバリューペアmethod - 「取得」、「投稿」post_data投稿するデータcancellation_token cancellation_token.cancelledがTrueかどうかを確認してくださいcallback - 結果を呼び出す関数（応答） socket_create(config, on_message) - ソケットを作成します。ソケットインスタンスを返す必要があります（エンジン固有のソケット状態を備えたテーブル）。
config -configテーブルnakama.create()または `satori.create（）に渡されますon_messageサーバーからメッセージが送信されたときに呼び出す機能socket_connect(socket, callback) - 接続ソケット。
socket - ソケットインスタンスはsocket_create()から返されましたcallback - 結果とともに呼び出す関数（OK、ERR） socket_send(socket, message) - ソケットにメッセージを送信します。
socket - ソケットインスタンスはsocket_create()から返されましたmessage - 送信するメッセージuuid() - uuidを作成します
このプロジェクトは、Apache-2ライセンスの下でライセンスされています。
