Guia do MagmaCore para programadores

A referência Java gerada permite pesquisar classes, métodos e assinaturas, com a versão e o commit do código registados para cada módulo.

O MagmaCore é uma biblioteca incorporada por shading nos plugins que a utilizam. Não é um plugin de servidor autónomo e não deve aparecer em depend como se os jogadores pudessem instalar um JAR de plugin MagmaCore.

Dependência e empacotamento

A coordenada de desenvolvimento atual é com.magmaguy:MagmaCore:2.2.0-SNAPSHOT, disponível no repositório de snapshots do MagmaGuy. Os snapshots podem mudar sem alterar essa versão. Registe o artefacto resolvido se precisar de compilações reproduzíveis.

Gradle Kotlin DSL

repositories {
    maven("https://repo.magmaguy.com/snapshots")
}

dependencies {
    implementation("com.magmaguy:MagmaCore:2.2.0-SNAPSHOT")
}

Maven sections

<repositories>
    <repository>
        <id>magmaguy-snapshots</id>
        <url>https://repo.magmaguy.com/snapshots</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.magmaguy</groupId>
        <artifactId>MagmaCore</artifactId>
        <version>2.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

Estas declarações resolvem a dependência. Configure a tarefa de shading para a incluir no JAR final do plugin. Siga as regras de relocação de um plugin existente com as mesmas necessidades de integração e verifique as pesquisas por reflexão baseadas em strings ao alterar nomes de pacotes. A distribuição já reloca org.luaj e org.reflections para com.magmaguy.shaded.

Cada plugin pode ter a sua própria cópia carregada da biblioteca. Classes Java com o mesmo nome carregadas por classloaders de plugins diferentes são tipos distintos. Use os contratos explícitos entre plugins, como o serviço de poderes Lua do EliteMobs e os adaptadores do registo de localizações. Não converta um objeto MagmaCore privado de outro plugin para o tipo da sua cópia.

Módulos e responsabilidades

Módulo	Responsabilidade
core	Ciclo de vida do plugin, configuração, comandos, menus, partidas, consultas de localização, scripts Lua, conteúdo Nightbreak e utilitários partilhados
nms:core	NMSManager, NMSAdapter e as interfaces EasyMinecraftGoals independentes da versão
nms:v*	Implementações do contrato NMS para cada versão do servidor
dist	Distribuição com shading que contém o núcleo e os adaptadores ativos

Os encantamentos partilhados, ações de itens, gestão de contas, menus de configuração, catálogos e atualizações pertencem aos serviços do núcleo. Reutilize o componente responsável ao acrescentar comportamento a um plugin que use a biblioteca.

Ciclo de vida do plugin

O ciclo de vida mínimo do núcleo segue o padrão dos plugins existentes:

CoreConsumer.java

package example;

import com.magmaguy.magmacore.MagmaCore;
import org.bukkit.plugin.java.JavaPlugin;

public final class CoreConsumer extends JavaPlugin {
    @Override
    public void onLoad() {
        MagmaCore.createInstance(this);
    }

    @Override
    public void onEnable() {
        MagmaCore.onEnable(this);
    }

    @Override
    public void onDisable() {
        MagmaCore.shutdown(this);
    }
}

Esta inicialização faz mais do que obter um objeto utilitário. Inicializa a gestão de contas, comandos partilhados, listeners e suporte para blocos temporários. A sobrecarga createInstance(plugin, NightbreakPluginSpec) fornece os textos específicos do plugin para os comandos partilhados.

Prefira métodos que recebam explicitamente o plugin proprietário. getInstance() refere-se ao singleton da cópia carregada da biblioteca. O plugin associado é definido quando essa instância é criada. Não o use para inferir o proprietário de todos os plugins que utilizam a biblioteca.

shutdown(plugin) limpa os registos de descargas, atualização de conteúdo, inicialização e atualização desse plugin. Depois, também encerra o sistema de execução partilhado da cópia carregada. Não se limita a remover uma entrada de registo. Chame-o para a sua própria biblioteca incorporada durante o encerramento do plugin. Nunca encerre a biblioteca de outro plugin para reiniciar a integração.

Chame createInstance em onLoad para registar o proprietário do arquivo de configurações do plugin antes de outro plugin poder importar conteúdo para ele. O arquivamento usa a implementação incorporada no plugin de destino; não interprete as regras de retirada de configurações desse plugin com a sua cópia do MagmaCore.

Para um arranque por fases, startInitialization aceita trabalho assíncrono, trabalho síncrono e callbacks de sucesso e de falha. Arquiva os ficheiros de configuração que correspondam a formatos retirados antes de executar a inicialização assíncrona. Mantenha as operações sobre mundos e entidades Bukkit na fase síncrona. Trabalho assíncrono demorado deve consultar isShutdownRequested(plugin) entre fases. getInitializationState e isPluginReady expõem o estado do gestor de inicialização.

NMS e entidades por pacotes

Inicialize NMS apenas se o plugin precisar dele, usando NMSManager.initializeAdapter(plugin) de com.magmaguy.easyminecraftgoals. Verifique NMSManager.isEnabled() antes de usar comportamento dependente do adaptador. A inicialização pode falhar ou encontrar uma versão de servidor não suportada.

A distribuição inclui estas famílias de adaptadores:

Adaptador	Versões de Minecraft
v1_21_R3	1.21.4
v1_21_R4	1.21.5
v1_21_R5	1.21.6, 1.21.7, 1.21.8
v1_21_R6	1.21.9, 1.21.10
v1_21_R7_spigot, v1_21_R7_paper	1.21.11, com implementações separadas para Spigot e Paper
v26	26.1 e a família atual de adaptadores 26.x

A seleção de um adaptador não garante compatibilidade com todas as versões futuras do servidor. O seletor de execução em NMSManager determina se o servidor instalado pode carregar um adaptador. Versões anteriores à 1.21.4 estão fora do conjunto atual.

O EasyMinecraftGoals gere as entidades que existem apenas através de pacotes, a sua visibilidade, o encaminhamento das interações e os utilitários de movimento e procura de caminhos. Estas não são entidades normais do mundo. Gira-as através da API responsável e limpe os objetos criados pelo seu plugin enquanto o adaptador ainda estiver disponível.

Consultas de localização e proteção

com.magmaguy.magmacore.location.LocationQueryRegistry disponibiliza consultas sobre masmorras e proteção de regiões, incluindo isInAnyDungeon, isInAnyProtectedRegion e canBuild.

Registe fornecedores personalizados com registerDungeonLocator ou registerProtectionProvider e remova o mesmo fornecedor quando o proprietário for desativado. O registo inclui adaptadores para plugins existentes e descobre fornecedores de masmorras entre plugins sem exigir que todos partilhem um classloader do MagmaCore.

Escolha a consulta correspondente à ação. Estar fora de uma masmorra não equivale a ter permissão para construir nesse local. Execute as consultas que acedem ao Bukkit ou a plugins de proteção na thread do servidor.

Compilar um plugin após alterações à biblioteca

Use JDK 21 e publique o MagmaCore no Maven Local com ./gradlew publishToMavenLocal, ou .\gradlew.bat publishToMavenLocal no Windows. Confirme que o plugin que usa a biblioteca resolve esse repositório e a versão pretendida, e volte a compilar o seu JAR com shading. Substituir uma biblioteca no Maven Local não atualiza um plugin já compilado.

Consulte o índice para programadores para APIs de plugins instalados. Essas integrações usam normalmente provided ou compileOnly. O MagmaCore segue o contrato de uma biblioteca incorporada.