Feature - Emotes API

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

@@ -58,6 +58,19 @@ public abstract class CosmeticModule extends ApolloModule {
      */
     public abstract void equipNpcCosmetics(Recipients recipients, UUID npcUuid, List<Cosmetic> cosmetics);
 
+    /**
+     * Equips the provided cosmetics on an NPC for the given {@link Recipients}, optionally layered on
+     * top of each recipient's own equipped cosmetics.
+     *
+     * @param recipients         the recipients that are receiving the packet
+     * @param npcUuid            the {@link UUID} of the NPC to equip the cosmetics on
+     * @param cosmetics          the cosmetics to equip, including optional {@link CosmeticOptions} per entry
+     *                           ({@link HatOptions}, {@link CloakOptions}, {@link PetOptions}, or {@link BodyOptions})
+     * @param copyLocalCosmetics {@code true} to copy each recipient's own equipped cosmetics onto the NPC first
+     * @since 1.2.7
+     */
+    public abstract void equipNpcCosmetics(Recipients recipients, UUID npcUuid, List<Cosmetic> cosmetics, boolean copyLocalCosmetics);
+
     /**
      * Unequips the provided cosmetics from an NPC for the given {@link Recipients}.
      *
@@ -77,6 +90,35 @@ public abstract class CosmeticModule extends ApolloModule {
      */
     public abstract void resetNpcCosmetics(Recipients recipients, UUID npcUuid);
 
+    /**
+     * Starts an emote on an NPC for the given {@link Recipients}.
+     *
+     * <p>Starting an emote replaces any emote already playing on the NPC.</p>
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @param npcUuid    the {@link UUID} of the NPC to play the emote on
+     * @param emote      the emote to play
+     * @since 1.2.7
+     */
+    public abstract void startNpcEmote(Recipients recipients, UUID npcUuid, Emote emote);
+
+    /**
+     * Stops the emote currently playing on an NPC for the given {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @param npcUuid    the {@link UUID} of the NPC to stop the emote on
+     * @since 1.2.7
+     */
+    public abstract void stopNpcEmote(Recipients recipients, UUID npcUuid);
+
+    /**
+     * Stops all emotes playing on every NPC for the given {@link Recipients}.
+     *
+     * @param recipients the recipients that are receiving the packet
+     * @since 1.2.7
+     */
+    public abstract void resetNpcEmotes(Recipients recipients);
+
     /**
      * Displays a spray for the given {@link Recipients}.
      *

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

@@ -0,0 +1,61 @@
+/*
+ * 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.cosmetic;
+
+import lombok.Builder;
+import lombok.Getter;
+import org.jetbrains.annotations.Range;
+
+/**
+ * Represents an emote that can be played on an NPC.
+ *
+ * @since 1.2.7
+ */
+@Getter
+@Builder
+public final class Emote {
+
+    /**
+     * Returns the Lunar Client emote id.
+     *
+     * <p>The value must be greater than 0.</p>
+     *
+     * @return the emote id
+     * @since 1.2.7
+     */
+    @Range(from = 1, to = Integer.MAX_VALUE) int id;
+
+    /**
+     * Returns the metadata used to select a variant for emotes that support one.
+     *
+     * <p>The value is ignored by emotes that do not use it. For example, a coin flip emote may use
+     * {@code 1} for heads and {@code 2} for tails, while a rock paper scissors emote may use {@code 1}
+     * for rock, {@code 2} for paper, and {@code 3} for scissors.</p>
+     *
+     * @return the emote metadata
+     * @since 1.2.7
+     */
+    int metadata;
+
+}

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

@@ -28,7 +28,10 @@
 import com.lunarclient.apollo.cosmetic.v1.EquipNpcCosmeticsMessage;
 import com.lunarclient.apollo.cosmetic.v1.RemoveSprayMessage;
 import com.lunarclient.apollo.cosmetic.v1.ResetNpcCosmeticsMessage;
+import com.lunarclient.apollo.cosmetic.v1.ResetNpcEmotesMessage;
 import com.lunarclient.apollo.cosmetic.v1.ResetSpraysMessage;
+import com.lunarclient.apollo.cosmetic.v1.StartNpcEmoteMessage;
+import com.lunarclient.apollo.cosmetic.v1.StopNpcEmoteMessage;
 import com.lunarclient.apollo.cosmetic.v1.UnequipNpcCosmeticsMessage;
 import com.lunarclient.apollo.module.cosmetic.options.BodyOptions;
 import com.lunarclient.apollo.module.cosmetic.options.CloakOptions;
@@ -55,13 +58,19 @@ public final class CosmeticModuleImpl extends CosmeticModule {
 
     @Override
     public void equipNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcUuid, @NonNull List<Cosmetic> cosmetics) {
+        this.equipNpcCosmetics(recipients, npcUuid, cosmetics, false);
+    }
+
+    @Override
+    public void equipNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcUuid, @NonNull List<Cosmetic> cosmetics, boolean copyLocalCosmetics) {
         List<com.lunarclient.apollo.cosmetic.v1.Cosmetic> cosmeticsProto = cosmetics.stream()
             .map(this::toProtobuf)
             .collect(Collectors.toList());
 
         EquipNpcCosmeticsMessage message = EquipNpcCosmeticsMessage.newBuilder()
             .setNpcUuid(NetworkTypes.toProtobuf(npcUuid))
             .addAllCosmetics(cosmeticsProto)
+            .setCopyLocalCosmetics(copyLocalCosmetics)
             .build();
 
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
@@ -90,6 +99,34 @@ public void resetNpcCosmetics(@NonNull Recipients recipients, @NonNull UUID npcU
         recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
     }
 
+    @Override
+    public void startNpcEmote(@NonNull Recipients recipients, @NonNull UUID npcUuid, @NonNull Emote emote) {
+        StartNpcEmoteMessage message = StartNpcEmoteMessage.newBuilder()
+            .setNpcUuid(NetworkTypes.toProtobuf(npcUuid))
+            .setEmote(com.lunarclient.apollo.cosmetic.v1.Emote.newBuilder()
+                .setId(checkStrictlyPositive(emote.getId(), "Emote#id"))
+                .setMetadata(emote.getMetadata())
+                .build())
+            .build();
+
+        recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
+    }
+
+    @Override
+    public void stopNpcEmote(@NonNull Recipients recipients, @NonNull UUID npcUuid) {
+        StopNpcEmoteMessage message = StopNpcEmoteMessage.newBuilder()
+            .setNpcUuid(NetworkTypes.toProtobuf(npcUuid))
+            .build();
+
+        recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
+    }
+
+    @Override
+    public void resetNpcEmotes(@NonNull Recipients recipients) {
+        ResetNpcEmotesMessage message = ResetNpcEmotesMessage.getDefaultInstance();
+        recipients.forEach(player -> ((AbstractApolloPlayer) player).sendPacket(message));
+    }
+
     @Override
     public void displaySpray(@NonNull Recipients recipients, @NonNull Spray spray) {
         DisplaySprayMessage message = DisplaySprayMessage.newBuilder()

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