Migrating from API 7 to API 8

SpongeAPI 8 is a significally upgraded API compared to SpongeAPI 7, such that every plugin will need to be updated to be compatible. While we cannot list every little thing that you will need to change here, this page contains some of the more common migrations that will be required.

Note

We provide a plugin template that you can clone to create your own plugins. While this guide is primarily intend for migrating plugins, you may find it useful to investigate this template to help your migration, particularly with the plugin metadata changes.

@Plugin annotation and migration from mcmod.info to sponge_plugins.json

SpongeAPI 8 introduces a new Plugin annotation that only contains the plugin ID. As a result, the SpongeAPI build no longer contains an annotation processor that will generate the metadata file for you.

To generate the metadata file, you can either:

  • Create the file yourself by creating sponge_plugins.json in your resources root and filling it out with the required information

  • Use SpongeGradle 2 and define the metadata in the buildscript as in this example

More information about the metadata file can be found at Plugin Metadata.

Game Lifecycle

The previous lifecycle events (such as GamePreInitializationEvent) have been removed. SpongeAPI 8 uses a clearer lifecycle so you know exactly when to register various parts of your plugin. Most of your plugin’s setup should now be done in “Register” events, such as RegisterCommandEvent or RegisterDataEvent, though there are a few generic events (such as LoadedGameEvent) that may also be used.

More information about the game lifecycle can be found at Plugin Lifecycle.

Engines

SpongeAPI 8 introduces the concept of an engine. While SpongeAPI 7 was mostly designed for servers, SpongeAPI 8 considers the client as a first class citizen. The Server and Client are both Engine.

In general plugin development, it is likely that you will only really consider the server - this is true even in singleplayer environments as the game client starts a singleplayer server. However, note that there can be times where the client is running but no server engine exists.

There are generic lifecycle events that fire when each engine starts. You can use the StartingEngineEvent, StartedEngineEvent and StoppingEngineEvent (if the engine hasn’t crashed) events if you need to be aware of when each engine starts.

As before, engines can restart multiple times within a game instance (generally, this will happen in clients where the server is started multiple times - a new server is started when a singleplayer game is started.)

Migrating to Engine Scoped Objects

With the introduction of Engines, some objects have now got engine specific versions. In particular:

When migrating your plugin, you will generally want to use the server variants of these interfaces. Be careful to check the return type of various methods that return these object to make sure you’re getting the correct type.

CatalogTypes and Registries

The Sponge registry has been overhauled and CatalogTypes no longer exist.

In the previous system, objects had an awareness of their own identifier through the CatalogType#getId method. This generally restricted these types to only exist in one registry. In SpongeAPI 8, any object can be placed in a registry of the correct type without implementing CatalogType, with the key to the object being provided separately, allowing an object to exist in multiple registries with different keys.

Additionally, unlike in SpongeAPI 7 and earlier where all registries were global to the game instance, in SpongeAPI 8 and later registries can be scoped to the engine

Plugins that wish to add items to the registry must do so during the RegisterRegistryValueEvent for the RegistryType they wish to register the object to. The standard registry types can be found at RegistryTypes. Similarly, plugins that wish to create their own registries can do so during the RegisterRegistryEvent.GameScoped, RegisterRegistryEvent.EngineScoped or RegisterRegistryEvent.WorldScoped event, depending on what scoping is required.

Custom Data

Data gets an overhaul in SpongeAPI 8, but the most impactful change to consider when migrating plugins is that custom data is now much simpler to use. In particular, there are two large changes as to how you implement custom data:

  • Data is now primarily driven by the Key system, rather than DataManipulators. Keys can be created at any time and do not need to be registered.

  • Any data supplied to data holders using an unregistered key is transient - for example, if data is supplied to a player using an unregistered key and the player dies (so their player object is recreated) that data is lost. To persist custom data, plugins must register their keys during the RegisterDataEvent and supply a DataRegistration (via the DataRegistration.Builder) that tells Sponge how to persist the data.

In addition, SpongeAPI 8 allows for custom keys to point to external data stores. This can be done by providing a DataProvider to the DataRegistration.

More information about data can be found at The Data API

Command Creation and Registration

Commands have been completely overhauled in SpongeAPI 8 in order to support Minecraft’s command completions, as well as to resolve long standing issues with the previous system. Most developers will want to use the structured command builder via Command#builder(). Additionally, commands should now be registered during the RegisterCommandEvent, those who use the command builder should register commands for the generic event RegisterCommandEvent<Command.Parameterized>.

SpongeAPI 8 also provides for ways to allow alternate frameworks to integrate at a low-level using CommandRegistrar.

More information about commands can be found at Plugin Commands.

Migration of Text to Adventure

SpongeAPI 8 uses the Adventure library to provide text manipulation. In general, Text objects have become Components, most components will be created via builder methods on that interface. For those who wish to emulate a Text.of(...) like behaviour, use the linear method in LinearComponents.

There are additional Sponge specific helper operations in the org.spongepowered.api.adventure package, specifically SpongeComponents for those who used the executeCallback function in SpongeAPI 7.

More information about text within Sponge can be found at Text.

Scheduler

The scheduler has been updated to better reflect the scope in which a scheduler resides:

  • The asynchronus Scheduler is game scoped and remains on the Game object (and the Sponge object)

  • Each Engine now has its own synchronus scheduler, and is available via the engine’s instance.

The Task object is no longer responsible for determining whether it is asynchronus or not, as such, the Task.Builder#async method has been removed. Additionally, building a Task no longer submits it, instead, you must submit the task to the relavant Scheduler via the submit(Task) method.

Sponge also provides a TaskExecutorService for each scheduler, should users prefer to the the Java ExecutorService for their tasks.

More information about the scheduler can be found at Scheduler.

Plugin Services

SpongeAPI 8 no longer supports custom plugin services, only supporting its own. If you want to provide an implementation for a Sponge service, you must now listen to the ProvideServiceEvent for the service interface you wish to provide the implementation for. Within this method, you may suggest a supplier that will create the service in the event your plugin is selected to provide the service. Note that most services are server scoped, meaning that it is possible for there to be multiple requests to provide some services during a game’s lifetime.

There is no guarantee that the event will get called for your plugin if another plugin has provided the service first or if Sponge is configured to only look for a specific service.

Plugins that wish to provide their own service interfaces should provide their own service management, or direct plugins to register a factory that implements that interface.

More information about services can be found at Services

Configurate

Configurate has been updated from version 3 to version 4, and along with it, its package name has changed from ninja.leaping.configurate to org.spongepowered.configurate, and has mostly dropped the use of get and set prefixes.

For more information on Configurate, you can view its manual here.