v13.0.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>13.0.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:13.0.0")
}

Important

Don't forget to shade the library.

---

Happy new year!

Important

XReflection

About

For the past few months I've been working on XReflection extensively. XReflection first started as a small group of classes
that's designed for Minecraft in mind specifically. It makes other classes that require reflection much easier.
However, I've been improving it a lot that simplifies this process, each simplification is in a stage. There are a total of
five stages and currently 4 of them are implemented. All these steps were mostly a proof-of-concept for the 5th and final stage.
This final stage allows developers to seamlessly use NMS/CraftBukkit classes across multiple versions, using real constructors, fields and methods, whether private, protected or public, with compile-time checked types and almost zero overhead.

Future Plans

XSeries packaged JAR is currently 700kb and 200kb belongs to the XReflection classes.
Since XReflection is becoming too big for this project, and frankly, even becoming an offtopic project,
I'm planning to split it into its own project. However, XSeries will
continue to use the stage I and stage II of XReflection as a dependency, but unnecessary classes will be excluded to decrease
the JAR file size. This new project will use Gradle as its build system as it's going to be multimodule with its own custom
IntelliJ plugin to make things easier. For now, XReflection will remain in XSeries until the preparations are done.

Paper's Reflection Remapper

Also, I've just saw this after finishing the stage IV (ASM generated classes), but
it seems like Paper also has a similar project named Reflection Remapper
which uses a similar interface-based system as well. However, there are some features that is missing from that project:

• ReflectionRemapper uses raw Java proxies (similar to Stage III - ReflectiveProxy in our project) but we also have ASM-generated classes as well
  which will improve performance significantly with almost zero overhead.
• ReflectionRemapper only supports mappings for a single version.
• ReflectionRemapper doesn't support proxy objects for return types or parameters.
• ReflectionRemapper doesn't have isInstance(), instance(), and getTargetClass(). I also plan to add a way to check whether
  a method is supported or not, however ReflectionRemapper doesn't have this feature.
• ReflectionRemapper doesn't have a proxy class generator utility.
• ReflectionRemapper cannot use real classes with fields, constructors and methods. However, this is going to be added to XRefleciton.

There are some other projects that are also similar to this as well, but none of them have the complete feature set that I have in mind.
Any suggestions or improvements are welcome to the current XReflection systems while it lasts here.

• Added experimental ReflectiveConstraint API for XReflection to make targets more precise.

• Added XAccessFlag used mainly for ReflectiveConstraints.

• Fixed ENTITY_EXPERIENCE_ORB_TOUCH v1.9 missing value for XSound.

• Improved ReflectionParser.

• Improved Unit Tests.

• Added @Contract annotations to most APIs.

• [XBiome] Fixed an issue with world min/max height.

• [XTag] Fixed INVENTORY_NOT_DISPLAYABLE for wheat.

• [XReflection] Using the suffix support for JetBrains @Language annotation, we no longer need to add semicolons or {}
  at the end of string APIs. Other than the readability improvement, this results in a slight performance
  improvement as well, since fewer characters are needed for parsing.

• More compliance with common best code practices.

  • Replaced RuntimeExceptions with suitable exceptions. Mostly defaulted to IllegalStateException
    when the error is too generic.
  • Replaced Cloneable and its clone() methods with copy()
  • Refactored some parts of the code for better readability.
  • Not all of these practices make sense, so I skipped some of them.

• Added experimental ReflectiveProxy API (XReflection Stage III - Proxification) which is has a significant readability advantage but
  has a significant
  performance disadvantage which makes it unusable in most sitautions, however this prototype will allow us to
  develop the next reflection API (Stage IV) which will have significant advantage in terms of both readability and
  performance if it's successful.

• Added experimental XReflectASM API (XReflection Stage IV - ASMification) which is the same as ReflectiveProxy which massive performance
  advantages that beat raw reflection because of generated code. However, this performance advantage is not as perfect for
  inaccessible class members. This is because of Java's Jigsaw project, and we need to use some really hacky workarounds to
  make this work for inaccessible methods. Read XReflectASM#MAGIC_ACCESSOR_IMPL field for more info.
  Once this is done, we can enter XReflection Stage V. It comes with an XProxifier which currently must be used programmatically.

• Added JMH Benchmark which is not 100% reliable due to:

  • Running inside IDE testing environment which can be affected by many external factors instead of using a JAR.
  • Not running in forked mode. We need to retain the server state.
  • Being run using Maven's exec plugin which might be able to affect our benchmarks.

v12.1.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>12.1.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:12.1.0")
}

Important

Don't forget to shade the library.

---

1.21.4 Support

Important

XSeries will no longer follow independent class principle due to a lot of changes caused by previous versions.
This version implements the abstraction concept from #239 as an experiment. This change was forced because
Minecraft now uses registries for most enum-like.

• Added v1.21.4 support thanks to @kangarko
• Implemented the @XMerge annotation system.
• Added license header for all classes.
• Added XItemFlag.
• Added XPatternType.
• Fixed XMaterial.BLACK_DYE for v1.8
• Fixed an error caused by XSound in older versions (issue with pulling system values)
• Fixed an issue with XPotion name matching system.
• MethodMemberHandles are now more lenient when it comes to public methods that are in superclasses of the target class.
• Added XTag.getTag(String name)
• XTag general class cleanup (Uses TagBuilder, we should also inline most tags)
• Deprecated a lot of methods. Although they wont be removed any time soon, you should update as soon as possible.
• Fixed XItemStack to use XPatternType.
• XPotion now covers more value ranges.
• Significantly improved unit tests.
• Fixed a few broken sound entries for v1.12
• Improved XEnchantment's Enchantment->XEnchantment mapping for older versions.
• XAttribute: Fixed some missing values. Also fixed the entire class for some older versions (specifically ~v1.15-1.19)
• XParticle: Fixed some missing/mismatched values.

v12.0.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>12.0.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:12.0.0")
}

Important

Don't forget to shade the library.

---

v1.21.3 Support - Registry Update

Important

XSeries will no longer follow independent class principle due to a lot of changes caused by previous versions.
This version implements the abstraction concept from #239 as an experiment. This change was forced because
Minecraft now uses registries for most enum-like.

This version introduces the new XRegistry/XModule system which is going to be inherited for XEnchantment, XPotion, XEntityType and XMaterial in later versions if this goes well.

• Added XAttribute.
• Fixed XSound & XBiome support for v1.21.3
• Fixed XTag.ORES not including diamonds and emeralds
• Fixed XItemStack support for v1.8.8

v11.3.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.3.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.3.0")
}

Important

Don't forget to shade the library.

---

• Replaced all JavaX annotations with JetBrains annotations.
• Added more annotations to XSkull APIs.
• Fixed some errors with XSkull API (specially when used for XItemStack) (Fixes #300)
• Added AggregateReflectiveSupplier
• Added more tests.
• XSkull will now try to create less verbose profile values which can be used for XItemStack but requires extra settings.

v11.2.2

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.2.2</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.2.2")
}

Important

Don't forget to shade the library.

---

• Added v1.21.1b78+ support for skulls.
• Improved how AggregateReflectiveHandle handles unknown class types for more flexibility.
• Fixed TURTLE_MASTER potion type issues for XPotion. (Fixes #294)
• Fixed some serialization issues with XItemStack. (Fixes #297)

v11.2.1

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.2.1</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.2.1")
}

Important

Don't forget to shade the library.

---

• Added v1.21 support.
• Added Object and CharSequence as predefined classes for ReflectionParser.
• ReflectionParser class declarations now support simple generics.
• XSkull will now more lenient with proxy reflection errors.
• Fixed particle deserialization from conkfig when no particle size is specified for dust particles.
• XReflection parameter and return types are now lazy.

v11.2.0.1

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.2.0.1</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.2.0.1")
}

Important

Don't forget to shade the library.

---

• XItemStack#parseColor now accepts hex colors
• XSkull Profileables are now nullable for certain types.
• Fixed XSkull proxy reflection issues on v1.18.1-1.19.4
• Removed all usage of the old XReflection within XSeries code.
• Fixed a few issues with NMSExtras.
• Due to people reporting "NMS_VERSION" from getVersionInformation() returning null, it was changed to "Unknown NMS" instead.
• Fixed an issue where trying to reflect a class handle with no names provided didn't provide a proper error.
• Added more Javadocs.

v11.2.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.2.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.2.0")
}

Important

Don't forget to shade the library.

---

• Fixed a lot of issues with XSkull
• Added more documentations to XReflection with a few renames and bug fixes.
• Added enum support for XReflection.
• Changed the default material for XItemStack.

v11.1.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.1.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.1.0") { isTransitive = false }
}

Important

Don't forget to shade the library.

---

v1.21 Support

XSkull

• Moved to another package. Classes have been split.
• Made non-API methods private inside XSkull.
• Fixed UUID detection as string values.
• Fixed a few issues with offline/online UUID profiles and their cachex.
• Added a lenient() and fallback() method to XSkull.
• Allows HTTPS requests for texture links.

XReflection

• Added more predefined classes to ReflectionParser.
• Added inner class support to XReflection

Others

• The of(String) method of XParticle & XEntityType now return Optional.

v11.0.0

Maven

<dependency>
    <groupId>com.github.cryptomorin</groupId>
    <artifactId>XSeries</artifactId>
    <version>11.0.0</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.cryptomorin:XSeries:11.0.0") { isTransitive = false }
}

Important

Don't forget to shade the library.

---

Quick Code Update

I'm very sorry for the class renames. It had to be done at some point.
You could simply do a RegEx replace in this order (unfortunately IntelliJ's Migrate feature doesn't work for nonexisting
classes properly):

• ReflectionUtils
  1. Replace import (static )?com.cryptomorin.xseries.ReflectionUtils
     with import $1com.cryptomorin.xseries.reflection.XReflection
  2. Replace ReflectionUtils with XReflection
  3. Replace (XReflection.)?sendPacket(Sync)?\( with MinecraftConnection.sendPacket(
  4. For people who want to use the new ClassHandle API:
     1. (?:XReflection\.)?getNMSClass\(([\w."]+), ([\w"]+)\) -> XReflection.ofMinecraft().inPackage(MinecraftPackage.NMS, $1).named($2).unreflect()
     2. (?:XReflection\.)?getCraftClass\("(?:([\w\.]+)(?:\.))?(\w+)"\) -> XReflection.ofMinecraft().inPackage(MinecraftPackage.CB, "$1").named("$2").unreflect()
• NMSExtras
  1. Replace import (static )?com.cryptomorin.xseries.NMSExtras
     with import $1com.cryptomorin.xseries.reflection.minecraft.NMSExtras
• SkullUtils
  1. Replace SkullUtils with XSkull
  2. Replace XSkull.applySkin\(([^,]+), ([\w\d_]+)\) with XSkull.of($1).profile($2).apply()

You may have to update some parts manually yourself after this replacement.

XReflection (Former ReflectionUtils)

Completely revamped. ReflectionUtils has been split into so many classes. While I understand this might upset some
people because
they now have to include an entire package for ReflectionUtils-dependent classes to work, the class was becoming
almost unmaintainable from all the clutter. Most of these new features are experimental and might change in the future.

• Now has a functional API.
• Added string-based reflection which works specially well in IntelliJ because of the syntax highlighting support. The
  performance of this approach is obviously much worse, but since this should only be done once (even if you're using
  the functional approach, you should cache all reflection calls), the readability advantages far outweigh the
  performance disadvantage.

void functionalAPI() {
    MinecraftClassHandle CraftMetaSkull = XReflection.ofMinecraft()
            .inPackage(MinecraftPackage.CB, "inventory")
            .named("CraftMetaSkull");
    MethodHandle profileGetterMeta = CraftMetaSkull.getterField()
            .named("profile")
            .returns(GameProfile.class)
            .makeAccessible()
            .reflect();
}

void stringAPI() {
    // Normally all classes you pass to a namespace are visible 
    // (classes created from XReflection handle methods or passed to parameter(), return(), etc methods)
    // But sometimes the only way to make these classes visible would be to import them manually here.
    // You can avoid doing this and use fully qualified names instead inside strings.
    ReflectiveNamespace ns = XReflection.namespaced().imports(GameProfile.class);

    // There are shorthand names for packages like "nms", "spigot" and "cb"
    // The "extends CraftMetaItem implements SkullMeta" is completely useless and
    // only included for brevity (doesn't affect anything if the found class doesn't implement the specified classes).
    MinecraftClassHandle CraftMetaSkull = ns.ofMinecraft(
            // This code will be highlighted when used in IntelliJ:
            "package cb.inventory; class CraftMetaSkull extends CraftMetaItem implements SkullMeta {}"
    );
    MethodHandle profileGetterMeta = CraftMetaSkull.field("private GameProfile profile;")
            .map(MinecraftMapping.OBFUSCATED, "a") // You can mix functional and string APIs
            .getter().reflect();
}

XSkull (Former SkullUtils)

XSkull was completely revamped, all thanks to @Condordito

• It now supports offline mode servers and has a more robust API.
• Fixed some issues with detecting the correct skin value passed.

XBlock

• Removed deprecated methods from XBlock.
• Fixed an issue with setting skulls using XBlock.setType()

Others

• Fixed Data.NAME_MAPPING for XParticle and XEntityType.
• Fixed a bug with ParticleDisplay on older versions.
• Fixed legacy support for XPotion.
• Fixed an issue with XWorldBorder in outdated servers.
• Fixed withLocationCaller() for Particles class.
• Removed the deprecated XMaterial.isOneOf() and XMaterial.matchXMaterial(int id, byte data)
• Fixed a lot of issues in XParticle thanks to @CJCrafter