Add support for nameplates (collectibles)

src/main/java/net/dv8tion/jda/api/entities/Collectibles.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.api.entities;
+
+import net.dv8tion.jda.api.utils.DiscordAssets;
+import net.dv8tion.jda.api.utils.ImageFormat;
+import net.dv8tion.jda.api.utils.ImageProxy;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * The collectibles a user has equipped.
+ *
+ * <p>This excludes avatar decorations and profile effects.
+ */
+public interface Collectibles {
+    /**
+     * Returns the equipped nameplate.
+     *
+     * @return The displayed nameplate
+     */
+    @Nullable
+    Nameplate getNameplate();
+
+    /**
+     * A decoration visible in Direct Messages and a guild's member list.
+     */
+    interface Nameplate {
+        /**
+         * Returns the SKU ID of this nameplate.
+         *
+         * <p>This is unique and will never change.
+         *
+         * @return The SKU ID
+         */
+        @Nonnull
+        String getSkuId();
+
+        /**
+         * Returns the asset path of this nameplate.
+         *
+         * <p>This is unique but not necessarily immutable.
+         *
+         * @return The asset path
+         */
+        @Nonnull
+        String getAssetPath();
+
+        /**
+         * Returns a URL of this nameplate, as an static asset.
+         *
+         * <p>Size parameters are ignored by this endpoint.
+         *
+         * @return The URL to this nameplate's static asset
+         *
+         * @see    #getAnimatedAssetUrl()
+         * @see    #getStaticAsset()
+         */
+        @Nonnull
+        default String getStaticAssetUrl() {
+            return getStaticAsset().getUrl();
+        }
+
+        /**
+         * Returns an {@link ImageProxy} of this nameplate, as a static asset.
+         *
+         * <p>Size parameters are ignored by this endpoint.
+         *
+         * @return The proxy to this nameplate's static asset
+         *
+         * @see    #getAnimatedAsset()
+         * @see    #getStaticAssetUrl()
+         */
+        @Nonnull
+        default ImageProxy getStaticAsset() {
+            return DiscordAssets.staticNameplate(ImageFormat.PNG, getAssetPath());
+        }
+
+        /**
+         * Returns a URL of this nameplate, as an animated asset.
+         *
+         * <p>Size parameters are ignored by this endpoint.
+         *
+         * @return The URL to this nameplate's animated asset
+         *
+         * @see    #getStaticAssetUrl()
+         * @see    #getAnimatedAsset()
+         */
+        @Nonnull
+        default String getAnimatedAssetUrl() {
+            return getAnimatedAsset().getUrl();
+        }
+
+        /**
+         * Returns an {@link ImageProxy} of this nameplate, as an animated asset.
+         *
+         * <p>Size parameters are ignored by this endpoint.
+         *
+         * @return The proxy to this nameplate's animated asset
+         *
+         * @see    #getStaticAsset()
+         * @see    #getAnimatedAssetUrl()
+         */
+        @Nonnull
+        default ImageProxy getAnimatedAsset() {
+            return DiscordAssets.animatedNameplate(ImageFormat.WEBM, getAssetPath());
+        }
+
+        /**
+         * Returns the name of the background color of this nameplate.
+         *
+         * @return Palette name of this nameplate's background color
+         *
+         * @see   <a href="https://docs.discord.com/developers/resources/user#nameplate" target="_blank">Official documentation for nameplates</a>
+         */
+        @Nonnull
+        String getPalette();
+    }
+}

src/main/java/net/dv8tion/jda/api/entities/Member.java

@@ -31,6 +31,7 @@
 import net.dv8tion.jda.api.utils.ImageFormat;
 import net.dv8tion.jda.api.utils.ImageProxy;
 import net.dv8tion.jda.api.utils.data.DataObject;
+import net.dv8tion.jda.internal.entities.CollectiblesImpl;
 import net.dv8tion.jda.internal.requests.restaction.AuditableRestActionImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 import net.dv8tion.jda.internal.utils.Helpers;
@@ -417,6 +418,31 @@ default ImageProxy getEffectiveAvatar(@Nonnull ImageFormat preferredFormat) {
         return avatar == null ? getUser().getEffectiveAvatar(preferredFormat) : avatar;
     }
 
+    /**
+     * Returns the collectibles this member has <b>equipped</b> on this guild specifically.
+     *
+     * @return The collectibles equipped by this member
+     */
+    @Nonnull
+    Collectibles getCollectibles();
+
+    /**
+     * Returns the collectibles currently displayed for this member, in the guild.
+     *
+     * <p>Each collectible will return the first value found:
+     * <ol>
+     *     <li>On the member</li>
+     *     <li>On the user</li>
+     *     <li>{@code null}</li>
+     * </ol>
+     *
+     * @return The collectibles effectively equipped by this member
+     */
+    @Nonnull
+    default Collectibles getEffectiveCollectibles() {
+        return new CollectiblesImpl.Effective(this);
+    }
+
     /**
      * The roles applied to this Member.
      * <br>The roles are ordered based on their position. The highest role being at index 0

src/main/java/net/dv8tion/jda/api/entities/User.java

@@ -338,6 +338,14 @@ default ImageProxy getEffectiveAvatar(@Nonnull ImageFormat preferredFormat) {
         return avatar == null ? getDefaultAvatar() : avatar;
     }
 
+    /**
+     * Returns the collectibles this user has <b>equipped</b>.
+     *
+     * @return The collectibles equipped by this user
+     */
+    @Nonnull
+    Collectibles getCollectibles();
+
     /**
      * Loads the user's {@link User.Profile} data.
      * Returns a completed RestAction if this User has been retrieved using {@link JDA#retrieveUserById(long)}.

src/main/java/net/dv8tion/jda/api/events/guild/member/update/GuildMemberUpdateCollectiblesEvent.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.api.events.guild.member.update;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Collectibles;
+import net.dv8tion.jda.api.entities.Member;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Indicates that a {@link Member} updated their {@link net.dv8tion.jda.api.entities.Guild Guild} {@link Collectibles}.
+ *
+ * <p>Can be used to retrieve members who change their per guild collectibles, the triggering guild, the old collectibles and the new collectibles.
+ *
+ * <p>Identifier: {@value #IDENTIFIER}
+ *
+ * <p><b>Requirements</b><br>
+ *
+ * <p>This event requires the {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GUILD_MEMBERS} intent to be enabled.
+ * <br>{@link net.dv8tion.jda.api.JDABuilder#createDefault(String) createDefault(String)} and
+ * {@link net.dv8tion.jda.api.JDABuilder#createLight(String) createLight(String)} disable this by default!
+ *
+ * <p>Additionally, this event requires the {@link net.dv8tion.jda.api.utils.MemberCachePolicy MemberCachePolicy}
+ * to cache the updated members. Discord does not specifically tell us about the updates, but merely tells us the
+ * member was updated and gives us the updated member object. In order to fire a specific event like this we
+ * need to have the old member cached to compare against.
+ */
+public class GuildMemberUpdateCollectiblesEvent extends GenericGuildMemberUpdateEvent<Collectibles> {
+    public static final String IDENTIFIER = "collectibles";
+
+    public GuildMemberUpdateCollectiblesEvent(
+            @Nonnull JDA api, long responseNumber, @Nonnull Member member, @Nullable Collectibles oldAvatarId) {
+        super(api, responseNumber, member, oldAvatarId, member.getCollectibles(), IDENTIFIER);
+    }
+
+    /**
+     * The old collectibles
+     *
+     * @return The old collectibles
+     */
+    @Nullable
+    public Collectibles getOldAvatarId() {
+        return getOldValue();
+    }
+
+    /**
+     * The new collectibles
+     *
+     * @return The new collectibles
+     */
+    @Nullable
+    public Collectibles getNewAvatarId() {
+        return getNewValue();
+    }
+}

src/main/java/net/dv8tion/jda/api/events/user/update/UserUpdateCollectiblesEvent.java

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.dv8tion.jda.api.events.user.update;
+
+import net.dv8tion.jda.api.JDA;
+import net.dv8tion.jda.api.entities.Collectibles;
+import net.dv8tion.jda.api.entities.User;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
+/**
+ * Indicates that the {@link Collectibles} of a {@link User} changed.
+ *
+ * <p>Can be used to retrieve the User who changed their collectibles and their previous collectibles.
+ *
+ * <p>Identifier: {@value #IDENTIFIER}
+ *
+ * <p><b>Requirements</b><br>
+ *
+ * <p>This event requires the {@link net.dv8tion.jda.api.requests.GatewayIntent#GUILD_MEMBERS GUILD_MEMBERS} intent to be enabled.
+ * <br>{@link net.dv8tion.jda.api.JDABuilder#createDefault(String) createDefault(String)} and
+ * {@link net.dv8tion.jda.api.JDABuilder#createLight(String) createLight(String)} disable this by default!
+ *
+ * <p>Additionally, this event requires the {@link net.dv8tion.jda.api.utils.MemberCachePolicy MemberCachePolicy}
+ * to cache the updated members. Discord does not specifically tell us about the updates, but merely tells us the
+ * member was updated and gives us the updated member object. In order to fire a specific event like this we
+ * need to have the old member cached to compare against.
+ */
+public class UserUpdateCollectiblesEvent extends GenericUserUpdateEvent<Collectibles> {
+    public static final String IDENTIFIER = "collectibles";
+
+    public UserUpdateCollectiblesEvent(
+            @Nonnull JDA api, long responseNumber, @Nonnull User user, @Nullable Collectibles oldCollectibles) {
+        super(api, responseNumber, user, oldCollectibles, user.getCollectibles(), IDENTIFIER);
+    }
+
+    /**
+     * The previous collectibles
+     *
+     * @return The previous collectibles
+     */
+    @Nullable
+    public Collectibles getOldCollectibles() {
+        return getOldValue();
+    }
+
+    /**
+     * The new collectibles
+     *
+     * @return The new collectibles
+     */
+    @Nullable
+    public Collectibles getNewCollectibles() {
+        return getNewValue();
+    }
+}

src/main/java/net/dv8tion/jda/api/hooks/ListenerAdapter.java

@@ -179,6 +179,8 @@ public void onUserUpdateDiscriminator(@Nonnull UserUpdateDiscriminatorEvent even
 
     public void onUserUpdateAvatar(@Nonnull UserUpdateAvatarEvent event) {}
 
+    public void onUserUpdateCollectibles(@Nonnull UserUpdateCollectiblesEvent event) {}
+
     public void onUserUpdateOnlineStatus(@Nonnull UserUpdateOnlineStatusEvent event) {}
 
     public void onUserUpdateActivityOrder(@Nonnull UserUpdateActivityOrderEvent event) {}
@@ -450,6 +452,8 @@ public void onGuildMemberUpdateNickname(@Nonnull GuildMemberUpdateNicknameEvent
 
     public void onGuildMemberUpdateAvatar(@Nonnull GuildMemberUpdateAvatarEvent event) {}
 
+    public void onGuildMemberUpdateCollectibles(@Nonnull GuildMemberUpdateCollectiblesEvent event) {}
+
     public void onGuildMemberUpdateBoostTime(@Nonnull GuildMemberUpdateBoostTimeEvent event) {}
 
     public void onGuildMemberUpdatePending(@Nonnull GuildMemberUpdatePendingEvent event) {}