This plugin allows server owners to control the World Downloader mod (sometimes refered to as WorldDownloader, WorldDL, or WDL) on their server, using its plugin channel API. It supports a wide range of functions, from simply disabling the mod to permission requests to only allowing downloading in certain areas.

World Downloader mod in "Request permissions" mode - the "request permission to download" button is currently hovered over

Why use WDLCompanion over other plugins? What features does WDLCompanion have?

The main benefit of WDLCompanion is that it fully implements WDL's plugin channel API, rather than simply kicking players immediately upon joining (which is horrible user experience). This gives you, as a server owner, a much wider degree of control over how WDL is used.

For basic configuration, you can toggle whether WorldDL can download at all, or set more specific settings (chunk caching, saving of entities, saving of tile entities, etcetera). This configuration can be global and can also be for specific worlds on your server.

You can also use the standard bukkit permissions system to grant players permissions. Those permissions are documented here.

WDLCompanion does some custom logging logic, so messages generated by it (player login, player request) are saved both in your global server log and in a custom log as a subfolder of the server log folder. This functionality can be disabled if you desire.

This plugin also allows for permission requests. If you want to allow players to use WDL, but not without your permission, this is the easiest way of doing so. They can request permission directly from inside the mod. (This is still a work in progress and the mod side of things isn't completely done, although it is functional). Permission requests allow you to temporarily grant a player permission and will expire after a configurable amount of time.

One of the most powerful features of this plugin is chunk overrides. Chunk overrides allow you to specify areas where players are always able to download regardless of the other parts of the map. This may not seem too powerful, but the key part is that these don't have to be static areas. For simple cases, you can just put a set of coordinates in the configuration file and use those, but there is a fully-functional API for dynamically generating chunk overrides from other plugins on a player-by-player basis. For instance, if you run a factions server, you can configure it so that players are only able to download in their own faction, or in their own faction and in wilderness areas, or anything else! If a player wants to download in an area that's not covered by an existing chunk override, they can just submit a permission request.

And before you ask: Yes, I am also the developer of the World Downloader mod. This is the official implementation of the plugin channel API. It's not going to break when the mod updates.

Usage

The main way you use this plugin is editing its configuration file.

Configuration

The default configuration file (viewable here) is fully annotated, so if you are unsure about what any setting does, look there first. Additionally, incorrect configuration files will generate warnings or errors in-game, letting you know what is wrong and how to fix it.

If you just want to disable World Downloader, all you need to do is set canDownloadInGeneral to false. That's all you need to do. (The other settings can remain true or false; if canDownloadInGeneral is false they are inferred to be false). Players will still be able to join, and can request permission still. I recommend that you set requestMessage to something for players who are requesting, so that they know your rules regarding use of the mod. You will need to reload the configuration using /wdl reload after making changes to it.

If you want to configure something for a specific world, edit the per-world tag. Inside of it, first put the world name (as it would appear in the world folder), and then put keys from the general configuration file there. If a value is not set in the per-world secion, the global value is used instead. If the world has multiple dimensions, you will need to specify all dimensions for the world name.

For chunk overrides, the configuration is a bit more complicated. By default, there are two types of chunk overrides: ChunkRange and BlockRange. These two are very similar with the only difference being that one works in chunk coordinates and the other in block coordinates. For both, there are minimum and maximum x and z coordinates, where having both the minimum and maximum set to each other gives a single chunk. BlockRange will round to the nearest chunk, due to the way WDL works. Both optionally can be confined to a specific world, specified by the world property.

Chunk overrides have a name (which is the key name for the configuration section) and optionally a tag. Both of these are mainly important in logging but are still sent to the client. tag doesn't really matter for simple chunk ranges, but is useful when it's something that updates dynamically (as packet optimizations can occur with it). Here's a sample configuration that defines two chunk overrides:

region1:
  type: BlockRange
  world: world
  tag: Freebuild area
  x1: 1000
  z1: 1000
  x2: 1100
  z2: 1250
region2:
  type: ChunkRange
  tag: Spawn chunks
  x1: -5
  z1: -5
  x2: 5
  z2: 5

Extension plugins are able to define additional types of chunk overrides. Generally, that plugin will document the structure of its own overrides (and should also provide warnings/errors when it is done incorrectly). See the extensions section below for a list of known extensions.

For more information on the configuration file, look here.

This plugin also has several permissions which can be used to grant players permission to use WDL.

Commands

As a player:

/wdl updateme - refresh your clientside permissions (generally shouldn't be necessary but can be used when permissions are changed). This can also be performed from inside of the mod.

As a moderator:

/wdl reload - reload the plugin configuration (/reload or /restart will also do this)
/wdl update <player> - manually update the given player's permissions (generally should not be necessary)
/wdl updateall - manually update the permissions of all online players (generally should not be necessary)
/wdl requests list [page] - list all current permission requests
/wdl requests show <player> - show the given player's request
/wdl requests accept <player> - accept the given player's request
/wdl requests reject <player> - reject the given player's request
/wdl requests revoke <player> - revoke the given player's request after it has been accepted

Note about World Downloader

Please don't treat players as guilty just because they have World Downloader installed. There are several legitimate reasons to have the mod installed:

To make a backup of something you've built (this is why I develop the mod)
To go into creative mode to experiment with building in single player before returning to multiplayer to actually build
To export 3D models of a build for use in fan art (this requires other tools beyond just WDL but is a common use nevertheless)

Also, WDL sends the permission packet whenever it joins the server (so that it can have accurate permission information before starting download). Just because the plugin says a player has the mod installed doesn't mean that they actually used it.

In general, if you're running a server where players build, players should be able to use the mod on their own builds. On the other hand, if you're running a minigame server or similar, it makes sense to block the mod by default.

Contributing

This plugin is open source; you can view the source code on github. Feel free to open issues there or submit pull requests.

If you want to create your own type of chunk override, look here for various examples.

The base World Downloader mod is also open source. Feel free to make suggestions there.

For information on WDL's plugin channel API, refer to the wiki.vg article.

Extensions

WDLCompanion has several extensions to integrate with other plugins, generally providing additional types of chunk overrides:

Have you written an extension that you want to add to this list? Let me know!

MCStats disclaimer

This plugin uses MCStats (pluginmetrics) for anonymous statistics. You can view these statistics here.