Como configurar um ambiente de desenvolvimento Fabric

Configurar um ambiente de modding para Fabric envolve quatro etapas: instalar um Java Development Kit, começar com o modelo de mod oficial, configurar os mapeamentos Yarn e, em seguida, executar o Gradle. O plugin de build Fabric baixa o Minecraft e conecta tudo o mais. Combine a versão do seu JDK e do Minecraft desde o início e o sistema de build cuida do resto.

O que você precisa primeiro

Antes de escrever código:

• Um JDK compatível com a sua versão do Minecraft. Versões mais recentes do Minecraft precisam de JDKs mais recentes. Verifique os requisitos da sua versão-alvo antes de instalar.
• Uma IDE. IntelliJ IDEA Community (gratuito) ou Eclipse funcionam bem. A maioria dos desenvolvedores Fabric usa IntelliJ porque a integração com o Gradle é mais suave.
• Git. Você clonará o repositório do modelo e gerenciará seu próprio código.

Você NÃO precisa instalar o Gradle. O modelo inclui um script wrapper que baixa a versão correta na primeira execução.

Passo a passo

1. Instale um JDK

   Baixe um JDK da Adoptium ou Oracle compatível com a versão do Minecraft que você deseja. Para o Minecraft 1.21, instale o Java 21. Indique o caminho para este JDK nas configurações da sua IDE.

2. Obtenha o modelo de mod de exemplo

   Vá até o repositório oficial de mods de exemplo do Fabric no GitHub e clone-o ou use-o como modelo. Renomeie o pacote e o ID do mod para os seus próprios.

3. Defina as versões no gradle.properties

   Abra o arquivo gradle.properties e atualize três linhas:

   • minecraft_version — a versão do Minecraft que pretende usar (ex: 1.21)
   • loader_version — a versão do Fabric loader compatível com a sua versão do Minecraft
   • yarn_mappings — a versão do Yarn para a sua versão do Minecraft

   Estas três versões devem corresponder, caso contrário o projeto não compilará.

4. Abra no seu IDE e sincronize

   Abra a pasta do projeto no seu IDE. Deixe o Gradle realizar uma sincronização inicial (baixar dependências, gerar configurações de execução).

5. Gerar fontes descompiladas

   No painel Gradle da sua IDE, execute genSources. Isso descompila o Minecraft usando nomes do Yarn para que você possa ler o código do jogo.

6. Lançar um cliente de teste

   Execute runClient para iniciar o Minecraft com seu mod carregado. O cliente de desenvolvimento inclui todas as capacidades de depuração.

É isso. Agora você tem um ambiente de desenvolvimento Fabric funcional.

Entendendo gradle.properties

Este arquivo configura toda a sua build. Três versões precisam estar sincronizadas:

minecraft_version=1.21
loader_version=0.15.11
yarn_mappings=1.21+build.32

Se o Minecraft for 1.21, mas o Yarn for 1.20.1, o Gradle não sincronizará com um erro enigmático. Sempre obtenha as versões correspondentes de fabricmc.net/use ou do modelo de exemplo.

O que o plugin de build faz

O plugin Gradle do Fabric é configurado em build.gradle e gerencia:

• Download do Minecraft
• Descompilação com os mappings escolhidos
• Remapeamento do seu código de volta para intermediário para compatibilidade
• Geração de configurações de execução do IDE

Você o configura uma vez; ele automatiza o resto. É por isso que o modelo importa — ele já tem tudo isso conectado corretamente.

Mappings explicados

O Minecraft é enviado ofuscado (nomes de classe como a, b, c). Os mappings traduzem esses nomes para nomes legíveis.

• Yarn: O padrão do Fabric. Inclui documentação. Fácil de ler.
• Mappings da Mojang: Oficiais, mas menos documentados. Nomes mais obscuros.

O modelo usa Yarn. Quando você executa genSources, o Minecraft é descompilado usando os nomes do Yarn para que você possa ler o código real. Quando você compila, o Fabric o remapeia de volta para intermediário (uma camada estável por baixo) para que o mod funcione em qualquer versão do Minecraft correspondente.

Problemas comuns de configuração

• ✓A sincronização do Gradle falha imediatamente: verifique gradle.properties. As versões do Minecraft, do loader e do Yarn devem coincidir. Utilize uma combinação conhecida do site do Fabric.
• ✓Erro do compilador sobre a versão do Java: o seu JDK está desatualizado para a versão do Minecraft. Instale um JDK mais recente e configure o seu IDE para apontar para ele.
• ✓Não consigo ler o código-fonte do Minecraft: execute genSources no painel Gradle e recarregue. A primeira execução é lenta porque descompila o jogo inteiro.
• ✓runClient não faz nada: aguarda a conclusão da sincronização inicial do Gradle. As configurações de execução são geradas durante a sincronização.
• ✓A IDE não importa o projeto: certifique-se de que a IDE tem um JDK selecionado nas suas configurações, e não um JRE.

Próximos passos após a configuração

Uma vez que o seu ambiente esteja funcionando:

1. Exclua ou renomeie as classes de mod de exemplo.
2. Crie seu próprio pacote de mod.
3. Implemente uma funcionalidade simples (um bloco, item ou listener de evento).
4. Execute runClient e teste no cliente de desenvolvimento.
5. Itere.

O cliente de desenvolvimento inclui suporte completo para depuração e hot-reload, tornando a iteração rápida

Notas específicas do IDE

IntelliJ IDEA:

• Importar como projeto Gradle (e não apenas uma pasta)
• Permitir que o Gradle sincronize completamente antes de executar qualquer tarefa
• As configurações de execução aparecem em "Gradle" no menu suspenso de execução

Eclipse:

• Importar como um projeto Gradle existente
• Clicar com o botão direito no projeto → Gradle → Atualizar Projeto Gradle após a sincronização
• As tarefas Gradle aparecem na visualização Gradle Tasks

PERGUNTAS FREQUENTES