Миграция с API 7 на API 8
SpongeAPI 8 - это значительно обновлённый API, по сравнению со SpongeAPI 7. Поэтому плагин нужно будет обновить, чтобы он был совместим. Пока мы не может перечислить каждую мелочь, которую вам нужно будет изменить. Эта страница содержит наиболее распространённые миграции, которые необходимо сделать.
Примечание
Мы предоставляем шаблон плагина, который вы можете клонировать для создания собственных плагинов. Хотя это руководство предназначено в первую очередь для миграции плагинов, вам может быть полезно исследовать этот шаблон, чтобы облегчить миграцию, особенно с изменениями метаданных плагина.
Аннотация @Plugin
и миграция с mcmod.info
на sponge_plugins.json
SpongeAPI 8 представляет новую аннотацию Plugin, которая содержит только ID плагина. В результате сборка SpongeAPI больше не содержит процессор с аннотациями, который создаст для вас файл метаданных.
Чтобы сгенерировать файл, вы можете:
Создайте файл самостоятельно, создав
Spong_plugins.json
в корне ваших ресурсов и заполнив его необходимой информацией.Используйте SpongeGradle 2 и определите метаданные в скрипте сборки, как в этом примере.<https://github.com/SpongePowered/sponge-plugin-template/blob/88d3c35853a687a7dc1540db43a9f9a135c03819/build.gradle.kts#L16-L40>__
Больше информации о метаданных файла, вы можете найти в Метаданные плагина.
Игровой жизненный цикл (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:
Player now has ClientPlayer and ServerPlayer subinterfaces
World now has ClientWorld and ServerWorld subinterfaces
Location now has ClientLocation and ServerLocation subinterfaces
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.