Transcurso de un Match

Consulta de estaciones

La información de todas las estaciones del local debe estar disponible para todos los asistentes del local. En caso de error en la operación del cliente Assistant, es necesario restablecer la información de las estaciones, y su Match asociado en caso de existir.

Descripción general

1. El cliente Assistant realiza una consulta sobre las estaciones.
2. Onsite devuelve la información de las estaciones del local, así como los Match que se juegan en cada una, en caso de existir uno vigente.

Flujo

Se requiere la siguiente ruta para la consulta de información de estaciones

Onsite: GET /stations/matches

Autorización: User (super, onsite), Assistant, Kiosk

Mediante la cual se obtienen la estaciones del local que cuentan con un dispositivo Timer vinculado y aceptado y, en caso de existir, el Match que se juega actualmente en la estación. La ruta responde con el estado 200 OK acompañado del siguiente cuerpo:

- id: 1
  name: 18
  screen: 2
  type: console
  seats: 2
  category:
    id: 1
    name: Retro
    isPcOnly: false
  zone:
    id: 2
    name: Hex
  observations: El cable tiene falso
  systems:
    - id: 1
      name: Xbox
    - id: 2
      name: PS4
    - id: 3
      name: WiiU
  match:
    id: 23
    stationId: 34
    gameSystemId: 32
    attendedAt: 1478304576
    isTimeRunning: true
    players
    - nick: Donnie Darko
      timeProductId: 2
      expiresAt: 1456738456
    - nick: Mr Nobody
      timeProductId: 5
      expiresAt: 1456738456
  tournamentMatch:
    tournamentXid: 3
    teamIds:
      - 2
      - 3

id

El identificador de la estación

name

El nombre asociado a la estación

screen

El número de pantalla a la que pertenece la estación

type

Tipo de estación, es decir, PC o consola

seats

Capacidad de asientos de la estación

category

Información de la categoría a la que pertenece la estación

zone

Información de la zona a la que pertenece la estación

observations

Información general sobre la estación

systems

Arreglo con identificador y nombre de los sistemas de la estación.

match.id

El identificador de la partida

match.stationId

El identificador de la estación donde está siendo jugado el Match

match.gameSystemId

El identificador del juego en uso para la partida

match.attendedAt

La fecha en que la partida fue asignada a la estación

match.isTimeRunning

Indica si la partida se encuentra corriendo, o si el tiempo se encuentra pausado

match.players

Un arreglo con el nick y el producto de tiempo contratado por los jugadores del Match actual en la estación

match.players.expiresAt

El momento en que el tiempo del jugador expira

tournamentMatch.tournamentXid

Identificador del torneo en Offsite.

tournamentMatch.teamIds

Identificadores de los equipos de torneo contendiendo en la estación.

En caso de que esta ruta se invocada desde un Kiosk, puede usarse el parámetro de búsqueda station_name para obtener la información de una estación dado el nombre de la misma.

Solicitud de servicio

Un jugador puede solicitar asistencia a través del cliente Kiosk o Timer. Posteriormente, su solicitud es recibida por los asistentes, quienes están facultados para atender la solicitud. Este proceso es descrito a continuación.

Descripción general

1. Desde Kiosk o Timer se solicita ayuda o servicio para uno o varios jugadores.
2. Onsite notifica a los asistentes de la nueva petición de servicio.

Flujo

Se require la siguiente ruta para el registro de un servicio en Onsite:

Onsite: POST /services

Autorización: Kiosk, Timer

Mediante la cual se notifica al local de la solicitud de asistencia por parte de un jugador. Dado que el motivo de la petición no es determinado aún en este momento, el cuerpo de la misma no contiene información.

Un cliente puede contar con, a lo más, un servicio pendiente de atención. Es por esto que únicamente debe existir para cada dispositivo un servicio con valor nulo para el campo type. En caso de no contar con servicios pendientes para el cliente, la ruta responde con el estado 201 Created acompañado del servicio recién creado. Por otro lado, si el cliente ya cuenta con un servicio pendiente de atención, se responde con el estado 200 OK acompañado de dicho servicio. Esto garantiza que el timer de una estación tiene a lo más un servicio sin ser atendido.

Como consecuencia de la invocación a POST /services correspondiente a una creación de servicio, se debe notificar vía socket a los asistentes acerca de la nueva solicitud de servicio, lo cual es logrado mediante la difusión Onsite broadcast: create_service.

Como observación, la presencia de los campos (categoryId, stationName) y kioskName es mutuamente excluyente. La presencia de los primeros dos implica que la solicitud de asistencia fue llevada a cabo desde un timer asociado a una estación. Por el contrario, la presencia del campo kioskName indica que la solicitud fue llevada a cabo desde un quiosco.

Adicionalmente, pueden consultarse manualmente los servicios existentes en el local. Esto con el fin de actualizar la información en algún cliente Assistant que haya sufrido una desconexión del sistema.

Onsite: GET /services

Autorización: Assistant

Mediante esta ruta es posible consultar los servicios solicitados en el local. Es posible consultar únicamente los servicios no atendidos aún mediante el uso del parámetro attended=false.

Esta ruta responde con el estado 200 OK acompañado de los servicios que cumplan con el criterio de petición.

Asistencia de servicio

Cuando un asistente atiende la petición de servicio de un cliente, se notifica al servidor Onsite con el objetivo de marcarla como atendida para todo el personal del local. Este proceso de describe en la siguiente sección.

Descripción general

1. Los clientes Assistant son notificados de la creación de un nuevo servicio desde Kiosk o Timer.
2. Un asistente atiende el servicio, indicando el motivo del mismo. En consecuencia, se establece la variable attendedAt del servicio como el tiempo en que un asistente lo sirve.
3. Se notifica a los asistentes del servicio atendido, con el fin de ser removido de los respectivos pool de notificaciones.

Flujo

Onsite: PUT /services/{id}

Autorización: Assistant

A través de esta ruta se actualiza el motivo de la solicitud de servicio de un cliente. El cuerpo del mensaje tiene la siguiente estructura

{
  "type": "menu"
}

donde type corresponde al tipo del servicio que fue solicitado, el cual puede ser únicamente uno de entre

Type	Servicio asociado
menu	Solicitar alimentos y bebidas
station	Solicitar cambio de mesa
game	Solicitar cambio de juego
checkin	Asistencia en Kiosk
support	Soporte al jugador

La ruta responde con el estado 200 OK acompañado del servicio modificado en caso de haber sido exitosa su actualización. Si el servicio referenciado no existe, se responde con el estado 404 Not found. Si el tipo de servicio especificado no corresponde a ninguno de los establecidos como aceptados, se responde con el estado 409 Conflict. Si desea actualizarse el tipo de asistencia de un servicio que ya fue establecido, se responde con el estado 403 Forbidden.

Cuando un asistente atiende un servicio, el Service asociado debe removerse del pool de notificaciones, por lo que el servidor Onsite debe notificar a los asistentes. Esto se logra difundiendo el mensaje: Onsite broadcast: delete_service.

Cambio de estación

Durante el transcurso de una partida de un grupo de jugadores, es posible que uno varios de ellos deseen cambiar de estación para continuar redimiendo su producto de tiempo. A continuación se describe el flujo que se sigue para llevar a cabo dicho proceso.

Flujo

Onsite: POST /stations/{id}/matches

Autorización: Assistant

Mediante esta ruta, un asistente solicita la creación de un Match para ser jugado en la estación indicada en la ruta. El cuerpo de la petición es el siguiente:

originMatchId: 279

Al recibir la petición, se confirma que la estación de destino cuente con la consola necesaria para continuar haciendo uso del juego contenido en el Match de origen. Posteriormente, se cierra el Match y se crea uno nuevo con los mismos jugadores y juego del Match original. El nuevo Match es asignado a la estación de destino y puesto en pausa. Si la estación a donde se cambia el jugador es una PC, el Match recién creado carecerá de juego asociado.

La ruta responde con el estado 201 Created acompañado del Match creado en la estación que recibe a los nuevos jugadores. La creación de la nueva partida es informada a los asistentes y timer como se indica en Onsite broadcast: update_match. De la misma manera es notificado el cierre de Match.

Si no se encuentra la estación destino, se responde con el estado 404 Not Found. Se responde con el estado 409 Conlict bajo cualquiera de los siguientes escenarios:

• La partida de origen no se encuentra.
• La estación de destino no cuenta con capacidad suficiente para albergar a los jugadores de la partida de origen.
• Si se desea cambiar la partida a una estación cuya categoría no es compatible con el tiempo de alguno de los jugadores.
• Si la estación de destino no cuenta con la consola requerida para seguir haciendo uso del juego del Match de origen.

Si la estación de destino está ocupada, o si la partida de la que se extraen jugadores no se encuentra activa, se responde con el estado 412 Precondition Failed.

Si el proceso de cambio de mesa falla, el Match de origen debe permanecer inalterado.

Establecer y remover juego

Al ser asignado un Match a una estación de tipo PC, el juego no es indicado por el asistente debido a que esto forma parte del flujo del cliente PC. Una vez que el jugador elige un juego en una PC y este es arrancado exitosamente, se establece el Game System elegido por el jugador. Posteriormente, al cerrar un juego también debe notificarse al servidor Onsite que el Match ya no cuenta con un Game System asociado. A continuación se describe el flujo seguido para establecer y remover juego en una PC.

Flujo

Onsite: PUT /match/game_system

Autorización: Timer

Mediante esta ruta se establece el juego del Match en la estación a la que pertenece el Timer. El cuerpo de la petición es el siguiente:

gameSystemId: 358

Al recibir la petición, se comprueba que exista un Match activo y que éste se encuentre siendo jugado en la estación asociada al Timer que realiza la petición. Posteriormente, si la petición corresponde a una reasignación de juego, se cierra el Match y se crea uno con los mismos datos, incluyendo además el juego con el gameSystemId indicado en la petición. Esta operación no crea un registro pause en el Time Log del jugador.

Esta ruta debe ser invocada también por el cliente PC cuando el jugador finaliza un juego, es decir, cuando el proceso asociado a un juego es terminado en el cliente. En este caso, se proporciona un gameSystemId nulo al momento del cambio.

La ruta responde con el estado 201 Created acompañado del Match recién creado para la estación. Adicionalmente, se notifica a los clientes Assistant del cambio como se indica en Onsite broadcast: update_match.

Si el Match no cuenta con Game System y no es proporcionado uno en la petición, se responde con el estado 400 Bad Request. Si no existe un Match activo siendo jugado en la estación asociada al Timer al momento de la petición, o si el juego no es compatible con el system PC, se responde con el estado 409 Conflict.

Si el Timer que lleva a cabo la petición no corresponde a una PC, se responde con el estado 501 Not Implemented.

Cambio de juego

A continuación se describe el flujo llevado a cabo por un asistente para solicitar el cambio de juego en una estación.

Flujo

Onsite: PUT /matches/{id}/game_system

Autorización: Assistant

Mediante estar ruta, un asistente solicita al servidor Onsite el cambio de juego para un Match que se encuentre siendo jugado al momento de llevar a cabo la petición. El cuerpo de la petición es el siguiente:

gameSystemId: 358

Al recibir la petición, se comprueba que el Match se encuentre vigente y que la estación cuente con la consola del juego que se desea usar. De ser así, se cierra el Match actual y se crea uno nuevo con la información de la partida anterior, siendo la única diferencia el Game System actualizado. Finalmente, se cambia la entrada de video de la estación para que coincida con la señal asociada a la consola del videojuego elegido en el cambio; esto sólo si la estación donde se juega no corresponde a una PC.

La partida recién creada debe iniciar en pausa para reflejar el nuevo tiempo de configuración. La notificación de creación de esta partida es enviada a los asistentes como se indica en Onsite broadcast: update_match.

Si el proceso es exitoso, el servidor Onsite responde con el estado 200 OK acompañado de la partida creada.

Si la partida aún no ha sido asignada a una estación, se responde con el estado 403 Forbidden. Si el Match donde se reemplazará el juego no se encuentra, se responde con el estado 404 Not Found.

La ruta responde con el estado 409 Conflict bajo cualquiera de los siguientes escenarios:

• El match se encuentra cerrado.
• La estación no cuenta con la consola requerida para usar el nuevo juego.
• El juego solicitado no se encuentra.
• No existen copias disponibles del juego solicitado para la consola.

Si se solicita realizar un cambio de juego a una estación con PC, se responde con el estado 501 Not Implemented.

Cambio de estado en una partida

A través del ciente Timer o Assistant es posible dar término a una partida activa en una estación, liberando la misma para ser utilizada por nuevos jugadores. Adicionalmente, un cliente Assistant puede pausar el tiempo de un Match que corre en una estación, pausando en consecuencia el tiempo de todos los jugadores participantes. El proceso es descrito a continuación.

Descripción general

1. El cliente solicita el cambio de estado en un Match.
2. El servidor Onsite comprueba la validez de la operación en función del estado del cliente y de la autenticación proporcionada, realiza el cambio e informa del resultado.

Flujo

Onsite: PUT /matches/{id}/status

Autorización: Assistant, Timer

Mediante esta ruta es posible cambiar el estado de tiempo sobre el match referenciado en la ruta. El cuerpo de la petición es el siguiente:

status: pause

donde status corresponde al nuevo estado que tomará el Match, y el cual puede ser pause, active, end. El comportamiento al recibir cada uno es el siguiente:

Nuevo estado	Autorización	Comportamiento
pause	Assistant	El tiempo de todos los jugadores del Match actual es pausado por uno tiempo máximos de 7 minutos, actualizando con Scheduler la nueva fecha de expiración del tiempo de la estación. La operación sólo puede llevarse a cabo si el tiempo de los jugadores se encuentra activo al momento de la petición.
active	Assistant	Se reanuda el tiempo de todos los jugadores en el Match actual, actualizando con Scheduler la nueva fecha de expiración. Sólo se permite esta operación si el tiempo de todos los jugadores se encuentra pausado.
end	Timer, Assistant	Se marca el Match como cerrado, comunicando a Scheduler el borrado de la partida. Se marca un registro pause en el conteo de tiempo de todos los jugadores involucrados en el Match. Esta operación puede llevarse a cabo indistintamente del estado previo del Match.

Nota

Todos los jugadores participantes en el mismo Match activo deben contar con el mismo estado en su registro de tiempo. En caso de proporcionar un valor end para la partida, el tiempo de los jugadores no finaliza, sino que es pausado.

Como respuesta a esta operación el estado es 200 OK acompañado de la información del Match actualizado. Si no es proporcionado el valor de estado, o si no coincide con los soportados por el sistema, se responde con el estado 400 Bad Request. Si el cliente que lleva a cabo la petición no cuenta con la autorización suficiente (ej. Timer desea pausar una partida) se responde con 403 Forbidden. En caso de no ubicar al Match con el identificador proporcionado, se responde con el estado 404 Not Found. En caso de solicitar pausar una sesión pausada, activar una sesión cuyo tiempo se encuentra activo, o llevar a cabo operaciones sobre un Match que ya ha sido cerrado; se responde con 409 Conflict.

Un cambio de estado entre activo, pausado o finalizado en un Match se notifica a los clientes Assistant del local, así como al Timer, como se indica en Onsite broadcast: update_match.

Si se cierra el match de los jugadores, estos se agregan al pool de Check Ins, notificando como en Onsite broadcast: create_checkin.

Expulsión de jugadores

A continuación se define el comportamiento llevado a cabo por el Asistente para remover a un grupo de jugadores de una partida en curso.

Flujo

Onsite: DELETE /matches/{id}/players

Autorización: Assistant

Mediante esta ruta se remueve del Match a los jugadores indicados en el cuerpo de la petición. Los jugadores removidos no son añadidos a un nuevo Match, por lo que son visibles desde el pool de jugadores. El cuerpo de la petición es el siguiente

nicks:
  aleeexkj
  susuhml

Como acción a esta petición, se pausa el tiempo de todos los jugadores en la partida. Posteriormente, se crea un nuevo Match con los jugadores que permanecen jugando. Finalmente, se reanuda el tiempo de los jugadores del nuevo Match. Por lo tanto, los jugadores expulsados contarán con su tiempo en pausa y serán visibles desde el pool de jugadores.

Esta ruta responde con el estado 200 OK acompañado del nuevo Match con los jugadores que permanecen en este. Si el Match no ha sido asignado a ninguna estación, se responde con el estado 403 Forbidden. Si alguno de los jugadores a remover no se encuentran en la partida, se responde con el estado 404 Not Found.

Esta ruta no soporta la expulsión completa de todos los jugadores. Si en la petición son proporcionados los nicks de todos los participantes en la partida, se responde con el estado 409 Conflict.

Si no es proporcionado al menos un jugador para abandonar la partida, se responde con el estado 422 Unprocessable Entity.

Como consecuencia del flujo exitoso de la aplicación, se notifica del cierre del Match original, así del Match resultante de la expulsión como en indica en Onsite broadcast: update_match. La adición de los jugadores expulsados al pool de Check Ins se notifica como en Onsite broadcast: create_checkin.

Obtención de un jugador invitado

Es posible para un asistente solicitar jugadores de tipo invitado al servidor Onsite, el cual a su vez solicitará a Offsite la creación de un Player que puede ser usado en la sucursal; y cuyas monedas adquiridas expirarán al momento del cierre de su Check In.

Flujo

Onsite: GET /players/guest

Autorización: Assistant

Mediante esta ruta se solicita al servidor Onsite la obtención de un jugador invitado. La ruta responde con el estado 200 OK acompañado de la siguiente información:

id: 2
nick: GuestCU1
avatarUrl: null
checkIn:
  id: 2232
  token: j5JSetsgHnpEpQPAY2J5a4KfeDrWGzWdx7jGMx68wKezRyfW
  createdAt: 1479862013
  updatedAt: 1479862013
  closedAt: null
createdAt: 1479862013
updatedAt: 1479862013

Dicho jugador debe ser agregado al pool de Check Ins para su gestión desde el cliente Assistant.

Si la sucursal ya no se encuentra dentro de horario operativo, se responde con el estado 412 Precondition Failed.

Offsite: GET /players/guest

Autorización: Location

A través de esta ruta, un servidor Onsite solicita a Offsite la obtención de un jugador invitado, el cual no debe contar con moneda Arena en ningún país.

Para obtener un jugador invitado a devolver, es necesario obtener aquellos jugadores Guest que se hayan generado para la sucursal. De este conjunto de jugadores es necesario remover a aquellos que cuenten con un Check In abierto. Si el conjunto restante de jugadores invitados tiene elementos, basta con devolver uno de éstos. Si no, debe crearse un nuevo jugador. En cualquier caso, debe crearse un nuevo Check In para el jugador y devolverse al servidor Onsite que realizó la petición.

La estructura que debe tener un nick generado por el servidor Offsite debe ser: Guest + <prefijo_de_sucursal> + <contador>.

La ruta responde con el estado 200 OK acompañado de la siguiente información:

id: 2
nick: GuestCU1
email: null
avatarUrl: null
coins: 0
profile: null
checkIn:
  id: 2232
  token: j5JSetsgHnpEpQPAY2J5a4KfeDrWGzWdx7jGMx68wKezRyfW
  createdAt: 1479862013
  updatedAt: 1479862013
  closedAt: null
  usedAt: 1479862013
createdAt: 1479862013
updatedAt: 1479862013

Consejo

Al generar un token en esta petición, es necesario marcarlo como usado, dado que es validado al momento de su generación.

Notificación de un Check In en el pool

Al incluir a un jugador en el pool, es necesario notificar a los asistentes que el Player se encuentra disponible para ser asignado a una nueva partida. La notificación se define como sigue.

Flujo

La notificación de adición de un Check In al pool de disponibles se lleva a cabo como se indica en Onsite broadcast: create_checkin.

Consulta del estado del pool de Check Ins

A continuación se describe el comportamiento de una ruta que tiene como propósito facilitar la recuperación de los Check Ins del pool.

Flujo

Se hace uso de la siguiente ruta para recuperar Check Ins

Onsite: GET /check_ins

Autorización: Assistant

Mediante esta ruta se obtienen los Check Ins abiertos y sin partida en transcurso. La ruta responde con el estado 200 OK acompañado de la siguiente información

- id: 45
  player:
    id: 1
    nick: Donnie Darko
    createdAt: 1479862013
    updatedAt: 1479862013
  timeExpired: true
  timeProductId: 2
  lastMatch:
    id: 47
    gameSystemId: 3
    joiningStationId: 6
    stationId: 23
    categoryId: Retro
    zoneId: 3
    createdAt: 1479862013
    attendedAt: 1479862013
    closedAt: 1479862013
    players:
      - nick: Donnie Darko
        timeProductId: 2
      - nick: Mr Nobody
        timeProductId: 5

Donde lastMatch puede no contener información.

Cierre de Check In

Un Check In es cerrado por asistente para indicar que el jugador abandona el local y renuncia a su tiempo restante. Este comportamiento es llevado a cabo invocando la ruta Onsite: POST /players/check_out.

Como comportamiento adicional, se notifica de la remoción del Check In del pool como se indica en Notificación de Check In eliminado.

Unir Check In a Match

Un Check In puede agregarse a una estación como se indica en el flujo Onsite: PUT /stations/{id}/matches.

Notificación de Check In eliminado

La remoción de un Check In del pool debe notificarse a los clientes Assistant del local como se indica en el broadcast Onsite broadcast: delete_checkin.

Remoción de una partida

El servidor Onsite notifica a los asistentes de la remoción de un Match de la lista de partidas vigentes en el local como se indica en Onsite broadcast: delete_match.

Operaciones sobre match grupal

A continuación se definen los comportamientos soportados por el sistema en relación a las partidas grupales.

Cambio de estado

Onsite: PUT /matchs_groups/{id}/status

Autorización: Assistant

Mediante esta ruta es posible cambiar el estado de tiempo sobre todas las estaciones donde se juega el match grupal indicado en la ruta. El cuerpo de la petición es el siguiente:

status: end

donde status corresponde al nuevo estado que tomará el Match grupal, y el cual puede ser únicamente end. El comportamiento al recibir cada uno es el siguiente:

Nuevo estado	Comportamiento
end	Se marca el Match como cerrado, comunicando a Scheduler el borrado de la partida. Se marca un registro end en el conteo de tiempo del jugador invitado asociado.

Como respuesta a esta operación el estado es 200 OK acompañado de la información del Match actualizado. Si no es proporcionado el valor de estado, o si no coincide con los soportados por el sistema, se responde con el estado 400 Bad Request. En caso de no ubicar al Group Match con el identificador proporcionado, se responde con el estado 404 Not Found. En caso de solicitar llevar a cabo operaciones sobre un Match que ya ha sido cerrado; se responde con 409 Conflict.

Al cerrar el match grupal, se notifica a los clientes Assistant del local, así como a los Timers involucrados, como se indica en Onsite broadcast: update_match_group. El jugador invitado es enviado al pool de Check Ins, notificando a los clientes como en Onsite broadcast: create_checkin.

Cambio de señal

Dado que no se otorga la función de cambio de juego para partidas grupales, es necesario otorgar la funcionalidad de cambio en la señal de entrada de la pantalla de alguna de las estaciones. A continuación se define el proceso de cambio en la señal digital en una estación durante una partida grupal.

Onsite: PUT /stations/signal

Autorización: Assistant

Mediante esta ruta, se solicita el cambio en la señal de un grupo de estaciones. El cuerpo de la petición es el siguiente:

alterOutputs:
  - stationId: 2
    systemId: 3
  - stationId: 25
    systemId: 2
  - stationId: 17
    systemId: 4

El servidor solicita al calendarizador el cambio en la señal para cada una de las estaciones con efecto inmediato.

La ruta responde con el estado 204 No Content si la solicitud se procesó correctamente.

Si alguno de los identificadores de sistema no existe, se responde con el estado 409 Conflict. Si alguna de las estaciones no pertenece a una partida grupal al momento de recibir la petición, se responde con el estado 412 Precondition Failed.

En caso de error, se preserva el cambio de input sobre las estaciones donde se tuvo éxito.