Difference between revisions of "Classic Protocol Extension/Old Extensions"

From wiki.vg
Jump to navigation Jump to search
(Deprecate version 1 of EnvMapAppearance.)
(Move version 2 of EnvMapAppearance to old extensions)
Line 223: Line 223:
 
! class="col0" | Total Size:
 
! class="col0" | Total Size:
 
| class="col1 rightalign" colspan="4" | 69 bytes
 
| class="col1 rightalign" colspan="4" | 69 bytes
 +
|}
 +
 +
====Version 2 (Deprecated since 21 June 2017)====
 +
:This extension allows the server to specify custom texture packs, and tweak appearance of map edges.
 +
:'''Client behavior:''' Client must be able to receive '''''EnvSetMapAppearance v2''''' packets any time during level load (after the first '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|LevelDataChunk]]''''' packet is received and until the '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|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 <code>0</code> and <code>MapDepth</code>, 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 '''''[[Classic_Protocol#Server_.E2.86.92_Client_packets|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.
 +
 +
:<h5>EnvSetMapAppearance v2 packet</h5>
 +
:''Server to Client''
 +
:{| class="wikitable"
 +
|- class="row0"
 +
! class="col0" | Packet ID
 +
! class="col1" | Field Name
 +
! class="col2" | Field Type
 +
! class="col3" | Example
 +
! class="col4" | Notes
 +
|- class="row1"
 +
| class="col0 centeralign" rowspan="6" | 0x1E
 +
(30)
 +
| class="col1 centeralign" | TexturePackURL
 +
| class="col2 centeralign" | string
 +
| class="col3 centeralign" | <code>http://example.com/mypack.zip</code>
 +
| class="col4" | Texture pack's full URL.
 +
Must be a HTTP/HTTPS URL, in .zip format, and served with <code>application/zip</code> mime type.
 +
If a .png is instead served, this is assumed to represent a terrain.png image.
 +
|- class="row2"
 +
| class="col1 centeralign" | SideBlock
 +
| class="col2 centeralign" | byte
 +
| class="col3 centeralign" | <code>7</code>
 +
| class="col4" | Block ID. Default value is 7 (Admincrete).
 +
|- class="row3"
 +
| class="col1 centeralign" | EdgeBlock
 +
| class="col2 centeralign" | byte
 +
| class="col3 centeralign" | <code>8</code>
 +
| class="col4" | Block ID. Default value is 8 (Water).
 +
|- class="row4"
 +
| class="col1 centeralign" | SideLevel
 +
| class="col2 centeralign" | short
 +
| class="col3 centeralign" | <code>31</code>
 +
| class="col4" | Elevation from bottom of the map, in blocks.
 +
Value should be between <code>0</code> and <code>MapDepth</code>.
 +
Default value is <code>MapDepth/2</code>.
 +
|- class="row5"
 +
| class="col1 centeralign" | CloudLevel
 +
| class="col2 centeralign" | short
 +
| class="col3 centeralign" | <code>31</code>
 +
| class="col4" | Elevation from bottom of the map, in blocks.
 +
Value should be between <code>-32768</code> and <code>32767</code>.
 +
Default value is <code>MapDepth + 2</code>.
 +
|- class="row6"
 +
| class="col1 centeralign" | MaximumViewDistance
 +
| class="col2 centeralign" | short
 +
| class="col3 centeralign" | <code>16</code>
 +
| class="col4" | The maximum view distance the client is allowed to see, in blocks.
 +
Default is 0. (Client has no limit on view distance.)
 +
|- class="row7"
 +
! class="col0" | Total Size:
 +
| class="col1 rightalign" colspan="4" | 73 bytes
 +
|}
 +
 +
:<h5>Texture pack .zip format</h5>
 +
:'''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 not listed below. If clients recognise these other files, then they may perform whatever is desired with them.
 +
:'''Note:''' If a texture pack does not contain a certain texture, clients should continue to use the existing texture from the previous texture pack.
 +
:{| class="wikitable"
 +
|- class="row0"
 +
! class="col0" | File name
 +
! class="col2" | Details
 +
|- class="row1"
 +
| class="col0 centeralign" | terrain.png
 +
| class="col2 centeralign" | Texture atlas that contains the textures that are applied to blocks.
 +
'''Note:''' Clients ''must'' support this texture to be considered compliant with the specification.
 +
|- class="row2"
 +
| class="col0 centeralign" | animations.png
 +
| class="col2 centeralign" | Texture atlas that contains the textures used for animations.
 +
|- class="row3"
 +
| class="col0 centeralign" | animations.txt
 +
| class="col2 centeralign" | File that specifies how the textures in animations.png should be applied to the terrain.png texture atlas.
 +
|- class="row3"
 +
| class="col0 centeralign" | char.png
 +
| class="col2 centeralign" | Default skin for humanoid models.
 +
|- class="row4"
 +
| class="col0 centeralign" | clouds.png
 +
| class="col2 centeralign" | Texture applied to clouds rendered by the client.
 +
|- class="row5"
 +
| class="col0 leftalign" colspan="2" | ''The following may be utilised by clients if EnvWeatherType is mutually supported:''
 +
|- class="row6"
 +
| class="col0 centeralign" | rain.png
 +
| class="col2 centeralign" | Texture applied to rain rendered by the client.
 +
|- class="row7"
 +
| class="col0 centeralign" | snow.png
 +
| class="col2 centeralign" | Texture applied to snow rendered by the client.
 +
|- class="row8"
 +
| class="col0 leftalign" colspan="2" | ''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''.
 +
|- class="row9"
 +
| class="col0 centeralign" | x.png
 +
| class="col2 centeralign" | 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''.
 +
|}
 +
 +
:<h5>animations.txt format</h5>
 +
:{| class="wikitable" style="display:block; max-width:1000px"
 +
|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'.
 
|}
 
|}

Revision as of 11:14, 21 June 2017

The extensions on this page have been deprecated or replaced.

ExtPlayerList

Version 1 (Deprecated since 28 August 2014)

Client Behavior
When ExtAddPlayerName packet is received for an unrecognized NameID, a new entry must be added to the autocompletion list and tab-list. When receiving ExtAddPlayerName packet for an already-listed NameID, client must update its ListName, GroupName, and GroupRank. Name list must persist when client changes worlds/maps.
Names on the tab-list should be grouped by GroupName in the player tab-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.
When an ExtAddEntity packet is received, it must be treated as the SpawnPlayer packet. InGameName should be shown above the player's heads in-game. Skin should be loaded using the given SkinName for a player name. When client receives ExtAddEntity packet for an already-spawned player, a duplicate entity must not be spawned and existing entity's position should not be changed. Instead their InGameName and SkinName should be updated. If a negative ID is given for ExtAddEntity, client must update player's own spawn point, InGameName, and SkinName. The client must ignore regular SpawnPlayer packets, if any are received. Name list should not be affected by ExtAddEntity.
Color codes may be either drawn or stripped from ListName, GroupName, and InGameName.
When a standard DespawnPlayer packet is received for a recognized EntityID, player model should be removed from a world. Name list should not be affected by DespawnPlayer.
When ExtRemovePlayerName packet is received for a recognized NameID, they should be removed from autocompletion list and tab-list. When DespawnPlayer or ExtRemovePlayerName packet is received for a negative or unrecognized PlayerID, no action should be taken.
Server Behavior
When a new player connects to the server, 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 ExtAddEntity in place of standard SpawnPlayer packet. Server should re-send ExtAddPlayerName packet, using the identical PlayerID, when player's ListName, GroupName, or GroupRank change. Server must reliably send an ExtRemovePlayerName when the player disconnects. Color codes are permitted in ListName, GroupName, and InGameName.
ExtAddPlayerName Packet
Server to Client
Packet ID Field Name Field Type Example Notes
0x16

(22)

NameID short 5 Between 0 and 255
PlayerName string Notch Player name used for autocompletion.

May be left empty (exclude from autocompletion).

ListName string &c[Op]Notch Name displayed in the in-game list.
GroupName string Staff
GroupRank byte 0 Rank of a player within the group.

A lower number means higher rank.

Total Size: 196 bytes
ExtAddEntity Packet
Server to Client
Packet ID Field Name Field Type Example Notes
0x17

(23)

EntityID byte 5 Between 0 and 127
InGameName string &cNotch Player name to be shown in-game, hovering above player model.
SkinName string Notch Player name whose skin should be used by the client.
Total Size: 130 bytes
ExtRemovePlayerName Packet
Server to Client
Packet ID Field Name Field Type Example Notes
0x18

(24)

NameID short 5 Between 0 and 255

Matches NameID of the ExtAddPlayerName packet

Total Size: 3 bytes

BlockDefinitionsExt

Version 1 (Deprecated since 9 May 2016)

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 custom block types that do not have minX/Y/Z values of 0, and maxX/Z values of 1.
Client Behavior: See the BlockDefinitions specification. Additionally, this extension depends on EnvMapAppearance extension and BlockDefinitions, and must only be enabled if BOTH extensions are mutually supported.
Texturing: See the 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 the BlockDefinitions specification.


This packet is the same as DefineBlock packet, except the 'shape field' is replaced by 6 fields indicating the bounding box of the block in pixel coordinates. Note that this packet does not support sprites, you must send a regular DefineBlock packet for that.

DefineBlockExt Packet
Server to Client
Packet ID Field Name Field Type Example Notes
37 Following fields from DefineBlock packet: BlockID, Name, Solidity, MovementSpeed, TopTextureID, SideTextureID, BottomTextureID, TransmitsLight, WalkSound, FullBright
MinX byte 0 Minimum X coordinate in pixels. Min allowed is 0, max allowed is 15.
MinY byte 0 Minimum Y coordinate in pixels. Min allowed is 0, max allowed is 15.
MinZ byte 0 Minimum Z coordinate in pixels. Min allowed is 0, max allowed is 15.
MaxX byte 16 Maximum X coordinate in pixels. Min allowed is 1, max allowed is 16.
MaxY byte 16 Maximum Y coordinate in pixels. Min allowed is 1, max allowed is 16.
MaxZ byte 16 Maximum Z coordinate in pixels. Min allowed is 1, max allowed is 16.
Following fields from DefineBlock packet: BlockDraw, FogDensity, FogR, FogG, FogB
Total Size: 85 bytes

EnvMapAppearance

Version 1 (Deprecated since 9 May 2016)

This extension allows the server to specify custom terrain textures, 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 packets any time during level load (after the first LevelDataChunk packet is received and until the LevelFinalize packet is received). If the TextureURL field is blank or if the given file could not be loaded for any reason, then the texture pack should be reset to client's default. If an unsupported block ID is given for SideBlock or EdgeBlock, it should be ignored. 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 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 default value, server should send an EnvMapAppearance packet with empty string for TextureURL. 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 packet
Server to Client
Packet ID Field Name Field Type Example Notes
0x1E

(30)

TextureURL string http://somesite.net/terrain.png Skin's full URL.

Must be an HTTP URL, ending with .png, and served with image/png 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

Version 2 (Deprecated since 21 June 2017)

This extension allows the server to specify custom texture packs, and tweak appearance of map edges.
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. If a .png is instead served, this is assumed to represent a terrain.png image.

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 not listed below. If clients recognise these other files, then they may perform whatever is desired with them.
Note: If a texture pack does not contain a certain texture, clients should continue to use the existing texture from the previous texture pack.
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'.