Protocol Documentation

Table of Contents

• minekube/gate/v1/gate_service.proto

  • ConnectPlayerRequest

  • ConnectPlayerResponse

  • DisconnectPlayerRequest

  • DisconnectPlayerResponse

  • GetPlayerRequest

  • GetPlayerResponse

  • ListPlayersRequest

  • ListPlayersResponse

  • ListServersRequest

  • ListServersResponse

  • Player

  • RegisterServerRequest

  • RegisterServerResponse

  • RequestCookieRequest

  • RequestCookieResponse

  • Server

  • StoreCookieRequest

  • StoreCookieResponse

  • UnregisterServerRequest

  • UnregisterServerResponse

  • GateService

• Scalar Value Types

Top

minekube/gate/v1/gate_service.proto

ConnectPlayerRequest

ConnectPlayerRequest is the request for ConnectPlayer method.

Field	Type	Label	Description
player	string		The player's username or ID to connect
server	string		The target server name to connect the player to

ConnectPlayerResponse

ConnectPlayerResponse is the response for ConnectPlayer method.

DisconnectPlayerRequest

DisconnectPlayerRequest is the request for DisconnectPlayer method.

Field	Type	Label	Description
player	string		The player's username or ID to disconnect
reason	string		The reason displayed to the player when they are disconnected.

Formats:

• {"text":"Hello, world!"} - JSON text component. See https://wiki.vg/Text_formatting for details.

• §aHello,\n§bworld! - Simple color codes. See https://wiki.vg/Text_formatting#Colors

Optional, if empty no reason will be shown. |

DisconnectPlayerResponse

DisconnectPlayerResponse is the response for DisconnectPlayer method.

GetPlayerRequest

GetPlayerRequest is the request for GetPlayer method.

Field	Type	Label	Description
id	string		Gets the player by their Minecraft UUID. Optional, if not set the username will be used. If both id and username are set, the id will be used. Must be a valid Minecraft UUID format (e.g. "550e8400-e29b-41d4-a716-446655440000")
username	string		Gets the player by their username. Optional, if not set the id will be used. Case-sensitive.

GetPlayerResponse

GetPlayerResponse is the response for GetPlayer method.

Field	Type	Label	Description
player	Player		The player matching the request criteria

ListPlayersRequest

ListPlayersRequest is the request for ListPlayers method.

Field	Type	Label	Description
servers	string	repeated	Filter players by server names. Optional, if empty all online players are returned. If specified, only returns players on the listed servers.

ListPlayersResponse

ListPlayersResponse is the response for ListPlayers method.

Field	Type	Label	Description
players	Player	repeated

ListServersRequest

ListServersRequest is the request for ListServers method.

ListServersResponse

ListServersResponse is the response for ListServers method.

Field	Type	Label	Description
servers	Server	repeated

Player

Player represents an online player on the proxy.

Field	Type	Label	Description
id	string		The player's Minecraft UUID
username	string		The player's username

RegisterServerRequest

RegisterServerRequest is the request for RegisterServer method.

Field	Type	Label	Description
name	string		The unique name of the server
address	string		The network address of the server (e.g. "localhost:25565")

RegisterServerResponse

RegisterServerResponse is the response for RegisterServer method.

RequestCookieRequest

RequestCookieRequest is the request for RequestCookie method.

Field	Type	Label	Description
player	string		The player's username or ID
key	string		The key of the cookie in format namespace:key

RequestCookieResponse

RequestCookieResponse is the response for RequestCookie method.

Field	Type	Label	Description
payload	bytes		The payload of the cookie. May be empty if the cookie is not found.

Server

Server represents a backend server where Gate can connect players to.

Field	Type	Label	Description
name	string		The unique name of the server.
address	string		The network address of the server.
players	int32		The number of players currently on the server.

StoreCookieRequest

StoreCookieRequest is the request for StoreCookie method.

Field	Type	Label	Description
player	string		The player's username or ID
key	string		The key of the cookie in format namespace:key
payload	bytes		The payload to store. Passing an empty payload will remove the cookie.

StoreCookieResponse

StoreCookieResponse is the response for StoreCookie method.

UnregisterServerRequest

UnregisterServerRequest is the request for UnregisterServer method.

Field	Type	Label	Description
name	string		The name of the server. Optional, if not set, the address will be used to match servers.
address	string		The address of the server. Optional, if not set, the name will be used to match servers. If both name and address are set, only the server that matches both properties exactly will be unregistered. If only the address is set, the first server matching that address will be unregistered.

UnregisterServerResponse

UnregisterServerResponse is the response for UnregisterServer method.

GateService

GateService is the service API for managing a Gate proxy instance. It provides methods for managing players and servers. All methods follow standard gRPC error codes and include detailed error messages.

Method Name	Request Type	Response Type	Description
GetPlayer	GetPlayerRequest	GetPlayerResponse	GetPlayer returns the player by the given id or username. Returns NOT_FOUND if the player is not online. Returns INVALID_ARGUMENT if neither id nor username is provided, or if the id format is invalid.
ListPlayers	ListPlayersRequest	ListPlayersResponse	ListPlayers returns all online players. If servers are specified in the request, only returns players on those servers.
ListServers	ListServersRequest	ListServersResponse	ListServers returns all registered servers.
RegisterServer	RegisterServerRequest	RegisterServerResponse	RegisterServer adds a server to the proxy. Returns ALREADY_EXISTS if a server with the same name is already registered. Returns INVALID_ARGUMENT if the server name or address is invalid.
UnregisterServer	UnregisterServerRequest	UnregisterServerResponse	UnregisterServer removes a server from the proxy. Returns NOT_FOUND if no matching server is found. Returns INVALID_ARGUMENT if neither name nor address is provided.
ConnectPlayer	ConnectPlayerRequest	ConnectPlayerResponse	ConnectPlayer connects a player to a specified server. Returns NOT_FOUND if either the player or target server doesn't exist. Returns FAILED_PRECONDITION if the connection attempt fails.
DisconnectPlayer	DisconnectPlayerRequest	DisconnectPlayerResponse	DisconnectPlayer disconnects a player from the proxy. Returns NOT_FOUND if the player doesn't exist. Returns INVALID_ARGUMENT if the reason text is malformed.
StoreCookie	StoreCookieRequest	StoreCookieResponse	StoreCookie stores a cookie on a player's client. Returns NOT_FOUND if the player doesn't exist. Passing an empty payload will remove the cookie.
RequestCookie	RequestCookieRequest	RequestCookieResponse	RequestCookie requests a cookie from a player's client. The payload in RequestCookieResponse may be empty if the cookie is not found.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)