Skip to content

Proto

Jump to bottom
RedVortexDev edited this page Sep 25, 2025 · 27 revisions

Protocol Documentation

Table of Contents

Top

clientbound_player.proto

S2CChestReference

Sent when the player opens a code chest.

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 S2CChestReference.Note repeated The additional info field of the action icon as a list of serialized components in JSON format.
tags int32 The amount of tags the action has.
arguments S2CChestReference.Argument repeated The arguments for the chest.
return_values S2CChestReference.ReturnValue repeated The return values of the action.

S2CChestReference.Argument

Represents an argument for the chest.

Field Type Label Description
type S2CChestReference.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 S2CChestReference.Note repeated Notes for the argument.

S2CChestReference.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.

S2CChestReference.ReturnValue

Represents a return value of an action.

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

S2CChestReference.ReturnValue.Simple

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

Field Type Label Description
text string

S2CChestReference.ReturnValue.Standard

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

Field Type Label Description
value_type S2CChestReference.Value
descriptions string repeated

S2CPlayerCurrency

Sent when the player joins the server.

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

S2CPlayerCurrency.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.

S2CPlayerPermissions

Sent when the player joins the server, 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)

S2CPlayerSwitchMode

Sent when the player switches modes.

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

S2CChestReference.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

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 bool 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).
plot_min_x int32 The minimum X coordinate of the plot.
plot_min_z int32 The minimum Z coordinate of the plot.
spawn_pos_x double The spawn X coordinate of the plot.
spawn_pos_y double The spawn Y coordinate of the plot.
spawn_pos_z double The spawn Z coordinate 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 S2CPlotInfo.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.

S2CPlotLineStarters

Sent when the player joins a plot or when the line starters change, requires the player to have developer permissions on the plot.

Field Type Label Description
line_starter S2CPlotLineStarters.CodeLineStarter repeated

S2CPlotLineStarters.CodeLineStarter

Field Type Label Description
location Location
chest S2CChestReference optional

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).

S2CPlotInfo.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

clientbound_server.proto

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).

S2CServerInfo

Sent when the player joins 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 S2CServerInfo.DFServerType The type of the server.

S2CServerInfo.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

data_type.proto

Location

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.

Template

Represents a code template.

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

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. Warning: IDs for vanish, idle, and verify will change in an upcoming refactor, the IDs here post-refactor. I hope this only releases after the refactor.

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

Top

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

GetByBlockOperation

Requests to get the template for 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 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, requires the player to have developer permissions on the plot, and the location being a valid line starter.

Field Type Label Description
location Location 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 Location 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 Location The location of the code block to replace.
template Template The template to replace the code block with.

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