Proto

Protocol Documentation

Table of Contents

• clientbound/clientbound_player.proto

  • S2CChestReference
  • S2CPlayerSwitchMode

• clientbound/clientbound_plot.proto

  • S2CCodeOperationResult

  • S2CMultiCodeOperationsResult

  • S2CPlotInfo

  • S2CPlotInfo.PlotPlayer

  • S2CPlotLineStarterUpdate

  • S2CPlotLineStarters

  • S2CPlotProfiling

  • S2CCodeOperationResult.Error

  • S2CPlotLineStarterUpdate.Action

• clientbound/clientbound_server.proto

  • S2CHandshakeResponse

  • S2CHandshakeResponse.Success

  • S2CHello

  • S2CServerBooster

  • S2CServerBooster.ActiveBooster

  • S2CHandshakeResponse.Error

• common/common_code.proto

  • ChestReference

  • ChestReference.Argument

  • ChestReference.Note

  • ChestReference.ReturnValue

  • ChestReference.ReturnValue.Simple

  • ChestReference.ReturnValue.Standard

  • ChestReference.Value

• common/common_player.proto

  • PlayerCurrency
  • PlayerCurrency.TicketBundle
  • PlayerInfo
  • PlayerPermissions

• common/common_plot.proto

  • CodeLineStarter

  • Region

  • PlotTag

• common/common_server.proto

  • ServerInfo

  • ServerInfo.DFServerType

• common/data_type.proto

  • Template

  • WorldLocation

  • LineStarterBlock

  • PlayerMode

• serverbound/serverbound_player.proto

  • C2SPlayerTeleport

• serverbound/serverbound_plot.proto

  • C2SCodeOperation
  • C2SMultiCodeOperations
  • DeleteByBlockOperation
  • DeleteByLocationOperation
  • GetByBlockOperation
  • GetByLocationOperation
  • PlaceOperation
  • ReplaceByBlockOperation
  • ReplaceByLocationOperation

• serverbound/serverbound_server.proto

  • C2SHandshakeRequest

• Scalar Value Types

Top

clientbound/clientbound_player.proto

S2CChestReference

Sent when the player opens a code chest.

Field	Type	Label	Description
reference	ChestReference		The action reference.

S2CPlayerSwitchMode

Sent when the player switches modes.

Field	Type	Label	Description
mode	PlayerMode		The mode the player is in.

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		true if the operation failed, false otherwise
template	string		The template JSON string, only if a get operation succeeded.

S2CMultiCodeOperationsResult

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

Field	Type	Label	Description
results	S2CCodeOperationResult	repeated	The results of all operations requested.

S2CPlotInfo

Sent when the player joins a plot.

Field	Type	Label	Description
id	int32		The identifier of the plot.
name	string		The name of the plot as a serialized component in JSON format.
owner_name	string		The name of the owner of the plot.
owner_uuid	string		The UUID of the owner of the plot (36 characters including dashes).
plot_size	int32		The size of the plot (1 = Basic, 2 = Large, 3 = Massive, 4 = Mega).
build_region	Region		The build region of the plot.
code_region	Region		The code region of the plot.
spawn_pos	Region		The spawn location of the plot.
is_owner	bool		Whether the player is the owner of the plot.
is_developer	bool		Whether the player has developer permissions on the plot, is an administrator, or is the support member in a session.
is_builder	bool		Whether the player has builder permissions on the plot, is an administrator, or is the support member in a session.
tags	PlotTag	repeated	The tags of this plot (e.g. "adventure", "combat", ...).
handle	string		The handle of the plot, or empty if none is set.
players	S2CPlotInfo.PlotPlayer	repeated	The players currently on the plot.

S2CPlotInfo.PlotPlayer

Represents a player in a plot.

Field	Type	Label	Description
user_name	string		The name of the player.
user_uuid	string		The UUID of the player (36 characters including dashes).
is_owner	bool		Whether the player is the owner of the plot.
is_developer	bool		Whether the player has developer permissions on the plot.
is_builder	bool		Whether the player has builder permissions on the plot.
mode	PlayerMode		The mode the player is in.

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		The line starter that was added or removed.
action	S2CPlotLineStarterUpdate.Action		The action performed.

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	The line starters on the plot.

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		The CPU usage of the plot in percentage (0 to 100).

S2CCodeOperationResult.Error

Represents an error that occurred while performing a code operation.

Name	Number	Description
NONE	0	No error, the operation succeeded.
NO_PERMISSION	1	The player does not have developer permissions on the plot.
NO_LOCATION	2	No location was provided for an operation that requires one.
INVALID_LOCATION	3	The provided location is not within the code region of the plot or is an invalid code block position.
NO_ACTION	4	No action was provided for an operation that requires one.
ACTION_NOT_FOUND	5	The provided action or line starter was not found on the plot.
NO_LOCATION_OR_TEMPLATE	6	Either a location or a template were not provided for an operation that requires both.
INVALID_LOCATION_OR_TEMPLATE	7	The provided location is invalid or the provided template is not a valid code template.
TEMPLATE_NOT_FIT	8	The provided template does not fit in the code region at the provided location.
INVALID_TEMPLATE	10	The provided template is not a valid code template.
INTERNAL_ERROR	9	An internal error occurred while performing the operation.
NO_OPERATION	11	No operation was provided.

S2CPlotLineStarterUpdate.Action

Represents an action performed on a line starter.

Name	Number	Description
ADD	0	A line starter was added.
CHANGE	1	A line starter was changed.
REMOVE	2	A line starter was removed.

Top

clientbound/clientbound_server.proto

S2CHandshakeResponse

Sent as a response to a C2SHandshakeRequest message.

Field	Type	Label	Description
error	S2CHandshakeResponse.Error		The error that occurred, if any.
success	S2CHandshakeResponse.Success		The server and player info, if the connection was successful.

S2CHandshakeResponse.Success

Field	Type	Label	Description
server_info	ServerInfo		The server info.
player_info	PlayerInfo		The player's info.

S2CHello

Sent by the server when the player connects to it, respond with C2SHandshakeRequest.

S2CServerBooster

Sent when the player joins the server.

Field	Type	Label	Description
is_active	bool		Whether a booster is currently active.
active_booster	S2CServerBooster.ActiveBooster	optional	The active booster, if any.

S2CServerBooster.ActiveBooster

Represents an active booster.

Field	Type	Label	Description
tipped	bool		Whether the booster was tipped by the player.
multiplier	int32		The multiplier of the booster (e.g. 2 for 2x).
time_remaining	int64		The time remaining of the booster in milliseconds.
user_name	string		The name of the player who activated the booster.
user_uuid	string		The UUID of the player who activated the booster (36 characters including dashes).

S2CHandshakeResponse.Error

Name	Number	Description
NONE	0	No error, the connection was successful.
INVALID_PROTOCOL	1	The given protocol version is invalid.
INCOMPATIBLE_PROTOCOL	2	The given protocol version is incompatible with the server.
ALREADY_CONNECTED	3	The player is already connected.

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.

Field	Type	Label	Description
material	string		The material of the action icon as a namespaced key (e.g. "minecraft:book").
name	string		The name of the action as a serialized component in JSON format.
description	string	repeated	The description of the action icon as a list of serialized components in JSON format.
additional_info	ChestReference.Note	repeated	The additional info field of the action icon as a list of serialized components in JSON format.
tags	int32	optional	The amount of tags the action has, only for actions.
arguments	ChestReference.Argument	repeated	The arguments for the chest, only for actions.
return_values	ChestReference.ReturnValue	repeated	The return values of the action, only for actions.
cancellable	bool	optional	Whether the action is cancellable, only for events.
cancelled_automatically	bool	optional	Whether the event is cancelled by default, only for events.

ChestReference.Argument

Represents an argument for the chest.

Field	Type	Label	Description
type	ChestReference.Value		The type of the argument.
plural	bool		Whether the argument is plural.
optional	bool		Whether the argument is optional.
description	string	repeated	The description of the argument as a list of serialized components in JSON format.
notes	ChestReference.Note	repeated	Notes for the argument.

ChestReference.Note

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

Field	Type	Label	Description
note	string	repeated	The note as a list of serialized components in JSON format.

ChestReference.ReturnValue

Represents a return value of an action.

Field	Type	Label	Description
standard_value	ChestReference.ReturnValue.Standard		A standard return value.
simple_value	ChestReference.ReturnValue.Simple		A simple return value.

ChestReference.ReturnValue.Simple

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

Field	Type	Label	Description
text	string		The text of the return value as a serialized component in JSON format.

ChestReference.ReturnValue.Standard

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

Field	Type	Label	Description
value_type	ChestReference.Value		The value type of the return value.
descriptions	string	repeated	The description of the return value as a list of serialized components in JSON format.

ChestReference.Value

Represents a value type.

Name	Number	Description
ANY_TYPE	0	Any value.
VARIABLE	1	Variable.
NUMBER	2	Number.
TEXT	3	String.
COMPONENT	4	Styled text.
LOCATION	5	Location.
VECTOR	6	Vector.
LIST	7	List.
DICT	8	Dictionary.
POTION	9	Potion effect.
PARTICLE	10	Particle effect.
SOUND	11	Sound.
SPAWN_EGG	12	Spawn egg.
PROJECTILE	13	Projectile.
VEHICLE	14	Vehicle.
ENTITY_TYPE	15	Entity type.
BLOCK	16	Block.
BLOCK_TAG	17	Block tag.
ITEM	18	Item.
BYTE	19	Byte.
NONE	20	None.

Top

common/common_player.proto

PlayerCurrency

Represents the player's currency information.

Field	Type	Label	Description
tokens	int32		The amount of tokens the player has.
tickets	int32		The amount of tickets the player has.
ticket_bundles	PlayerCurrency.TicketBundle	repeated	The unclaimed ticket bundles the player has.
sparks	int32		The amount of sparks the player has.

PlayerCurrency.TicketBundle

Represents an unclaimed ticket bundle.

Field	Type	Label	Description
event_name	string		The name of the event the bundle is from.
prize_name	string		The name of the prize the bundle is for.
ticket_amount	int32		The amount of tickets in the bundle.

PlayerInfo

Represents general information about the player.

Field	Type	Label	Description
currency	PlayerCurrency		The player's currency information.
permissions	PlayerPermissions		The player's permissions.

PlayerPermissions

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

Field	Type	Label	Description
donor	int32		The donor rank level of the player. (Noble, Emperor, Mythic, Overlord)
vip	int32		The VIP rank level of the player. (VIP)
qa	int32		The QA rank level of the player. (QA)
youtuber	int32		The YouTube rank level of the player. (YouTube)
support	int32		The support rank level of the player. (JrHelper, Helper, SrHelper)
moderation	int32		The mod rank level of the player. (JrMod, Mod, SrMod)
admin	int32		The admin rank level of the player. (Dev, Admin, Owner)

Top

common/common_plot.proto

CodeLineStarter

Represents a code line starter in the plot.

Field	Type	Label	Description
location	WorldLocation		The location of the line starter.
chest	ChestReference	optional	The action reference.

Region

Represents a cuboid region in the world.

Field	Type	Label	Description
min	WorldLocation		The minimum corner of the region.
max	WorldLocation		The maximum corner of the region.

PlotTag

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

Name	Number	Description
ARCADE	0	One or multiple fast and fun minigames!
VERSUS	1	Compete with other players!
COMBAT	2	Fight your enemies!
PARKOUR	3	Prove your platforming skills!
ADVENTURE	4	Games with many places to explore!
ROLEPLAY	5	Become part of an immersive setting or story!
STRATEGY	6	Plan your next moves to be victorious!
PUZZLE	7	Put your mind to the test!
TRIVIA	8	Try to guess the correct answers!
RESOURCES	9	Games where you collect resources to advance!
ELIMINATION	10	Be the last one standing!
CREATION	11	Games in which you can express your creativity!
MISCELLANEOUS	12	Plots that don't really fit the other categories!

Top

common/common_server.proto

ServerInfo

Represents information about the server.

Field	Type	Label	Description
protocol_version	string		The version of the protocol in semver format, major versions are not guaranteed to be compatible.
bungee_name	string		The identifier of the server.
patch_version	string		The patch version of the server.
server_type	ServerInfo.DFServerType		The type of the server.

ServerInfo.DFServerType

Represents a server type.

Name	Number	Description
MAIN	0	Main nodes.
BETA	1	Node beta.
DEV	2	Dev nodes.
PUBLIC_TEST	3	Unused.
PUBLIC_EVENT	4	Event node.
LOCAL_DEV	5	Local dev servers.
PRIVATE	6	Private nodes.

Top

common/data_type.proto

Template

Represents a code template.

Field	Type	Label	Description
json	string		The template JSON string.
data	string		The template code data.

WorldLocation

Represents a location.

Field	Type	Label	Description
x	double		The X coordinate.
y	double		The Y coordinate.
z	double		The Z coordinate.
pitch	float		The pitch.
yaw	float		The yaw.

LineStarterBlock

Represents a line starter type.

Name	Number	Description
EVENT	0	A Player / Entity Event.
FUNCTION	2	A Function.
PROCESS	3	A Process.

PlayerMode

Represents a player's mode.

Name	Number	Description
PLAY	0	Play mode.
BUILD	1	Build mode.
DEV	2	Dev (code) mode.
CODE_STALK	3	Code spectate (stalk) mode.
VERIFY	4	Account check (verify) mode.
VANISH	5	Mod vanish mode.
IDLE	6	Spawn (idle) mode.

Top

serverbound/serverbound_player.proto

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	WorldLocation		The location to teleport to.

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		The operation to get the template for the code block at the given location.
get_by_block	GetByBlockOperation		The operation to get the template for the code block with the given line starter type and action name.
place	PlaceOperation		The operation to place a template at the given location.
delete_by_location	DeleteByLocationOperation		The operation to delete the code block at the given location.
delete_by_block	DeleteByBlockOperation		The operation to delete the code block with the given line starter type and action name.
replace_by_location	ReplaceByLocationOperation		The operation to replace the code block at the given location with the given template.
replace_by_block	ReplaceByBlockOperation		The operation to replace the code block with the given line starter type and action name with the given template.

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	The operations to perform.

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		The type of line starter of the code block to delete.
action	string		The sign action name of the code block to delete.

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	WorldLocation		The location of the code block to delete.

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		The type of line starter of the code block to get the template for.
action	string		The sign action name of the code block to get the template for.

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	WorldLocation		The location of the code block to get the template for.

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	WorldLocation		The location to place the template at.
template	Template		The template to place.

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		The type of line starter of the code block to replace.
action	string		The sign action name of the code block to replace.
template	Template		The template to replace the code block with.

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	WorldLocation		The location of the code block to replace.
template	Template		The template to replace the code block with.

Top

serverbound/serverbound_server.proto

C2SHandshakeRequest

Notifies the server you are interested in receiving ModAPI messages. 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		The version of the protocol the client is using.

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)