Add NametagVisibilityOverride to Nametag (#305)

# Conflicts:
#	gradle/libs.versions.toml

Author: ItsNature

api/src/main/java/com/lunarclient/apollo/module/nametag/Nametag.java

@@ -45,4 +45,13 @@ public final class Nametag {
      */
     List<Component> lines;
 
+    /**
+     * Returns the {@link NametagVisibilityOverride} override for this nametag.
+     *
+     * @return the visibility override
+     * @since 1.2.9
+     */
+    @Builder.Default
+    NametagVisibilityOverride visibilityOverride = NametagVisibilityOverride.NONE;
+
 }

api/src/main/java/com/lunarclient/apollo/module/nametag/NametagVisibilityOverride.java

@@ -0,0 +1,59 @@
+/*
+ * 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.nametag;
+
+/**
+ * Represents an override of the vanilla team-based nametag visibility
+ * outcome for the target player, from the viewpoint of the receiving player.
+ *
+ * @since 1.2.9
+ */
+public enum NametagVisibilityOverride {
+
+    /**
+     * The vanilla team-based nametag visibility applies.
+     *
+     * @since 1.2.9
+     */
+    NONE,
+
+    /**
+     * Shows the nametag, as if the target's team nametag visibility
+     * were {@code always}, still respecting invisibility.
+     *
+     * @since 1.2.9
+     */
+    SHOWN,
+
+    /**
+     * Hides the nametag, as if the target's team nametag visibility
+     * were {@code never}.
+     *
+     * <p>Applies even when the target is not on any team.</p>
+     *
+     * @since 1.2.9
+     */
+    HIDDEN
+
+}

common/src/main/java/com/lunarclient/apollo/module/nametag/NametagModuleImpl.java

@@ -50,6 +50,11 @@ public void overrideNametag(@NonNull Recipients recipients, @NonNull UUID player
             builder.addAdventureJsonLines(ApolloComponent.toJson(line));
         }
 
+        NametagVisibilityOverride visibility = nametag.getVisibilityOverride();
+        if (visibility != null && visibility != NametagVisibilityOverride.NONE) {
+            builder.setVisibilityOverride(this.toProtobuf(visibility));
+        }
+
         ApolloManager.getNetworkManager().sendPacket(recipients, builder.build());
     }
 
@@ -68,4 +73,8 @@ public void resetNametags(@NonNull Recipients recipients) {
         ApolloManager.getNetworkManager().sendPacket(recipients, message);
     }
 
+    private com.lunarclient.apollo.nametag.v1.NametagVisibilityOverride toProtobuf(NametagVisibilityOverride visibility) {
+        return com.lunarclient.apollo.nametag.v1.NametagVisibilityOverride.forNumber(visibility.ordinal() + 1);
+    }
+
 }

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.1</version>
+            <version>0.2.4</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.1'
+        api 'com.lunarclient:apollo-protos:0.2.4'
     }
     ```
   </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.1")
+        api("com.lunarclient:apollo-protos:0.2.4")
     }
     ```
   </Tab>

docs/developers/modules/nametag.mdx

@@ -50,6 +50,7 @@ public void overrideNametagExample(Player target) {
                 .color(NamedTextColor.RED)
                 .build()
         ))
+        .visibilityOverride(NametagVisibilityOverride.NONE)
         .build()
     );
 }
@@ -100,6 +101,15 @@ public void resetNametagsExample(Player viewer) {
 ))
 ```
 
+`.visibilityOverride(NametagVisibilityOverride)` overrides the vanilla team-based nametag visibility outcome for the target player, from the viewpoint of the receiving player.
+- `SHOWN` displays the nametag as if the target's team nametag visibility were `always` (still respecting invisibility)
+- `HIDDEN` hides the nametag as if it were `never`, even when the target is not on any team.
+- `NONE` keeps the vanilla behavior.
+
+```java
+.visibilityOverride(NametagVisibilityOverride.NONE)
+```
+
 </Tab>
 
 <Tab>
@@ -129,6 +139,7 @@ public void overrideNametagExample(Player target) {
     OverrideNametagMessage message = OverrideNametagMessage.newBuilder()
         .setPlayerUuid(ProtobufUtil.createUuidProto(target.getUniqueId()))
         .addAllAdventureJsonLines(lines)
+        .setVisibilityOverride(NametagVisibilityOverride.NAMETAG_VISIBILITY_OVERRIDE_NONE)
         .build();
 
     ProtobufPacketUtil.broadcastPacket(message);
@@ -186,6 +197,7 @@ public void overrideNametagExample(Player target) {
     message.addProperty("@type", "type.googleapis.com/lunarclient.apollo.nametag.v1.OverrideNametagMessage");
     message.add("player_uuid", JsonUtil.createUuidObject(target.getUniqueId()));
     message.add("adventure_json_lines", lines);
+    message.addProperty("visibility_override", "NAMETAG_VISIBILITY_OVERRIDE_NONE");
 
     JsonPacketUtil.broadcastPacket(message);
 }

example/bukkit/api/src/main/java/com/lunarclient/apollo/example/api/module/NametagApiExample.java

@@ -28,6 +28,7 @@
 import com.lunarclient.apollo.example.module.impl.NametagExample;
 import com.lunarclient.apollo.module.nametag.Nametag;
 import com.lunarclient.apollo.module.nametag.NametagModule;
+import com.lunarclient.apollo.module.nametag.NametagVisibilityOverride;
 import com.lunarclient.apollo.player.ApolloPlayer;
 import com.lunarclient.apollo.recipients.Recipients;
 import java.util.Optional;
@@ -54,6 +55,7 @@ public void overrideNametagExample(Player target) {
                     .color(NamedTextColor.RED)
                     .build()
             ))
+            .visibilityOverride(NametagVisibilityOverride.NONE)
             .build()
         );
     }

example/bukkit/json/src/main/java/com/lunarclient/apollo/example/json/module/NametagJsonExample.java

@@ -58,6 +58,7 @@ public void overrideNametagExample(Player target) {
         message.addProperty("@type", "type.googleapis.com/lunarclient.apollo.nametag.v1.OverrideNametagMessage");
         message.add("player_uuid", JsonUtil.createUuidObject(target.getUniqueId()));
         message.add("adventure_json_lines", lines);
+        message.addProperty("visibility_override", "NAMETAG_VISIBILITY_OVERRIDE_NONE");
 
         JsonPacketUtil.broadcastPacket(message);
     }

example/bukkit/proto/src/main/java/com/lunarclient/apollo/example/proto/module/NametagProtoExample.java

@@ -28,6 +28,7 @@
 import com.lunarclient.apollo.example.proto.util.AdventureUtil;
 import com.lunarclient.apollo.example.proto.util.ProtobufPacketUtil;
 import com.lunarclient.apollo.example.proto.util.ProtobufUtil;
+import com.lunarclient.apollo.nametag.v1.NametagVisibilityOverride;
 import com.lunarclient.apollo.nametag.v1.OverrideNametagMessage;
 import com.lunarclient.apollo.nametag.v1.ResetNametagMessage;
 import com.lunarclient.apollo.nametag.v1.ResetNametagsMessage;
@@ -59,6 +60,7 @@ public void overrideNametagExample(Player target) {
         OverrideNametagMessage message = OverrideNametagMessage.newBuilder()
             .setPlayerUuid(ProtobufUtil.createUuidProto(target.getUniqueId()))
             .addAllAdventureJsonLines(lines)
+            .setVisibilityOverride(NametagVisibilityOverride.NAMETAG_VISIBILITY_OVERRIDE_NONE)
             .build();
 
         ProtobufPacketUtil.broadcastPacket(message);

gradle/libs.versions.toml

@@ -11,7 +11,7 @@ geantyref = "1.3.11"
 idea = "1.1.7"
 jetbrains = "24.0.1"
 lombok = "1.18.38"
-protobuf = "0.2.2"
+protobuf = "0.2.4"
 gson = "2.10.1"
 shadow = "9.4.1"
 spotless = "8.4.0"