final docs changes

Author: ItsNature

api/src/main/java/com/lunarclient/apollo/module/cosmetic/Cosmetic.java

@@ -31,6 +31,7 @@
 import lombok.Builder;
 import lombok.Getter;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Range;
 
 /**
  * Represents a single cosmetic with optional per-type display settings.
@@ -44,10 +45,12 @@ public final class Cosmetic {
     /**
      * Returns the Lunar Client cosmetic id for this entry.
      *
+     * <p>The value must be greater than 0.</p>
+     *
      * @return the cosmetic id
      * @since 1.2.6
      */
-    int id;
+    @Range(from = 1, to = Integer.MAX_VALUE) int id;
 
     /**
      * Returns optional cosmetic display options for this cosmetic id.

api/src/main/java/com/lunarclient/apollo/module/cosmetic/CosmeticModule.java

@@ -35,6 +35,8 @@
 import java.util.List;
 import java.util.UUID;
 import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Range;
 
 /**
  * Represents the cosmetic module.
@@ -87,21 +89,26 @@ public abstract class CosmeticModule extends ApolloModule {
     /**
      * Removes every instance of a spray id for the given {@link Recipients}.
      *
+     * <p>The spray id must be greater than 0.</p>
+     *
      * @param recipients the recipients that are receiving the packet
      * @param sprayId    the spray cosmetic id
      * @since 1.2.6
      */
-    public abstract void removeSpray(Recipients recipients, int sprayId);
+    public abstract void removeSpray(Recipients recipients, @Range(from = 1, to = Integer.MAX_VALUE) int sprayId);
 
     /**
      * Removes every instance of a spray id at a specific block for the given {@link Recipients}.
      *
+     * <p>The spray id must be greater than 0. If {@code location} is {@code null}, every
+     * instance of the spray id is removed regardless of position.</p>
+     *
      * @param recipients the recipients that are receiving the packet
      * @param sprayId    the spray cosmetic id
-     * @param location   the block location of the spray to remove
+     * @param location   the block location of the spray to remove, or {@code null} to remove all
      * @since 1.2.6
      */
-    public abstract void removeSpray(Recipients recipients, int sprayId, ApolloBlockLocation location);
+    public abstract void removeSpray(Recipients recipients, @Range(from = 1, to = Integer.MAX_VALUE) int sprayId, @Nullable ApolloBlockLocation location);
 
     /**
      * Resets all server sprays for the given {@link Recipients}.

api/src/main/java/com/lunarclient/apollo/module/cosmetic/Spray.java

@@ -28,6 +28,7 @@
 import java.time.Duration;
 import lombok.Builder;
 import lombok.Getter;
+import org.jetbrains.annotations.Range;
 
 /**
  * Represents a spray.
@@ -45,10 +46,12 @@ public final class Spray {
     /**
      * Returns the Lunar Client spray cosmetic id.
      *
+     * <p>The value must be greater than 0.</p>
+     *
      * @return the spray cosmetic id
      * @since 1.2.6
      */
-    int sprayId;
+    @Range(from = 1, to = Integer.MAX_VALUE) int sprayId;
 
     /**
      * Returns the {@link ApolloBlockLocation} of the block the spray is placed on.
@@ -78,8 +81,6 @@ public final class Spray {
     /**
      * Returns the {@link Duration} for how long the spray remains visible on the client.
      *
-     * <p>Maximum duration is 600 seconds (10 minutes).</p>
-     *
      * @return the display duration
      * @since 1.2.6
      */

common/src/main/java/com/lunarclient/apollo/module/cosmetic/CosmeticModuleImpl.java

@@ -44,6 +44,8 @@
 import lombok.NonNull;
 import org.jetbrains.annotations.Nullable;
 
+import static com.lunarclient.apollo.util.Ranges.checkStrictlyPositive;
+
 /**
  * Provides the cosmetic module.
  *
@@ -67,9 +69,13 @@ public void equipNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcU
 
     @Override
     public void unequipNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcUuid, @NonNull List<Integer> cosmeticIds) {
+        List<Integer> validatedIds = cosmeticIds.stream()
+            .map(id -> checkStrictlyPositive(id, "Cosmetic#id"))
+            .collect(Collectors.toList());
+
         UnequipNpcCosmeticsMessage message = UnequipNpcCosmeticsMessage.newBuilder()
             .setNpcUuid(NetworkTypes.toProtobuf(npcUuid))
-            .addAllCosmeticIds(cosmeticIds)
+            .addAllCosmeticIds(validatedIds)
             .build();
 
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
@@ -87,7 +93,7 @@ public void resetNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcU
     @Override
     public void displaySpray(@NonNull Recipients recipients, @NonNull Spray spray) {
         DisplaySprayMessage message = DisplaySprayMessage.newBuilder()
-            .setSprayId(spray.getSprayId())
+            .setSprayId(checkStrictlyPositive(spray.getSprayId(), "Spray#sprayId"))
             .setLocation(NetworkTypes.toProtobuf(spray.getLocation()))
             .setFacing(NetworkTypes.toProtobuf(spray.getFacing()))
             .setRotation(spray.getRotation())
@@ -100,7 +106,7 @@ public void displaySpray(@NonNull Recipients recipients, @NonNull Spray spray) {
     @Override
     public void removeSpray(@NonNull Recipients recipients, int sprayId) {
         RemoveSprayMessage message = RemoveSprayMessage.newBuilder()
-            .setSprayId(sprayId)
+            .setSprayId(checkStrictlyPositive(sprayId, "Spray#sprayId"))
             .build();
 
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
@@ -109,7 +115,7 @@ public void removeSpray(@NonNull Recipients recipients, int sprayId) {
     @Override
     public void removeSpray(@NonNull Recipients recipients, int sprayId, @Nullable ApolloBlockLocation location) {
         RemoveSprayMessage.Builder builder = RemoveSprayMessage.newBuilder()
-            .setSprayId(sprayId);
+            .setSprayId(checkStrictlyPositive(sprayId, "Spray#sprayId"));
 
         if (location != null) {
             builder.setLocation(NetworkTypes.toProtobuf(location));
@@ -127,9 +133,13 @@ public void resetSprays(@NonNull Recipients recipients) {
 
     private com.lunarclient.apollo.cosmetic.v1.Cosmetic toProtobuf(Cosmetic cosmetic) {
         com.lunarclient.apollo.cosmetic.v1.Cosmetic.Builder builder = com.lunarclient.apollo.cosmetic.v1.Cosmetic.newBuilder()
-            .setId(cosmetic.getId());
+            .setId(checkStrictlyPositive(cosmetic.getId(), "Cosmetic#id"));
 
         CosmeticOptions options = cosmetic.getOptions();
+        if (options == null) {
+            return builder.build();
+        }
+
         if (options instanceof HatOptions) {
             HatOptions hatOptions = (HatOptions) options;
             builder.setHatOptions(com.lunarclient.apollo.cosmetic.v1.HatOptions.newBuilder()

common/src/main/java/com/lunarclient/apollo/util/Ranges.java

@@ -62,6 +62,21 @@ public static int checkPositive(int value, String name) {
         return value;
     }
 
+    /**
+     * Returns the value if it is strictly positive (greater than 0),
+     * otherwise throws an {@link IllegalArgumentException}.
+     *
+     * @param value the value to check
+     * @param name the name of the value
+     * @return the value
+     * @throws IllegalArgumentException if the value is not strictly positive
+     * @since 1.2.6
+     */
+    public static int checkStrictlyPositive(int value, String name) {
+        if(value <= 0) throw new IllegalArgumentException(name + " must be greater than 0");
+        return value;
+    }
+
     /**
      * Returns the value if it is positive, otherwise throws an
      * {@link IllegalArgumentException}.