Feature - Totem Counter Module

.github/workflows/deploy.yml

@@ -41,7 +41,7 @@ jobs:
                 fi
 
         -   name: Gradle Publish
-            if: "${{ github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/version/') }}"
+            if: "${{ github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/heads/version/') || github.ref == 'refs/heads/feature/totem-counter-module' }}"
             run: ./gradlew publish
 
         -   name: Gradle Release

api/src/main/java/com/lunarclient/apollo/module/totemcounter/TotemCounter.java

@@ -0,0 +1,57 @@
+/*
+ * 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.totemcounter;
+
+import java.util.UUID;
+import lombok.Builder;
+import lombok.Getter;
+import org.jetbrains.annotations.Range;
+
+/**
+ * Represents a totem counter which can be shown on the client.
+ *
+ * @since 1.3.0
+ */
+@Getter
+@Builder
+public final class TotemCounter {
+
+    /**
+     * Returns the totem counter player's {@link UUID}.
+     *
+     * @return the player uuid
+     * @since 1.3.0
+     */
+    UUID playerUuid;
+
+    /**
+     * Returns the totem counter {@link Integer} amount of totems the player
+     * has popped.
+     *
+     * @return the totem counter pops
+     * @since 1.3.0
+     */
+    @Range(from = 0, to = Integer.MAX_VALUE) int pops;
+
+}

api/src/main/java/com/lunarclient/apollo/module/totemcounter/TotemCounterModule.java

@@ -0,0 +1,123 @@
+/*
+ * 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.totemcounter;
+
+import com.lunarclient.apollo.module.ApolloModule;
+import com.lunarclient.apollo.module.ModuleDefinition;
+import com.lunarclient.apollo.option.Option;
+import com.lunarclient.apollo.option.SimpleOption;
+import com.lunarclient.apollo.recipients.Recipients;
+import io.leangen.geantyref.TypeToken;
+import java.util.Collection;
+import java.util.UUID;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Represents the totem counter module.
+ *
+ * <p>Overrides the totem pops shown by the client's Totem Counter mod.
+ * The client keeps counting totem pops on its own on top of the overridden
+ * values, unless {@link #DISABLE_LOCAL_TRACKING} is enabled.</p>
+ *
+ * @since 1.3.0
+ */
+@ApiStatus.NonExtendable
+@ModuleDefinition(id = "totem_counter", name = "Totem Counter")
+public abstract class TotemCounterModule extends ApolloModule {
+
+    /**
+     * Whether the client stops tracking and resetting totem pops on its own.
+     *
+     * @since 1.3.0
+     */
+    public static final SimpleOption<Boolean> DISABLE_LOCAL_TRACKING = Option.<Boolean>builder()
+        .comment("Set to 'true' to stop the client from tracking and resetting totem pops on its own, otherwise 'false'.")
+        .node("disable-local-tracking").type(TypeToken.get(Boolean.class))
+        .defaultValue(false).notifyClient().build();
+
+    protected TotemCounterModule() {
+        this.registerOptions(
+            TotemCounterModule.DISABLE_LOCAL_TRACKING
+        );
+    }
+
+    @Override
+    public boolean isClientNotify() {
+        return true;
+    }
+
+    /**
+     * Overrides the {@link TotemCounter}s for the {@link Recipients}.
+     *
+     * @param recipients    the recipients that are receiving the packet
+     * @param totemCounters the totem counters
+     * @since 1.3.0
+     */
+    public abstract void overrideTotemCounters(Recipients recipients, Collection<TotemCounter> totemCounters);
+
+    /**
+     * Overrides the {@link TotemCounter} for the {@link Recipients}.
+     *
+     * @param recipients   the recipients that are receiving the packet
+     * @param totemCounter the totem counter
+     * @since 1.3.0
+     */
+    public abstract void overrideTotemCounter(Recipients recipients, TotemCounter totemCounter);
+
+    /**
+     * Resets the {@link TotemCounter} for the {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @param playerUuid the player whose totem counter we are manipulating
+     * @since 1.3.0
+     */
+    public abstract void resetTotemCounter(Recipients recipients, UUID playerUuid);
+
+    /**
+     * Resets the {@link TotemCounter} for the {@link Recipients}.
+     *
+     * @param recipients   the recipients that are receiving the packet
+     * @param totemCounter the totem counter
+     * @since 1.3.0
+     */
+    public abstract void resetTotemCounter(Recipients recipients, TotemCounter totemCounter);
+
+    /**
+     * Resets the {@link TotemCounter}s for the {@link Recipients}.
+     *
+     * @param recipients  the recipients that are receiving the packet
+     * @param playerUuids the players whose totem counters we are manipulating
+     * @since 1.3.0
+     */
+    public abstract void resetTotemCounter(Recipients recipients, Collection<UUID> playerUuids);
+
+    /**
+     * Resets all {@link TotemCounter}s for the {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @since 1.3.0
+     */
+    public abstract void resetTotemCounters(Recipients recipients);
+
+}

common/src/main/java/com/lunarclient/apollo/module/totemcounter/TotemCounterModuleImpl.java

@@ -0,0 +1,96 @@
+/*
+ * 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.totemcounter;
+
+import com.lunarclient.apollo.ApolloManager;
+import com.lunarclient.apollo.network.NetworkTypes;
+import com.lunarclient.apollo.recipients.Recipients;
+import com.lunarclient.apollo.totemcounter.v1.OverrideTotemCountersMessage;
+import com.lunarclient.apollo.totemcounter.v1.ResetTotemCounterMessage;
+import com.lunarclient.apollo.totemcounter.v1.ResetTotemCountersMessage;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.UUID;
+import lombok.NonNull;
+
+import static com.lunarclient.apollo.util.Ranges.checkPositive;
+
+/**
+ * Provides the totem counter module.
+ *
+ * @since 1.3.0
+ */
+public final class TotemCounterModuleImpl extends TotemCounterModule {
+
+    @Override
+    public void overrideTotemCounters(@NonNull Recipients recipients, @NonNull Collection<TotemCounter> totemCounters) {
+        OverrideTotemCountersMessage.Builder builder = OverrideTotemCountersMessage.newBuilder();
+
+        for (TotemCounter totemCounter : totemCounters) {
+            builder.addTotemCounters(this.toProtobuf(totemCounter));
+        }
+
+        ApolloManager.getNetworkManager().sendPacket(recipients, builder.build());
+    }
+
+    @Override
+    public void overrideTotemCounter(@NonNull Recipients recipients, @NonNull TotemCounter totemCounter) {
+        this.overrideTotemCounters(recipients, Collections.singleton(totemCounter));
+    }
+
+    @Override
+    public void resetTotemCounter(@NonNull Recipients recipients, @NonNull UUID playerUuid) {
+        this.resetTotemCounter(recipients, Collections.singleton(playerUuid));
+    }
+
+    @Override
+    public void resetTotemCounter(@NonNull Recipients recipients, @NonNull TotemCounter totemCounter) {
+        this.resetTotemCounter(recipients, Collections.singleton(totemCounter.getPlayerUuid()));
+    }
+
+    @Override
+    public void resetTotemCounter(@NonNull Recipients recipients, @NonNull Collection<UUID> playerUuids) {
+        ResetTotemCounterMessage.Builder builder = ResetTotemCounterMessage.newBuilder();
+
+        for (UUID playerUuid : playerUuids) {
+            builder.addPlayerUuids(NetworkTypes.toProtobuf(playerUuid));
+        }
+
+        ApolloManager.getNetworkManager().sendPacket(recipients, builder.build());
+    }
+
+    @Override
+    public void resetTotemCounters(@NonNull Recipients recipients) {
+        ResetTotemCountersMessage message = ResetTotemCountersMessage.getDefaultInstance();
+        ApolloManager.getNetworkManager().sendPacket(recipients, message);
+    }
+
+    private com.lunarclient.apollo.totemcounter.v1.TotemCounter toProtobuf(TotemCounter totemCounter) {
+        return com.lunarclient.apollo.totemcounter.v1.TotemCounter.newBuilder()
+            .setPlayerUuid(NetworkTypes.toProtobuf(totemCounter.getPlayerUuid()))
+            .setPops(checkPositive(totemCounter.getPops(), "TotemCounter#pops"))
+            .build();
+    }
+
+}

docs/developers/lightweight/json/packet-util.mdx

@@ -15,7 +15,7 @@ To utilize Apollo Modules, first define a list of the modules you want to use:
 ```java
 private static final List<String> APOLLO_MODULES = Arrays.asList("auto_text_hotkey", "beam", "border", "chat", "colored_fire", "combat", "cooldown",
     "entity", "glint", "glow", "hologram", "inventory", "limb", "mod_setting", "nametag", "nick_hider", "notification", "pay_now", "packet_enrichment",
-    "rich_presence", "saturation", "server_link", "server_rule", "staff_mod", "stopwatch", "team", "tebex", "title", "tnt_countdown", "transfer", "vignette", "waypoint"
+    "rich_presence", "saturation", "server_link", "server_rule", "staff_mod", "stopwatch", "team", "tebex", "title", "tnt_countdown", "totem_counter", "transfer", "vignette", "waypoint"
 );
 ```
 
@@ -59,6 +59,7 @@ static {
     CONFIG_MODULE_PROPERTIES.put("server_rule", "crystal-optimizer", false);
     CONFIG_MODULE_PROPERTIES.put("tnt_countdown", "tnt-ticks", 80);
     CONFIG_MODULE_PROPERTIES.put("title", "clear-title-on-server-switch", false);
+    CONFIG_MODULE_PROPERTIES.put("totem_counter", "disable-local-tracking", false);
     CONFIG_MODULE_PROPERTIES.put("waypoint", "server-handles-waypoints", false);
 }
 ```

docs/developers/lightweight/protobuf.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.2.4</version>
+            <version>0.2.5</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.2.4'
+        api 'com.lunarclient:apollo-protos:0.2.5'
     }
     ```
   </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.2.4")
+        api("com.lunarclient:apollo-protos:0.2.5")
     }
     ```
   </Tab>

docs/developers/lightweight/protobuf/packet-util.mdx

@@ -15,7 +15,7 @@ To utilize Apollo Modules, first define a list of the modules you want to use:
 ```java
 private static final List<String> APOLLO_MODULES = Arrays.asList("auto_text_hotkey", "beam", "border", "chat", "colored_fire", "combat", "cooldown",
     "entity", "glint", "glow", "hologram", "inventory", "limb", "mod_setting", "nametag", "nick_hider", "notification", "pay_now", "packet_enrichment",
-    "rich_presence", "saturation", "server_link", "server_rule", "staff_mod", "stopwatch", "team", "tebex", "title", "tnt_countdown", "transfer", "vignette", "waypoint"
+    "rich_presence", "saturation", "server_link", "server_rule", "staff_mod", "stopwatch", "team", "tebex", "title", "tnt_countdown", "totem_counter", "transfer", "vignette", "waypoint"
 );
 ```
 
@@ -65,6 +65,7 @@ static {
     CONFIG_MODULE_PROPERTIES.put("server_rule", "crystal-optimizer", Value.newBuilder().setBoolValue(false).build());
     CONFIG_MODULE_PROPERTIES.put("tnt_countdown", "tnt-ticks", Value.newBuilder().setNumberValue(80).build());
     CONFIG_MODULE_PROPERTIES.put("title", "clear-title-on-server-switch", Value.newBuilder().setBoolValue(false).build());
+    CONFIG_MODULE_PROPERTIES.put("totem_counter", "disable-local-tracking", Value.newBuilder().setBoolValue(false).build());
     CONFIG_MODULE_PROPERTIES.put("waypoint", "server-handles-waypoints", Value.newBuilder().setBoolValue(false).build());
 }
 ```

docs/developers/modules.mdx

@@ -37,6 +37,7 @@ These modules are available to all servers using Apollo and do not require any p
 🔗 [Tebex](/apollo/developers/modules/tebex)<br/>
 🔗 [Title](/apollo/developers/modules/title)<br/>
 🔗 [TNT Countdown](/apollo/developers/modules/tntcountdown)<br/>
+🔗 [Totem Counter](/apollo/developers/modules/totemcounter)<br/>
 🔗 [Transfer](/apollo/developers/modules/transfer)<br/>
 🔗 [Vignette](/apollo/developers/modules/vignette)<br/>
 🔗 [Waypoint](/apollo/developers/modules/waypoint)<br/>

docs/developers/modules/_meta.json

@@ -30,6 +30,7 @@
     "tebex": "Tebex",
     "title": "Title",
     "tntcountdown": "TNT Countdown",
+    "totemcounter": "Totem Counter",
     "transfer": "Transfer",
     "vignette": "Vignette",
     "waypoint": "Waypoint"