Bukkit, CraftBukkit, Spigot & BungeeCord 1.13 Development Builds

Dear SpigotMC Community,

It is my pleasure to announce that development builds for the Minecraft 1.13 release are now available. I will outline important considerations/changes below, but it is important that you read this post in its entirety, including the original 1.13-pre7 section. Even if you have already read that part, please read it again as it is still very much applicable.

In terms of server preparation, we have now added 1.13 to the "Tested Minecraft Versions" resource field, as well as created a new field called "Native Minecraft Version". This second field has two choices - "Legacy (<1.13)" and "1.13". If you are a developer you should please set this field to indicate what api-version you used to program your plugin, as it will no doubt be an important consideration for server owners looking to update.

As for general server stability we expect that this update will fall into three key "waves" for those looking to update. We are currently in the extreme caution wave and expect to advance through them as 1.13.x versions are released by Mojang.

1. Extreme Caution (1.13 - Current): This version is stable for those looking to run a public server based on Minecraft 1.13, but only if an entire reset of all worlds and data is performed, and all plugins in use have a Native Minecraft Version of 1.13. It is not safe to use on existing worlds. There are known Vanilla bugs that will irreparably delete data from your old world, or otherwise render it unusable. You may use this version to test conversion of your world, but you will NEED to restore your world from a 1.12.2 backup before moving onto the second wave.
2. Caution (1.13.x - future): There are no known world conversion bugs, and you should be able to safely update your world. Native 1.13 plugins should be used, but older plugins will function as well as they are ever likely to. Caution is still advised as there may be undiscovered data loss bugs.
3. Normal (1.13.x - far future): There have been no world conversion bugs reported for quite some time, so it is probably safe to update your world. Native 1.13 plugins should be used, but older plugins will function as well as they are ever likely to.

*** Spigot 1.12.2 worlds must be converted using CraftBukkit/Spigot and NOT Vanilla.

In terms of API changes between 1.13-pre7 and 1.13, there is the following to note:

• DyeColor.SILVER has been replaced by DyeColor.LIGHT_GRAY. A legacyValueOf method is provided for conversion.
• New coral blocks have been added, and the existing coral fans updated to be Waterlogged, rather than Directional.
• New tags have been added, and outdated ones removed.
• Dolphin and Fish now extend WaterMob.
• LivingEntity Swimming APIs and events have been added.
• EntityChangeBlockEvent has been updated to use BlockData
• EntityPotionEffectEvent has been added as a beta event.
• Legacy serialized ItemStack conversion has been improved.
• Scoreboard related text length limits have been increased.
• Byte setData methods have been removed from the Block interface to prevent people using them incorrectly in 1.13 plugins.

Please note that stability rules don't apply, and the API may be subject to further breaking change (although this is unlikely and we will endeavour not to do so).

Enjoy, but please keep in mind everything else mentioned below. In particular I have been disappointed by the quality of some of the bug reports coming in. Even if the bug seems obvious/simple to you, it may not be to me, and if I have to ask for clarification then a fix will be delayed. Bugs are being fixed quickly, and for free - it is not much to ask that you spend 10-15 minutes writing a decent report that has been tested in 1.12 and Vanilla. If you are a developer you should also consider taking a look at the bug yourself. This is a stressful time for all and your patience is appreciated.

~md_5


----------------------------------------------------------------------------------------------------------------------------------


It's a big one!

After over 200 days of work and more than 500 commits, it is time for me to announce that the first 1.13 versions of CraftBukkit/Spigot/BungeeCord are now available to the public. Before continuing further I must stress the point that these are not release builds. They are not designed to be used on live servers, and if you run them without creating backups you will lose data. They are being released now to 1) allow plugin developers to begin porting their plugins, and 2) allow community members to contribute the finishing touches and improvements.

1.13 is different from any previous versions in several key aspects. As evidenced by some of the numbers above, it is the largest release of Minecraft ever, with a huge amount of changes, features, and bugs introduced. It is difficult to put an exact assessment on the scope of the changes, but a jump from 1.8 to 1.12 all at once is a fair approximation (i.e. all 4 previous updates merged together). In addition to all of these changes made to Vanilla, the Bukkit API has also had to adapt. The centerpiece of this release is that the Material API has been completely overhauled to both mirror Vanilla more closely, and also add BlockData features which have been missing for a long time. The flip side of this is that the scope of the changes means forwards/backwards compatibility is not assured.

One of the key strengths of the Bukkit API is that there is a strong emphasis on forwards compatibility and that there is a good chance you can pick up a plugin that has not been updated in many years with the expectation that it will still run on your server. This is something that we wish to maintain, so a considerable amount of time has been spent writing a compatibility layer that will allow many plugins to function to some degree. Some more detail about what is and isn't supported will be given in the developer oriented changelogs below, but the key points for server owners to be aware of are as follows:

• The compatibility layer is not a substitute for updating plugins. The official recommendation is that you do not run a production server until each and every plugin you use has been updated and verified to work with 1.13.
• The compatibility layer is largely best effort support. Significant time and effort has already been invested in making it behave correctly and predictably. The layer is good enough that we can run around 20 popular plugins without significant issues, and further development is not likely to be a priority. Also the current implementation has been in testing for > 6 months and can handle many edge cases that may not be immediately obvious to further changes.
• The compatibility layer will add overhead to the plugins that use it. Nothing comes for free and in this case the trade off is that Materials have to be converted continuously between the old and new APIs.
• The compatibility layer is not recommended for use with plugins that save material or item data. Although code has been written to accommodate this use case it should be used with caution.

Notes for Developers
The 1.13 API is largely not backwards compatible with older versions. This means that if your plugin targets native 1.13 support it will NOT be able to run on < 1.13. Whilst forwards compatibility has always been a design goal of Bukkit, backwards compatibility has not been. If you wish to maintain support for older versions (e.g. 1.8) then you will need to concurrently develop two versions of your plugin. It is our hope however that going forwards only recent Bukkit versions will be supported by developers as this is the best way for the community as a whole to keep evolving. Once you have made the necessary changes to your plugin to enable successful compilation against the 1.13 API, you must add the following to your plugin.yml:

Code (Text):

api-version: 1.13

This will signal to the server that your plugin has been coded with 1.13 in mind, and that it should not apply any sort of backwards compatibility measures. As a result you will also need to make sure that you have programmed your code to account for reading of older configurations, data, etc. More on this later.

API Changes
What follows is a short summary of (almost) all changes made to the Bukkit API between 1.12.2 and 1.13, as well as a short explanation regarding them. Some of these are also explained in more detail in a previous post.

• Two paintings, BURNINGSKULL and DONKEYKONG have been renamed to BURNING_SKULL and DONKEY_KONG respectively to bring them in line with Vanilla names. A minimal amount of backwards compatibility has been added, but it is expected the impact of this change will be minimal as Art is not a commonly used API.
• ChunkSnapshot.getRawBiomeRainfall has been removed. This method was deprecated over a year ago as RawBiomeRainfall is no longer a phenomenon within Minecraft.
• Two Particles, FOOTSTEP and ITEM_TAKE have been removed as they no longer exist. A number of additional particles have been added; the REDSTONE particle now takes DustOptions as a parameter, and the BLOCK_CRACK, BLOCK_DUST, and FALLING_DUST particles have been updated to support the new BlockData API.
• A significant number of Sounds have been added/removed/renamed to the Sound enum. This is allowed by precedent and the API contract of that class.
• The PLAY_ONE_TICK statistic has been replaced by the PLAY_ONE_MINUTE statistic; SWIM_ONE_CM by WALK_ON_WATER_ONE_CM; DIVE_ONE_CM by WALK_UNDER_WATER_ONE_CM. No backwards compatibility has been provided and the impact to plugins is expected to be minimal. The new DROP_COUNT, TIME_SINCE_REST, and SWIM_ONE_CM statistics have also been added.
• Various methods in UnsafeValues have been added/removed/changed. These methods are not API so will not be discussed further.
• A new WorldType, BUFFET has been added. Note that the old CUSTOMIZED worlds are not supported in Vanilla anymore. Do not update a CUSTOMIZED map to 1.13.
• The Bed BlockState has been deprecated as it serves no useful purpose now that each bed colour has its own Material.
• The Biome enum has been brought into line with the new Vanilla biome names. There was some consideration whether to make this change or not, but the consensus on IRC was that now is a prudent time to do so. No backwards compatibility has been provided, so most plugins dealing with Biomes will require changes.
• The FlowerPot BlockState has been deprecated as each potted flower is now its own Material, rather than tile entity.
• The NoteBlock BlockState has been deprecated as note blocks are no longer tile entities.
• Several methods in the Skull BlockState to do with rotation and skull type have been deprecated as these are now either properties of the BlockData (rotation) or Material (type).
• Enchantment no longer has numeric IDs, and now implements Keyed with NamespacedKeys matching those in Vanilla. The getName method has been deprecated as the names provided are confusing / nonstandard, and the Enchantment key should be used instead. This class may change further before final API release. The isCursed method has also been deprecated as cursed enchantments are no longer treated specially by the game.
• The internal name strings of several EntityTypes have been changed following their changes in Vanilla. No backwards compatibility has been provided as the methods for accessing them via the API are deprecated.
• The deprecated Fish class (originally meaning FishHook) has been undeprecated and now represents the Fish entities added to the game. This may affect some usages of the PlayerFishEvent.
• The setInstrument / setNote methods of NotePlayEvent have been deprecated as they now have no effect. This is because the instrument / note played are now directly related to the block present in the world.
• FurnaceRecipe is now Keyed like normal crafting recipes. Plugins should update to define their own NamespacedKey, otherwise Bukkit is forced to randomly generate one.
• The SpawnEggMeta SpawnedType methods have been deprecated as the spawn egg for each entity is now its own Material.
• A new overload of Scoreboard.registerNewObjective which allows specifying a display name has been added. This is because internal changes suggest that display name mutability may not always be supported.
• Select dependencies have been upgraded including SnakeYaml, MySQL, and SQLite. SQLite databases may not be able to be downgraded back to older servers.
• BukkitScheduler.cancelAllTasks has been removed - this method is only ever called by mistake.
• Material.isTransparent has been deprecated as it does not appear to have a well defined meaning anymore. Contributions linking it back to Vanilla are welcome.

And the big ones

• All Materials have been renamed to match the names used in Vanilla. The old Materials have been prefixed with LEGACY_ and can only be validly accessed by plugins targeting previous API versions. Plugins converting data from old versions should use the new boolean parameter in Material.getMaterial and Material.matchMaterial to return the new Material with the closest possible mapping. Note however that there is not a 1:1 mapping between all old and all new Materials so correct conversion may not be possible.
• MaterialData, and by extension all subclasses, and all related methods have been deprecated. MaterialData objects can only be validly created by plugins targeting previous API versions. BlockData is the replacement and all methods that once took MaterialData have a BlockData equivalent. createBlockData and related methods present in both Material and Bukkit/Server can be used to get BlockData instances and parse BlockData from the Vanilla style strings, e.g. minecraft:cake[bites=3]. To get strings like this for serialization, you can use the BlockData.getAsString method. As is the convention in Bukkit BlockData instances are mutable, but not linked to the underlying block and therefore must be manually set back after changing. You can cast BlockData instances to the specific types you need, and the class hierarchy has been designed so related classes share common interfaces.
• All occurrences of integer Material IDs have been removed. Some compatibility exists for extremely common old usages, e.g. setTypeId but really there are no excuses and developers should have stopped using these methods many many years ago.
• Plugin channels have been normalized in the Minecraft protocol. This means that they MUST match the format of a valid namespaced key, i.e. "namespace:key". Backwards compatibility is a difficult problem in this circumstance, but because plugin channels are designed primarily for use with mods, which require updates for each version, we have not done any automatic conversion. The exception to this is the BungeeCord channel which must remain both past, present, and future as "BungeeCord", rather than the namespaced format.

Further notes for developers
The API is not final so the usual rules about breakages do not yet apply. This means that plugins written for one version of 1.13 may not work for another version of 1.13. The 1.13 builds will all have a very short expiration timer (~3 days) to help accomodate this. If you have questions or concerns about changes that you think should be made to the API they should be brought up on IRC or the bug tracker as soon as possible. Contributions are also welcome via the usual channels.

Further notes for server owners
The safest route at this point in time is to not carry over any data from 1.12.2. Of course migration of old data is possible and is worth testing for the benefit of future owners, but keep in mind that even the Vanilla world migration may introduce subtle irreparable destruction to your world that may not be immediately obvious.

Closing Notes
As stated above this release has been in development since November last year. It represents the culmination of hundreds of hours of mostly individual effort. There is still a long way to go yet, but if SpigotMC has helped you in any way, shape, or form I 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.

~md_5

PS: No, I didn't forget installation instructions, if you don't know how to get it at this point it is not ready for you.

PPS: Bug reports which do not 1) contain a declaration of testing in Vanilla and without plugins, or 2) in the case of plugin API bugs, contain a minimal reproduction case (source + jar please) will be closed. Bug reports must contain step by step instructions to reproduce the bug from a clean server install with no assumptions or prior knowledge. Also make sure you include the full output of /version in your report. Please copy and paste this statement to the bottom of your report to indicate that you have read and understood it.

PPPS: Failure to include the above statement will result in a 24 hour ban from the forums.