v13.3.0

Author: CryptoMorin

README.md

@@ -1,3 +1,5 @@
+![XSeries Logo](https://github.com/user-attachments/assets/4b179b17-3f2b-4640-bc50-df2275300bcb)
+
 # XSeries
 
 [![Minecraft](https://img.shields.io/badge/Minecraft-1.21.5-dark_green.svg)](https://shields.io/)
@@ -13,7 +15,7 @@ Some utilities are completely unrelated to cross-version support such as NoteBlo
 > [!IMPORTANT]
 > Don't forget to add `api-version: "1.13"` to your **plugin.yml**.
 > This will not prevent your plugin from working even if the server is not using Minecraft v1.13
-> This is only required if you want to use one of the XBase/XModule classes. 
+> This is only required if you want to use one of the XBase/XModule classes.
 
 > [!CAUTION]
 > Make sure to [shade](https://github.com/CryptoMorin/XSeries?tab=readme-ov-file#shading)
@@ -42,7 +44,8 @@ You can use some of these utilities individually or use the maven dependency.
 Most of the utilities are intended to be independent. However, some
 utilities such as [XParticle](core/src/main/java/com/cryptomorin/xseries/particles/XParticle.java) are intended to use
 another class ([ParticleDisplay](core/src/main/java/com/cryptomorin/xseries/particles/ParticleDisplay.java)).
-All XBase/XModule classes also depend on these base classes and also [XRegistry](core/src/main/java/com/cryptomorin/xseries/base).
+All XBase/XModule classes also depend on these base classes and
+also [XRegistry](core/src/main/java/com/cryptomorin/xseries/base).
 
 #### Maven ![maven-central](https://img.shields.io/maven-central/v/com.github.cryptomorin/XSeries)
 
@@ -53,21 +56,26 @@ All XBase/XModule classes also depend on these base classes and also [XRegistry]
     <artifactId>XSeries</artifactId>
     <version>version</version>
 </dependency>
-
-<!-- If you want to use XSkull and you use 'spigot-api' dependency you need the following: -->
-<repository>
-    <id>minecraft-libraries</id>
-    <name>Minecraft Libraries</name>
-    <url>https://libraries.minecraft.net/</url>
-</repository>
-<dependency>
-<groupId>com.mojang</groupId>
-    <artifactId>authlib</artifactId>
-    <version>6.0.54</version>
-    <scope>provided</scope>
-</dependency>
 ```
 
+> [!NOTE]
+> If you want to use XSkull and you use `spigot-api` dependency you need the following:
+> ```xml
+> <repository>
+>     <id>minecraft-libraries</id>
+>     <name>Minecraft Libraries</name>
+>     <url>https://libraries.minecraft.net/</url>
+> </repository>
+> ```
+> ```xml
+> <dependency>
+>     <groupId>com.mojang</groupId>
+>     <artifactId>authlib</artifactId>
+>     <version>6.0.54</version>
+>     <scope>provided</scope>
+> </dependency>
+> ```
+
 Gradle
 
 ```kotlin

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

@@ -31,14 +31,12 @@
 import org.jetbrains.annotations.ApiStatus;
 
 import java.lang.invoke.MethodHandle;
-import java.util.regex.Pattern;
 
 import static com.cryptomorin.xseries.reflection.XReflection.ofMinecraft;
 
 /**
  * Utility class for sharing methods relating to {@link BaseComponent}.
  */
-@ApiStatus.Experimental
 public final class MessageComponents {
     private static final MethodHandle CraftChatMessage_fromJson;
 
@@ -61,16 +59,36 @@ public final class MessageComponents {
         CraftChatMessage_fromJson = fromJson;
     }
 
+    // @formatter:off
+    public interface MessageText {
+        String asString();
+        BaseComponent asComponent();
+    }
+    public static final class MessageTextString implements MessageText {
+        private final String string;
+        public MessageTextString(String string) {this.string = string;}
+
+        public String asString() {return string;}
+        public BaseComponent asComponent() {return MessageComponents.fromLegacy(string);}
+    }
+    public static final class MessageTextComponent implements MessageText {
+        private final BaseComponent component;
+        public MessageTextComponent(BaseComponent component) {this.component = component;}
+
+        public String asString() {return component.toLegacyText();}
+        public BaseComponent asComponent() {return component;}
+    }
+    // @formatter:on
+
     /**
      * This method is only officially available on <a href="https://github.com/PaperMC/Paper/blob/c98cd65802fcecfd3db613819e6053e2b8cbdf4f/paper-server/src/main/java/org/bukkit/craftbukkit/util/CraftChatMessage.java#L350-L352">Paper</a>.
      */
+    @ApiStatus.Experimental
     public static Object bungeeToVanilla(BaseComponent component) throws Throwable {
         String json = ComponentSerializer.toString(component);
         return CraftChatMessage_fromJson.invoke(json);
     }
 
-    private static final Pattern url = Pattern.compile("^(?:(https?)://)?([-\\w_.]{2,}\\.[a-z]{2,4})(/\\S*)?$");
-
     @SuppressWarnings("deprecation")
     public static BaseComponent fromLegacy(String message) {
         return new TextComponent(TextComponent.fromLegacyText(message));

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

@@ -39,6 +39,7 @@
 import java.util.Objects;
 import java.util.function.Function;
 
+import static com.cryptomorin.xseries.messages.MessageComponents.*;
 import static com.cryptomorin.xseries.reflection.XReflection.ofMinecraft;
 import static com.cryptomorin.xseries.reflection.minecraft.MinecraftConnection.sendPacket;
 
@@ -55,6 +56,7 @@
  * @author Crypto Morin
  * @version 4.0.0
  * @see XReflection
+ * @see ActionBar
  */
 public final class Titles {
     /**
@@ -74,7 +76,7 @@ public final class Titles {
             ClientboundSetTitleTextPacket,
             ClientboundSetSubtitleTextPacket;
 
-    private BaseComponent title, subtitle;
+    private MessageText title, subtitle;
     private final int fadeIn, stay, fadeOut;
 
     /**
@@ -175,16 +177,20 @@ public final class Titles {
         ClientboundSetSubtitleTextPacket = subtitleCtor;
     }
 
-    public Titles(BaseComponent title, BaseComponent subtitle, int fadeIn, int stay, int fadeOut) {
+    public Titles(MessageText title, MessageText subtitle, int fadeIn, int stay, int fadeOut) {
         this.title = title;
         this.subtitle = subtitle;
         this.fadeIn = fadeIn;
         this.stay = stay;
         this.fadeOut = fadeOut;
     }
 
+    public Titles(BaseComponent title, BaseComponent subtitle, int fadeIn, int stay, int fadeOut) {
+        this(new MessageTextComponent(title), new MessageTextComponent(subtitle), fadeIn, stay, fadeOut);
+    }
+
     public Titles(String title, String subtitle, int fadeIn, int stay, int fadeOut) {
-        this(MessageComponents.fromLegacy(title), MessageComponents.fromLegacy(subtitle), fadeIn, stay, fadeOut);
+        this(new MessageTextString(title), new MessageTextString(subtitle), fadeIn, stay, fadeOut);
     }
 
     public Titles copy() {
@@ -210,12 +216,12 @@ public void send(Player player) {
     public static void sendTitle(@NotNull Player player,
                                  int fadeIn, int stay, int fadeOut,
                                  @Nullable String title, @Nullable String subtitle) {
-        sendTitle(player, fadeIn, stay, fadeOut, MessageComponents.fromLegacy(title), MessageComponents.fromLegacy(subtitle));
+        sendTitle(player, fadeIn, stay, fadeOut, new MessageTextString(title), new MessageTextString(subtitle));
     }
 
     public static void sendTitle(@NotNull Player player,
                                  int fadeIn, int stay, int fadeOut,
-                                 @Nullable BaseComponent title, @Nullable BaseComponent subtitle) {
+                                 @Nullable MessageText title, @Nullable MessageText subtitle) {
         Objects.requireNonNull(player, "Cannot send title to null player");
         if (title == null && subtitle == null) return;
 
@@ -228,11 +234,11 @@ public static void sendTitle(@NotNull Player player,
                 packets.add(ClientboundSetTitlesAnimationPacket.invoke(fadeIn, stay, fadeOut));
 
                 if (title != null) {
-                    packets.add(ClientboundSetTitleTextPacket.invoke(MessageComponents.bungeeToVanilla(title)));
+                    packets.add(ClientboundSetTitleTextPacket.invoke(MessageComponents.bungeeToVanilla(title.asComponent())));
                 }
 
                 if (subtitle != null) {
-                    packets.add(ClientboundSetSubtitleTextPacket.invoke(MessageComponents.bungeeToVanilla(title)));
+                    packets.add(ClientboundSetSubtitleTextPacket.invoke(MessageComponents.bungeeToVanilla(subtitle.asComponent())));
                 }
             } catch (Throwable e) {
                 throw new RuntimeException(e);
@@ -243,7 +249,7 @@ public static void sendTitle(@NotNull Player player,
         }
 
         if (SUPPORTS_TITLES) {
-            player.sendTitle(title.toLegacyText(), subtitle.toLegacyText(), fadeIn, stay, fadeOut);
+            player.sendTitle(title.asString(), subtitle.asString(), fadeIn, stay, fadeOut);
             return;
         }
 
@@ -330,30 +336,28 @@ public static Titles parseTitle(@NotNull ConfigurationSection config, @Nullable
         return new Titles(title, subtitle, fadeIn, stay, fadeOut);
     }
 
-    public BaseComponent getTitle() {
+    public MessageText getTitle() {
         return title;
     }
 
-    public BaseComponent getSubtitle() {
+    public MessageText getSubtitle() {
         return subtitle;
     }
 
-    @Deprecated
     public void setTitle(String title) {
-        this.title = MessageComponents.fromLegacy(title);
+        this.title = new MessageTextString(title);
     }
 
-    @Deprecated
     public void setSubtitle(String subtitle) {
-        this.subtitle = MessageComponents.fromLegacy(subtitle);
+        this.subtitle = new MessageTextString(subtitle);
     }
 
     public void setTitle(BaseComponent title) {
-        this.title = title;
+        this.title = new MessageTextComponent(title);
     }
 
     public void setSubtitle(BaseComponent subtitle) {
-        this.subtitle = subtitle;
+        this.subtitle = new MessageTextComponent(subtitle);
     }
 
     /**

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

@@ -216,7 +216,9 @@ public static Map<UUID, String> usernamesToUUIDs(@NotNull Collection<String> use
 
         try {
             for (String username : usernames) {
-                finalUsernames.put(username, MojangRequestQueue.USERNAME_REQUESTS.lock(username));
+                KeyedLock<String> lock = MojangRequestQueue.USERNAME_REQUESTS.lock(username);
+                lock.lock();
+                finalUsernames.put(username, lock);
             }
 
             {
@@ -349,21 +351,27 @@ public static GameProfile getOrFetchProfile(@NotNull final GameProfile profile)
             }
         }
 
-        GameProfile cached = handleCache(profile, realUUID);
-        if (cached != null) return cached;
+        try (KeyedLock<UUID> lock = MojangRequestQueue.UUID_REQUESTS.lock(realUUID)) {
+            lock.lock();
 
-        JsonElement request = requestProfile(profile, realUUID);
-        JsonObject profileData = request.getAsJsonObject();
-        List<String> profileActions = new ArrayList<>();
-        GameProfile fetchedProfile = createGameProfile(profileData, profileActions);
+            GameProfile cached = handleCache(profile, realUUID);
+            if (cached != null) return cached;
 
-        fetchedProfile = PlayerProfiles.sanitizeProfile(fetchedProfile);
-        cacheProfile(fetchedProfile);
+            JsonElement request = requestProfile(profile, realUUID);
+            JsonObject profileData = request.getAsJsonObject();
+            List<String> profileActions = new ArrayList<>();
+            GameProfile fetchedProfile = createGameProfile(profileData, profileActions);
 
-        INSECURE_PROFILES.put(realUUID, Optional.of(fetchedProfile));
-        MOJANG_PROFILE_CACHE.cache(new PlayerProfile(realUUID, profile, fetchedProfile, profileActions));
+            fetchedProfile = PlayerProfiles.sanitizeProfile(fetchedProfile);
+            cacheProfile(fetchedProfile);
 
-        return fetchedProfile;
+            INSECURE_PROFILES.put(realUUID, Optional.of(fetchedProfile));
+            MOJANG_PROFILE_CACHE.cache(new PlayerProfile(realUUID, profile, fetchedProfile, profileActions));
+
+            return fetchedProfile;
+        } catch (Throwable ex) {
+            throw new IllegalStateException("Failed to fetch porfile for " + profile, ex);
+        }
     }
 
     @SuppressWarnings("OptionalAssignedToNull")
@@ -387,8 +395,7 @@ public static GameProfile getOrFetchProfile(@NotNull final GameProfile profile)
 
     private static @NotNull JsonElement requestProfile(@NotNull GameProfile profile, UUID realUUID) {
         JsonElement request;
-        try (KeyedLock<UUID> lock = MojangRequestQueue.UUID_REQUESTS.lock(realUUID)) {
-            lock.lock();
+        try {
             request = UUID_TO_PROFILE.session(null)
                     .append(PlayerUUIDs.toUndashedUUID(realUUID) + "?unsigned=" + !REQUIRE_SECURE_PROFILES)
                     .request();
@@ -401,6 +408,7 @@ public static GameProfile getOrFetchProfile(@NotNull final GameProfile profile)
             MOJANG_PROFILE_CACHE.cache(new PlayerProfile(realUUID, profile, null, null));
             throw new UnknownPlayerException(realUUID, "Player with the given properties not found: " + profile);
         }
+
         return request;
     }
 

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

@@ -64,7 +64,7 @@ default GameProfile getProfile() {
     }
 
     @Override
-    default boolean isComplete() {return getDelegateProfile().isComplete();}
+    default boolean isReady() {return getDelegateProfile().isReady();}
 
     @Override
     @NotNull

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

@@ -52,7 +52,7 @@ public abstract class ProfileContainer<T> implements Profileable {
     public abstract T getObject();
 
     @Override
-    public boolean isComplete() {
+    public boolean isReady() {
         return true;
     }
 

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

@@ -84,17 +84,18 @@ public interface Profileable {
     GameProfile getProfile();
 
     /**
-     * Whether this profile has all necessary information to construct its {@link #getProfile()} right away.
-     * When this returns true, it means some kind of request has to be sent to Mojang servers
-     * in order to retrieve information.
+     * Whether this profile has all the necessary information to construct its {@link #getProfile()} right away.
+     * When this method returns false, it means some kind of request has to be sent to Mojang servers
+     * in order to retrieve some information.
      * <p>
-     * This doesn't necessarily mean that this profile has all information (skin, username, UUID, etc.)
-     * it merely means that it has all the information it needs in memory to compute {@link #getProfile()}
-     * and doesn't need to a request using {@link com.cryptomorin.xseries.profiles.mojang.MinecraftClient MinecraftClient}.
+     * Even if this method returns true, it doesn't necessarily mean that this profile has all information (textures, username, UUID, etc.)
+     * it merely means that it has all the information it needs in memory to compute its {@link #getProfile()}
+     * and doesn't need to a request any data using {@link com.cryptomorin.xseries.profiles.mojang.MinecraftClient MinecraftClient}.
      *
      * @see #prepare(Collection)
      */
-    boolean isComplete();
+    @Contract(pure = true)
+    boolean isReady();
 
     /**
      * Tests whether this profile has any issues or throws any exception.
@@ -109,6 +110,7 @@ public interface Profileable {
      * Any other type of exception that might happen are still ignored.
      */
     @Nullable
+    @Contract("-> new")
     default ProfileException test() {
         try {
             getProfile();
@@ -129,6 +131,7 @@ default ProfileException test() {
      */
     @Nullable
     @ApiStatus.Internal
+    @Contract("-> new")
     default GameProfile getDisposableProfile() {
         GameProfile profile = getProfile();
         return profile == null ? null : PlayerProfiles.clone(profile);
@@ -429,7 +432,7 @@ final class RawGameProfileProfileable implements Profileable {
         public RawGameProfileProfileable(GameProfile profile) {this.profile = Objects.requireNonNull(profile);}
 
         @Override
-        public boolean isComplete() {
+        public boolean isReady() {
             return true;
         }
 

core/src/main/java/com/cryptomorin/xseries/profiles/objects/cache/CacheableProfileable.java

@@ -77,7 +77,7 @@ public final boolean hasExpired() {
     }
 
     @Override
-    public final boolean isComplete() {
+    public final boolean isReady() {
         return !hasExpired(false);
     }
 

core/src/main/java/com/cryptomorin/xseries/profiles/objects/transformer/TransformableProfile.java

@@ -91,7 +91,7 @@ private void transform() {
     }
 
     @Override
-    public boolean isComplete() {
+    public boolean isReady() {
         return true;
     }