XSkull improvements + Titles minor changes

Author: CryptoMorin

core/src/main/java/com/cryptomorin/xseries/XItemStack.java

@@ -927,6 +927,12 @@ private void customModelData() {
                         }
                     }
                 }
+
+                // Setting an empty component will save it and change the internal meta which affects isSimilar()
+                if (!customModelData.getColors().isEmpty() || !customModelData.getStrings().isEmpty() ||
+                        !customModelData.getFlags().isEmpty() || !customModelData.getFloats().isEmpty()) {
+                    meta.setCustomModelDataComponent(customModelData);
+                }
             } else if (SUPPORTS_CUSTOM_MODEL_DATA) {
                 String modelData = config.getString("custom-model-data");
                 if (modelData != null && !modelData.isEmpty()) {

core/src/main/java/com/cryptomorin/xseries/messages/Titles.java

@@ -23,7 +23,6 @@
 
 import com.cryptomorin.xseries.reflection.XReflection;
 import com.cryptomorin.xseries.reflection.minecraft.MinecraftClassHandle;
-import com.cryptomorin.xseries.reflection.minecraft.MinecraftConnection;
 import com.cryptomorin.xseries.reflection.minecraft.MinecraftPackage;
 import net.md_5.bungee.api.chat.BaseComponent;
 import org.bukkit.configuration.ConfigurationSection;
@@ -54,7 +53,7 @@
  * PacketPlayOutTitle: https://minecraft.wiki/w/Protocol#Title
  *
  * @author Crypto Morin
- * @version 4.0.0
+ * @version 4.0.1
  * @see XReflection
  * @see ActionBar
  */
@@ -240,11 +239,11 @@ public static void sendTitle(@NotNull Player player,
                 if (subtitle != null) {
                     packets.add(ClientboundSetSubtitleTextPacket.invoke(MessageComponents.bungeeToVanilla(subtitle.asComponent())));
                 }
-            } catch (Throwable e) {
-                throw new RuntimeException(e);
+            } catch (Throwable ex) {
+                throw new IllegalStateException("Failed to create packets with title: " + title + " and subtitle: " + subtitle, ex);
             }
 
-            MinecraftConnection.sendPacket(player, packets.toArray(new Object[0]));
+            sendPacket(player, packets.toArray(new Object[0]));
             return;
         }
 
@@ -254,19 +253,23 @@ public static void sendTitle(@NotNull Player player,
         }
 
         try {
-            Object timesPacket = PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_TIMES, CHAT_COMPONENT_TEXT.invoke(title), fadeIn, stay, fadeOut);
-            sendPacket(player, timesPacket);
+            // There are also constructors with only the fade/stay/fadeout or just the text components,
+            // but we will use the full constructor for all of them just to be sure.
+            List<Object> packets = new ArrayList<>(3);
+            Object titleComponent = CHAT_COMPONENT_TEXT.invoke(title);
+
+            packets.add(PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_TIMES, titleComponent, fadeIn, stay, fadeOut));
 
             if (title != null) {
-                Object titlePacket = PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_TITLE, CHAT_COMPONENT_TEXT.invoke(title), fadeIn, stay, fadeOut);
-                sendPacket(player, titlePacket);
+                packets.add(PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_TITLE, titleComponent, fadeIn, stay, fadeOut));
             }
             if (subtitle != null) {
-                Object subtitlePacket = PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_SUBTITLE, CHAT_COMPONENT_TEXT.invoke(subtitle), fadeIn, stay, fadeOut);
-                sendPacket(player, subtitlePacket);
+                packets.add(PACKET_PLAY_OUT_TITLE.invoke(TITLE_ACTION_SUBTITLE, CHAT_COMPONENT_TEXT.invoke(subtitle), fadeIn, stay, fadeOut));
             }
-        } catch (Throwable throwable) {
-            throwable.printStackTrace();
+
+            sendPacket(player, packets.toArray(new Object[0]));
+        } catch (Throwable ex) {
+            throw new IllegalStateException("Failed to send packets for title: " + title + " and subtitle: " + subtitle, ex);
         }
     }
 

core/src/main/java/com/cryptomorin/xseries/profiles/builder/ProfileInstruction.java

@@ -31,6 +31,7 @@
 import com.cryptomorin.xseries.profiles.objects.DelegateProfileable;
 import com.cryptomorin.xseries.profiles.objects.ProfileContainer;
 import com.cryptomorin.xseries.profiles.objects.Profileable;
+import com.google.common.base.Function;
 import com.mojang.authlib.GameProfile;
 import org.bukkit.block.BlockState;
 import org.bukkit.inventory.ItemStack;
@@ -40,17 +41,16 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
-import java.util.Objects;
+import java.util.*;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
 
 /**
  * Represents an instruction that sets a property of a {@link GameProfile}.
  * It uses a {@link #profileContainer} to define how to set the property and
  * a {@link #profileable} to define what to set in the property.
+ * <p>
+ * This class must be created from one of {@link XSkull} methods.
  *
  * @param <T> The type of the result produced by the {@link #profileContainer} function.
  */
@@ -87,9 +87,9 @@ public T removeProfile() {
         return profileContainer.getObject();
     }
 
-    @ApiStatus.Experimental
     @NotNull
     @Contract(value = "_ -> this", mutates = "this")
+    @ApiStatus.Experimental
     public ProfileInstruction<T> profileRequestConfiguration(ProfileRequestConfiguration config) {
         this.profileRequestConfiguration = config;
         return this;
@@ -111,13 +111,15 @@ public ProfileInstruction<T> lenient() {
      */
     @Override
     @Nullable
+    @ApiStatus.Internal
     public GameProfile getProfile() {
         // Just here to handle the JavaDocs.
         return profileContainer.getProfile();
     }
 
     @Override
     @Contract(pure = true)
+    @ApiStatus.Internal
     public Profileable getDelegateProfile() {
         return profileContainer;
     }
@@ -151,6 +153,8 @@ public ProfileInstruction<T> fallback(@NotNull Profileable... fallbacks) {
     /**
      * Called when any of the {@link #fallback(Profileable...)} profiles are used,
      * this is also called if no fallback profile is provided, but the main one {@link #profile(Profileable)} fails.
+     * <p>
+     * Make sure that {@link #lenient()} is not, otherwise this will never be used.
      *
      * @see #onFallback(Runnable)
      */
@@ -187,6 +191,7 @@ public ProfileInstruction<T> onFallback(@NotNull Runnable onFallback) {
      * @throws ProfileChangeException If any type of {@link ProfileException} occurs, they will be accumulated
      *                                in form of suppressed exceptions ({@link Exception#getSuppressed()}) in this single exception
      *                                starting from the main profile, followed by the fallback profiles.
+     * @see #applyAsync()
      */
     @NotNull
     public T apply() {
@@ -270,6 +275,9 @@ public T apply() {
      * }</pre>
      *
      * @return A {@link CompletableFuture} that will complete asynchronously.
+     * @see #apply()
+     * @see Profileable#prepare()
+     * @see Profileable#prepare(Collection, ProfileRequestConfiguration, Function)
      */
     @NotNull
     public CompletableFuture<T> applyAsync() {

core/src/main/java/com/cryptomorin/xseries/profiles/builder/XSkull.java

@@ -73,8 +73,8 @@
  * I don't know if this cache system works across other servers or is just specific to one server.
  *
  * @author Crypto Morin, Erick Alexander
- * @version 11.2.1
- * @see XMaterial
+ * @version 12.0.0
+ * @see Profileable
  * @see XReflection
  */
 public final class XSkull {
@@ -140,7 +140,7 @@ public static ProfileInstruction<Skull> of(@NotNull BlockState state) {
 
 
     /**
-     * We'll just return an x shaped hardcoded skull.<br>
+     * We'll just return a prohibition sign hardcoded skull.<br>
      * <a href="https://minecraft-heads.com/custom-heads/miscellaneous/58141-cross">minecraft-heads.com</a>
      */
     private static final GameProfile DEFAULT_PROFILE = PlayerProfiles.signXSeries(ProfileInputType.BASE64.getProfile(
@@ -150,15 +150,17 @@ public static ProfileInstruction<Skull> of(@NotNull BlockState state) {
     ));
 
     /**
-     * Retrieves the default {@link GameProfile} used by XSkull.
+     * The default {@link GameProfile} used by {@link ProfileInstruction} as a last resort
+     * when none of the fallback values could be retrieved. This profile represents
+     * <a href="http://textures.minecraft.net/texture/c10591e6909e6a281b371836e462d67a2c78fa0952e910f32b41a26c48c1757c">
+     * a red prohibition sign on a silver head.</a>
      * This method creates a clone of the default profile to prevent modifications to the original.
      *
-     * @return A clone of the default {@link GameProfile}.
+     * @return A clone of the default {@link Profileable}.
      */
     @NotNull
     @Contract(value = "-> new", pure = true)
     protected static Profileable getDefaultProfile() {
-        // We copy this just in case something changes the GameProfile properties.
         return Profileable.of(PlayerProfiles.clone(DEFAULT_PROFILE), false);
     }
 }

core/src/main/java/com/cryptomorin/xseries/profiles/mojang/PlayerProfileFetcherThread.java

@@ -34,9 +34,9 @@
 @ApiStatus.Internal
 public final class PlayerProfileFetcherThread implements ThreadFactory {
     /**
-     * An executor service with a fixed thread pool of size 2, used for asynchronous operations.
+     * An executor service with a fixed thread pool of size 10, used for asynchronous operations.
      */
-    public static final ExecutorService EXECUTOR = Executors.newFixedThreadPool(2, new PlayerProfileFetcherThread());
+    public static final ExecutorService EXECUTOR = Executors.newFixedThreadPool(10, new PlayerProfileFetcherThread());
 
     private static final AtomicInteger COUNT = new AtomicInteger();
 

core/src/main/java/com/cryptomorin/xseries/profiles/objects/Profileable.java

@@ -58,10 +58,16 @@
  * Represents any object that has a {@link GameProfile} or one can be created with it.
  * These objects are cached.
  * <p>
+ * Usually this class is intended to be used with {@link com.cryptomorin.xseries.profiles.builder.XSkull XSkull}
+ * by defining the profile to set for {@link ProfileInstruction#profile(Profileable)}, however it can be used by itself for more advanced
+ * systems if you know what you're doing.
+ * <p>
  * A {@link GameProfile} is an object that represents information about a Minecraft player's
  * account in general (not specific to this or any other server)
  * The most important information contained within this profile however, is the
  * skin texture URL which the client needs to properly see the texture on items/blocks.
+ * The server itself doesn't process the texture from the URL, it gives it to the client for
+ * it to download and process the texture instead.
  *
  * @see com.cryptomorin.xseries.profiles.objects.cache.CacheableProfileable
  * @see TimedCacheableProfileable
@@ -93,6 +99,7 @@ public interface Profileable {
      * and doesn't need to a request any data using {@link com.cryptomorin.xseries.profiles.mojang.MinecraftClient MinecraftClient}.
      *
      * @see #prepare(Collection)
+     * @since 12.0.0
      */
     @Contract(pure = true)
     boolean isReady();
@@ -169,10 +176,30 @@ default String getProfileValue() {
         return PlayerProfiles.getOriginalValue(getProfile());
     }
 
+    /**
+     * A single version of {@link #prepare(Collection, ProfileRequestConfiguration, Function)}.
+     * This simply performs profile lookup asynchrously and returns after it's done, or it
+     * will instantly return if {@link #isReady()} is true.
+     *
+     * @return A future containing the same object.
+     * @since 12.0.0
+     */
+    @NotNull
+    @Contract("-> new")
+    @ApiStatus.Experimental
+    default CompletableFuture<Profileable> prepare() {
+        if (isReady()) return CompletableFuture.completedFuture(this);
+
+        return XReflection.stacktrace(CompletableFuture
+                .supplyAsync(this::getProfile, PlayerProfileFetcherThread.EXECUTOR)
+                .thenApply(x -> this));
+    }
+
     /**
      * @see #prepare(Collection, ProfileRequestConfiguration, Function)
      */
     @NotNull
+    @Contract("_ -> new")
     @ApiStatus.Experimental
     static <C extends Collection<Profileable>> CompletableFuture<C> prepare(@NotNull C profileables) {
         return prepare(profileables, null, null);
@@ -188,8 +215,10 @@ static <C extends Collection<Profileable>> CompletableFuture<C> prepare(@NotNull
      *                     otherwise that specific profile will be ignored.
      * @param <C>          the type of the collection used for the profiles.
      * @return the same collection unmodified. (The profiles are cached inside the {@link Profileable} itself, so you can use them directly now)
+     * @see #prepare()
      */
     @NotNull
+    @Contract("_, _, _ -> new")
     @ApiStatus.Experimental
     static <C extends Collection<Profileable>> CompletableFuture<C> prepare(
             @NotNull C profileables, @Nullable ProfileRequestConfiguration config,

core/src/test/com/cryptomorin/xseries/test/Constants.java

@@ -47,7 +47,7 @@ public static Path getTestPath() {
     }
 
     /**
-     * This sends unnecessary requests to Mojang and also delays out work too,
+     * This sends unnecessary requests to Mojang and also delays our work too,
      * so let's not test when it's not needed.
      */
     public static final boolean TEST_MOJANG_API = false;

core/src/test/com/cryptomorin/xseries/test/XSeriesTests.java

@@ -548,6 +548,7 @@ private static void testSkulls() {
                 .lenient().apply();
 
         // Currently broken. Seems like Mojang disabled this API? Read MojangAPI.usernamesToUUIDs for more info.
+        // [5/31/2025] It's working again!
         if (Constants.TEST_MOJANG_API_BULK) {
             log("Testing bulk username to UUID conversion");
             Map<UUID, String> mapped = MojangAPI.usernamesToUUIDs(Arrays.asList("yourmom1212",

core/src/test/com/cryptomorin/xseries/test/XSkullRequestQueueTest.java

@@ -25,12 +25,14 @@
 import com.cryptomorin.xseries.profiles.lock.KeyedLock;
 import com.cryptomorin.xseries.profiles.lock.KeyedLockMap;
 import com.cryptomorin.xseries.profiles.lock.MojangRequestQueue;
+import com.cryptomorin.xseries.profiles.objects.Profileable;
 import com.cryptomorin.xseries.reflection.XReflection;
 import com.cryptomorin.xseries.test.util.XLogger;
 import org.junit.jupiter.api.Assertions;
 
 import java.lang.invoke.MethodHandle;
 import java.util.*;
+import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.atomic.AtomicInteger;
 
 final class XSkullRequestQueueTest {
@@ -80,6 +82,24 @@ public static void test() {
             int times = cache.getValue().get();
             Assertions.assertEquals(1, times, () -> "Cached more than once: " + cache.getKey() + " -> " + times);
         }
+
+        realTest();
+    }
+
+    private static void realTest() {
+        // This can vary specially for the second request since
+        // they have to wait for the first one to finish.
+        // The best way to test this would be to somehow limit your
+        // internet speed significantly.
+        // Whatever the duration is, it should progressively get smaller and smaller.
+        // 800ms -> 630ms -> 600ms -> 5ms -> 0ms
+        List<CompletableFuture<Void>> profiles = new ArrayList<>(5);
+
+        for (int i = 1; i <= 5; i++) {
+            profiles.add(XLogger.logTimingsAsync("Notch Async Lookup " + i, () -> Profileable.username("Hex_26").getProfile()));
+        }
+
+        CompletableFuture.allOf(profiles.toArray(new CompletableFuture[0])).join();
     }
 
     private static String blackhole(int i) {

core/src/test/com/cryptomorin/xseries/test/util/XLogger.java

@@ -22,9 +22,23 @@
 
 package com.cryptomorin.xseries.test.util;
 
+import java.util.concurrent.CompletableFuture;
+
 public final class XLogger {
     public static void log(String message) {
         // We should probably use an actual logger?
         System.out.println("[XSeries] " + message);
     }
+
+    public static CompletableFuture<Void> logTimingsAsync(String prefix, Runnable runnable) {
+        return CompletableFuture.runAsync(() -> logTimings(prefix, runnable));
+    }
+
+    public static void logTimings(String prefix, Runnable runnable) {
+        long before = System.currentTimeMillis();
+        runnable.run();
+        long after = System.currentTimeMillis();
+        long diff = after - before;
+        log('[' + prefix + "] Took " + diff + "ms");
+    }
 }