Skip to main content

Game Events API

An overview of the game events API that the Synthergy game server provides for clients to send and receive game events.

Overview​

Synthergy's game server serves a Socket.io server endpoint that provides a real-time event API for sending and receiving game events. A Socket.io client can connect to the server and emit and listen for events to communicate with the server and other connected clients.

Event List​

The following enum (defined here) describes the events that the server can send and receive. Any connected client is responsible for handling any incoming events and emitting its own events to the server as needed.

export const enum Events {
  // SERVER TO CLIENT

  /** Emitted by the server when a new client joins to send session data */
  Session = 'session',
  /** Emits to all clients in a lobby when a lobby is updated (e.g. join, leave) to send updated lobby data */
  LobbyUpdated = 'lobby:updated',
  /** Emits to all players in a game when the game has started */
  GameStarted = 'game:started',
  /** Emits to all players in a game when the game state is updated */
  GameStateUpdated = 'game:stateUpdated',
  /** Emits to all players in a game when the game enters a new phase */
  GamePhaseChanged = 'game:phaseChanged',
  /** Emits to all players in a game when the game is closed */
  GameClosed = 'game:closed',

  // CLIENT TO SERVER

  /** Emitted when a client requests to create a game lobby */
  CreateLobby = 'lobby:create',
  /** Emitted when a client requests to join a game lobby */
  JoinLobby = 'lobby:join',
  /** Emitted when a client requests to leave a game lobby */
  LeaveLobby = 'lobby:leave',
  /** Emitted when a player sends a message in the lobby chat */
  SendLobbyChatMessage = 'lobby:sendChatMessage',
  /** Emitted when the lobby host changes the size of the lobby */
  SetLobbySize = 'lobby:setSize',
  /** Emitted when a lobby host starts the game */
  StartGame = 'lobby:start',
  /** Emitted when a player sends a message in the game chat */
  SendGameChatMessage = 'game:sendChatMessage',
  /** Emitted when a player chooses a player to accuse */
  SetAccusationVote = 'game:setAccusationVote',
  /** Emitted when a player decides whether to pardon or execute an accused player */
  SetJudgementVote = 'game:setJudgementVote',
  /** Emitted when a player chooses who to visit at night */
  SetNightTarget = 'game:setNightTarget',
  /** Emitted when a player updates their journal */
  SetJournal = 'game:setJournal',
}

Additionally, each event has its own payload type that is sent with the event, described in the following sections.

Server to Client Events​

The following interface (defined here) describes the payload for each event that the server can send to a client.

export interface ServerToClientEvents {
  [Events.Session]: (sessionData: { sessionId: string; userId: string }) => void
  [Events.LobbyUpdated]: (lobbyData: LobbyData) => void
  [Events.GameStarted]: (playerNumber: number, name: string, faction: Faction, role: Role) => void
  [Events.GameStateUpdated]: (gameState: GameState) => void
  [Events.GamePhaseChanged]: (newPhase: Phase) => void
  [Events.GameClosed]: () => void
}

An example of how a client would handle a Session event would be as follows:

socket.on(Events.Session, sessionData => {
  console.log('Received session data:', sessionData)
})

Client to Server Events​

The following interface (defined here) describes the payload for each event that a client can send to the server.

export interface ClientToServerEvents {
  [Events.CreateLobby]: (size?: number, callback?: ErrorCallback) => void
  [Events.JoinLobby]: (lobbyCode?: string, callback?: ErrorCallback) => void
  [Events.LeaveLobby]: (callback?: ErrorCallback) => void
  [Events.SendLobbyChatMessage]: (message: string, callback?: ErrorCallback) => void
  [Events.SetLobbySize]: (size: number, callback?: ErrorCallback) => void
  [Events.StartGame]: (callback?: ErrorCallback) => void
  [Events.SendGameChatMessage]: (message: string, callback?: ErrorCallback) => void
  [Events.SetAccusationVote]: (accusation: number | undefined, callback?: ErrorCallback) => void
  [Events.SetJudgementVote]: (choice: JudgementVote, callback?: ErrorCallback) => void
  [Events.SetNightTarget]: (target: number | undefined, callback?: ErrorCallback) => void
  [Events.SetJournal]: (journal: [string, string], callback?: ErrorCallback) => void
}

The ErrorCallback type is a function that returns whether the event was successful, in addition to any error message that may have occurred.

type ErrorCallback = (status: { success: boolean; error?: string }) => void

A client would emit a CreateLobby event as follows:

socket.emit(Events.CreateLobby, status => {
  if (status.success) {
    console.log('Lobby created successfully!')
  } else {
    console.error('Failed to create lobby:', status.error)
  }
})