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).
Juegos en red a través de Colyseus
Sección titulada «Juegos en red a través de Colyseus»En Project Settings > Online > Session:
- Provider:
colyseus. - Address / Port: el servidor Colyseus (
localhost/2567, owss://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"]).
Qué de Online funciona a través de él
Sección titulada «Qué de Online funciona a través de él»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:
| Start | Desde código | A través de Colyseus |
|---|---|---|
| Automatic | Online.quick_match() | Una sala con sitio, o una nueva; su primer juego es el anfitrión. |
| Host | Online.host() | Una sala nueva; este juego es el anfitrión y juega. |
| Dedicated Server | Online.serve(), el servidor exportado | Una sala nueva; el servidor ejecuta el mundo, sin jugador propio. |
| Join | Online.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.
El SDK de Colyseus en Grost
Sección titulada «El SDK de Colyseus en Grost»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).
Peticiones y respuestas
Sección titulada «Peticiones y respuestas»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ódigo | Por qué |
|---|---|
Colyseus.REQUEST_REJECTED | El handler la rechazó (ctx.reject(reason)); el motivo está en err["reason"]. |
Colyseus.REQUEST_FAULTED | El handler falló, o la sala no tiene uno para ese tipo. |
Colyseus.REQUEST_CLOSED | La conexión se cerró antes de la respuesta. |
Colyseus.REQUEST_TIMED_OUT | No hubo respuesta a tiempo (el último argumento, timeout_ms: 10 segundos; 0 espera siempre). |
HTTP, cuentas y latencia
Sección titulada «HTTP, cuentas y latencia»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.