AstroBackCooldown Documentation

Requirements: Paper, Purpur, or Folia server running Minecraft 1.20+. Java 21+.

Two-tier (default + VIP)

VIPs get 10s, defaults get 60s.

cooldowns:
  default: 60
  vip: 10
  # Add more groups as needed
  staff: 0
fallback-cooldown: 60
ignore-permission: "astrobackcooldown.bypass"
ignore-on-essentials-bypass: true

Five-tier ranks ladder

Each rank gets a faster /back. Top tier has no cooldown.

cooldowns:
  default: 120
  vip: 60
  vip-plus: 45
  mvp: 30
  mvp-plus: 15
  king: 5
  immortal: 0
fallback-cooldown: 120

PvP server (long cooldown)

Strict cooldowns to prevent /back from being a get-out-of-PvP card.

cooldowns:
  default: 600  # 10 minutes
  vip: 300
  mvp: 180
  staff: 0
fallback-cooldown: 600
pvp-extra-seconds: 300  # additional cooldown if died in PvP

Skyblock (very short for everyone)

Players /back constantly between their island and warps.

cooldowns:
  default: 5
  vip: 0
fallback-cooldown: 5

Config location

Give VIPs faster /back without buying CMI

Scenario: You run EssentialsX. You added a VIP donation tier and want them to get a 10s /back cooldown vs the default 60s.

1. Install AstroBackCooldown.
2. Edit config.yml: set cooldowns.vip = 10, cooldowns.default = 60.
3. Make sure LuckPerms is installed (it is the source of the group lookup).
4. Test: /lp user <yourself> parent set vip, /back, then /back again within 10s — should work the second time.

No cooldown for staff

Scenario: Staff respond to tickets and teleport between players constantly.

1. Set cooldowns.staff: 0 in config.yml.
2. OR grant astrobackcooldown.bypass via LuckPerms — both work.
3. Test by switching to staff group and verifying no cooldown enforcement.

Extra PvP penalty

Scenario: Players use /back to escape PvP fights. You want to discourage this with a higher cooldown after a PvP death.

1. Set pvp-extra-seconds: 300 in config.yml.
2. Plugin tracks PvP deaths via EntityDamageByEntityEvent.
3. Next /back after a PvP death adds 300s on top of the normal cooldown.

Disable cooldown during weekend events

Scenario: You run no-cooldown weekends as a community perk.

1. Run /backcd disable from console at event start.
2. Run /backcd enable at event end.
3. Or schedule both via cron with /backcd schedule weekend.

Tip: Use LuckPerms to manage permissions per player or group.

EssentialsX (required)

AstroBackCooldown intercepts the /back command before EssentialsX processes it. EssentialsX must be installed and the /back command enabled.

LuckPerms (required)

Source of the player's group. Without LuckPerms, all players fall through to 'default' cooldown.

CMI

CMI replaces /back with its own implementation. AstroBackCooldown does NOT intercept CMI's /back. To use both, disable CMI's /back or alias it.

WorldGuard

If a region has flag 'use back: deny', /back fails before our cooldown applies. No conflict.

Cooldown applies to all players regardless of group

Cause: LuckPerms not installed or player has no group set.

Fix:

• Install LuckPerms.
• Verify with /lp user <player> info — primary group should match a key in cooldowns.<group>.
• If no LuckPerms, the plugin uses fallback-cooldown for everyone.

VIP players still wait the default cooldown

Cause: Group name typo in config.yml or VIP is not the primary group.

Fix:

• Match group keys exactly: 'vip' not 'VIP' or 'Vip'.
• Make sure VIP is the primary group: /lp user <player> info, check 'primary group'.
• If they inherit VIP via track, you need to set it as primary explicitly.

Cooldown never expires (player is locked out forever)

Cause: Plugin failed to track the cooldown end time, server clock changed, or restart cleared in-memory state.

Fix:

• Run /backcd reset <player> to clear their cooldown manually.
• Set 'persist-cooldowns: true' in config.yml to save cooldown state across restarts.
• Check server clock with `date` — drastic time changes can confuse the cooldown calculation.

Cooldown applies to /home, /spawn too

Cause: Misconfiguration — AstroBackCooldown only listens for /back. Other commands are handled by Essentials' built-in cooldowns.

Fix:

• Check Essentials' config.yml for other command cooldowns (Essentials supports per-command cooldown).
• AstroBackCooldown does not intercept anything except /back and /back <player>.

Does this work without EssentialsX?

No. EssentialsX provides the /back command itself. AstroBackCooldown only adds a cooldown overlay. Without Essentials there is no /back to override.

Can I have a cooldown per world?

Not in 1.0. Per-world cooldowns are on the roadmap. Workaround: use Essentials' built-in 'no-back-in-other-worlds' option to disable /back in worlds where you want strict rules.

How does it handle a player who switches groups mid-cooldown?

The cooldown was set based on the group at /back time. Switching groups does not reset the cooldown. Next /back uses the new group's cooldown.

Will it persist cooldowns across server restarts?

Only if 'persist-cooldowns: true' is set. Default is false (cooldowns reset on restart) to keep things simple.

Can I bypass the cooldown for a single command (admin override)?

Yes. /backcd bypass <player> grants a one-shot bypass — the next /back ignores cooldown. /backcd bypass <player> permanent grants a permanent bypass equivalent to the bypass permission.

Does pvp-extra-seconds stack with itself?

No. The PvP extra is added once per /back call. If a player dies in PvP, /back's, dies in PvP again, /back's, the extra applies fresh each time, not stacked.

What is the performance overhead?

Negligible. One HashMap lookup per /back call, one PlayerCommandPreprocessEvent listener. Tested at 0% TPS impact on a 100-player server.

Can I customize the cooldown message shown to the player?

Yes. Edit 'cooldown-message' in config.yml. Default: '&cYou must wait %seconds% more seconds before using /back.'

v1.0.02026-05-13

• Initial public release
• Per-LuckPerms-group cooldowns
• Optional PvP extra cooldown
• astrobackcooldown.bypass permission
• /backcd commands (bypass, reset, enable, disable, reload)
• Customizable cooldown message