Classic Protocol Extension/Proposals

Template

Add your proposal at the end of the page. Please use existing extensions as your guide to formatting. Please sign your proposals and comments by ending it with ~~~~.

===ExtensionName===
:Proposed by ~~~~
:Brief summary of the extension.
:'''Motivation''': Explain why this is needed or how it is useful.
:'''Client Behavior''': Detailed description of all new behavior that game clients need to implement in order to support this extension. Consider interaction with other extensions.
:'''Server Behavior''': Detailed description of all new behavior that game servers need to implement in order to support this extension. Consider interaction with other extensions.
:(Packet definitions, remarks, illustrations, and data tables go here)
:(Comments go here, please sign them)

Proposals

PlaySound

Proposed by !!!WARLOCK!!!

This extension allows server to play custom sound and musics on client.

Motivation: Servers can play custom musics or sound effects just in time or when something changes. Useful for gamemodes such as zombie survival, Servers can play zombie moaning sound while zombies are close to players. Player join and leave sounds, Kill streak sounds for games such as CTF, Radio and DJ class for players and sound effects for explosions and player deaths.

Client Behavior: Client must download and load, or load the sound directly from the URL with the ID. Client must be able to download any time after MapFinalize has sent. If the URL is empty then the Client must unload the sound with that ID. Client must unload the sound and load a new one if there's a sound with existing ID. Client must be able to play the sound right after receiving the PlaySound packet. The last playing sound can not be ignored or stopped when a new sound is going to be played. Files type must be in .WAV, otherwise they're ignored. Client must ignore downloading the existing files from Server if they're saved in drive. Client must not change the volume of all environments (Place/Destroy, Walk sounds) on SetVolume packet. Client must change a local variable for volume of next playing sound on SetVolume packet.

Server Behavior: Server must ignore sending the same url multiple times. Server can not send quick loops of sound due to network speed and client crash possibility. It's better to load all of required sounds after map load for better performance. Server must not send high sized file cause of time and speed it takes for download. Files type must be in .WAV, otherwise they're ignored. Server can change the volume before playing a sound. For a better networking, It's suggested to not send PlaySound instead of changing volume to zero.

LoadSound packet

Server to client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	ID	byte	143	Gives the URL an ID.
	URL	string	http://site.com/firstblood.wav	Address to a .WAV file, put this empty for unload.
	Total Size:	66 bytes

PlaySound packet

Server to client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	ID	byte	125	Plays the sound saved as ID.
	Total Size:	2 bytes

SetVolume packet

Server to client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	Percent	byte	87	Set the next playing sound(s) volume to a Percentage.
	Total Size:	2 bytes

ClientRedirection

Proposed by Sysr q (talk) 10:17, 12 May 2014 (UTC)

This extension allows servers to give clients a redirection to a separate, possibly "private" server.

Motivation: Allowing servers to redirect clients would be useful in several cases. Allowing a singular "hub" server to redirect players to various external (but related) servers depending on the gamemode they wish to play would allow tightly integrated networks. If servers are using an external "balancer" or some sort of Minecraft-aware proxy, the server could signal the proxy move its connection on the client's behalf to another server.

Client Behavior: Clients should be ready to receive a ClientRedirection packet any time after they receive a LevelFinalize packet. When clients receive a ClientRedirection packet, they should prompt the user with a message indicating the server they're being redirected too, and allow the user to continue or quit. Non-player clients (e.g., proxies) have the option of silently reconnecting on the client's behalf. Clients should then open a new connection to the newly redirected server, and begin standard negotiation protocol.

Server Behavior: Servers should only send a ClientRedirection packet after the they have sent a LevelFinalize packet. They should ensure the new server the client is being redirected to exists, and preferably is online and available.

ClientRedirection packet

Server to client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	Address	string	mc.example.org	Can be an IP address (IPv4/IPv6) or a hostname.
	Port	int	25565
	Name	string	Joe Blogg's Freebuild	(optional) User-friendly name to be displayed in user prompt.
Total Size:	133 bytes

BlockDefinitions

Proposed by Hetal, with contributions by fragmer.

This extension allows servers to define new block types with custom IDs and appearance.

Motivation: To allow defining block types without client modifications. To make full use of custom textures.

Client Behavior: This extension depends on EnvMapAppearance extension, and must only be enabled if BOTH extensions are mutually supported. Client should be able receive any number of DefineBlock and RemoveBlockDefinition packets during the level loading process (after receiving LevelInitialize and until receiving LevelFinalize packets). However, dependent on client, this can be sent after level loading (Some clients might just find it more extensible than others). Client must keep track of all defined blocks between level changes or until they are individually removed with RemoveBlockDefinition.

Client must be able to accept and render blocks as specified in DefineBlock packets. Clients must accept any valid definitions with BlockID between 128 and 255, inclusive. If a new definition is accepted for an already-defined BlockID, the old definition should be replaced. If RemoveBlockDefinition is received for a non-defined BlockID, it should be ignored.

Texturing: New textured are defined by altering terrain.png and specifying it with EnvSetMapAppearance packet. DefineBlock fields TopTextureID, SideTextureID, and BottomTextureID refer to a tile number within terrain.png. Tiles are numbered 0 (top-left corner) through 255 (bottom-right corner), increasing left-to-right within each row. Tiles 0-127 are reserved for standardized blocks. Refer to table 1 for a list of standard tiles (TODO). Block definitions can use these tiles, but texture makers should be careful not to accidentally overwrite tiles in this range (top half of terrain.png) to avoid changing appearance of standardized blocks that use them. Positions 128-255 (the bottom half of terrain.png) can be textured and used in any way.

Server Behavior: Server may send any number of DefineBlock packets when client expects it. Server should only use IDs of currently-defined blocks in block data sent in LevelDataChunk packets, SetBlock packets, or any other packets that expect block IDs.

Compatibility: TODO: Define what the server should do for non-supporting clients. Define how the client should store map files with block definitions. Maybe integrate this with ClassicWorld definition?

There are two packets, one for liquids and one for all other blocks. Both packets share a common number of fields initially, and are then followed by several packet specific fields.

Common packet structure

Server to Client

Field Name	Field Type	Example	Notes
BlockID	byte	128	Between 128 and 255 (unsigned).
Name	String	Cactus	Short, unique, player-friendly name for the block.
Solidity	byte	1	Specified collision mode for this block type. Blocks may be walk-through (0), swim-through (1), or solid (2). Walk-through blocks do not collide with the player, and do not interfere with jumping. Players fall through these blocks. Swim-through blocks allow the player to descend or ascend slowly (at WalkSpeed), as if they were swimming. Solid blocks collide with the player. Players may walk on these.
MovementSpeed	byte	1	Player movement speed modifier, defined relative to regular walk speed. Ratio to normal speed is computed with this formula: y = 2(x-128)/64 Thus a value of 0 translates to 0.25 ratio (25% speed), 128 to 1.00 ratio (100% speed), and 255 to 3.96 (396% speed). If Solidity is set to 0 or 1, speed is modified while player is inside (i.e. colliding with) the block. If Solidity is set to 2, speed is modified while player is standing on the block. If player is affected by several tiles, the lowest of all modifiers is used.
TopTextureID	byte	1	Refers to a terrain.png tile. Between 0 and 255 (unsigned). Can be same as other texture IDs.
SideTextureID	byte	2	Refers to a terrain.png tile. Between 0 and 255 (unsigned). Can be same as other texture IDs.
BottomTextureID	byte	3	Refers to a terrain.png tile. Between 0 and 255 (unsigned). Can be same as other texture IDs.
Opacity	byte	255	Full-tile opacity value. Between 0 (fully transparent) and 255 (fully opaque).
TransmitsLight	byte	0	Whether this block allows the sunlight to go through, for level-lighting purposes.
WalkSound	byte	0	ID of a sound that client may play when player "steps" on, "walks" through, or "swims" through this tile. Must be one of sound IDs defined in https://github.com/andrewphorn/ClassiCube-Client/blob/master/src/main/java/com/mojang/minecraft/level/tile/Block.java#L24-L35. The sounds start from 0 (None).
FullBright	byte	0	Whether or not the block/liquid is affected by shadows (such as lava). 0 = Affected (darkened when in shadow) 1 = Not affected (always bright).

DefineBlock Packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
35	Shape	byte	0	Shape of the block model: Cube (1), Slab (2), Upside down slab (3), Sprite (4)
	BlockDraw	byte	0	Can be 0 (fully opaque), 1 (transparent), or 3 (translucent).
	Total Size:	76 bytes

DefineLiquid Packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
36	FogDensity	byte	0	Density of fog while client's camera is inside this liquid. Value of 0 means "do not change fog" -- level's default settings are used. Values between 1 and 255 are mapped to OpenGL's GL_FOG_DENSITY value for GL_EXP2 style fog with the following formula: GL_FOG_DENSITY = (x+1)/128 Thus value of 1 means density of ~0.0156, value of 127 means 1.0000, and 255 means 2.0000
	FogR	byte	255	Red component of the aforementioned fog. Only applies if FogDensity is above 0.
	FogG	byte	255	Green component of the aforementioned fog. Only applies if FogDensity is above 0.
	FogB	byte	255	Blue component of the aforementioned fog. Only applies if FogDensity is above 0.
	Total Size:	78 bytes

RemoveBlockDefinition Packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
37	BlockID	byte	128	Between 128 and 255
Total Size:	2 bytes

Future References: The client developers will be able to add more base blocks but then the server developers will have to change their Ids sent if the block is being occupied as a base block. If any of the fields are incorrectly configured, the client shall disconnect with an error message briefly describing why it crashed ("Invalid Custom Block located at Id : ID").

Example: Let's say I have a block called bullet being launched from a block (the block launching the bullet is not required for this situation). I could add that block's Id to the client using ADD_CUSTOM_BLOCK by AddCustomBlock((byte)128/*BulletBlockId*/, (byte)2);, and if my textureUrl in the EnvMapAppearance sent before/afterwards was actually containing a bullet in the correct slot, the block would inherit actual bullet textures making it realistic and yet again fun.

TABLE 1: TODO: list of tiles already defined in terrain.png, for both standard and CustomBlocks level 1 blocks.

TABLE 2: TODO: list of sounds available for footstep and breaking sounds

LongerMessages

Proposed by F (talk) 21:43, 28 August 2014 (UTC)

This extension allows clients to accept messages longer than 64 characters, and send them to the server in parts.

Motivation: To allow players to write longer messages!

Client Behavior: When a regular-length message is sent, a single Message packet is sent, with the unused PlayerID (aka MessageType) byte set to 0. When an extra-long message is sent, multiple Message packets are sent. All packets except the last one should have the unused byte set to 1, meaning "this message continues in the next Message packet".

Server Behavior: Server should check the unused PlayerID (aka MessageType) byte of every incoming Message packet. If the value is non-zero, it should treat it as a partial message. Partial messages should be stored and prepended to the next message received from this player, until a message with a 0 byte is received.

No new packets are defined, but treatment of Message packet is altered.

ColorCodeControl

Proposed by F (talk) 22:00, 28 August 2014 (UTC)

Gives servers an option to allow players to type in color codes, and a way to render & character in chat.

Motivation: Allow players to type in color codes and to use & in chat.

Client Behavior: When this extension is mutually supported, treat character sequence && as meaning "draw an & character", without modifying current color. Do not allow & to be typed or pasted into chat unless ColorCodeControl packet has been received with AllowColorCodes set to 1.

Server Behavior: When this extension is mutually supported, server may send ColorCodeControl packet to allow client to type or paste color codes. Server should treat && as described above.

ColorCodeControl packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
??	AllowColorCodes	byte	0	0 = disallow 1 = allow
Total Size:	2 bytes

UnicodeChat

Proposed by F (talk) 22:48, 28 August 2014 (UTC)

Expands character encoding beyond ASCII. There are three ways to go about this:

1. Expand charset to 256 characters using Win-1252.
   • Pro: Easiest to implement in clients (few changes to FontRenderer needed) and servers (no multibyte character support needed).
   • Pro: No new packets needed.
   • Pro: Easy to create custom fonts.
   • Pro: Easy for servers to maintain compatibility with legacy clients, since only 128 characters need to be remapped, most of which have decent ASCII matches.
   • Pro: Low resource use (low RAM and VRAM use, no additional CPU use, small font file).
   • Con: Still only 256 characters. Only covers Latin-derived (English and Western/Central European) languages and common symbols.
2. Expand charset to Unicode Basic Multilingual Plane (BMP) with UCS-2 fixed-length encoding.
   • Pro: Lots of characters (~65k) covering most languages and symbols.
   • Pro: Not too hard to implement (characters still fixed-width, native support in WinAPI / Java / C#).
   • Pro: Free fonts available that covers all characters.
   • Con: New renderer (possibly third-party library) needed for rendering.
   • Con: Higher resource use (higher RAM and VRAM use, more CPU use, large font file).
   • Con: Very hard to create custom fonts.
   • Con: Still does not cover all characters.
   • Con: Hard for servers to maintain compatibility with legacy clients.
   • Con: Always uses 2 bytes per character for transmission (twice as much as ASCII/CP-1252).
3. Expand charset to Unicode Basic Multilingual Plane (BMP) with UTF-8 variable-length encoding.
   • Pro: Lots of characters (~65k) covering most languages and symbols.
   • Pro: Not too hard to implement (characters can be freely converted to/from UCS-2, which is natively support in WinAPI / C#).
   • Pro: Free fonts available that covers all characters.
   • Pro: Uses 1 byte per character for transmission, most of the time.
   • Con: New renderer (possibly third-party library) needed for rendering.
   • Con: Higher resource use (higher RAM and VRAM use, more CPU use, large font file).
   • Con: Hard to create custom fonts (unless some fallback rules are implemented).
   • Con: Still does not cover all characters.
   • Con: Hard for servers to maintain compatibility with legacy clients.
4. Expand charset to full Unicode with UTF-8 variable-length encoding. Includes all the supplemental Unicode planes.
   • Pro: Widely used in other software.
   • Pro: Theoretically covers all languages and symbols.
   • Pro: Uses 1 byte per character for transmission, most of the time.
   • Con: Does not actually cover all languages and symbols due to non-existence of 100% fonts.
   • Con: Hard to find free fonts that extend beyond the BMP.
   • Con: Harder to work with strings (due to variable-width characters).
   • Con: Third-party library needed for rendering.
   • Con: Highest resource use (highest RAM and VRAM use, most CPU use, largest font files).
   • Con: Hardest to implement (no native support in WinAPI / C#).
   • Con: Hard to create custom fonts (unless some fallback rules are implemented).
   • Con: Hard for servers to maintain compatibility with legacy clients.

ColorControl

Proposed by !!!WARLOCK!!!

Changes the color alpha (A) of Messagetypes to a custom number.

Motivation: Allows servers to make gradient/glass like text messages at Message Type's IDs.

Client Behavior: If this packet is received, Client should directly change the alpha color of the specified chat message into a custom number. If the default message ID `0` is received, client should be changing the alpha code of the all incoming and received chat lines into the specified number. The alpha code remains until the client disconnects from the server, and should be functional with all incoming and already received messages. Client should be able to receive this message after the Initial map load.

Server Behavior: Server can send this packet to clients right after client finished loading the initial map. Message type can be any of stated/defined numbers on the packet (Message Type).

ColorControl packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	Message Type	byte	11	Message Type ID.
	Alpha Code	byte	154	Alpha code of color (From 0 - 255).
	Total Size:	3 bytes

SelectionCuboid v2

Proposed by FabTheZen, classic1234 and Rayne

Motivation: Allows the server to not only highlight parts of a world, but also determine whether those regions are walk through or not. This could be used to disallow players to walk inside restricted areas or zones which they are not allowed to build in. It could also be used as a jail when accompanied with the '-hax' option.

Client behavior: The client must receive the SelectionCuboid extension with version 2. It must also determine whether any selections on the map walk through or not.

Server behavior: The server behaves the same way SelectionCuboid v1 does.

MakeSelection packet v2

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	SelectionID	byte	0	Numeric ID of the selection. Between 0 and 127.
	Label	string	SomeZone	Text label associated with the selection
	StartX	short	1	X coordinate of the starting point
	StartY	short	2	Y coordinate of the starting point
	StartZ	short	3	Z coordinate of the starting point
	EndX	short	5	X coordinate of the ending point
	EndY	short	6	Y coordinate of the ending point
	EndZ	short	7	Z coordinate of the ending point
	Red	short	255	Between 0 and 255.
	Green	short	34	Between 0 and 255.
	Blue	short	128	Between 0 and 255.
	Opacity	short	255	0 = fully transparent 255 = fully opaque
	Walkthrough	byte	0	0 = Not walkthrough 1 = Walkthrough
Total Size:	87 bytes

Player Animation

Proposed by ByteBit

Let the player to do certain actions/animations on the client

Motivation: Other players will be able to see the block another is holding or whether one placed a block or not. It makes the game's feel more realistic, because blocks don't pop out a no where.

Client Behavior: On recieve the client should perform the actions required for the animation.

Server Behavior: The server may send the packet if needed any time after the map is send.

AnimatePlayer packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0xAC (172)	Animation Type	byte	1	Specifies what animation to perform (0: Hold block; 1: Set block; 2: Destroy block; 3: Player name visibility)
	Player ID	byte	1	What player to perform this animation on
	Additional byte	byte	49 (Obsidian)	Needed for specific animations (Block type for 0,1 and 2; for 3: true(1)/false(0))
Total Size:	3 bytes

PlayerHealth

Proposed by Apotter96 (talk) 02:29, 26 July 2015 (UTC)alex96

Gives players life count that is controlled by the server and reflected by the client at the top left of the game screen. The server.

Motivation: RPG and Gun games can go more extensive if they wish with lives.

Client Behavior: Display player's lives at the top left of screen when the server sends the packet. On player connect, the server needs to tell the client the max amount of lives the player can have, in between 5 and 20. May also dictate how many lives the server is allowed to send. Both need to check with the other end so they can comply together.

Server Behavior: At any time the server can send the packet telling the client the amount of lives the player has. Once a player connects, the server needs to tell the client how many lives the player is allowed to have, in between 5 and 20. Both need to check with the other end so they can comply together.

UpdateLives packet

Server to client

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	Lives	int	15	How many lives the player has
	MaxLives	int	15	The Max amount of lives
	Total Size:	2 bytes

UpdateLives packet

Client to server

Packet ID	Field Name	Field Type	Example	Notes
0x?? (??)	MaxLives	int	15	The Max amount of lives
	Total Size:	2 bytes

(Comments go here, please sign them)

EnvMapAppearance v2

Proposed by UnknownShadow200

This extension allows the server to specify custom texture packs, and tweak appearance of map edges.

Motivation: To provide more ways to customize map appearance, including functionality that's currently provided by World of Minecraft's scheme.

Client behavior: Client must be able to receive EnvSetMapAppearance v2 packets any time during level load (after the first LevelDataChunk packet is received and until the LevelFinalize packet is received). If the TexturePackURL field is blank or if the given file could not be loaded for any reason, then the texture pack should be reset to the client's default. If an unsupported block ID is given for SideBlock or EdgeBlock, it should be ignored. The given SideLevel value should be adjusted to fit between 0 and MapDepth, if necessary. Client should keep using these appearance parameters for future maps, unless specified otherwise by the server.

Server behavior: Server may send EnvSetMapAppearance v2 packets after the last LevelDataChunk packet is sent for a level. Server should not use any custom block IDs unless the client declared the appropriate CustomBlocks support level. To reset the texture pack to the client's default one, server should send an EnvSetMapAppearance v2 packet with empty string for TexturePackURL. To reset other fields, server should simply use the default values (listed below).

Block type restrictions: Only solid blocks are allowed to be used for SideBlock and EdgeBlock. Sprites (Sapling, Dandelion, Rose, BrownMushroom, RedMushroom, Rope, Fire) partial-height blocks (Slab, CobblestoneSlab, Snow), and transparent blocks (Air, Leaves, Glass) cannot be used for those fields.

EnvSetMapAppearance v2 packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x1E (30)	TexturePackURL	string	http://example.com/mypack.zip	Texture pack's full URL. Must be a HTTP/HTTPS URL, in .zip format, and served with application/zip mime type.
	SideBlock	byte	7	Block ID. Default value is 7 (Admincrete).
	EdgeBlock	byte	8	Block ID. Default value is 8 (Water).
	SideLevel	short	31	Elevation from bottom of the map, in blocks. Value should be between 0 and MapDepth. Default value is MapDepth/2.
Total Size:	69 bytes

Texture pack .zip format

Note: Clients may choose to ignore optional files. These clients are still considered to be compliant with the specification.

Note: Texture packs may also contain other files that are not listed below. If clients recognise these other files, then they may perform whatever is desired with them. Otherwise, clients must ignore these other files.

Note: If a texture pack does not contain a certain texture, clients should continue to use the existing texture from the previous texture pack.

Note: Servers are highly advised to avoid texture pack .zips over 4 MB, as these may be rejected by clients.

File name	Optional	Details
terrain.png	No	Texture atlas that contains the textures that are applied to blocks.
animations.png	Yes	Texture atlas that contains the textures used for animations.
animations.txt	Yes	File that specifies how the textures in animations.png should be applied to the terrain.png texture atlas. TODO link to format description.
char.png	No	Default skin for humanoid models.
clouds.png	Yes	Texture applied to clouds rendered by the client.
The following may be utilised by clients if EnvWeatherType is mutually supported:
rain.png	Yes	Texture applied to rain rendered by the client.
snow.png	Yes	Texture applied to snow rendered by the client.
The following may be utilised by clients if ChangeModel is mutually supported: Note: The default texture for humanoid models is specified by char.png. Block models use textures from terrain.png.
x.png	Yes	Default texture applied to a model for model string x. For example, the Crocodile model has the model string croc. The default texture that would be applied is specified by croc.png.

animations.txt format

Each line is in the format: <TileX> <TileY> <FrameX> <FrameY> <Frame size> <Frames count> <Tick delay> - TileX and TileY indicate the coordinates of the tile in terrain.png that will be replaced by the animation frames. These range from 0 to 15. (inclusive of 15) - FrameX and FrameY indicates the pixel coordinates of the first animation frame in animations.png. The top left pixel coordinate is (0, 0) - Frame size indicates the size in pixels of an animation frame. - Frames count indicates the number of used frames. The first frame is located at (FrameX, FrameY), second frame at (FrameX + FrameSize, FrameY) and so forth. - Tick delay is the number of ticks a frame doesn't change. For instance, a value of 0 means that the frame would be changed every tick, while a value of 2 would mean 'replace with frame 1, don't change frame, don't change frame, replace with frame 2'.