Proto

Protocol Documentation

clientbound/clientbound_player.proto
- S2CChestReference
- S2CPlayerSwitchMode
clientbound/clientbound_plot.proto
clientbound/clientbound_server.proto
common/common_code.proto
common/common_player.proto
common/common_plot.proto
common/common_server.proto
- ServerInfo
- ServerInfo.DFServerType
common/data_type.proto
serverbound/serverbound_player.proto
- C2SPlayerMode
- C2SPlayerTeleport
serverbound/serverbound_plot.proto
serverbound/serverbound_server.proto
- C2SHandshakeRequest
Scalar Value Types

clientbound/clientbound_player.proto

S2CChestReference

Sent when the player opens a code chest.

Field	Type	Label	Description
reference	ChestReference

S2CPlayerSwitchMode

Sent when the player switches modes.

Field	Type	Label	Description
mode	PlayerMode

Top

clientbound/clientbound_plot.proto

S2CCodeOperationResult

Sent as a response to a C2SCodeOperation message, error is true if the operation failed (see each operation for details), template is not empty only if a get operation succeeded.

Field	Type	Label	Description
error	S2CCodeOperationResult.Error
template	string

S2CMultiCodeOperationsResult

Sent as a response to a C2SMultiCodeOperations message, contains the results of all operations requested.

Field	Type	Label	Description
results	S2CCodeOperationResult	repeated

S2CPlotInfo

Sent when the player joins a plot. The plot name is a serialized Minecraft component.

Field	Type	Label
id	int32
name	string
owner_name	string
owner_uuid	string
plot_size	int32
build_region	Region
code_region	Region
spawn_pos	APILocation
is_owner	bool
is_developer	bool
is_builder	bool
tags	PlotTag	repeated
handle	string
players	S2CPlotInfo.PlotPlayer	repeated

S2CPlotInfo.PlotPlayer

Represents a player in a plot.

Field	Type	Label	Description
user_name	string
user_uuid	string
is_owner	bool
is_developer	bool
is_builder	bool
mode	PlayerMode

S2CPlotLineStarterUpdate

Sent when a line starter is added or removed from the plot, requires the player to have developer permissions on the plot.

Field	Type	Label	Description
line_starter	CodeLineStarter
action	S2CPlotLineStarterUpdate.Action

S2CPlotLineStarters

Sent when the player joins a plot, requires the player to have developer permissions on the plot.

Field	Type	Label	Description
line_starter	CodeLineStarter	repeated

S2CPlotProfiling

Sent when the plot finishes a lag measurement, requires the player to have developer permissions on the plot, and be profiling the plot.

Field	Type	Label	Description
cpu_usage	int32

S2CCodeOperationResult.Error

Represents an error that occurred while performing a code operation.

Name	Number	Description
NONE	0
NO_PERMISSION	1
NO_LOCATION	2
INVALID_LOCATION	3
NO_ACTION	4
ACTION_NOT_FOUND	5
NO_LOCATION_OR_TEMPLATE	6
INVALID_LOCATION_OR_TEMPLATE	7
TEMPLATE_NOT_FIT	8
INVALID_TEMPLATE	10
INTERNAL_ERROR	9
NO_OPERATION	11

S2CPlotLineStarterUpdate.Action

Represents an action performed on a line starter.

Name	Number	Description
ADD	0
CHANGE	1
REMOVE	2

Top

clientbound/clientbound_server.proto

S2CHandshakeResponse

Sent as a response to a C2SHandshakeRequest message.

Field	Type	Label	Description
error	S2CHandshakeResponse.Error
success	S2CHandshakeResponse.Success

S2CHandshakeResponse.Success

Contains connection metadata after a successful handshake.

Field	Type	Label	Description
server_info	ServerInfo

S2CPlayerInfo

Sent after the player joins the server with their currency and permission information.

Field	Type	Label	Description
currency	PlayerCurrency
permissions	PlayerPermissions

S2CServerBooster

Sent when the player joins the server.

Field	Type	Label	Description
is_active	bool
active_booster	S2CServerBooster.ActiveBooster	optional

S2CServerBooster.ActiveBooster

Represents an active booster.

Field	Type	Label	Description
tipped	bool
multiplier	int32
time_remaining	int64
user_name	string
user_uuid	string

S2CHandshakeResponse.Error

Name	Number	Description
NONE	0
INVALID_PROTOCOL	1
INCOMPATIBLE_PROTOCOL	2
ALREADY_CONNECTED	3
NOT_APPLICABLE	4

Top

common/common_code.proto

ChestReference

Represents a reference to an action and its arguments, sent when the player opens a code chest and bundled in other messages. Display text is serialized as Minecraft components.

Field	Type	Label
material	string
name	string
description	string	repeated
additional_info	ChestReference.Note	repeated
tags	int32	optional
arguments	ChestReference.Argument	repeated
return_values	ChestReference.ReturnValue	repeated
cancellable	bool	optional
cancelled_automatically	bool	optional

ChestReference.Argument

Represents an argument for the chest.

Field	Type	Label
type	ChestReference.Value
plural	bool
optional	bool
description	string	repeated
notes	ChestReference.Note	repeated

ChestReference.Note

Represents a note in the notes field of an action icon.

Field	Type	Label	Description
note	string	repeated

ChestReference.ReturnValue

Represents a return value of an action.

Field	Type	Label	Description
standard_value	ChestReference.ReturnValue.Standard
simple_value	ChestReference.ReturnValue.Simple

ChestReference.ReturnValue.Simple

A simple return value, which only contains a text field.

Field	Type	Label	Description
text	string

ChestReference.ReturnValue.Standard

A standard return value, which contains the value and descriptions fields.

Field	Type	Label	Description
value_type	ChestReference.Value
descriptions	string	repeated

ChestReference.Value

Represents a value type.

Name	Number	Description
ANY_TYPE	0
VARIABLE	1
NUMBER	2
TEXT	3
COMPONENT	4
LOCATION	5
VECTOR	6
LIST	7
DICT	8
POTION	9
PARTICLE	10
SOUND	11
SPAWN_EGG	12
PROJECTILE	13
VEHICLE	14
ENTITY_TYPE	15
BLOCK	16
BLOCK_TAG	17
ITEM	18
BYTE	19
NONE	20

Top

common/common_player.proto

PlayerCurrency

Represents the player's currency information. Ticket bundle names are serialized Minecraft components.

Field	Type	Label
tokens	int32
tickets	int32
ticket_bundles	PlayerCurrency.TicketBundle	repeated
sparks	int32

PlayerCurrency.TicketBundle

Represents an unclaimed ticket bundle.

Field	Type	Label	Description
event_name	string
prize_name	string
ticket_amount	int32

PlayerPermissions

Represents the player's permissions, admins will have all permissions set to their highest level.

Field	Type	Label	Description
donor	int32
vip	int32
qa	int32
youtuber	int32
support	int32
moderation	int32
admin	int32

Top

common/common_plot.proto

CodeLineStarter

Represents a code line starter in the plot.

Field	Type	Label	Description
location	APILocation
chest	ChestReference	optional

Region

Represents a cuboid region in the world.

Field	Type	Label	Description
min	APILocation
max	APILocation

PlotTag

Represents a tag, also known as a category, a plot can have.

Name	Number	Description
ARCADE	0
VERSUS	1
COMBAT	2
PARKOUR	3
ADVENTURE	4
ROLEPLAY	5
STRATEGY	6
PUZZLE	7
TRIVIA	8
RESOURCES	9
ELIMINATION	10
CREATION	11
MISCELLANEOUS	12

Top

common/common_server.proto

ServerInfo

Represents information about the server.

Field	Type	Label	Description
protocol_version	string
bungee_name	string
patch_version	string
server_type	ServerInfo.DFServerType

ServerInfo.DFServerType

Represents a server type.

Name	Number	Description
MAIN	0
BETA	1
DEV	2
PUBLIC_TEST	3
PUBLIC_EVENT	4
LOCAL_DEV	5
PRIVATE	6

Top

common/data_type.proto

APILocation

Represents a location.

Field	Type	Label	Description
x	double
y	double
z	double
pitch	float
yaw	float

Template

Represents a code template.

Field	Type	Label	Description
json	string
data	string

LineStarterBlock

Represents a line starter type.

Name	Number	Description
EVENT	0
FUNCTION	2
PROCESS	3

PlayerMode

Represents a player's mode.

Name	Number	Description
PLAY	0
BUILD	1
DEV	2
CODE_STALK	3
VERIFY	4
VANISH	5
IDLE	6

Top

serverbound/serverbound_player.proto

C2SPlayerMode

Switches a player's mode, the player must have the permission to do so.

Field	Type	Label	Description
mode	PlayerMode

C2SPlayerTeleport

Teleports the player to the specified location, the player must be building or coding, and the location will be clamped to the plot boundaries.

Field	Type	Label	Description
location	APILocation

Top

serverbound/serverbound_plot.proto

C2SCodeOperation

Requests to execute a code operation. An S2CCodeOperationResult message will be sent as a response, the relevant field will be set depending on the operation requested.

Field	Type	Label	Description
get_by_location	GetByLocationOperation
get_by_block	GetByBlockOperation
place	PlaceOperation
delete_by_location	DeleteByLocationOperation
delete_by_block	DeleteByBlockOperation
replace_by_location	ReplaceByLocationOperation
replace_by_block	ReplaceByBlockOperation

C2SMultiCodeOperations

Requests to execute multiple code operations in one message. An S2CMultiCodeOperationResult message will be sent as a response, containing the results of all operations requested.

Field	Type	Label	Description
operations	C2SCodeOperation	repeated

DeleteByBlockOperation

Requests to delete the code block with the given line starter type and action name, requires the player to have developer permissions on the plot, and that the code block exists.

Field	Type	Label	Description
type	LineStarterBlock
action	string

DeleteByLocationOperation

Requests to delete the code block at the given location, requires the player to have developer permissions on the plot, and the location being a valid line starter.

Field	Type	Label	Description
location	APILocation

GetByBlockOperation

Requests to get the template for the given line starter type and action name, requires the player to have developer permissions on the plot, and that the code block exists.

Field	Type	Label	Description
type	LineStarterBlock
action	string

GetByLocationOperation

Requests to get the template for the code block at the given location, if the location is a line starter, the entire line will be returned, otherwise only the code block will be returned, requires the player to have developer permissions on the plot, and the location being a valid line starter.

Field	Type	Label	Description
location	APILocation

PlaceOperation

Requests to place a template at the given location, requires the player to have developer permissions on the plot, the location being a valid line starter, and that the template will not override any blocks nor exit the plot bounds.

Field	Type	Label	Description
location	APILocation
template	Template

ReplaceByBlockOperation

Requests to replace the code block with the given line starter type and action name with the given template, requires the player to have developer permissions on the plot, and that the code block exists, and that the template will not override any blocks nor exit the plot bounds (except for the blocks being replaced).

Field	Type	Label	Description
type	LineStarterBlock
action	string
template	Template

ReplaceByLocationOperation

Requests to replace the code block at the given location with the given template, requires the player to have developer permissions on the plot, the location being a valid line starter, and that the template will not override any blocks nor exit the plot bounds (except for the blocks being replaced).

Field	Type	Label	Description
location	APILocation
template	Template

Top

serverbound/serverbound_server.proto

C2SHandshakeRequest

Notifies the server you are interested in receiving ModAPI messages. The client sends this during the configuration stage. This must be sent before any ModAPI messages are sent by the client. A S2CHandshakeResponse message will be sent in response.

Field	Type	Label	Description
protocol_version	string

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)

Warning

This repository is a work in progress, packets may be changed, added, and removed at any time, and this repository may go unmaintained for long periods of time. No promises are made.

Uh oh!