Migrando da API 7 para a API 8
SpongeAPI 8 é uma API significantemente melhorada comparada a SpongeAPI 7, de forma que todos plugins terão de ser atualizados para serem compatíveis. Apesar de não podermos listar aqui cada pequena coisa que deve ser mudada, está página contém algumas das migrações mais comuns que são necessárias.
Nota
Nós fornecemos um modelo de plugin que você pode clonar para criar seus próprios plugins. Apesar desse guia ser primariamente focado em migração de plugins, você pode achar útil investigar esse modelo para ajudar na sua migração, particularmente com relação as mudanças de metadados dos plugins.
Anotação @Plugin
e migração de mcmod.info
para sponge_plugins.json
SpongeAPI 8 introduz uma nova anotação Plugin que só contém o plugin ID. Como resultado, a compilação da SpongeAPI não contém mais um processador de anotações que gera os metadados para você.
Para gerar o arquivo de metadados, você pode:
Criar o arquivo você mesmo com o nome de
sponge_plugins.json
na raíz de recursos e preencher as informações necessáriasUsar o SpongeGradle 2 e definir os metadados no script de compilação, como neste exemplo
Mais informações sobre o arquivo de metadados pode ser encontrado em Plugin Metadata.
Ciclo de vida do jogo
Os eventos de ciclo de vida anteriores (como GamePreInitializationEvent
) foram removidos. A SpongeAPI 8 usa um ciclo de vida mais claro, assim você saberá exatamente quando registrar as diversas partes do seu plugin. A maior parte das configurações do seu plugin agoram devem ser feitas nos eventos “Register”, como RegisterCommandEvent ou RegisterDataEvent, também há alguns casos genéricos (como LoadedGameEvent) que podem ser utilizados.
Mais informações sobre o ciclo de vida do jogo pode ser encontrada em Ciclo de Vida de um Plugin.
Motores
SpongeAPI 8 introduz o conceito de motores (Engine). Enquanto a SpongeAPI 7 foi primariamente desenhada para servidores, a SpongeAPI 8 considera os clientes como residentes de primeira classe. Tanto Server, quanto Client são ambos Engine.
No desenvolvimento geral de plugins, é muito provável que você irá somente considerar o servidor - isso é verdade até mesmo nos ambientes de jogador único, dado que o jogo inicia um servidor de jogador único. No entanto, note que há momentos em que o cliente está rodando mas não existe nenhum motor de servidor.
Existem eventos genéricos de ciclo de vida que são lançados quando cada um dos motores inicia. Você pode usar os eventos StartingEngineEvent, StartedEngineEvent e StoppingEngineEvent (se o motor não tiver fechado inesperadamente) se precisar saber exatamente quando cada motor inicia.
Como anteriormente, os motores podem reiniciar várias vezes dentro de uma instância do jogo (geralmente, isso irá acontecer em clientes onde o servidor é iniciado várias vezes - um novo servidor é iniciado sempre que um novo jogo de jogador único é iniciado.)
Migrando para Objetos de Escopo de Motor (Engine Scoped Objects)
Com a introdução das Engines
(Motores), alguns objetos agora receberam versões especifícas por motor. Em particular:
Player agora tem as sub-interfaces ClientPlayer e ServerPlayer
World agora tem as sub-interfaces ClientWorld e ServerWorld
Location agora tem as sub-interfaces ClientLocation e ServerLocation
Ao migrar o seu plugin, você geralmente irá querer utilizar a variante para servidores dessas interfaces. Tome cuidado ao verificar o retorno dos metodos que retornam esses tipos, para ter certeza que está obtendo o tipo correto.
CatalogTypes e Registries
O registro do Sponge foi revisitado e agora CatalogTypes
não existem mais.
No sistema anterior, objetos tinham conhecimento dos seus próprios identificadores através do método CatalogType#getId
. Isso geralmente restringia esses tipos de existirem em apenas um registro. Na SpongeAPI 8, qualquer objeto pode ser colocado em um registro do tipo correto sem implementar o CatalogType
, com a chave para o objeto sendo fornecida separadamente, permitindo um objeto de existir em diferentes registros com diferentes chaves.
Adicionalmente, diferentemente da SpongeAPI 7 e anteriores, onde todos registros eram globais para a instância do jogo, na SpongeAPI 8 e superior, registros podem ter o escopo de um motor (engine)
Plugins que desejam adicionar items ao registro devem o fazer durante o evento RegisterRegistryValueEvent para o RegistryType que desejam registrar o objeto. Os tipos padrões de registros podem ser encontrado em RegistryTypes. Similarmente, plugins que desejam criar os próprios registros devem o fazer durante o evento RegisterRegistryEvent.GameScoped, RegisterRegistryEvent.EngineScoped ou RegisterRegistryEvent.WorldScoped, dependendo do escopo necessário.
Custom Data
A API de Data obteve uma revisão na SpongeAPI 8, mas a mudança mais impactante a se considerar ao migrar plugins, é que agora dados customizados são mais simples de utilizar. Em particular, existem duas grandes mudanças em como implementar dados customizados:
Data agora é primariamente orientada ao sistema de Key, ao invés dos
DataManipulators
. Chaves (Keys) podem ser criadas a qualquer momento e não precisam ser registradas.Qualquer dado fornecido para data holders usando uma chave não registrada, será transiente - por exemplo, se o dado for fornecido a um jogador usando uma chave não registrada, e o jogador em questão morrer (consequentemente o objeto do jogador será recriado), o dado será perdido. Para persistir dados customizados, os plugins devem registrar suas chaves durante o evento RegisterDataEvent e fornecer um DataRegistration (via DataRegistration.Builder) que diz ao Sponge como persistir os dados.
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.