World Downloader API / WDLCompanion 1.2.0

The official implementation of the World Downloader plugin channel API

  1. pokechu22
    Tested Minecraft Versions:
    • 1.8
    • 1.9
    • 1.10
    • 1.11
    • 1.12
    • 1.13
    • 1.14
    Source Code:
    https://github.com/Pokechu22/WorldDownloader-Serverside-Companion
    Contributors:
    Pokechu22

    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.

    [​IMG]

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


    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. (Also, note that as of version 1.1.0, the default configuration documentation for chunk overrides is incorrect). 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:

    Code (Text):

    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

    A note about World Downloader Mod


    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.
    Tyrelis, _Drezed_, ScuroK and 6 others like this.

Recent Updates

  1. Version 1.2.0
  2. Version 1.1.4
  3. Version 1.1.3

Recent Reviews

  1. coolpvpv
    coolpvpv
    5/5,
    Version: 1.2.0
    very good it does detect worlddownloader so i would recommend this for some servers
  2. ShadedPL
    ShadedPL
    5/5,
    Version: 1.2.0
    Very elegant solution! Are there any plans to release it to 1.14? I see the original mod is already on that version. Thanks in advance :)
  3. SomeonePIX
    SomeonePIX
    5/5,
    Version: 1.1.4
    Cool thank you for updating. But please check around for other bypassed WDL version and keep it updated for preventing this and other hacked WDL which can be work, nice job tnx
  4. SomeonePIX
    SomeonePIX
    5/5,
    Version: 1.1.3
    Cool plugin to prevent WDL but some WDL cant be detected. Dou you planing some update pls in future? tnx
  5. Exeyelius
    Exeyelius
    5/5,
    Version: 1.1.3
    Great plugin, so many retards thinking it's 1.7 available lmao. Anyways, cheers boi for this plugin!
  6. Sollembum78
    Sollembum78
    5/5,
    Version: 1.1.3
    @jCripton Page clearly says it's for 1.8 and up, your'e being stupid rating this plugin bad for what it not suppose to do. Rate for what it claims to be and how well it does.
  7. jCripton
    jCripton
    2/5,
    Version: 1.1.3
    WDLCompanion don't work on PaperSpigot 1.7.10, fix it please.
    I can download the maps (Not OP) !! I really need it, your plugin is useful :(
  8. Visur
    Visur
    5/5,
    Version: 1.1.2
    The only plugin that works! And this is why every single review is a five star. Keep up the work! Nothing "not" working ;)! Keep us updated on this plugin please!
  9. dev_rauf
    dev_rauf
    5/5,
    Version: 1.1.2
    Super plugin. Works like a charm.
    Couldn't you make one for version 1.5.2?
    You are the best ;)
    --------------------------------------------------------------------------------------------------------
    1. pokechu22
      Author's Response
      Oh, whoops, didn't see this review for a while. Unfortunately it's not possible to port this for 1.5.2 as WDL's plugin messaging interface was only added in 1.8 versions (and backported to 1.7.10) - 1.5 builds are no longer being maintained.
  10. Isaacey
    Isaacey
    5/5,
    Version: 1.1.1
    Honestly works like a charm, prevents any type of world download interaction to your server.

    Really would recommend!