feat: enable cooldown group data keys

Signed-off-by: Gabriel Harris-Rouquette <gabizou@me.com>

src/main/java/org/spongepowered/api/data/Keys.java

@@ -100,6 +100,7 @@
 import org.spongepowered.api.data.value.MapValue;
 import org.spongepowered.api.data.value.SetValue;
 import org.spongepowered.api.data.value.Value;
+import org.spongepowered.api.data.value.ValueContainer;
 import org.spongepowered.api.data.value.WeightedCollectionValue;
 import org.spongepowered.api.effect.VanishState;
 import org.spongepowered.api.effect.particle.ParticleEffect;
@@ -185,6 +186,7 @@
 import org.spongepowered.api.entity.living.monster.spider.Spider;
 import org.spongepowered.api.entity.living.monster.zombie.ZombieVillager;
 import org.spongepowered.api.entity.living.monster.zombie.ZombifiedPiglin;
+import org.spongepowered.api.entity.living.player.CooldownTracker;
 import org.spongepowered.api.entity.living.player.Player;
 import org.spongepowered.api.entity.living.player.User;
 import org.spongepowered.api.entity.living.player.chat.ChatVisibility;
@@ -223,6 +225,7 @@
 import org.spongepowered.api.item.enchantment.EnchantmentTypes;
 import org.spongepowered.api.item.inventory.Inventory;
 import org.spongepowered.api.item.inventory.ItemStack;
+import org.spongepowered.api.item.inventory.ItemStackLike;
 import org.spongepowered.api.item.inventory.ItemStackSnapshot;
 import org.spongepowered.api.item.inventory.Slot;
 import org.spongepowered.api.item.inventory.equipment.EquipmentType;
@@ -239,6 +242,7 @@
 import org.spongepowered.api.projectile.source.ProjectileSource;
 import org.spongepowered.api.raid.Raid;
 import org.spongepowered.api.raid.RaidWave;
+import org.spongepowered.api.registry.DefaultedRegistryType;
 import org.spongepowered.api.statistic.Statistic;
 import org.spongepowered.api.tag.Tag;
 import org.spongepowered.api.util.Axis;
@@ -752,9 +756,24 @@ public final class Keys {
      * The amount of ticks a {@link EndGateway} has to wait for the next teleportation.
      * or
      * The amount of ticks a {@link Crafter} has to wait for the next craft.
+     * or
+     * The amount of ticks an {@link ItemStack} has to wait before being used again, primarily in conjunction
+     * with {@link #COOLDOWN_GROUP} in a joined {@link ValueContainer} to be offered as a custom cooldown. Using
+     * a {@link DataManipulator#mutableOf( Iterable)} to set this value using {@link Value#mutableOf( Key, Object)}
+     * to join together a group is ideal.
      */
     public static final Key<Value<Ticks>> COOLDOWN = Keys.key(ResourceKey.sponge("cooldown"), Ticks.class);
 
+    /**
+     * The {@link ResourceKey group} of an {@link ItemStackLike ItemStack} that would apply a
+     * cooldown to the item when used. Note that this affects the {@link CooldownTracker} when
+     * a {@link Player} uses the item. Can be used in tandem with the {@link #COOLDOWN} key
+     * to apply a cooldown to said group. A group will differentiate a cooldown from the default
+     * {@link ItemStackLike ItemStack} cooldown based on the
+     * {@link ItemType#key(DefaultedRegistryType) ResourceKey}.
+     */
+    public static final Key<Value<ResourceKey>> COOLDOWN_GROUP = Keys.key(ResourceKey.sponge("cooldown_group"), ResourceKey.class);
+
     /**
      * The coordinate scale of a {@link WorldType} applied to the coordinates of a {@link ServerPlayer player}
      * when traveling in between {@link ServerWorld worlds}.

src/main/java/org/spongepowered/api/entity/living/player/CooldownTracker.java

@@ -58,6 +58,13 @@ public interface CooldownTracker {
      */
     Optional<Ticks> cooldown(ItemStack stack);
 
+    /**
+     * Gets the cooldown for the specified {@link ResourceKey group} in ticks
+     * for the player, or empty if the group is not on cooldown.
+     *
+     * @param group The group to get the cooldown for
+     * @return The cooldown remaining for this group in ticks, if not on cooldown
+     */
     Optional<Ticks> cooldown(ResourceKey group);
 
     /**