9 Years of SpigotMC | Spigot & BungeeCord 1.18-1.18.2 Release

Edit (1 March): 1.18.2 is now available with --rev 1.18.2. BungeeCord 1.18.2 is in the usual location.

Edit: 1.18.1 is now available with --rev 1.18.1. A BungeeCord update is not required.

Edit (9 December): 1.18 is now the default version.

Edit: 1.18 release is now available.

Dear All

As we mark the 9-year anniversary of SpigotMC.org, it is my pleasure to announce that development/preview builds of Spigot for Minecraft 1.18 are now available. Owing to the shorter interval between 1.17 and 1.18 this is a smaller update than previous major releases. There are however still some significant changes, particularly around world generation and biomes, so some initial caution is advised.

Plugin Updates
With the exception of plugins referencing removed biomes/particles and changes to third-party libraries (especially MySQL), there are no breakages expected. As a server owner, if a plugin is breaking on Minecraft updates, you should be encouraging developers to code their plugin in a way that it does not break (read: use the API). Doing this once is much more efficient than depending on an update every release. As a developer you should use the API wherever possible — a stable API is what distinguishes plugins from mods. If you cannot use the API, then you should contribute one, or at least open a feature request stating the API desired and why you need it. This will prevent you needing to update your plugin each release and will cumulatively save server owners and the community thousands of hours each year. You should consider it your duty to the community to do this.

Java Version
Mojang has decided to make Minecraft 1.18 require Java 17 or later. You can install this from a third party such as Azul Zulu or your Linux package manager. Please note that the --illegal-access=permit workaround is no longer possible on this version. Please also note that current versions of Java 17 have a bug which may affect users on single-core systems. If you have such a system consider adding -Djava.util.concurrent.ForkJoinPool.common.parallelism=1 as a Java argument.

Backups
Please make sure you have recent and tested backups for your server before upgrading. As always it is not possible to downgrade your server to an earlier version. This is especially important for this release due to the permanent alterations to older worlds.

World Upgrading
Although upgrades from between any two version pairs are technically possible, it is recommended that all upgrades are conducted from 1.17.x. This means that you should first upgrade your world completely on 1.17.x using the --forceUpgrade server argument, and then do the same on 1.18.

Bug Reports
If you are reporting a bug to JIRA, please make sure that you read the guidelines and have compared the results between Vanilla & Spigot, and also the 1.17.1 versions before reporting — this speeds up the process for us immensely and ensures more bugs get fixed more quickly. Please report bugs, or issues you think might be bugs, to JIRA and not in this thread, Discord, or any place other than JIRA. We prefer good quality but uncertain reports over no reports at all.

Developers
Please see the below post(s).

Downloading / Installing
In order to get 1.18, simply run the latest BuildTools. Please make sure both your BuildTools and Java versions are up to date. There may be mandatory BuildTools updates throughout the 1.18 release cycle, so it is good practice to ensure that you are always using the latest version. You can download the latest BuildTools from this link.

Code (Text):

java -jar BuildTools.jar

If you haven't used BuildTools to create a server jar yet, it is suggested you first read the 1.8 announcement and the BuildTools Wiki.

BungeeCord is available in the usual location: https://ci.md-5.net/job/BungeeCord/

Closing Notes
Each release represents the culmination of hundreds of hours of effort, so if SpigotMC has helped you in any way, shape, or form we encourage you to leave a donation, contribution, or nice message. If nothing else, at least please make sure that any bug reports you may open are polite, clear, specific, and have been tested thoroughly both without plugins and on Vanilla.

Enjoy,
~Spigot Team

PS: Join our Discord.

 

Developer Notes

API Changes
You can view a complete summary of the API changes between 1.17.1 and 1.18.x at this link. There are no intentional API breakages but do note that there may be slight unavoidable changes. A short list of things to look out for include:

• Java 17 may change behaviour, particularly if reflection is used.
• MySQL has been upgraded to the 8.x driver series. This driver is more strict in some operations (eg, mistakenly using executeQuery when executeUpdate should be used instead) and may require plugin updating.
• Google Guava and GSON have been bumped to the newer versions per Mojang.
• Some biomes have been renamed or removed.
• The world height extends to less than 0 and greater than 256.
• There have been extensive internal changes to world generation and biome code. Any plugin-facing changes at this stage however are unintentional, so please report them as bugs.

We have also reserved one of the below posts to keep you updated about new additions and changes made early on in the release period (before 1.18 becomes the default version).

Bootstrap Jar
The main spigot-1.18.jar is now a bootstrap jar which contains all libraries. You cannot directly depend on this jar. You should depend on Spigot/Spigot-API/target/spigot-api-1.18-R0.1-SNAPSHOT-shaded.jar (download), or the entire contents of the bundler directory from your server, or use a dependency manager such as Maven or Gradle to handle this automatically.

Future API
There are plans underway to change the way many enums in the API are handled so that custom content can be better supported. These changes are not expected to break most plugin jars (backwards compatibility will be provided), however they may unavoidably break plugin source code (though the Maven version will be bumped if this occurs). To reduce the risk of breakage, please consider avoiding the use of switch statements and EnumSet over enums which implement 'Keyed'.

Planned Removal of commons-lang
The API currently includes a very outdated copy of commons-lang. This API dependency is now deprecated and will be removed from the API and eventually the Server in a future release. Please consider switching to Google Guava (which is a supported bundled API) or using your own copy of the much more recent commons-lang3.

NMS
Please refer to the 1.17 post for information about NMS — it is still current. As always, but especially now, please try and avoid/limit NMS usage at all costs. If you must use NMS please ensure you check the value of CraftMagicNumbers.INSTANCE.getMappingsVersion() is what you expect before loading your plugin and note that development against a 'Mojang Mapped' jar is now preferred as only classes remain 'Spigot Mapped' (see 1.17 post). For your convenience the examples have been updated and posted below.

Example Dependency Config

Code (Text):

<dependency>
    <groupId>org.spigotmc</groupId>
    <artifactId>spigot</artifactId>
    <version>1.18-R0.1-SNAPSHOT</version>
    <classifier>remapped-mojang</classifier>
    <scope>provided</scope>
</dependency>

Example Maven Config

Code (Text):

<plugin>
    <groupId>net.md-5</groupId>
    <artifactId>specialsource-maven-plugin</artifactId>
    <version>1.2.3</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>remap</goal>
            </goals>
            <id>remap-obf</id>
            <configuration>
                <srgIn>org.spigotmc:minecraft-server:1.18-R0.1-SNAPSHOT:txt:maps-mojang</srgIn>
                <reverse>true</reverse>
                <remappedDependencies>org.spigotmc:spigot:1.18-R0.1-SNAPSHOT:jar:remapped-mojang</remappedDependencies>
                <remappedArtifactAttached>true</remappedArtifactAttached>
                <remappedClassifierName>remapped-obf</remappedClassifierName>
            </configuration>
        </execution>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>remap</goal>
            </goals>
            <id>remap-spigot</id>
            <configuration>
                <inputFile>${project.build.directory}/${project.artifactId}-${project.version}-remapped-obf.jar</inputFile>
                <srgIn>org.spigotmc:minecraft-server:1.18-R0.1-SNAPSHOT:csrg:maps-spigot</srgIn>
                <remappedDependencies>org.spigotmc:spigot:1.18-R0.1-SNAPSHOT:jar:remapped-obf</remappedDependencies>
            </configuration>
        </execution>
    </executions>
</plugin>

Example Manual Commands

Code (Text):

java -cp $HOME/.m2/repository/net/md-5/SpecialSource/1.11.0/SpecialSource-1.11.0-shaded.jar:$HOME/.m2/repository/org/spigotmc/spigot/1.18-R0.1-SNAPSHOT/spigot-1.18-R0.1-SNAPSHOT-remapped-mojang.jar net.md_5.specialsource.SpecialSource --live -i $PLUGIN.jar -o $PLUGIN-obf.jar -m $HOME/.m2/repository/org/spigotmc/minecraft-server/1.18-R0.1-SNAPSHOT/minecraft-server-1.18-R0.1-SNAPSHOT-maps-mojang.txt --reverse
java -cp $HOME/.m2/repository/net/md-5/SpecialSource/1.11.0/SpecialSource-1.11.0-shaded.jar:$HOME/.m2/repository/org/spigotmc/spigot/1.18-R0.1-SNAPSHOT/spigot-1.18-R0.1-SNAPSHOT-remapped-obf.jar net.md_5.specialsource.SpecialSource --live -i $PLUGIN-obf.jar -o $PLUGIN.jar -m $HOME/.m2/repository/org/spigotmc/minecraft-server/1.18-R0.1-SNAPSHOT/minecraft-server-1.18-R0.1-SNAPSHOT-maps-spigot.csrg

Your $PLUGIN.jar is then ready for distribution. $HOME refers to your user directory (C:\Users\<name> on Windows).

 

Comment support
A long existing problem with config files has finally been fixed - comments are no longer deleted when saving. Additionally, there is now API to set different types of comments to any YAML key.

API Changes
Some of the old configuration concepts had to be dropped as they make no sense anymore.

• The buildHeader method has been removed from the FileConfiguration class as headers are now handled differently. If you extend it, make sure to adjust your implementation.
• The YAMLConfigurationOptions' copyHeader method is now deprecated and just wraps the new parseComments method. Additionally, the header method is now deprecated. getHeader and setHeader shall be used instead.

Here is a brief summary of the new API:

• List<String> getComments(String path), List<String> getInlineComments(String path), void setComments(String path, List<String> comments) and void setInlineComments(@NotNull String path, @Nullable List<String> comments) can now be invoked on any ConfigurationSection.
  All these methods work with a list of comments - each entry is a new line. Empty strings represent a comment without text (just a #) while null entries are saved as an empty line.
• Introduced dedicated methods to get and set the header and the new footer.

Example
Bukkit distinguishes between two comment types: Block comments and inline comments. Here is an example:

Code (YAML):

# This is a header,
# it can be as long as you want
#

# Additionally, both the empty comment and the empty line above belong to the header too.
# BUT

# only until the last empty line.
# This last empty line separates the header from the comment that belongs to the first key.
# In this case these 3 lines are the block comment of configSection1.
configSection1:
   # Block comment related to configSection2
    configSection2: # Inline comment related to configSection2
        # Block comments
        # can be
        #
        # as long as want

        # and can contain empty lines and empty comments.
        key1: value 1 # Inline comments can also
                      # contain multiple lines
                      #

                      # empty comments and empty lines!
       # This is the next block comment, related to key2.
       key2: value 2

All other variants of comments are not supported by Bukkit and will be deleted.