Skip to content

Proto

Jump to bottom
RedVortexDev edited this page Aug 21, 2026 · 30 revisions

Protocol Documentation

Table of Contents

Top

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 Description
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 Description
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 Description
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 Description
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

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.

Clone this wiki locally