Ir al contenido
Descargar
Plugins

Colyseus

El cliente de Colyseus, un servidor multijugador: emparejamiento, salas, estado que se sincroniza solo, mensajes y sus cuentas. Además da a los juegos en red el proveedor colyseus: el mismo juego, sin código de red, jugando por internet a través de un servidor Colyseus.

Se instala desde Edit > Plugins (Colyseus, gobuengine/plugins-colyseus): se baja a plugins/colyseus del proyecto y se activa. Sus bibliotecas son para Windows, la web (juegos exportados sin Thread Support, lo predeterminado) y Android (dispositivos de 64 bits; activarlo marca el permiso INTERNET en los presets de Android).

En Project Settings > Online > Session:

  • Provider: colyseus.
  • Address / Port: el servidor Colyseus (localhost / 2567, o wss://example.com).
  • Mode: el tipo de partida; los jugadores solo se encuentran con jugadores del mismo modo.

Con Start: Automatic (o Online.quick_match("forest", 4)), Colyseus entra en una sala de ese modo con sitio o crea una. El primer juego de una sala es el anfitrión (ejecuta el mundo); la sala reenvía los paquetes. Si el anfitrión se va, el jugador con el id más bajo pasa a ser el anfitrión y la partida sigue (Session > Host Migration; desactivado, la partida termina).

El servidor necesita la sala de reenvío del plugin. El repositorio del plugin tiene ese servidor listo en Source/server (npm install, npm start; puerto 2567): GobuRelayRoom, emparejada por modo. Un servidor Colyseus propio toma la sala de ahí y la registra como gobu_relay: defineRoom(GobuRelayRoom).filterBy(["mode"]).

El juego es el mismo que con cualquier proveedor: lo que se replica, @action, @everyone, @predicted, los datos guardados (@persistent, los guarda el anfitrión o el servidor dedicado), el login de los jugadores, Online.kick() y la migración del anfitrión. Funcionan todos los Session > Start, con salas de Session > Mode:

StartDesde códigoA través de Colyseus
AutomaticOnline.quick_match()Una sala con sitio, o una nueva; su primer juego es el anfitrión.
HostOnline.host()Una sala nueva; este juego es el anfitrión y juega.
Dedicated ServerOnline.serve(), el servidor exportadoUna sala nueva; el servidor ejecuta el mundo, sin jugador propio.
JoinOnline.join()Una sala abierta (la de un servidor dedicado, la de un anfitrión); nunca una nueva.

El puerto es el del servidor Colyseus (Session > Port, el que usan estas funciones si no se les da uno). Cuando un servidor dedicado se cierra, la partida termina para sus jugadores; cuando se va un anfitrión que juega, otro jugador ocupa su lugar.

Un anfitrión que juega inicia sesión como los demás (Online > Login; con Check: Game Code sus propias reglas reciben su login_requested, con id 1). Online.kick(), y un login que el anfitrión rechaza, cierran también la conexión de ese jugador con la sala, así que un juego que no sale por sí mismo (uno modificado) se va igual.

Para un juego que usa Colyseus directamente (sus salas, sus esquemas de estado, sus mensajes), el plugin trae el SDK como el módulo de Grost Colyseus (plugins/colyseus/colyseus.gro, Colyseus SDK 0.18.15). Su servidor es Colyseus 0.18: el estado de las salas de un servidor 0.17 no se decodifica (los juegos de Online juegan en los dos). Sus envoltorios son structs: guárdalos en variables mut, y guarda la sala en una variable del script: una sala que nadie tiene se va.

mut client := Colyseus.Client.new("ws://localhost:2567")
mut room := client.join_or_create("my_room")
room.on_state_changed(fn() { print(room.get_state()) })
mut callbacks := room.callbacks()
_ = callbacks.listen("score", fn(value: Option[float], previous: Option[float]) { print(value) })
room.send_message("move", { "x": 3 })

El estado son Dictionaries (room.get_state()), que describe la reflexión del servidor. Un juego también puede describirlo él mismo con Colyseus.field() y Colyseus.schema(), y room.set_state_type(). Los comentarios del propio módulo cuentan el resto (señales en room.native, propiedades de solo lectura como métodos).

room.request() manda un mensaje que el servidor contesta: la respuesta es lo que devuelve el onMessage de la sala para ese tipo.

_ = room.request("buy", { "item": "sword" }, fn(err: Dictionary, data: Dictionary) {
if err.is_empty() {
print("gold left: ", data.get("gold", 0))
} elif err.get("code", 0) == Colyseus.REQUEST_REJECTED {
print("not sold: ", err.get("message", ""))
}
})

Una respuesta que no es un objeto llega en data["value"]. Cuando falla, err["code"] dice por qué:

CódigoPor qué
Colyseus.REQUEST_REJECTEDEl handler la rechazó (ctx.reject(reason)); el motivo está en err["reason"].
Colyseus.REQUEST_FAULTEDEl handler falló, o la sala no tiene uno para ese tipo.
Colyseus.REQUEST_CLOSEDLa conexión se cerró antes de la respuesta.
Colyseus.REQUEST_TIMED_OUTNo hubo respuesta a tiempo (el último argumento, timeout_ms: 10 segundos; 0 espera siempre).

client.http (get_request, post, put, patch, delete) y client.auth (sign_in_anonymously, sign_in_with_email_and_password…) contestan igual: callback(err: Dictionary, data: Dictionary), con err vacío cuando salió bien.

room.ping(callback) mide la ida y vuelta por la conexión de la sala (callback(rtt_ms: int)). Antes de entrar, client.get_latency(callback) mide el servidor, y client.select_by_latency() elige el más cercano de varios:

_ = client.select_by_latency(["wss://eu.example.com", "wss://us.example.com"], fn(err: Dictionary, data: Dictionary) {
print("nearest: ", data.get("endpoint", ""), " in ", data.get("latency_ms", 0.0), " ms")
})

client.consume_seat_reservation(reservation) entra con un asiento que el servidor reservó para el jugador (matchMaker.joinOrCreate(), reserveSeatFor()), como uno que devuelve una ruta HTTP del servidor.