nakama defold
v3.4.0
Cliente Lua para Nakama Server escrito en Lua 5.1.
Nakama es un servidor de código abierto diseñado para alimentar juegos y aplicaciones modernas. Las características incluyen cuentas de usuario, chat, social, casamenteros, multijugador en tiempo real y mucho más.
Este cliente implementa las opciones completas de API y socket con el servidor. Está escrito en Lua 5.1 para ser compatible con los motores de juego con sede en Lua.
La documentación completa está disponible aquí.
Deberá configurar el servidor y la base de datos antes de poder conectarse con el cliente. La forma más simple es usar Docker, pero echar un vistazo a la documentación del servidor para otras opciones.
Instalar y ejecutar los servidores. Sigue estas instrucciones.
Agregue el cliente a su proyecto.
game.project . El cliente ahora aparecerá en la carpeta nakama en su proyecto.Agregue dependencias a su proyecto. En los proyectos Defold, debe agregar una de las siguientes dependencias a Game.project:
Use las credenciales de conexión para inicializar al 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 la decodificación de Base64 para la sesión de la sesión Tokens de sesión y tanto la codificación y decodificación de Base64 de los datos de coincidencias. El codificador y el decodificador Base64 predeterminado se escribe en LUA. Para aumentar el rendimiento de los pasos de codificación y decodificación de Base64, es posible usar un codificador base64 escrito en C. En proyectos defold debe agregar la siguiente dependencia al juego.
El cliente tiene muchos métodos para ejecutar varias funciones en el servidor o abrir conexiones de socket en tiempo real con el servidor.
Hay una variedad de formas de autenticarse con el servidor. La autenticación puede crear un usuario si aún no existen con esas credenciales. También es fácil de autenticarse con un perfil social de Google Play, Facebook, Centro de juegos, 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 la sección Solicitudes a continuación para ejecutar este fragmento (a) sincrónicamente.
Cuando se autentica, el servidor responde con un token de autenticación (JWT) que puede usarse para autenticar las solicitudes de API. El token contiene propiedades útiles y se deserializa en una tabla 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 ) Se recomienda almacenar el token de autenticación de la sesión y verificar en el inicio si ha expirado. Si el token ha expirado, debe reautiar. Si el token está a punto de expirar, debe actualizarse. El tiempo de vencimiento del token se puede cambiar como una configuración en el servidor. Puede almacenar la sesión usando session.store(session) y luego la restauró 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 )El cliente incluye muchas API incorporadas para varias características del servidor de juegos. Se puede acceder a estos con los métodos que usan una función de devolución de llamada para devolver un resultado (es decir, asíncrono) o rendimiento hasta que se reciba un resultado (es decir, sincrónico y debe ejecutarse dentro de una 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 );El cliente Nakama proporciona una función de conveniencia para crear y comenzar una coroutine para ejecutar múltiples solicitudes sincrónicamente una tras otra:
nakama . sync ( function ()
local account = client . get_account ()
local result = client . update_account ( request )
end )Nakama tiene una configuración de reintento global y por solicitud para controlar cómo se vuelven a contactar las llamadas API fallidas.
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 ))Cree un token de cancelación y pase eso con una solicitud para cancelar la solicitud antes de que se haya completado.
-- 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 )Puede conectarse al servidor a través de una conexión WebSocket en tiempo real para enviar y recibir mensajes de chat, recibir notificaciones y emparejarse en una coincidencia multijugador.
Primero debe crear un socket en tiempo real al servidor:
local client = nakama . create_client ( config )
-- create socket
local socket = client . create_socket ()
nakama . sync ( function ()
-- connect
local ok , err = socket . connect ()
end )Luego proceda a unirse a un canal de chat y envíe un mensaje:
-- 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 de cliente tiene oyentes de eventos que se solicitan en varios eventos recibidos del servidor. Ejemplo:
socket . on_disconnect ( function ( message )
print ( " Disconnected! " )
end )Oyentes disponibles:
on_disconnect : maneja un evento para cuando el cliente se desconecte del 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 admite cualquier contenido binario en el atributo data de un mensaje de coincidencia. Independientemente de su tipo de datos, el servidor solo acepta datos codificados en Base64 , por lo que asegúrese de no publicar datos de texto sencillo o incluso JSON, o el servidor Nakama reclamará los datos malformados y desconectar a su cliente (establecer el registro del servidor para debug para detectar estos eventos).
Nakama se basará automáticamente en los datos de la coincidencia si el mensaje se creó usando nakama.create_match_data_message() . Nakama también basará automáticamente el decodificar los datos de coincidencia recibidos antes de llamar al oyente 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 ) En un multijugador transmitido, recibirá los mensajes de otros clientes. El cliente ya ha basado64 decodificó los datos del mensaje antes de enviarlos al oyente on_matchdata . Si los datos estaban codificados JSON, como en el ejemplo anterior, debe decodificarlo usted mismo:
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 )Los mensajes iniciados por el servidor en una coincidencia autorizada vendrán como JSON válido de forma predeterminada.
Cliente de Lua para Satori escrito en Lua 5.1.
Satori es un servidor de LiveOPS para juegos que impulsa analíticos procesables, pruebas A/B y configuración remota. Use el cliente Satori Defold para comunicarse con Satori desde su juego Defold.
Cree un cliente Satori usando la tecla API desde el tablero 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 )Luego autenticar para obtener su sesión:
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 el cliente, puede obtener cualquier experimento o indicador de características, el usuario pertenece.
satori . sync ( function ()
local experiments = satori . get_experiments ( client )
pprint ( experiments )
local flags = satori . get_flags ( client )
pprint ( flags )
end )La hoja de ruta de desarrollo se gestiona como problemas de GitHub y las solicitudes de extracción son bienvenidas. Si está interesado en mejorar el código, abra un problema para discutir los cambios o entregarlo y discutirlo en el Foro de la Comunidad.
Las pruebas unitarias se pueden encontrar en la carpeta tests . Ejecutarlos usando el telescopio (tenedor que admite Lua 5.3+):
./tsc -f test/test_nakama.lua test/test_satori.lua test/test_socket.lua test/test_session.lua
Los documentos de API se generan con LDOC y se implementan en páginas GitHub.
Al cambiar los comentarios de la API, vuelva a ejecutar LDOC y confirme los cambios en docs/* .
Nota: Comentarios para nakama/nakama.lua deben hacerse en codegen/main.go .
Para ejecutar 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 las instrucciones en la carpeta Codegen.
Adaptar a los clientes Nakama y Satori Desfoldia a otro motor basado en LUA debe ser tan fácil como proporcionar otro módulo de motor al configurar el 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 )El módulo del motor debe proporcionar las siguientes funciones:
http(config, url_path, query_params, method, post_data, cancellation_token, callback) - Realice la solicitud HTTP.
config - TABLA DE CONFIGURA PASADA A nakama.create() O satori.create()url_path - Ruta para agregar al URI basequery_params - pares de valor clave para usar como parámetros de consulta de URLmethod - "Obtener", "Publicar"post_data - datos para publicarcancellation_token : verifique si cancellation_token.cancelled es verdaderocallback : función para llamar con el resultado (respuesta) socket_create(config, on_message) - crea socket. Debe devolver la instancia de socket (tabla con estado de enchufe específico del motor).
config - TABLA DE CONFIGURA PASADA A nakama.create() O `SATORI.CREATE ()on_message : función para llamar cuando se envía un mensaje desde el servidor socket_connect(socket, callback) - Conecte el socket.
socket - Socket Instance devuelto de socket_create()callback : función para llamar con el resultado (OK, err) socket_send(socket, message) : envíe el mensaje en Socket.
socket - Socket Instance devuelto de socket_create()message - Mensaje para enviar uuid() - crear un uuid
Este proyecto tiene licencia bajo la licencia Apache-2.
