nakama defold
v3.4.0
Lua Client for Nakama Server yang ditulis di LUA 5.1.
Nakama adalah server open-source yang dirancang untuk menyalakan game dan aplikasi modern. Fitur termasuk akun pengguna, obrolan, sosial, mak comblang, multiplayer realtime, dan banyak lagi.
Klien ini mengimplementasikan opsi API dan soket lengkap dengan server. Ini ditulis dalam Lua 5.1 untuk kompatibel dengan mesin game berbasis LUA.
Dokumentasi lengkap tersedia di sini.
Anda harus mengatur server dan database sebelum Anda dapat terhubung dengan klien. Cara paling sederhana adalah dengan menggunakan Docker tetapi melihat dokumentasi server untuk opsi lain.
Pasang dan jalankan server. Ikuti instruksi ini.
Tambahkan klien ke proyek Anda.
game.project . Klien sekarang akan muncul di folder nakama di proyek Anda.Tambahkan dependensi ke proyek Anda. Dalam proyek -proyek Defold, Anda perlu menambahkan salah satu dependensi berikut ke Game.project:
Gunakan kredensial koneksi untuk menginisialisasi klien 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 )(Opsional) Nakama menggunakan decoding base64 untuk sesi token sesi dan kedua pengkodean base64 dan decoding data kecocokan. Encoder dan decoder base default ditulis di Lua. Untuk meningkatkan kinerja Base64 Encode dan Decode Langkah -langkah, dimungkinkan untuk menggunakan encoder Base64 yang ditulis dalam C. Dalam proyek yang ditentukan Anda perlu menambahkan ketergantungan berikut ke Game.project:
Klien memiliki banyak metode untuk menjalankan berbagai fitur di server atau membuka koneksi soket realtime dengan server.
Ada berbagai cara untuk mengotentikasi dengan server. Otentikasi dapat membuat pengguna jika belum ada dengan kredensial tersebut. Juga mudah untuk diotentikasi dengan profil sosial dari Google Play Games, Facebook, Game Center, dll.
local client = nakama . create_client ( config )
local email = " [email protected] "
local password = " batsignal "
local session = client . authenticate_email ( email , password )
pprint ( session )Catatan : Lihat bagian Permintaan di bawah untuk menjalankan cuplikan ini (a) secara serentak.
Ketika diautentikasi server merespons dengan token auth (JWT) yang dapat digunakan untuk mengotentikasi permintaan API. Token berisi properti yang bermanfaat dan didesosialisasi ke dalam tabel 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 ) Disarankan untuk menyimpan token auth dari sesi dan memeriksa saat startup jika telah kedaluwarsa. Jika token telah kedaluwarsa, Anda harus reutentikasi. Jika token akan kedaluwarsa itu harus disegarkan. Waktu kedaluwarsa token dapat diubah sebagai pengaturan di server. Anda dapat menyimpan sesi menggunakan session.store(session) dan kemudian memulihkannya menggunakan 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 )Klien mencakup banyak API bawaan untuk berbagai fitur server game. Ini dapat diakses dengan metode yang menggunakan fungsi panggilan balik untuk mengembalikan hasil (mis. Asynchronous) atau hasil sampai hasilnya diterima (mis. Sinkron dan harus dijalankan dalam Lua coroutine).
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 );Klien Nakama menyediakan fungsi kenyamanan untuk membuat dan memulai coroutine untuk menjalankan beberapa permintaan secara serempak satu demi satu:
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakama memiliki konfigurasi coba kembali global dan per-permintaan untuk mengontrol bagaimana panggilan API yang gagal diulang.
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 ))Buat token pembatalan dan lulus dengan permintaan untuk membatalkan permintaan sebelum selesai.
-- 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 )Anda dapat terhubung ke server melalui koneksi Websocket realtime untuk mengirim dan menerima pesan obrolan, mendapatkan pemberitahuan, dan membuat Matchmake menjadi pertandingan multipemain.
Pertama -tama Anda harus membuat soket realtime ke server:
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )Kemudian lanjutkan untuk bergabung dengan saluran obrolan dan kirim pesan:
-- 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! " )Soket klien memiliki pendengar acara yang dipanggil pada berbagai acara yang diterima dari server. Contoh:
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )Pendengar yang tersedia:
on_disconnect - menangani acara ketika klien terputus dari server.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 mendukung setiap konten biner dalam atribut data dari pesan kecocokan. Terlepas dari tipe data Anda, server hanya menerima data yang dikodekan Base64 , jadi pastikan Anda tidak memposting data teks sederhana atau bahkan JSON, atau server Nakama akan mengklaim data yang salah dan lepaskan klien Anda (atur server logging ke debug untuk mendeteksi peristiwa ini).
Nakama akan secara otomatis mendasarkan 64 menyandikan data kecocokan Anda jika pesan dibuat menggunakan nakama.create_match_data_message() . Nakama juga akan secara otomatis mendekode 64 mendekode data kecocokan yang diterima sebelum memanggil pendengar 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 ) Dalam multipemain yang disampaikan, Anda akan menerima pesan klien lain. Klien telah Base64 mendekodekan data pesan sebelum mengirimkannya ke pendengar on_matchdata . Jika data dikodekan JSON, seperti pada contoh di atas, Anda perlu memecahkan kode sendiri:
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 )Pesan yang diprakarsai oleh server dalam pertandingan otoritatif akan datang sebagai JSON yang valid secara default.
Klien LUA untuk Satori ditulis dalam LUA 5.1.
Satori adalah server LIVEOPS untuk game yang mendukung analitik yang dapat ditindaklanjuti, pengujian A/B dan konfigurasi jarak jauh. Gunakan Satori Defold Client untuk berkomunikasi dengan Satori dari dalam game Defold Anda.
Buat klien Satori menggunakan kunci API dari dasbor 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 )Kemudian otentikasi untuk mendapatkan sesi Anda:
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 )Menggunakan klien Anda bisa mendapatkan eksperimen atau bendera fitur apa pun, pengguna milik.
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )Peta jalan pengembangan dikelola sebagai masalah gitub dan permintaan tarik dipersilakan. Jika Anda tertarik untuk meningkatkan kode, buka masalah untuk membahas perubahan atau mampir dan diskusikan di Forum Komunitas.
Tes unit dapat ditemukan di folder tests . Jalankan mereka menggunakan teleskop (garpu yang mendukung LUA 5.3+):
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
Dokumen API dihasilkan dengan LDOC dan digunakan ke halaman GitHub.
Saat mengubah komentar API, rerun LDOC dan lakukan perubahan dalam docs/* .
Catatan: Komentar untuk nakama/nakama.lua harus dibuat di codegen/main.go .
Untuk menjalankan 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
Lihat instruksi di folder Codegen.
Mengadaptasi klien Nakama dan Satori Defold ke mesin berbasis LUA lainnya harus semudah menyediakan modul mesin lain saat mengkonfigurasi klien 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 )Modul mesin harus menyediakan fungsi -fungsi berikut:
http(config, url_path, query_params, method, post_data, cancellation_token, callback) - buat permintaan http.
config - Tabel konfigurasi diteruskan ke nakama.create() atau satori.create()url_path - jalur untuk menambahkan ke pangkalan URIquery_params - pasangan nilai kunci untuk digunakan sebagai parameter kueri urlmethod - "Get", "Post"post_data - Data untuk dipostingcancellation_token - periksa apakah cancellation_token.cancelled benarcallback - Fungsi untuk menelepon dengan hasil (respons) socket_create(config, on_message) - Buat soket. HARUS Mengembalikan Socket Instance (Tabel dengan status soket spesifik engine).
config - Tabel Konfigurasi diteruskan ke nakama.create() atau `satori.create ()on_message - Fungsi untuk menelepon saat pesan dikirim dari server socket_connect(socket, callback) - Sambungkan soket.
socket - Socket Instance dikembalikan dari socket_create()callback - Fungsi untuk menelepon dengan hasil (ok, err) socket_send(socket, message) - Kirim pesan di soket.
socket - Socket Instance dikembalikan dari socket_create()message - Pesan untuk Mengirim uuid() - buat uuid
Proyek ini dilisensikan di bawah lisensi APACHE-2.
