Spigot & BungeeCord 1.17 & 1.17.1

Discussion in 'News and Announcements' started by md_5, Jun 11, 2021.

Thread Status:
Not open for further replies.
  1. md_5

    Administrator Developer

    Update 6 July 2021: We have updated to 1.17.1. This is a minor but important update. All users are advised to upgrade.

    Dear SpigotMC Community

    We are pleased to announce the first builds of Spigot for Minecraft 1.17 are now available. Although this is a moderately sized update overall there are some major changes and very important points to note, so please read the following carefully.

    Java Version
    Mojang has decided to make Minecraft 1.17 require Java 16 or later. As this is not an LTS version, it is not available by default in the repositories of some popular Linux distributions. You may therefore have to manually install it from a third party such as Azul Zulu. If you see an error message that looks similar to Unsupported Java detected (55.0). This version of Minecraft requires at least Java 16. your Java version is incompatible and you will need to upgrade. If you are using a shared host you should contact your host for instructions on how to do this, otherwise if you are hosting yourself you can check your java version with java -version.

    If you have problems with plugins after updating Java you may be able to temporarily work around this by adding --illegal-access=permit straight after java in your command line. Please note however that this is a temporary workaround and might not work in future Java versions.

    Caves and Cliffs
    Mojang has delayed many features, including extended world heights, generation changes, and certain blocks/items to Minecraft 1.18. Although most of these features are still accessible in 1.17 through the use of either the experimental datapack or commands, and Spigot provides APIs for them, it must be remembered that these features are experimental/disabled for a reason. You are welcome to test them, report Spigot bugs, and contribute API, but be cautious and wary of bugs and the potential for future incompatible changes. There is every chance a world created with the experimental datapack will not be able to be upgraded to 1.18 when it is released. You also cannot remove the experimental datapack once it has been added to a world.

    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.

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

    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.16.5 versions before reporting — this speeds up the process for us immensely during this stressful time.
    Please report bugs, or issues you think might be bugs, to JIRA and not in this thread.

    Please see the below posts.

    A Plea to Those Distributing Spigot Jars
    Whilst we do not and cannot condone Spigot jars other than those officially sourced via BuildTools, this is a plea to those who do distribute jars to please ensure that they are kept up to date. Too often we see users running the first build of Spigot for a particular Minecraft version when it is dozens-hundreds of builds and several months out of date. This is detrimental to the entire community. It is detrimental to users of those builds who experience bugs and crashes; it is detrimental to plugin developers who cannot take advantage of new API; and it is detrimental to us who have to deal with the consequences. So please, if for whatever reason you are distributing Spigot, please ensure it is kept up to date.

    Re: Expectations & Entitlement
    Almost a year ago I wrote in the 1.16 release thread about how disappointed we were in the attitude displayed by many users. I just wanted to draw attention to that post again, first to say thank you for the many kind messages then (they really mean a lot), and secondly to say thank you for the improvements in behaviour this time round. Please remember that an update is not a singular thing that begins or ends with this post. An update is a large commitment and unimaginably stressful period for everyone which lasts for weeks and severely disrupts normal life. We ask you to please keep all this in mind in all your interactions over the coming weeks, and thank those that are already doing so.

    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.

    In order to get 1.17.1, simply run the latest BuildTools with the required arguments. Please make sure both your BuildTools and Java versions are up to date. There may be mandatory BuildTools updates throughout the 1.17 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 --rev 1.17.1
    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/

    ~Spigot Team

    PS: Join our Discord.
    #1 md_5, Jun 11, 2021
    Last edited: Jul 6, 2021
    • Like x 122
    • Winner x 44
    • Friendly x 23
    • Agree x 6
    • Optimistic x 3
    • Funny x 2
    • Informative x 2
    • Creative x 2
  2. md_5

    Administrator Developer

    Developer Notes

    API Changes
    You can view a complete summary of the API changes between 1.16.5 and 1.17 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 16 may change behaviour, particularly if reflection is used.
    • Grass Paths have been renamed to Dirt Paths.
    • Endermites no longer track if they are spawned by players.
    • Cauldrons may be filled with substances other than water.
    • The world height may be less than 0 or greater than 256.
    • There are lots of new blocks calling existing events. Examples include BlockFormEvent, BlockGrowEvent, BlockSpreadEvent and EntityChangeBlockEvent. If one is missing please let us know via a bug report.
    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.17 becomes the default version).

    Library Loader
    Recent versions of 1.16.5, and of course 1.17 include new library loading functionality. This functionality allows the server to load dependencies from Maven Central at runtime, eliminating the need for you to shade them into your jar. It is intended that this API be used for common and large non-Minecraft dependencies, for example database drivers, the Kotlin runtime, and HTTP clients/servers. Specialised libraries should continue to be shaded+relocated or packaged in a separate plugin. A major advantage of the library API is that it reduces plugin size, eliminates the need for relocation, and (in some circumstances) allows multiple versions of the same library to be used by different plugins. An example of using the API is inserting the following into your plugin.yml:

    Code (Text):
        - com.squareup.okhttp3:okhttp:4.9.0
    Please note that for the time being you should not re-declare libraries which are also declared by your dependencies. This might change at a future date, though note that dependency resolution is an extraordinarily complicated topic full of compromises and pitfalls.

    Website API
    @simpleauthority has been hard at work on an official API for the SpigotMC website. If for whatever reason you need to retrieve information from the SpigotMC website, please try and use the API. You can view this api here, and keep your eyes peeled in the coming days for the release of version 0.2 which features even more information. As always, contributions are welcome, especially from experienced PHP developers.

    It pains us to say this every time, but NMS is not API. When you are trying to figure out how to do something, the first move should never be packets or NMS. Bafflingly almost daily we see people bypassing the API to do simple things such as Scoreboards, BossBars, or Particles. There is no reason to do this. Ever. Fully-featured APIs for these things have existed since Mojang added them. Every time you go near NMS you need to ask yourself: 1) Do I need NMS for this? 2) Is there an API for this? 3) Can I contribute / create an API for this? Perpetual (ab)use of NMS by developers hurts everyone. It hurts server owners who must constantly wait for updates and it hurts other developers by stunting API growth and providing a bad example.

    This being said there are some important changes to NMS this release, namely that all fields have been reverted to their obfuscated form. This, along with the repackaging of NMS, are crucial steps in the highly requested process of transitioning to using the so-called 'Mojang Mappings' for development of Spigot itself. In order to assist developers with the transition we have added an additional option to BuildTools, --remapped. This option will install additional Spigot jars into your local Maven repository with the classifiers remapped-obf and remapped-mojang. You can use these to develop against a 'Mojang Mapped' Spigot jar, and then use the below Maven configuration to produce a jar suitable for distribution. By splitting the transition in this way we hope to achieve the best of all worlds — disruption during the busy update period is minimal but with some helpful changes, and developers get a gentle introduction with the option to experiment with a full transition as soon as they are ready. The full transition will be completed subject to developers having some time to get familiar with the process, make additional tooling, and most importantly offer their feedback (despite being highly requested by plugin developers it is still unclear that a transition for Spigot directly benefits plugin developers compared to previous possibilities).

    When choosing to use the 'Mojang Mappings', it is absolutely imperative that you are aware of the conditions attached to them as well as the Mojang EULA. These are not restrictions you can simply ignore. In particular you may only 'use the mappings for development purposes'. This means that you must only use the remapped-mojang jar for development and must remap your plugin prior to distribution. For those not using Maven you can download SpecialSource to help you do this here, and we encourage the creation of instructions/tools for other build systems.

    Remember, using APIs has many many advantages and we would really appreciate your support in creating the best API possible. The advent of the Mojang Mappings should be seen as a reason to use less NMS, not more.

    Example Dependency Config
    Code (Text):
    Example Maven Config
    Code (Text):

    Example Manual Commands
    Code (Text):
    java -cp $HOME/.m2/repository/net/md-5/SpecialSource/1.10.0/SpecialSource-1.10.0-shaded.jar:$HOME/.m2/repository/org/spigotmc/spigot/1.17-R0.1-SNAPSHOT/spigot-1.17-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.17-R0.1-SNAPSHOT/minecraft-server-1.17-R0.1-SNAPSHOT-maps-mojang.txt --reverse
    java -cp $HOME/.m2/repository/net/md-5/SpecialSource/1.10.0/SpecialSource-1.10.0-shaded.jar:$HOME/.m2/repository/org/spigotmc/spigot/1.17-R0.1-SNAPSHOT/spigot-1.17-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.17-R0.1-SNAPSHOT/minecraft-server-1.17-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).
    #2 md_5, Jun 11, 2021
    Last edited: Jun 14, 2021
    • Like x 39
    • Winner x 19
    • Friendly x 8
    • Agree x 4
    • Useful x 3
    • Funny x 1
    • Optimistic x 1
    • Creative x 1
  3. md_5

    Administrator Developer

    Recently Added APIs / Changes
    • New AbstractSkeleton class for Wither Skeletons and Strays. These other types of Skeleton will no longer be instanceof Skeleton, rather AbstractSkeleton.
    Forthcoming APIs
    • Entity armor events
    • Configuration comment support
    #3 md_5, Jun 11, 2021
    Last edited: Jun 14, 2021
    • Winner x 26
    • Like x 22
    • Friendly x 3
    • Informative x 2
    • Funny x 1
  4. Thanks for all the hard work!
    • Agree Agree x 23
    • Friendly Friendly x 7
    • Like Like x 4
    • Funny Funny x 1
  5. simpleauthority


    Good work!
    • Friendly Friendly x 4
    • Like Like x 2
    • Agree Agree x 1
    • Funny Funny x 1
  6. drives_a_ford


    Great job! :)
    • Agree Agree x 6
    • Like Like x 2
    • Funny Funny x 1
  7. pog
    • Like Like x 6
  8. saphiria


    So many years later and you still work hard for this community. Thank you.
    • Like Like x 10
    • Agree Agree x 3
    • Friendly Friendly x 3
    • Funny Funny x 1
  9. ty
    • Like Like x 4
    • Funny Funny x 1
    • Like Like x 5
    • Agree Agree x 1
    • Funny Funny x 1
  11. Choco


    • Like Like x 4
    • Funny Funny x 1
  12. [​IMG]
    Great job as always. Thanks for putting up with us! <3
    #12 PikaMug, Jun 11, 2021
    Last edited: Jun 11, 2021
    • Funny x 28
    • Like x 5
    • Winner x 2
    • Friendly x 2
    • Agree x 1
  13. Great job. Ty
    • Like Like x 2
    • Funny Funny x 1
  14. Awesome! Thanks for the hard work!
    #14 ryandw11, Jun 11, 2021
    Last edited: Jun 11, 2021
    • Optimistic Optimistic x 2
    • Funny Funny x 1
  15. many thanks
    • Like Like x 1
  16. Happy to see this released! Thank you for the option to preserve mojang mappings at runtime for development purposes and thank you for the quick update.
  17. Thank you once again mate!
    • Winner Winner x 1
  18. md_5 your a legend
    • Agree Agree x 7
Thread Status:
Not open for further replies.