Primeiros passos com addons

This page is a translated version of the page Add-on Getting Started and the translation is 100% complete.

Primeiros passos com addons explica o que você precisa ter pronto antes de conectar seu próprio mod de Forge ao DragonMineZ: as versões das ferramentas, os mods que você deve evitar e as partes do DMZ em que um addon pode confiar com segurança. Leia antes de Criar um addon de DMZ.

Para quem é

Estas páginas são para desenvolvedores de addons de Forge que querem que o jar do seu mod reaja ao DMZ: conceder TP extra, escutar mudanças de forma, adicionar novos tipos de objetivos e recompensas de missões, adicionar botões ao Menu de Utilidades e assim por diante. Se você só quer ajustar números ou adicionar raças, formas, missões ou desejos, não precisa de nada disso; veja Escopo e pré-requisitos.

O DMZ não tem uma API Java para registrar novas raças, formas, habilidades ou técnicas: novas raças e formas são adicionadas por arquivos de configuração JSON (veja Raças personalizadas e Formas personalizadas).

Ferramentas necessárias

Requisito	Versão	Onde é declarado
Minecraft	`1.20.1`	`gradle.properties`
Forge	`47.4.10` (aceita `[47,)`)	`gradle.properties`, `mods.toml` do addon
ForgeGradle	`6.0.30`	Plugins do `build.gradle.kts`
Java	`17`	Toolchain do `build.gradle.kts`
Mappings	Parchment `2023.09.03-1.20.1`	`gradle.properties`
GeckoLib	`4.8.3+`	`gradle.properties`, `mods.toml` do addon
TerraBlender	`3.0.1.10+`	`gradle.properties`, `mods.toml` do addon
Curios API	`5.14.1+1.20.1` ou mais recente	`gradle.properties`, `mods.toml` do addon

Use exatamente estas versões (ou faixas de versão compatíveis) no build.gradle ou build.gradle.kts, no gradle.properties e no mods.toml do seu addon; caso contrário, você terá erros de carregamento de classes e de mixins incompatíveis em tempo de execução. O DMZ está atualmente na versão 2.2-alpha do mod (gradle.properties).

GeckoLib, TerraBlender e Curios são dependências obrigatórias do DMZ, então também precisam estar no classpath de execução do seu ambiente de desenvolvimento.

Mods incompatíveis

O DMZ se recusa a iniciar (lança uma IllegalStateException durante o carregamento) quando algum destes mods está instalado, e os declara como incompatible no seu mods.toml:

Legendary Tooltips (legendarytooltips)
Epic Fight (epicfight)
Better Combat (bettercombat)

Não dependa deles, não os inclua nem os adicione às suas configurações de execução de desenvolvimento.

Versões de pré-lançamento

2.2-alpha é uma versão de pré-lançamento. As versões alpha e beta do DMZ só deixam entrar em um mundo ou servidor os nomes de usuário da lista de permissões. O nome de usuário de desenvolvimento padrão do ForgeGradle, Dev, está na lista de permissões, então o runClient funciona sem configurar nada: mantenha esse nome de usuário para seus testes locais.

Estrutura de pacotes

Antes de escrever qualquer código de hook, dê uma olhada na estrutura do código-fonte (AI/Context.md no repositório do DMZ a documenta em detalhes):

com.dragonminez.client: renderização, GUI e animação; só cliente.
com.dragonminez.common: configuração, estatísticas, rede, missões e desejos; a parte que a maioria dos addons usa.
com.dragonminez.server: comandos, armazenamento, geração de mundo e eventos de servidor.
com.dragonminez.mixin: mixins; evite depender deles em um addon.

Os addons devem se conectar quase exclusivamente a com.dragonminez.common: é a camada compartilhada e a mais estável. Os únicos hooks do lado do cliente pensados para addons são DMZClientEvent e os slots do Menu de Utilidades (veja Implementação e eventos).

Duas formas de integração

Dependência obrigatória: seu addon exige que o DMZ esteja presente (mandatory=true no mods.toml). É a opção mais simples, mas seu addon não carrega sem o DMZ.
Dependência opcional: seu addon funciona sozinho e só ativa o comportamento específico do DMZ quando o DMZ é detectado. O próprio DMZ usa esse padrão nas suas integrações opcionais (common/compat/WeaponLevelingCompat.java, common/compat/ApotheosisCompat.java): verifique ModList.get().isLoaded("dragonminez") uma única vez e mantenha toda classe que importa código do DMZ atrás dessa verificação. É o recomendado se o seu addon tem valor sem o DMZ instalado. Veja Padrão de dependência opcional.

No que você pode confiar

Eventos: as classes aninhadas de com.dragonminez.common.events.DMZEvent (servidor e comum) e com.dragonminez.client.events.DMZClientEvent (cliente) são a superfície pública de hooks prevista. Veja Implementação e eventos para a lista completa.
Estado do jogador somente leitura: StatsCapability, StatsProvider e StatsData, para ler raça, forma, estatísticas e recursos.
Registros de extensão: QuestObjectiveRegistry e QuestRewardRegistry (tipos de conteúdo de missão personalizados), DMZTextPlaceholders (%placeholders% personalizados em textos de missões e diálogos) e UtilityMenuScreen.addMenuSlot (botões no Menu de Utilidades do cliente).
Registros: MainItems, MainBlocks, MainEntities, MainAttributes, MainEffects, MainEnchants (e as outras classes Main*) em common/init/ expõem referências RegistryObject e DeferredRegister que você pode importar diretamente.

No que não convém confiar

Valores enviados pelo cliente para qualquer coisa relacionada ao progresso. O DMZ também não confia neles; leia a capability do lado do servidor.
Alterar campos de StatsData diretamente fora de eventos ou comandos. Prefira reagir aos eventos ou cancelá-los em vez de mexer nos valores, e prefira os comandos existentes do DMZ quando precisar alterar algo que pertence ao DMZ.
Registrar pacotes no canal de rede do DMZ. Os ids de pacote do DMZ dependem da ordem de registro; use seu próprio canal.
Depender das classes de com.dragonminez.mixin ou de partes internas do DMZ não mencionadas acima. Elas podem mudar sem aviso entre versões.

Próximo passo

Quando seu ambiente de desenvolvimento compilar contra o DMZ e você vir que ele é detectado em tempo de execução, siga para Implementação e eventos para conectar os hooks de verdade e depois para Criar um addon de DMZ para a configuração completa do Gradle e do mods.toml.