Cooldowns - Add CooldownStyle

api/src/main/java/com/lunarclient/apollo/module/cooldown/Cooldown.java

@@ -27,6 +27,7 @@
 import java.time.Duration;
 import lombok.Builder;
 import lombok.Getter;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a cooldown which can be shown on the client.
@@ -64,4 +65,14 @@ public final class Cooldown {
      */
     Icon icon;
 
+    /**
+     * Returns the cooldown {@link CooldownStyle}.
+     *
+     * <p>If {@code null}, the style defaults to the user's local Cooldown Mod settings.</p>
+     *
+     * @return the cooldown style
+     * @since 1.2.5
+     */
+    @Nullable CooldownStyle style;
+
 }

api/src/main/java/com/lunarclient/apollo/module/cooldown/CooldownStyle.java

@@ -0,0 +1,72 @@
+/*
+ * This file is part of Apollo, licensed under the MIT License.
+ *
+ * Copyright (c) 2026 Moonsworth
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.lunarclient.apollo.module.cooldown;
+
+import java.awt.Color;
+import lombok.Builder;
+import lombok.Getter;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Represents the {@link Cooldown} style, allowing customization of the circle start, end, edge & text color.
+ *
+ * @since 1.2.5
+ */
+@Getter
+@Builder
+public final class CooldownStyle {
+
+    /**
+     * Returns the cooldown circle start {@link Color}.
+     *
+     * @return the circle start color
+     * @since 1.2.5
+     */
+    @Nullable Color circleStartColor;
+
+    /**
+     * Returns the cooldown circle end {@link Color}.
+     *
+     * @return the circle end color
+     * @since 1.2.5
+     */
+    @Nullable Color circleEndColor;
+
+    /**
+     * Returns the cooldown circle edge {@link Color}.
+     *
+     * @return the circle edge color
+     * @since 1.2.5
+     */
+    @Nullable Color circleEdgeColor;
+
+    /**
+     * Returns the cooldown text {@link Color}.
+     *
+     * @return the text color
+     * @since 1.2.5
+     */
+    @Nullable Color textColor;
+
+}

common/src/main/java/com/lunarclient/apollo/module/cooldown/CooldownModuleImpl.java

@@ -29,6 +29,7 @@
 import com.lunarclient.apollo.network.NetworkTypes;
 import com.lunarclient.apollo.player.AbstractApolloPlayer;
 import com.lunarclient.apollo.recipients.Recipients;
+import java.awt.Color;
 import lombok.NonNull;
 
 /**
@@ -40,12 +41,17 @@ public final class CooldownModuleImpl extends CooldownModule {
 
     @Override
     public void displayCooldown(@NonNull Recipients recipients, @NonNull Cooldown cooldown) {
-        DisplayCooldownMessage message = DisplayCooldownMessage.newBuilder()
+        DisplayCooldownMessage.Builder builder = DisplayCooldownMessage.newBuilder()
             .setName(cooldown.getName())
             .setDuration(NetworkTypes.toProtobuf(cooldown.getDuration()))
-            .setIcon(NetworkTypes.toProtobuf(cooldown.getIcon()))
-            .build();
+            .setIcon(NetworkTypes.toProtobuf(cooldown.getIcon()));
+
+        CooldownStyle style = cooldown.getStyle();
+        if (style != null) {
+            builder.setStyle(this.toProtobuf(style));
+        }
 
+        DisplayCooldownMessage message = builder.build();
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
     }
 
@@ -69,4 +75,30 @@ public void resetCooldowns(@NonNull Recipients recipients) {
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
     }
 
+    private com.lunarclient.apollo.cooldown.v1.CooldownStyle toProtobuf(CooldownStyle style) {
+        com.lunarclient.apollo.cooldown.v1.CooldownStyle.Builder builder = com.lunarclient.apollo.cooldown.v1.CooldownStyle.newBuilder();
+
+        Color circleStartColor = style.getCircleStartColor();
+        if (circleStartColor != null) {
+            builder.setCircleStartColor(NetworkTypes.toProtobuf(circleStartColor));
+        }
+
+        Color circleEndColor = style.getCircleEndColor();
+        if (circleEndColor != null) {
+            builder.setCircleEndColor(NetworkTypes.toProtobuf(circleEndColor));
+        }
+
+        Color circleEdgeColor = style.getCircleEdgeColor();
+        if (circleEdgeColor != null) {
+            builder.setCircleEdgeColor(NetworkTypes.toProtobuf(circleEdgeColor));
+        }
+
+        Color textColor = style.getTextColor();
+        if (textColor != null) {
+            builder.setTextColor(NetworkTypes.toProtobuf(textColor));
+        }
+
+        return builder.build();
+    }
+
 }

docs/developers/lightweight/protobuf/getting-started.mdx

@@ -26,7 +26,7 @@ Available fields for each message, including their types, are available on the B
         <dependency>
             <groupId>com.lunarclient</groupId>
             <artifactId>apollo-protos</artifactId>
-            <version>0.0.6</version>
+            <version>0.0.9</version>
         </dependency>
     </dependencies>
     ```
@@ -41,7 +41,7 @@ Available fields for each message, including their types, are available on the B
     }
 
     dependencies {
-        api 'com.lunarclient:apollo-protos:0.0.6'
+        api 'com.lunarclient:apollo-protos:0.0.9'
     }
     ```
   </Tab>
@@ -55,7 +55,7 @@ Available fields for each message, including their types, are available on the B
     }
 
     dependencies {
-        api("com.lunarclient:apollo-protos:0.0.6")
+        api("com.lunarclient:apollo-protos:0.0.9")
     }
     ```
   </Tab>

docs/developers/modules/cooldown.mdx

@@ -45,6 +45,31 @@ public void displayCooldownItemExample(Player viewer) {
 }
 ```
 
+### Displaying a Cooldown with a custom style
+
+```java
+public void displayCooldownWithStyleExample(Player viewer) {
+    Optional<ApolloPlayer> apolloPlayerOpt = Apollo.getPlayerManager().getPlayer(viewer.getUniqueId());
+
+    apolloPlayerOpt.ifPresent(apolloPlayer -> {
+        this.cooldownModule.displayCooldown(apolloPlayer, Cooldown.builder()
+            .name("book-cooldown")
+            .duration(Duration.ofSeconds(30))
+            .icon(ItemStackIcon.builder()
+                .itemName("BOOK")
+                .build())
+            .style(CooldownStyle.builder()
+                .circleStartColor(ApolloColors.RED)
+                .circleEndColor(ApolloColors.GREEN)
+                .circleEdgeColor(ApolloColors.DARK_GRAY)
+                .textColor(ApolloColors.LIGHT_PURPLE)
+                .build())
+            .build()
+        );
+    });
+}
+```
+
 ### Displaying a Cooldown with a resource
 
 ```java
@@ -56,8 +81,8 @@ public void displayCooldownResourceExample(Player viewer) {
             .name("lunar-cooldown")
             .duration(Duration.ofSeconds(15))
             .icon(SimpleResourceLocationIcon.builder()
-                .resourceLocation("lunar:logo/logo-200x182.svg")
-                .size(12)
+                .resourceLocation("lunar:logo/logo-64x64.png")
+                .size(24)
                 .build()
             )
             .build()
@@ -74,6 +99,7 @@ public void removeCooldownExample(Player viewer) {
 
     apolloPlayerOpt.ifPresent(apolloPlayer -> {
         this.cooldownModule.removeCooldown(apolloPlayer, "enderpearl-cooldown");
+        this.cooldownModule.removeCooldown(apolloPlayer, "book-cooldown");
         this.cooldownModule.removeCooldown(apolloPlayer, "lunar-cooldown");
     });
 }
@@ -107,9 +133,43 @@ public void resetCooldownsExample(Player viewer) {
 
 `.icon(SimpleResourceLocationIcon)` is how you display a custom texture icon. Read the [icons utilities page](/apollo/developers/utilities/icons) to learn more about icons.
 ```java
-.icon(SimpleResourceLocationIcon.builder().resourceLocation("lunar:logo/logo-200x182.svg").size(12).build())
+.icon(SimpleResourceLocationIcon.builder().resourceLocation("lunar:logo/logo-64x64.png").size(24).build())
 ```
 
+`.style(CooldownStyle)` is how you customize the visual appearance of the cooldown circle and text. See the `CooldownStyle` section below for more.
+```java
+.style(CooldownStyle.builder()
+    .circleStartColor(ApolloColors.RED)
+    .circleEndColor(ApolloColors.GREEN)
+    .circleEdgeColor(ApolloColors.DARK_GRAY)
+    .textColor(ApolloColors.LIGHT_PURPLE)
+    .build())
+```
+
+### `CooldownStyle` Options
+
+`.circleStartColor(java.awt.Color)` is the color displayed at the start of the cooldown circle animation. See the [colors page](/apollo/developers/utilities/colors) for more.
+```java
+.circleStartColor(ApolloColors.RED)
+```
+
+`.circleEndColor(java.awt.Color)` is the color displayed at the end of the cooldown circle animation. See the [colors page](/apollo/developers/utilities/colors) for more.
+```java
+.circleEndColor(ApolloColors.GREEN)
+```
+
+`.circleEdgeColor(java.awt.Color)` is the color of the circle's edge/border. See the [colors page](/apollo/developers/utilities/colors) for more.
+```java
+.circleEdgeColor(ApolloColors.DARK_GRAY)
+```
+
+`.textColor(java.awt.Color)` is the color of the cooldown timer text rendered in the center of the circle. See the [colors page](/apollo/developers/utilities/colors) for more.
+```java
+.textColor(ApolloColors.LIGHT_PURPLE)
+```
+
+All `CooldownStyle` fields are optional; any field left unset will fall back to the client's default value.
+
 </Tab>
 
 <Tab>
@@ -128,14 +188,34 @@ public void displayCooldownItemExample(Player viewer) {
 }
 ```
 
+**Displaying a Cooldown with a custom style**
+
+```java
+public void displayCooldownWithStyleExample(Player viewer) {
+    DisplayCooldownMessage message = DisplayCooldownMessage.newBuilder()
+        .setName("book-cooldown")
+        .setDuration(ProtobufUtil.createDurationProto(Duration.ofSeconds(30)))
+        .setIcon(ProtobufUtil.createItemStackIconProto("BOOK", 0, 0))
+        .setStyle(CooldownStyle.newBuilder()
+            .setCircleStartColor(ProtobufUtil.createColorProto(new Color(255, 85, 85))) // ApolloColors.RED
+            .setCircleEndColor(ProtobufUtil.createColorProto(new Color(85, 255, 85))) // ApolloColors.GREEN
+            .setCircleEdgeColor(ProtobufUtil.createColorProto(new Color(85, 85, 85))) // ApolloColors.DAR_GRAY
+            .setTextColor(ProtobufUtil.createColorProto(new Color(255, 85, 255))) // ApolloColors.LIGHT_PURPLE
+            .build())
+        .build();
+
+    ProtobufPacketUtil.sendPacket(viewer, message);
+}
+```
+
 **Displaying a Cooldown with a resource**
 
 ```java
 public void displayCooldownResourceExample(Player viewer) {
     DisplayCooldownMessage message = DisplayCooldownMessage.newBuilder()
         .setName("lunar-cooldown")
         .setDuration(ProtobufUtil.createDurationProto(Duration.ofSeconds(15)))
-        .setIcon(ProtobufUtil.createSimpleResourceLocationIconProto("lunar:logo/logo-200x182.svg", 12))
+        .setIcon(ProtobufUtil.createSimpleResourceLocationIconProto("lunar:logo/logo-64x64.png", 24))
         .build();
 
     ProtobufPacketUtil.sendPacket(viewer, message);
@@ -181,6 +261,27 @@ public void displayCooldownItemExample(Player viewer) {
 }
 ```
 
+**Displaying a Cooldown with a custom style**
+
+```java
+public void displayCooldownWithStyleExample(Player viewer) {
+    JsonObject message = new JsonObject();
+    message.addProperty("@type", "type.googleapis.com/lunarclient.apollo.cooldown.v1.DisplayCooldownMessage");
+    message.addProperty("name", "book-cooldown");
+    message.addProperty("duration", JsonUtil.createDurationObject(Duration.ofSeconds(30)));
+    message.add("icon", JsonUtil.createItemStackIconObject("BOOK", 0, 0));
+
+    JsonObject style = new JsonObject();
+    style.add("circle_start_color", JsonUtil.createColorObject(new Color(255, 85, 85))); // ApolloColors.RED
+    style.add("circle_end_color", JsonUtil.createColorObject(new Color(85, 255, 85))); // ApolloColors.GREEN
+    style.add("circle_edge_color", JsonUtil.createColorObject(new Color(85, 85, 85))); // ApolloColors.DAR_GRAY
+    style.add("text_color", JsonUtil.createColorObject(new Color(255, 85, 255))); // ApolloColors.LIGHT_PURPLE
+    message.add("style", style);
+
+    JsonPacketUtil.sendPacket(viewer, message);
+}
+```
+
 **Displaying a Cooldown with a resource**
 
 ```java
@@ -189,7 +290,7 @@ public void displayCooldownResourceExample(Player viewer) {
     message.addProperty("@type", "type.googleapis.com/lunarclient.apollo.cooldown.v1.DisplayCooldownMessage");
     message.addProperty("name", "lunar-cooldown");
     message.addProperty("duration", JsonUtil.createDurationObject(Duration.ofSeconds(15)));
-    message.add("icon", JsonUtil.createSimpleResourceLocationIconObject("lunar:logo/logo-200x182.svg", 12));
+    message.add("icon", JsonUtil.createSimpleResourceLocationIconObject("lunar:logo/logo-64x64.png", 24));
 
     JsonPacketUtil.sendPacket(viewer, message);
 }

example/bukkit/api/src/main/java/com/lunarclient/apollo/example/api/listener/ApolloPlayerApiListener.java

@@ -29,6 +29,7 @@
 import com.lunarclient.apollo.event.player.ApolloRegisterPlayerEvent;
 import com.lunarclient.apollo.example.ApolloExamplePlugin;
 import com.lunarclient.apollo.example.api.module.TeamApiExample;
+import com.lunarclient.apollo.example.module.impl.CooldownExample;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import org.bukkit.entity.Player;
 
@@ -58,9 +59,13 @@ private void onApolloRegister(ApolloRegisterPlayerEvent event) {
 
         this.example.getBeamExample().displayBeamExample(player);
         this.example.getBorderExample().displayBorderExample(player);
-        this.example.getCooldownExample().displayCooldownItemExample(player);
         this.example.getNametagExample().overrideNametagExample(player);
         this.example.getWaypointExample().displayWaypointExample(player);
+
+        CooldownExample cooldownExample = this.example.getCooldownExample();
+        cooldownExample.displayCooldownItemExample(player);
+        cooldownExample.displayCooldownWithStyleExample(player);
+        cooldownExample.displayCooldownResourceExample(player);
     }
 
 }