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árias

  • Usar 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:

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.