Bukkit

Description

Cooldowns and warmups can be very simple: for example if you just want a 60-second cooldown for "/home" you simply change the "cooldown.home" setting to "60" (in fact, this is the default, so you don't have to do anything at all).

However, in order to support some requests for more elaborate setups, there are additional options that can be changed. These are documented here to give a clearer understanding of how these options interact with each other.

Config cascading

Just like events, warmups and cooldowns support config cascading in the order of: permissons, world, global. So you can define a home cooldown of 30 seconds for the permission "newbie" and then anyone who has permission newbie will have that cooldown. You can define a spawn cooldown of 1800 seconds (30 mins) for your world "otherworld" and then, when on that world, the cooldown is 1800 seconds. However, if your global cooldown is 30 seconds, when players are on world "world", the spawn cooldown will only be 30 seconds.

Two important notes to this per-world behavior is that it is based on the SOURCE world of the player and it is also dynamic in nature. To illustrate, lets assume world A and world B. You have defined the global "/home" cooldown as 60 seconds, but on world B you have defined it as 300 seconds (5 mins). Player has home "homeA" on world A and "homeB" on world B.

1. Player, standing on world A, types "/home homeB". Because they are on world A, the "home" cooldown is checked for 60 seconds. If they haven't run /home in the last 60 seconds, they are teleported to their home "homeB" on world B. This teleport time will be referred to as t.
2. Player, now standing on world B, types "/home homeA" at t+65 seconds. Player is refused the /home and given a message that the cooldown for "home" is still 235 seconds (300-65), because on world B, the configuration says they must wait 300 seconds between uses.
3. Player hops into a multiverse portal and is back on world A. Now at t+70 seconds, they type "/home homeA" and this one succeeds, even though just 5 seconds ago it told them they had 235 seconds to wait. This is because on world A, the cooldown is only 60 seconds.
4. Admin changes the global cooldown to 30 seconds in the config and runs "/hsp rc" to live-reload the config.
5. Player, still standing on world A, types "/home homeA" at t+105 seconds (35 seconds after #3 above). Even though the config was set to 60 seconds when they original typed the command in #3, the cooldown is now 30 seconds as a result of the reload and so the command succeeds.

Cooldown/Warmup per world

If you want to modify the above behavior so that when on world B, player has a 300 second cooldown unique to that world and then the global 60 seconds cooldown applies to all other worlds, you can set the "cooldownPerWorld" flag for world B, like so:

# cooldown example
cooldown:
  home: 60

  world:
    B:
      cooldownPerWorld: true
      home: 300

With this setup, here is an example scenario:

1. Player is on world B and types "/home homeA". If it's been 300 seconds since the last /home command, they will be sent to homeA on world A.
2. On world A, they can immediately type "/home homeB" and will be taken to homeB on world B, because the "home.worldB" cooldown is unique to world B and isn't counted when they are on world A.
3. Now on world B again, if they type "/home homeA", they will be given a cooldown message using worldB's 300 second cooldown timer.

Cooldown/Warmup per permission

Per-permission cooldown/warmups work exactly like per-world, including their own "cooldownPerPermission" flag. Note that per-permission cooldown/warmups are the MOST SPECIFIC.

For example, if you define a 10-second per-permission cooldown for permission "my.custom.perm" and Player X is standing on world B (with the above per-world config), Player X's cooldown will be 10 seconds, not 300. It is done this way because most all Permission systems allow for per-world settings, so if you wanted Player X to be subject to the same 300 seconds cooldown as everyone else on world B, you would just use your permission system to revoke his permission "my.custom.perm" on world B.

Cooldown per home

There is a "cooldownPerHome" setting (warmupPerHome doesn't make sense) that you can turn on globally. When enabled, if a player uses a named home (such as "/home homeA"), a cooldown will be used specific to that home. By default, the cooldown applied will be whatever is used normally by the above cascading checks. In the above 5-step cascading example, if "cooldownPerHome" had been set to true, #2 would have succeeded. This is because in #1, the player used their "home.homeA" cooldown, but "home.homeB" was still available.

If after step 5, the player immediately tried to type "/home homeA" again, it would fail because the cooldown is 30 seconds and they haven't waited that long. However, with "cooldownPerHome" set to true, the player could immediately type "/home homeB" and they would be teleported to their home bar on world B. Once on world B, however, both cooldowns are now used and on world B they have to wait 300 seconds to use either again.

Let's say you wanted to change that behavior, so that each named home is on it's own specific timer independent of the world or global default. You can set the "cooldownPerHomeOverride" config flag to something, let's say 15 seconds. Here's what that might look like now:

1. Player on world A type "/home homeB" - they are transported to their home bar on world B.
2. If they immediately type "/home homeB" again, now standing on world B, they will be told they have a 15 second cooldown to wait, even though world B's cooldown is defined as 300.
3. If they type "/home" with no arguments on world B, the home strategy for world B will be executed. This might, for example, take them to their default home on world B (perhaps this was even set to their home homeB). This works because the default "/home" is not subject to the 15-second cooldown per named home.
4. If they now type "/home" again, they will have a 300 second cooldown to wait until the next one.
5. If they type "/home homeA", they will be transported to home homeA on world A, since cooldown "home.homeA" is unused at this point.