Difference between revisions of "Classic Protocol Extension/Proposals"

From wiki.vg
Jump to navigation Jump to search
(Remove duplication from BlockDefinitionsExt specification.)
(Promote BlockDefinitions and BlockDefinitionsExt to core.)
Line 118: Line 118:
 
! class="col0" | Total Size:
 
! class="col0" | Total Size:
 
| class="col1 rightalign" colspan="4" | 133 bytes
 
| class="col1 rightalign" colspan="4" | 133 bytes
|}
 
 
===BlockDefinitions===
 
:Proposed by Hetal, with contributions by fragmer.
 
:This extension allows servers to define new block types with custom IDs and appearance, as well as the ability to redefine the properties of standard block types.
 
:'''Motivation''': To allow defining block types without client modifications. To make full use of custom textures.
 
:'''Client Behavior''': This extension depends on [[Classic_Protocol_Extension#EnvMapAppearance|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 '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|LevelInitialize]]''''' and until receiving '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|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 1 and 254, 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 textures are defined by altering <code>terrain.png</code> and specifying it with '''''[[Classic_Protocol_Extension#EnvSetMapAppearance_packet|EnvSetMapAppearance]]''''' packet. '''''DefineBlock''''' fields ''TopTextureID'', ''SideTextureID'', and ''BottomTextureID'' refer to a tile number within <code>terrain.png</code>. Tiles are numbered 0 (top-left corner) through 255 (bottom-right corner), increasing left-to-right within each row. Refer to [http://123dmwm.tk/ID-Overlay.png this] image for a list of standard tiles, and a graphical list of tile indices.
 
 
:'''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 '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|LevelDataChunk]]''''' packets, '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|SetBlock]]''''' packets, or any other packets that expect block IDs.
 
 
:'''Compatibility''': For non-supporting clients, the server must convert custom block ids into fallback block ids (e.g. 'lamp' fallbacks to lava) that lie within the client's set of supported blocks. (TODO: Define how the client should store map files with block definitions. Maybe integrate this with ClassicWorld definition?) 0 is not allowed to be redefined, nor is 255, as 255 is typically used by servers to indicate 'outside map bounds'. Note that sending a '''''RemoveBlockDefinition''''' packet for a standard tile id '''is not defined''', and may lead to undesired consequences.
 
 
:<h5>DefineBlock Packet</h5>
 
:''Server to Client''
 
:{| class="wikitable"
 
|-
 
| Packet ID
 
! Field Name
 
! Field Type
 
! Example
 
! Notes
 
|-
 
| class="centeralign" rowspan="16" | 35
 
| class="centeralign" | BlockID
 
| class="centeralign" | byte
 
| class="centeralign" | <code>128</code>
 
| Between 1 and 254 (unsigned).
 
|-
 
| class="centeralign" | Name
 
| class="centeralign" | String
 
| class="centeralign" | <code>Cactus</code>
 
| Short, unique, player-friendly name for the block.
 
|-
 
| class="centeralign" | Solidity
 
| class="centeralign" | byte
 
| class="centeralign" | <code>1</code>
 
| 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.
 
|-
 
| class="centeralign" | MovementSpeed
 
| class="centeralign" | byte
 
| class="centeralign" | <code>1</code>
 
| Player movement speed modifier, defined relative to regular walk speed. Ratio to normal speed is computed with this formula:
 
y = 2<sup>(x-128)/64</sup>
 
Thus a value of <code>0</code> translates to 0.25 ratio (25% speed), <code>128</code> to 1.00 ratio (100% speed), and <code>255</code> 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.
 
|-
 
| class="centeralign" | TopTextureID
 
| class="centeralign" | byte
 
| class="centeralign" | <code>1</code>
 
| Refers to a <code>terrain.png</code> tile.
 
Between 0 and 255 (unsigned).
 
Can be same as other texture IDs.
 
|-
 
| class="centeralign" | SideTextureID
 
| class="centeralign" | byte
 
| class="centeralign" | <code>2</code>
 
| Refers to a <code>terrain.png</code> tile.
 
Between 0 and 255 (unsigned).
 
Can be same as other texture IDs.
 
|-
 
| class="centeralign" | BottomTextureID
 
| class="centeralign" | byte
 
| class="centeralign" | <code>3</code>
 
| Refers to a <code>terrain.png</code> tile.
 
Between 0 and 255 (unsigned).
 
Can be same as other texture IDs.
 
|-
 
| class="centeralign" | TransmitsLight
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Whether this block allows the sunlight to go through, for level-lighting purposes.
 
|-
 
| class="centeralign" | WalkSound
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| ID of a sound that client may play when player "steps" on, "walks" through, or "swims" through this tile.
 
0 = no sound, 1 = wood, 2 = gravel, 3 = grass, 4 = stone, 5 = metal, 6 = glass, 7 = wool, 8 = sand, 9 = snow.
 
|-
 
| class="centeralign" | FullBright
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Whether or not the block/liquid is affected by shadows (such as lava).
 
* 0 = Affected (darkened when in shadow)
 
* 1 = Not affected (always bright).
 
|-
 
| class="centeralign" | Shape
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Shape of the block model:
 
* Sprite = 0,
 
* Cube with height = 1-16
 
(e.g. slab would have a shape of '8', snow would have '2', dirt would have '16')
 
|-
 
| class="centeralign" | BlockDraw
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Can be:
 
* 0 = fully opaque
 
* 1 = transparent (e.g. like glass)
 
* 2 = transparent but with no face culling of same neighbours (e.g. like leaves)
 
* 3 = translucent, where texture's alpha is blended (e.g. like ice or water)
 
* 4 = gas (e.g. like air)
 
|-
 
| class="centeralign" | FogDensity
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Density of fog while client's camera is inside this block.
 
Value of <code>0</code> 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 <code>1</code> means density of ~0.0156, value of <code>127</code> means 1.0000, and <code>255</code> means 2.0000
 
|-
 
| class="centeralign" | FogR
 
| class="centeralign" | byte
 
| class="centeralign" | <code>255</code>
 
| Red component of the aforementioned fog. Only applies if ''FogDensity'' is above <code>0</code>.
 
|-
 
| class="centeralign" | FogG
 
| class="centeralign" | byte
 
| class="centeralign" | <code>255</code>
 
| Green component of the aforementioned fog. Only applies if ''FogDensity'' is above <code>0</code>.
 
|-
 
| class="centeralign" | FogB
 
| class="centeralign" | byte
 
| class="centeralign" | <code>255</code>
 
| Blue component of the aforementioned fog. Only applies if ''FogDensity'' is above <code>0</code>.
 
|-
 
! Total Size:
 
| class="rightalign" colspan="4" | 80 bytes
 
|}
 
 
:<h5>RemoveBlockDefinition Packet</h5>
 
:''Server to Client''
 
:{| class="wikitable"
 
|-
 
! Packet ID
 
! Field Name
 
! Field Type
 
! Example
 
! Notes
 
|-
 
| class="centeralign" | 36
 
| class="centeralign" | BlockID
 
| class="centeralign" | byte
 
| class="centeralign" | <code>128</code>
 
| Between 128 and 255
 
|-
 
! Total Size:
 
| class="rightalign" colspan="4" | 2 bytes
 
 
|}
 
|}
  
Line 1,051: Line 891:
 
! class="col0" | Total Size:
 
! class="col0" | Total Size:
 
| class="col1 rightalign" colspan="4" | 1282 bytes
 
| class="col1 rightalign" colspan="4" | 1282 bytes
|}
 
 
 
===BlockDefinitionsExt===
 
:Proposed by UnknownShadow200
 
:This extension allows servers to define new block types with custom IDs and appearance.
 
:'''Motivation''': To allow defining block types that do not have minX/Y/Z values of 0, and maxX/Z values of 1.
 
:'''Client Behavior''': See '''''BlockDefinitions''''' specification. Additionally, this extension depends on [[Classic_Protocol_Extension#EnvMapAppearance|EnvMapAppearance extension]] and '''BlockDefinitions''', and must only be enabled if BOTH extensions are mutually supported.
 
 
:'''Texturing''': See '''''BlockDefinitions''''' specification. The MinX/Y/Z and MaxX/Y/Z fields also affect the location within the terrain tile for a given face that the block should sample texels from. (e.g. if minX and minZ was 8, and maxX and maxZ was 16, then for the terrain.png tile with pixels from (0, 0) to (16, 16), the top face would be drawn with the subset of pixels from (8, 8) to (16, 16))
 
 
:'''Server Behavior''': See '''''BlockDefinitions''''' specification.
 
 
 
This packet is essentially the same as DefineBlock packet, except the 'shape field' is replaced by 6 fields indicating the bounding box of the block.
 
Note that this packet does not support sprites, you must send a regular DefineBlock packet for that.
 
:<h5>DefineBlockExt Packet</h5>
 
:''Server to Client''
 
:{| class="wikitable"
 
|-
 
| Packet ID
 
! Field Name
 
! Field Type
 
! Example
 
! Notes
 
|-
 
| class="centeralign" rowspan="16" | 37
 
| class="leftalign" colspan="4" | Following fields from DefineBlock packet: BlockID, Name, Solidity, MovementSpeed, TopTextureID, SideTextureID, BottomTextureID, TransmitsLight, WalkSound, FullBright,
 
|-
 
| class="centeralign" | MinX
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Minimum X coordinate in pixels. Min allowed is 0, max allowed is 15.
 
|-
 
| class="centeralign" | MinY
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Minimum Y coordinate in pixels. Min allowed is 0, max allowed is 15.
 
|-
 
| class="centeralign" | MinZ
 
| class="centeralign" | byte
 
| class="centeralign" | <code>0</code>
 
| Minimum Z coordinate in pixels. Min allowed is 0, max allowed is 15.
 
|-
 
| class="centeralign" | MaxX
 
| class="centeralign" | byte
 
| class="centeralign" | <code>16</code>
 
| Maximum X coordinate in pixels. Min allowed is 1, max allowed is 16.
 
|-
 
| class="centeralign" | MaxY
 
| class="centeralign" | byte
 
| class="centeralign" | <code>16</code>
 
| Maximum Y coordinate in pixels. Min allowed is 1, max allowed is 16.
 
|-
 
| class="centeralign" | MaxZ
 
| class="centeralign" | byte
 
| class="centeralign" | <code>16</code>
 
| Maximum Z coordinate in pixels. Min allowed is 1, max allowed is 16.
 
|-
 
| class="leftalign" colspan="4" | Following fields from DefineBlock packet: BlockDraw, FogDensity, FogR, FogG, FogB
 
|-
 
! Total Size:
 
| class="rightalign" colspan="4" | 85 bytes
 
 
|}
 
|}

Revision as of 10:53, 10 January 2016

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

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.

CloudLevel short 31 Elevation from bottom of the map, in blocks.

Value should be between -32768 and 32767. Default value is MapDepth + 2.

MaximumViewDistance short 16 The maximum view distance the client is allowed to see, in blocks.

Default is 0. (Client has no limit on view distance.)

Total Size: 73 bytes

Texture pack .zip format

Note: It is up to clients which files (except for terrain.png) they support in a texture pack. 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 Details
terrain.png Texture atlas that contains the textures that are applied to blocks.

Note: Clients must support this texture to be considered compliant with the specification.

animations.png Texture atlas that contains the textures used for animations.
animations.txt File that specifies how the textures in animations.png should be applied to the terrain.png texture atlas.
char.png Default skin for humanoid models.
clouds.png Texture applied to clouds rendered by the client.
The following may be utilised by clients if EnvWeatherType is mutually supported:
rain.png Texture applied to rain rendered by the client.
snow.png 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 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'.

ExtPlayerList v3

Proposed by Cheesse
This extension builds upon the current version and adds the ability to change the visibility of name tags.
Motivation: Provides more flexibility in naming of players and loading of skins, autocompletion, and player tab-list display. Separates tracking of in-game entities (spawned player models) and names on the player list. ExtAddPlayerName/ExtRemovePlayerName packets take over managing the player names list (tab-list), and ExtAddEntity3/DespawnPlayer packets are used only to manage in-game entities.Provides more flexibility in naming of players and loading of skins, autocompletion, and player tab-list display. Separates tracking of in-game entities (spawned player models) and names on the player list. ExtAddPlayerName/ExtRemovePlayerName packets take over managing the player names list (tab-list), and ExtAddEntity3/DespawnPlayer packets are used only to manage in-game entities.
Client Behavior: When ExtAddPlayerName packet is received for an unused NameID, a new name must be added to the player-name list. When receiving ExtAddPlayerName packet for an already-listed NameID, client must update its ListName, GroupName, and GroupRank. Names on the player-name list should be grouped by GroupName in the player-name list. Names within a GroupName should be sorted by GroupRank (in ascending order). Names with the same GroupName and GroupRank should be sorted alphabetically by ListName. Color codes may be either drawn or stripped from ListName, GroupName, and InGameName. Player-name list must persist when client changes worlds/maps.
When an ExtAddEntity3 packet is received, it must be treated as the SpawnPlayer packet. A player model must be spawned in-game at the given location, with InGameName text drawn above it. Skin should be loaded using the given SkinName for a player name. If SkinName appears to be a player name, skin should be downloaded from the default skin server. If SkinName appears to be a full URL to a PNG image (starts with http:// or https:// and ends with .png) then skin should be downloaded from that URL. If image is correctly sized/proportioned to use as a skin for the current model, it should be used. If a blank or unrecognized value is given for SkinName, or if given image could not be downloaded or used, then the default skin should be used. The client must also set the visibility according to NameVisibility and the collision ability of the entity according to CanCollide. When client receives ExtAddEntity3 packet for an already-spawned player, a duplicate entity must not be spawned and existing entity's position must not be changed. Instead their InGameName, SkinName, NameVisibility, and CanCollide attributes must be updated. If a negative EntityID is given for ExtAddEntity3, client must update player's own spawn point, InGameName, and SkinName. If any undefined value is given in the NameVisibility or CanCollide fields, the client should ignore these fields. The client must ignore regular SpawnPlayer packets, if any are received.
When a standard DespawnPlayer packet is received for a recognized EntityID, player model must be removed from a world. When ExtRemovePlayerName packet is received for a recognized NameID, their name must be removed from player-name list. Packets with out-of-range or unrecognized NameIDs must be ignored.
In-game entities must never be affected by ExtAddPlayerName or ExtRemovePlayerName packets. Player name list must never be affected by ExtAddEntity3 or DespawnPlayer packets.
Server Behavior: Unique NameID between 0 and 255 should be assigned to every online player or every player on a map for each map. When a new player connects to the server or joins a new map, ExtAddPlayerName must be sent. GroupName and GroupRank can be used in any way, for example to group players by map/world or rank/class/faction. Server must use ExtAddEntity3 in place of standard SpawnPlayer packet. Server should re-send ExtAddPlayerName packet, using the identical NameID, when player's ListName, GroupName, or GroupRank change. Server must reliably send an ExtRemovePlayerName packet when the player disconnects. Color codes are permitted in ListName, GroupName, and InGameName.
This extension only replaces the ExtAddEntity2 packet of the ExtPlayerList extension version 2. Thus, only the ExtAddEntity3 packet is shown here.

ExtAddEntity3 packet

Server to client
Packet ID Field Name Field Type Example Notes
0x??

(??)

EntityID byte 5 Between 0 and 127
InGameName string &cNotch Player name to be shown in-game hovering above the player.
SkinName string Notch Name of the skin that should be used by the client. Could also be a URL to a PNG image.
SpawnX short 1 X coordinate (32 units per block) of entity's spawn location.
SpawnY short 2 Y coordinate (32 units per block) of entity's spawn location.
SpawnZ short 3 Z coordinate (32 units per block) of entity's spawn location.
SpawnYaw byte 4 Orientation (left-right) at the entity's spawn location.
SpawnPitch byte 5 Orientation (up-down) at the entity's spawn location.
NameVisibility byte 6 Visibility of the InGameName of the entity. Obstacles can be blocks or other entities.
  • 0 = (Default) Visible only by hovering the cursor over the entity within view. Ignores any obstacles in the way.
  • 1 = Visible only by hovering the cursor over the entity within view. Invisible when obstacles block the entity.
  • 2 = Always visible within view (name tag shrinks over distance). Ignores any obstacles in the way.
  • 3 = Always visible within view (name tag shrinks over distance). Invisible when obstacles block the entity.
  • 4 = Always visible anywhere (name tag does not shrink over distance). Ignores any obstacles in the way.
  • 5 = Always visible anywhere (name tag does not shrink over distance). Invisible when obstacles block the entity.
  • 6 = Never visible.
CanCollide byte 0
  • 0 = (default) Can collide with the player.
  • 1 = Cannot collide with the player.
Total Size: 140 bytes
(Comments go here, please sign them)

HackControl v2

Proposed by Cheesse
This extension allows more control over the abilities of players.
Motivation: To gain control over the movement and action abilities of players.
Client Behavior: Client must be able to receive HackControl2 packets at any time and apply the changes defined in the packet immediately. Any value may be given in any field to allow or adjust an ability. If a negative value is given in any field, the client should set that value to its default. If 0 is given in any field, the client must deactivate that ability and prevent its use by the player unless otherwise stated.
Server Behavior: Server may send HackControl2 packets to successfully connected clients at any time.

HackControl2 packet

Server to client
Packet ID Field Name Field Type Example Notes
0x??

(??)

FlySpeed byte 0 Defines the speed of flight in player units per quarter-second. A value of 0 or less means the player is not allowed to fly.
NoClip byte 0
  • 0 = Prevent no-clipping
  • 1 = Allow no-clipping
WalkSpeed byte 64 Defines the normal speed of walking in player units per quarter-second. Any negative value allows the player to travel at any speed and overrides any value set by RunSpeed.
RunSpeed byte 16 Helps define the ratio of the running speed to the walking speed. This value is then divided by 32 and added to 1 to get the ratio. A value less than or equal to 0 means the player is not allowed to run.
AllowRespawn byte 1
  • 0 = Prevent respawning
  • 1 = Allow respawning
PointOfView byte 0
  • 0 = First-person view
  • 1 = Third-person behind view
  • 2 = Third-person front view

Setting this field to a defined value will prevent the player from changing their point of view. Setting it to an undefined value will allow the player to switch points of view.

JumpHeight short 40 Maximum height in player units of the player's normal jump.
SuperJumpHeight short 9001 Maximum height in player units of any other jump abilities the player has, like using speed to get a higher jump. A SuperJumpHeight value of 0 means the player is not allowed to superjump. Any negative SuperJumpHeight will override any value in JumpHeight and allow the player to jump to any height.
Total Size: 11 bytes
(Comments go here, please sign them)

EnvWeatherType v2

Proposed by Cheesse
This extension allows the server to change the weather conditions and amount of fog.
Motivation: To allow the server to create a setting, scene or mood on a map; or to limit the players vision for things like smoke bombs in games. (Fog/View Distance is placed here because the EnvSetMapAppearance2 packet would be too big to include such a versatile feature.)
Client Behavior: Client must be able to receive EnvSetWeatherType2 packets at any time and apply the changes defined in the packet immediately. If an undefined value is used in the WeatherType or WeatherStrength fields, the client should ignore that value. If a negative value is given in the MaxFog field, the client should set that value to its own default. The client should make smooth changes between different strengths of weather and fog distances.
Server Behavior: Server may send EnvSetWeatherType2 packets to successfully connected clients at any time.

EnvSetWeatherType2 packet

Server to client
Packet ID Field Name Field Type Example Notes
0x??

(??)

WeatherType byte 0
  • 0 = Sunny
  • 1 = Rainy
  • 2 = Snowy
WeatherStrength byte 120 These values should be scaled such that a value of 120 should correspond to 100%. From 0-120.
MaxFog short 128 The distance in blocks of the wall of fog away from the player
Total Size: 5 bytes
(Comments go here, please sign them)

MessageTypes v2

Proposed by Cheesse
This extension adds new ways of presenting information to the player.
Motivation: To allow the server to send messages in different places and for limited times.
Client Behavior: Client must interpret the PlayerID field of the standard Message packet as the Message Type field. Certain values in this field correspond to different locations for messages on the screen. Any undefined values in this field should be ignored and presented as regular chat messages. Without mutual server-client support for this extension, this field should be ignored.
Server Behavior: Server may use the PlayerID field of the Message packet to have that message placed at a certain location on the player's screen.
MessageType Value Meaning Message Placement
0 Chat In the chatbox.
1 Status1 At the top right of the screen.
2 Status2 At the top right of the screen below Status1.
3 Status3 At the top right of the screen below Status2.
11 BottomRight1 At the bottom right of the screen.
12 BottomRight2 At the bottom right of the screen above BottomRight1.
13 BottomRight3 At the bottom right of the screen above BottomRight2.
45 LeftHotbar On top of the hotbar aligned to the left.
54 RightHotbar On top of the hotbar aligned to the right.
100 BigAnnouncement In large font slightly above the center of the screen.
200 SmallAnnouncement Near the center of the screen below BigAnnouncement.

This extension does not define any new packets.

(Comments go here, please sign them)

ExtMapInfo

Proposed by Cheesse
This extension allows the server to send the client some of the map's metadata and other information
Motivation: To allow clients to save metadata with the maps they choose to save. This extension can also be modified to add more features to maps.
Client Behavior: Client must be able to receive FinalMapInfo packets at any time after a LevelInitialize packet has been received and before a FinalMapInfo packet has been received. Client should store the values in these fields in memory to be used later. The metadata defined in these fields come from those defined in the ClassicWorld file definitions. Client should ignore any LevelFinalize packets recieved.
Server Behavior: Server must send FinalMapInfo packets with the correct values after it has finished sending the client the raw block data after sending a LevelInitialize packet. The server should not send this packet at any other time. The server should never send any LevelFinalize packets to the client.

FinalMapInfo packet

Server to client
Packet ID Field Name Field Type Example Notes
0x??

(??)

"FormatVersion byte 1 The FormatVersion is currently set to 1.
"MapName" string main The name of the map.
"UUID" byte array [16] abcdefghijklmnop The UUID of the map.
"XSize" short 128 The length of the map in the X dimension.
"YSize" short 128 The length of the map in the Y dimension.
"ZSize" short 128 The length of the map in the Z dimension.
"CreatedBy" string Cheesse The name of the author of the map. This should be an existing Classicube username.
"MapGenSoftware" string Mapbuilder The name of the software used to generate the map.
"MapGenName" string Flat The name of the generator function used to generate the map.
"TimeCreated" long 1234567890 The UTC Unix timestamp of the time the map was generated.
"TimeLastModified" long 1234567890 The UTC Unix timestamp of the time the map was last modified.
Total Size: 298 bytes
(Comments go here, please sign them)

BulkBlockUpdate

Proposed by Buzz, UnknownShadow200
Allows servers to send a single packet that contains 256 block updates.
Motivation: Reduce bandwidth usage and hence increase responsiveness to clients during times of heavy block updates, e.g. for large cuboids or lava survival servers.
Client Behavior: When this extension is mutually supported, treat the packet in the same manner as a list of up to 256 SetBlock packets.
Server Behavior: When this extension is mutually supported, server may send BlockBulkUpdate packet to the client after the LevelFinalize packet for the current level has been sent to the client.

BulkBlockUpdate packet

Server to Client
Packet ID Field Name Field Type Example Notes
0x26

(38)

Count unsigned byte 0 The number of block updates used in this packet - 1. (e.g. a value of 0 means 1 block update is used).
Indices byte array[1024] [52, 3443] A packed list of the indices within the current level of the blocks that are to be updated.

Each element is a 32 bit integer in big endian order.

Blocks byte array[256] [5, 10] A packed list of the new blocks to set at each corresponding index in the indices array.
Total Size: 1282 bytes