World Downloader API / WDLCompanion
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.
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:
- A Skyblock support for WDLCompanion
- Factions support for WDLCompanion
- WorldGuard support for WDLCompanion
- RedProtect support for WDLCompanion
- GriefPrevention support for WDLCompanion
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.
@Pokechu22
Yes, thanks. :)
@Dilen2002
Sorry for the confusion; it wasn't intended to be a link, but rather a comment about documentation for extensions. I've edited it to be (hopefully) more clear, and also added a section about extensions - does it make more sense now?
Hello! Your link to chunk override examples doesn't work.
@Pokechu22
Ohh, thank you, I had no idea that because a lot of English and I did not read above information
Sorry for my bad english
@zuhir
Did you edit your configuration file (config.yml)? By default, the plugin does not change any settings of the mod, only log that the player joined. You need to set the "canDownloadInGeneral" value to "false" for the download button to change.
The plugin does not work for me: /. In the console I get the player to come with WDL but when playing the "Download world" do not ask me anything special: /
Sorry for my bad english :/
@ShaneHD
When it syndicates, you can add the Factions support for WDLCompanion plugin to use factions. Unfortunately it's taking longer than I'd expect for it to get approved :/
Everything's configurable in game with /f perm (on a faction-by-faction and relation-by-relation basis). I think it's an extremely flexible system. There's an example configuration on that plugin page.
I've got separate extension plugins since it simplifies dependency management and also lets me release other ones without needing to update this plugin.
@ShaneHD
That's doable, although I'll need to make a few tweaks to the factions extension plugin (which I haven't uploaded yet).
I want people only to be able to download faction bases, with a blacklist for faction names.
@Th3PotatoArmyHD
Not a public one, but I can say as the developer of both the plugin and the World Downloader mod, it should restrict it.
Note that you do need to set up the configuration for it to do anything.
yh thanks seen that after i posted my comment lol
@F64_Rx
Did you enable it in the configuration? (set logMode to "individual" or "combined"). Also, note that the logs folder for the plugin is a subfolder for the main logs folder, not the plugins folder.
[16:48:28] [Server thread/INFO]: [WDLCompanion] Player F64_Rx has WDL enabled.
says this in my normal log but no other logs gets generated in my folder
download couple mins after if w as released xD
@F64_Rx
FYI, I actually did upload a new version with the logging support (and it was approved a little while ago).
oh ok
@F64_Rx
There's some stuff you can do with liteloader that I don't know the details of, but it's not very practical. I don't know of any way to handle the coremod versions.
not if you can but is there anyway of blocking older versions of wdl?
@F64_Rx
It'll come out around when the next version of WDL comes out. Mainly so that new features are included in the config. Although I actually could do a release now with some of those features.
any news on update :p