Skip to content

Proto

Jump to bottom
RedVortexDev edited this page Sep 15, 2025 · 31 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

S2CCodeTemplate

Sent as a response to a C2SGetTemplate message, error is true if the player does not have developer permissions on the plot, or if the location is not a valid code block position

Field Type Label Description
json string The template as a JSON string.
error bool Whether an error occurred while getting the template.

S2CPlaceTemplateResult

Sent as a response to a C2SPlaceTemplate message, error is true if the player does not have developer permissions on the plot, or if the location is not a valid code block position, or if the template overrides any blocks / exits the plot bounds.

Field Type Label Description
error bool Whether an error occurred while placing the template.

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.

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.

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

C2SGetTemplate

Requests the template at the given location, requires the player to have developer permissions on the plot, and the location being a valid code block position. An S2CCodeTemplate packet will be sent as a response.

Field Type Label Description
location Location The location of the code block to get the template of.

C2SPlaceTemplate

Requests to place a template at the given location, requires the player to have developer permissions on the plot, the location being a valid code block position, and that the template will not override any blocks nor exit the plot bounds. An S2CPlaceTemplateResult packet will be sent as a response.

Field Type Label Description
location Location The location of the code block to place the template at.
json string The template JSON string.
data string The template code data.

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