Difference between revisions of "Classic Protocol Extension/Proposals"

From wiki.vg
Jump to navigation Jump to search
(→‎Custom Block: editing client/server behavior. 50% done)
Line 179: Line 179:
 
| class="col1 rightalign" colspan="4" | 66 bytes
 
| class="col1 rightalign" colspan="4" | 66 bytes
 
|}
 
|}
===Custom Block===
+
===BlockDefinitions===
:Proposed by Rayne and Hetal on behalf of the MCForge team
+
:Proposed by Rayne and Hetal on behalf of the MCForge team, with contributions by fragmer.
:This extension allows support for custom blocks
+
:This extension allows servers to define new block types with custom IDs and appearance.
:'''Motivation''': The motivation of this extension is to give the server a reliable way to add blocks into the client without actually modifying the client.
+
:'''Motivation''': To allow defining block types without client modifications. To make full use of custom textures.
:'''Client Behavior''': First of all the client sends the CustomBlock packet consisting of the block Id, a byte stating if it is walk-through'able, liquid, or solid before the Level Finalize packet so it does not interfere with rendering. Then the client will define block into the specified Id if that Id is not already occupied else the client will disconnect gracefully (What we call crashing around here) and link them to a position to the terrain.png (Preferably the Id slot). Then the client will add the block with the specified information and will texture the block with the texture URL. The texture image file will be the same as the previous texture template except that it will consist of only one block so we do not have to redefine the textures of other blocks.
+
:'''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). Client must keep track of all defined blocks between level changes or until they are individually removed with '''''RemoveBlockDefinition'''''.
:'''Server Behavior''': The server will receive the Custom Block packet and start allowing use of the extra blocks. The textures of these blocks can be changed by simply using the EnvSetMapAppearance packet (Which should be sent before Level Finalize after all the blocks have been added) as the positions in terrain.png (It shall parse the texture positions as the Texture Id specified, left to right right after the base textures end; The cracks for Survival Test may be overrided).
+
: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 <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 <code>0</code> (top-left corner) through <code>255</code> (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 <code>terrain.png</code>) to avoid changing appearance of standardized blocks that use them. Positions 128-255 (the bottom half of <code>terrain.png</code>) 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 '''''[[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.
 +
 
 
:2 new packets will be introduced. ADD_CUSTOM_BLOCK composes of: byte BlockID; byte topTextureId; byte sideTextureId; byte bottomTextureId; [Texture positions on terrain.png] byte breakSound (Any sound in the client's sound enum); byte walkSound (Any sound in the client's sound enum); byte modelType (solidCube(0), transparentCube(1), slab(2), liquid(3), sprite(4)), . REMOVE_CUSTOM_BLOCK composes of just the block Id which is a byte (Also sent before Level Finalize). If the composition is 1, then the player shall be able to swim through the block at the same speed as water. If the composition is 2, the player will not be able to walk through the block (unlike flowers). The server must support both EnvMapAppearance and this extension for the extension to work properly.
 
:2 new packets will be introduced. ADD_CUSTOM_BLOCK composes of: byte BlockID; byte topTextureId; byte sideTextureId; byte bottomTextureId; [Texture positions on terrain.png] byte breakSound (Any sound in the client's sound enum); byte walkSound (Any sound in the client's sound enum); byte modelType (solidCube(0), transparentCube(1), slab(2), liquid(3), sprite(4)), . REMOVE_CUSTOM_BLOCK composes of just the block Id which is a byte (Also sent before Level Finalize). If the composition is 1, then the player shall be able to swim through the block at the same speed as water. If the composition is 2, the player will not be able to walk through the block (unlike flowers). The server must support both EnvMapAppearance and this extension for the extension to work properly.
 
:'''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").
 
:'''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").

Revision as of 08:12, 25 October 2014

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

PlayerClick

Proposed by umby24
This extension is used to alert server owners that a player has clicked on something.
Motivation: The motivation for this extension is to allow for the creation of more interactive maps.
Client Behavior: Whenever a client clicks on something (right, middle or left click) the client should send a PlayerClicked packet to the server.
Server Behavior: Server should be ready to accept PlayerClicked packet at any time after level sending has completed. At which point, handling of this packet is entirely up to the server developer.

PlayerClicked packet

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

(??)

Button byte 0 0 = Left click, 1 = Middle click, 2 = Right Click
Total Size: 2 bytes
(Comments go here, please sign them)

CustomWorld

Proposed by Rayne
This extension is used to customize the world by allowing the server to assign different textures to mobs and blocks
Motivation: The motivation for this extension is to allow the server to create their own custom mobs and blocks without needing to modify the client. This means hosts could improve their minigames by adding skins to easily recognize the two different teams and creating skins to represent different entities in a role-playing server.
Client Behavior: The client must receive the URL of the skin and the entity to assign it to, to be ready to download the resource and give the skin to the entity. If the resource isn't found nothing else happens
Server Behavior: The server should send a valid URL which locates the source and the ID of the entity to assign the skin to.

SetSkin packet

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

(??)

EntityID byte 0 The id of the entity
SkinURL string "http://www.example.com/image.png" The URL to download the resource from
Total Size: 66 bytes

BlockDefinitions

Proposed by Rayne and Hetal on behalf of the MCForge team, 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). 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.
2 new packets will be introduced. ADD_CUSTOM_BLOCK composes of: byte BlockID; byte topTextureId; byte sideTextureId; byte bottomTextureId; [Texture positions on terrain.png] byte breakSound (Any sound in the client's sound enum); byte walkSound (Any sound in the client's sound enum); byte modelType (solidCube(0), transparentCube(1), slab(2), liquid(3), sprite(4)), . REMOVE_CUSTOM_BLOCK composes of just the block Id which is a byte (Also sent before Level Finalize). If the composition is 1, then the player shall be able to swim through the block at the same speed as water. If the composition is 2, the player will not be able to walk through the block (unlike flowers). The server must support both EnvMapAppearance and this extension for the extension to work properly.
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)66/*BulletBlockId*/, (byte)2);, and if my textureUrl in the EnvMapAppearance sent afterwards was actually containing a bullet in the correct slot, the block would inherit actual bullet textures making it realistic and yet again fun.

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 / Java / 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: Very hard to create custom fonts.
    • 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: Harder to implement (no native support in WinAPI / Java / C#).
    • Con: Impossible to create custom fonts.
    • Con: Very 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