Package com.ultikits.ultitools.annotations.command

Annotation Interface CmdCD

@Target({METHOD,TYPE}) @Retention(RUNTIME) public @interface CmdCD
Marks a @CmdMapping method as subject to a per-player cooldown.

Enforcement requires a CooldownValidator in the executor's ValidatorChain. The default chain built by BaseCommandExecutor.createDefaultValidatorChain() supplies one. A custom chain that omits CooldownValidator while a mapping -- or the executor class itself -- declares this annotation is refused at plugin load, naming the offending class and, when known, the offending mapping method (SILENT-11 / D-01, D-04). No opt-out exists for this refusal: Phase 3 D-08's module-granularity isolation is the accepted escape hatch -- the offending module alone fails to load, every other module still starts.

As of 6.3.0 this annotation may also be applied at the class level. CooldownValidator resolves it most-derived-wins: a mapping method's own @CmdCD first, then a class-level one on the concrete executor class, then one on the method's declaring class. A class-level annotation therefore cools down every mapping that does not declare its own.

Binding the cooldown to a config key (6.3.0)

Instead of value(), key() can name a @ConfigEntry path on the module's own config entity, given by config(); the value is in seconds, like value(): 

 @CmdCD(config = EssentialsConfig.class, key = "features.wild.cooldown")
  • The default lives only in the config field. Leave value() unset; setting both refuses the module at load.
  • Checked at load, refusing the module alone and naming the key and the value, when the config class is not registered exactly once for the module, the key matches no @ConfigEntry path, the field is not an int, long, Integer or Long, or the value is negative, null or above Integer.MAX_VALUE. A bound value of 0 means "no cooldown", the same as value = 0.
  • Applied at /ul reload. The resolved seconds are cached per executor and refreshed only after a successful configuration reload, so a panel edit takes effect at the next /ul reload and a refused reload never takes effect. An invalid value on reload keeps the running one, logs a WARNING and reports the reload as partial, naming the key, the refused value and the value kept (#595). A cooldown already running keeps the end time it was stamped with, whatever the new value is: a reload to 0 stamps no new cooldown, and the running ones expire on their own. Executors sharing one validator chain keep all their bindings.
  • Panel edits are range-checked. A panel write that sets a bound key outside this range (a negative value, for example) is refused like a @Range violation, and nothing is written.
  • No @Range on a bound field. The binding's range above is the field's range. A module @Range on the same field would make an out-of-range reload throw from the config reload itself, which aborts the rest of that module's reload (issue #509) instead of keeping the running value.
  • Modules only. A binding in an External Plugin API executor is refused.
  • Declare api-version: 630 in the module's plugin.yml: an older framework silently ignores these elements and would enforce no cooldown at all. 6.3.0 refuses a module that uses a binding while declaring a lower api-version.
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<? extends AbstractConfigEntity>
    config
    Config entity class whose @ConfigEntry key key() names; it must be registered exactly once for the module.
    String
    key
    @ConfigEntry path whose value, in seconds (0 for no cooldown), is the cooldown.
    int
    value
     

  • Element Details

    • value

      int value
      Returns:
      cooldown time in seconds; a value of 0 or less disables the cooldown for this mapping. Leave unset when key() is set.
      Default:
      0

    • config

      Class<? extends AbstractConfigEntity> config
      Config entity class whose @ConfigEntry key key() names; it must be registered exactly once for the module. Default: AbstractConfigEntity itself, meaning unbound. See "Binding the cooldown to a config key" above.
      Returns:
      the bound config entity class
      Since:
      6.3.0
      Default:
      com.ultikits.ultitools.abstracts.AbstractConfigEntity.class

    • key

      String key
      @ConfigEntry path whose value, in seconds (0 for no cooldown), is the cooldown. Matched as @ConfigEntry(path = ...) declares it, or the field name when the path is empty. Requires config(); excludes value(). Default: unbound.
      Returns:
      the bound cooldown key
      Since:
      6.3.0
      Default:
      ""