Skip to content

Frontend API Documentation

Jump to bottom
Logan McNaughton edited this page Aug 2, 2025 · 37 revisions

Lobby

The mupen64plus-core API only handles communication during gameplay. gopher64-netplay-server implements a lobby API for organizing and starting games.

The lobby server communicates with the frontend using WebSockets. The data is JSON formatted. The JSON key type allows the client and server to determine what kind of message is being sent/received.

Messages sent by the frontend

type: request_create_room

The frontend sends this message to attempt to create a new room. The client_sha will be used to ensure that all players have the same version of the emulator (to prevent desyncs). When a player joins, their client_sha needs to match the client_sha in the request_create_room message, or they will not be allowed to join.

The MD5 is the MD5 of the ROM. netplay_version needs to match the netplay_version of the server. emulator is the name of the emulator, gopher64-netplay-server can host games from multiple emulators at the same time, and this field is used to filter the games so only games related to this emulator are presented to the user.

game_name is the name of the ROM. room_name is an arbitrary room name chosen by the user, same for player_name.

This is just a request to create a room. The server will respond with reply_create_room. If it is unsuccessful, the accept field in the reply will be non-zero, and the message will say what error occurred. If it is successful, accept will be 0.

features is a JSON object with key/value pairs specifying features specific to the room. For example, if the creator is using GLideN64 you might want to populate features with {"gfx": "gliden64"}, since other players using different video plugins will likely cause a desync.

buffer_target is an int that represents the local input buffer target for each player. Defaults to 2 if not specified.

auth and authTime is required if the server is running with --enable-auth. See Client Authentication.

fields:

  • room (object)
    • room_name (string)
    • password (string) (optional)
    • MD5 (string)
    • game_name (string)
    • features (object) (optional)
    • buffer_target (int) (optional)
  • player_name (string)
  • client_sha (string)
  • netplay_version (int)
  • emulator (string)
  • authTime (string) (optional)
  • auth (string) (optional)

type: request_get_rooms

netplay_version needs to match the netplay_version of the server.

auth and authTime is required if the server is running with --enable-auth. See Client Authentication.

The server will respond with reply_get_rooms.

fields:

  • netplay_version (int)
  • emulator (string)
  • authTime (string) (optional)
  • auth (string) (optional)

type: request_join_room

This is a request to join a room. The client_sha needs to match the client_sha of the person that created the room. The port would have been retrieved by a previous call to request_get_rooms.

The server will respond with reply_join_room.

fields:

  • player_name (string)
  • room (object)
    • password (string) (optional)
    • MD5 (string)
    • port (int)
  • client_sha (string)

type: request_players

The server will respond with reply_players when this is sent. The port would have been retrieved in a previous call.

fields:

  • room (object)
    • port (int)

type: request_motd

The server will reply with reply_motd.

type: request_begin_game

The frontend must ensure that only 1 player can send this message (that only player 1 can start the game). The server will reply with reply_begin_game.

fields:

  • room (object)
    • port (int)

type: request_chat_message

Sent when a player wants to send a chat message to the group. The server will send a reply_chat_message message to all users, including the user that sent this.

fields:

  • player_name (string)
  • message (string)
  • room (object)
    • port (int)

type: request_edit_room

Only player 1 can send this request. Name and port must match the existing room. MD5, game_name, and features can be new values.

fields:

  • room (object)
    • name (string)
    • port (int)
    • MD5 (string)
    • game_name (string)
    • features (object) (optional)

type: request_ping

Used to request the ping in milliseconds between the player and the server.

fields:

None

Messages sent by the netplay server

type: reply_get_rooms

Sent in reply to a request_get_rooms message. The frontend will receive one message, with a list of rooms. The message will contain the MD5 of the ROM. protected will be either true or false, indicating whether the room is password protected.

features is a JSON object with key/value pairs specifying features specific to the room. For example, if the creator is using GLideN64, features might be populated with {"gfx": "gliden64"}.

fields:

  • rooms ([] of "room" objects)
    • room (object)
      • protected (bool)
      • room_name (string)
      • MD5 (string)
      • port (int)
      • game_name (string)
      • features (object)
  • accept (int) (0 means no error occurred)
  • message (string) (only populated if accept is non-zero)

type: reply_create_room

Sent in reply to request_create_room if the creation was successful.

fields:

  • room (object)
    • protected (bool)
    • room_name (string)
    • MD5 (string)
    • port (int)
    • game_name (string)
    • features (object)
  • player_name (string)
  • accept (int) (0 means creation was successful)
  • message (string) (only populated if accept is non-zero)

type: reply_join_room

Sent in reply to request_join_room. An accept value of 0 means that the request to join the room was successful. Any other reply is an error, and the join failed. If the join failed, the message field will say why.

fields:

  • room (object)
    • protected (bool)
    • room_name (string)
    • MD5 (string)
    • port (int)
    • game_name (string)
    • features (object)
  • player_name (string)
  • accept (int) (0 means join was successful)
  • message (string) (only populated if accept is non-zero)

type: reply_players

Sent in reply to request_players. Also sent when someone leaves the room. It will be a list with 4 elements, containing the names of each player.

fields:

  • player_names ([]string, 4 elements)

type: reply_chat_message

Sent to all players when someone sends a request_chat_message

fields:

  • message (string)

type: reply_begin_game

Sent to all players in response to request_begin_game. This is the signal that all players should start the emulator core.

  • accept (int) (0 means game can start)
  • message (string) (only populated if accept is non-zero)

type: reply_motd

Sent in response to request_motd. The MOTD message is determined by the server and should be displayed for all players.

fields:

  • message (string)

type: reply_edit_room

Sent to all players in response to request_edit_room.

  • room (object)
    • protected (bool)
    • room_name (string)
    • MD5 (string)
    • port (int)
    • game_name (string)
    • features (object)
  • accept (int) (0 means no error)
  • message (string) (only populated if accept is non-zero)

type: reply_ping

Sent in response to request_ping. message is the ping in milliseconds.

  • accept (int) (0 means no error)
  • message (string)

Gameplay

During gameplay, the netplay server uses the mupen64plus-core API, documented here: https://github.com/mupen64plus/mupen64plus-core/blob/master/doc/emuwiki-api-doc/Mupen64Plus-v2.0-Netplay-API.mediawiki

Clone this wiki locally