Plugin channels/World downloader

Documentation of the World Downloader mod's plugin channel configuration system.

Implemented in-mod here. A bukkit implementation is available here.

Regarding channel names: 1.13 has necessitated namespacing the channels, i.e.,  ,   instead of  ,  ,. Support for both channel names has been backported to 1.12, and it will automatically select whichever channels are supported. If targetting older MC versions, make sure to listen and respond on both sets of channels.

A note before implementing these channels
Please do not misuse these channels, and please do implement the full collection (including permission requests). They only make sense when used completely.

These channels have been designed in a very deliberate way, so that players should not need to circumvent the system for valid uses of the mod (and yes, there are valid uses (perhaps the majority are, even)... otherwise, these channels wouldn't exist!). Implementing only a subset and neglecting permission requests means that players need to go through other channels, of which you don't have control over. Implementing permission requests allows you to set specific policies for use of the mod, something that isn't possible any other way.

These channels act as a guideline that governs how you wish the mod to be used on your server. Obviously, it can't be a hard rule (that's very much technically impossible), so choose something granular and practical.

Data types
All types here are as specified by Java's and can be read using a, unless otherwise noted. They do not use the standard protocol data types. Additionally, the format is not directly compatible with some standard channel implementations - if you use forge or sponge's default indexed codecs, things won't work right (those use 1 byte; this uses 4 bytes).

Chunk Overrides
Chunk Overrides are areas that the player is allowed to download in even if the rest of the map is restricted. As the name suggests, it is defined by a chunk's area.

If the start and end x coordinates are the same, the chunk at that position can be saved (they are both inclusive).

Implementations are encouraged to try and merge chunk overrides with the same tag before sending, but this is not required.

A Chunk Override has the following structure:

is sent to show that World Downloader is ready to receive new permissions. Don't send permissions until this is received - it may still be saving from another part of the map or another sever where it has permission, and revoking permission in the middle of (allowed) saving is a Bad Thing&trade;.

Content is not present on very old versions of the mod. In all versions where it is present, content is a UTF-8 string. In older versions, it is a simple version number; in newer versions, it is a JSON blob that contains some information including the version; if it starts with a  then it MUST be a valid JSON blob. The exact specification for the JSON blob has not been finalized, but it currently contains the following information fields:


 * A version number.
 * A version number.


 * Will include information about why the INIT packet is being sent, however values are unspecified at this time.
 * Will include information about why the INIT packet is being sent, however values are unspecified at this time.

Additionally there are fields starting with "X-", which are provided for information purposes only.


 * A link to this documentation.
 * A link to this documentation.


 * Contains information about the state of this system; will include information about when the channels change. Currently.
 * Contains information about the state of this system; will include information about when the channels change. Currently.

This channel is sent from the server to the client to specify various permissions. It uses a 4-byte integer at the start to indicate a section. There is no required order, but it is conventional to put them in numerical order.

In all cases unless otherwise indicated, if a packet is not sent its values are treated as 'true'.

Default values
Specifies the default value used for permissions not sent.

Note that sending this packet does not actually change the value for other packets; it instead specifies an internal fallback. Thus, this packet can be sent at any time to change this default without needing to resend other packets.

Basic data
Sets some of the standard properties.

Entity track distances
Used to specify any custom entity track distances on the server, because they may change on spigot servers. More info on why this is needed on the project wiki.

The client is free to ignore these values, and will use sane defaults based off of whether the server's brand includes "spigot" if they are not sent. However, by default these values are used.

Permission request info
Information used with permission requests.

Set chunk overrides
Sets the entire set of chunk overrides.

Modify group chunk overrides
Add chunk overrides to a group or sets chunk overrides in that group.

Remove chunk overrides by tag
Removes chunk overrides with the given tag from a specific group.

Set chunk overrides by tag
Sets all of the chunk overrides in a single with a specific tag to a new set.

Note: All of the new ranges should have the same tag as the tag that is being replaced.

Used for permission requests. Sent from the client to the server. On the server, a moderator/admin/whoever can approve or deny the request, and then other messages are sent to grant such permissions.

Valid fields and their values:


 * : Whether or not chunks downloading in all terrain is allowed.   if so,   otherwise.
 * : Whether chunks can be cached as the player moves about the world.   if so,   otherwise.
 * : Distance from the player chunks can be saved (in a square). If -1, all distance is allowed.  Only applies when   is not true; if that is true this is ignored and thus in most cases that should be done (since a value of -1 still only allows saving what can be seen).  The value is an integer as a string, potentially negative.
 * : Whether or not entities can be saved.   if so,   otherwise.
 * : Whether tile entities can be saved as the player moves about the world.   if so,   otherwise.
 * : Whether chests and other tile entities that require manual interaction can be saved as the player moves about the world. Requires   to also be true.    if so,   otherwise.
 * : Whether entity ranges should be sent to the player.   if so,   otherwise, but if your server doesn't change entity ranges from the vanilla defaults this doesn't need to be sent.

Not all fields need to be set. No field should be specified more than once in a packet. If the field isn't set but was sent on a previous packet, the field should still be unset - clear the last request before adding in the new one (however, if a request was accepted, the requested permissions should not be cleared). A packet without any requests should clear the current request list.