Миграция с API 7 на API 8

SpongeAPI 8 - это значительно обновлённый API, по сравнению со SpongeAPI 7. Поэтому плагин нужно будет обновить, чтобы он был совместим. Пока мы не может перечислить каждую мелочь, которую вам нужно будет изменить. Эта страница содержит наиболее распространённые миграции, которые необходимо сделать.

Примечание

Мы предоставляем шаблон плагина, который вы можете клонировать для создания собственных плагинов. Хотя это руководство предназначено в первую очередь для миграции плагинов, вам может быть полезно исследовать этот шаблон, чтобы облегчить миграцию, особенно с изменениями метаданных плагина.

Аннотация @Plugin и миграция с mcmod.info на sponge_plugins.json

SpongeAPI 8 представляет новую аннотацию Plugin, которая содержит только ID плагина. В результате сборка SpongeAPI больше не содержит процессор с аннотациями, который создаст для вас файл метаданных.

Чтобы сгенерировать файл, вы можете:

Больше информации о метаданных файла, вы можете найти в Метаданные плагина.

Игровой жизненный цикл (Game Lifecycle)

Прошлые ивенты жизненного цикла (такие как GamePreInitializationEvent) были удалены. SpongeAPI 8 использует более четкий жизненный цикл, чтобы вы точно знали, когда регистрировать различные части вашего плагина. Большая часть настройки плагина должна выполняться в ивентах типа «Register», таких как RegisterCommandEvent или RegisterDataEvent. Хотя есть несколько общих ивентов (например, LoadedGameEvent), их также можно использовать.

Больше информации об игровом жизненном цикле вы можете узнать в Жизненный цикл плагина.

Движки (Engines)

В SpongeAPI 8 представлена ​​концепция движка. В то время как SpongeAPI 7 был в основном разработан для серверов, SpongeAPI 8 рассматривает клиента как гражданина первого класса (a first class citizen). Server и Client являются Engine.

В общем, при разработке плагинов, скорее всего, вы действительно будете рассматривать только сервер — это верно даже в однопользовательских средах, поскольку игровой клиент запускает одиночный сервер. Однако обратите внимание, что могут быть случаи, когда клиент работает, но не существует ядра сервера.

Существуют общие ивенты жизненного цикла, которые запускаются при запуске каждого движка. Вы можете использовать события StartingEngineEvent, StartedEngineEvent и StoppingEngineEvent (если движок не был крашнут), если вам нужно знать, когда запускается каждый движок.

Как и раньше, движки могут перезапускаться несколько раз в пределах экземпляра игры (как правило, это происходит в клиентах, где сервер запускается несколько раз — новый сервер запускается при запуске одиночной игры).

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 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 Команды.

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 Текст.

Планировщик

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 Планировщик.

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 Сервисы

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.