Entidades Personalizadas com Hephaestus-Engine

Sempre sonhou em preencher seu servidor Minecraft com criaturas personalizadas que realmente parecem diferentes? Não retexturas ou resource packs que trocam mobs existentes, mas entidades completamente novas com modelos e animações únicos. É aí que entra o Hephaestus-Engine. É uma biblioteca Java que permite projetar e implantar modelos personalizados diretamente em servidores compatíveis com vanilla, sem necessidade de launcher especial ou gambiarras.

O que este projeto faz

Hephaestus-Engine é uma biblioteca de modelos personalizados e animação criada para servidores Minecraft: Java Edition. Fica entre o código do seu servidor e o cliente do jogador, permitindo criar entidades que usam modelos 3D personalizados em vez da aparência padrão de Steve ou Creeper. O projeto suporta plataformas de servidor populares como Paper, Spigot, Minestom e Bukkit, portanto, quer você esteja executando um pequeno servidor de sobrevivência modificado ou uma arena PvP massiva, há uma versão compatível.

A biblioteca lida com algo que normalmente é doloroso de fazer no Minecraft vanilla: ela gera automaticamente o resource pack que os clientes precisam para ver seus modelos personalizados e o fornece quando os jogadores entram. Você projeta seus modelos no Blockbench (um editor 3D gratuito baseado na web), os exporta e os fornece ao Hephaestus. O mecanismo faz o resto.

Por que modelos personalizados importam no seu servidor

Mobs padrão do Minecraft são bons se você estiver executando vanilla. Mas no momento em que você quer uma luta de chefe personalizada, um vendor NPC único ou apenas uma criatura assinatura que torna seu servidor memorável, você bate em uma parede. Você não pode facilmente mudar como uma entidade parece sem instalar um mod (que quebra compatibilidade vanilla) ou depender de stands de armadura invisíveis com stands de exibição de itens improvisados (que é uma gambiarra e é lento).

Hephaestus resolve isso permitindo que você defina como uma entidade personalizada parece e como se move, depois lida com toda a mágica de rede que faz os clientes a verem. Seus jogadores não precisam instalar nada extra. Se eles estiverem no vanilla Java Edition com o resource pack que você está fornecendo, verão seus modelos personalizados como se fossem parte do jogo.

Um exemplo prático: imagine um minigame tower defense onde ondas de inimigos mecânicos cada vez mais complexos atacam jogadores. Sem modelos personalizados, você fica preso usando mobs padrão com exibições de itens criativas anexadas. Com Hephaestus, você pode projetar criaturas mecânicas reais no Blockbench, animá-las caminhando para frente, dar-lhes animações de ataque únicas e implantá-las como entidades reais no servidor.

Configurando Hephaestus-Engine

A instalação depende do seu sistema de compilação. O projeto hospeda seus artefatos em um repositório Maven personalizado, então você precisará apontar sua ferramenta de compilação para ele.

Se você está usando Gradle (a abordagem recomendada), adicione o repositório unnamed ao seu build.gradle.kts:

repositories {
 maven("https://repo.unnamed.team/repository/unnamed-public/")
}

Em seguida, adicione a dependência principal e quaisquer adaptadores necessários:

dependencies {
 implementation("team.unnamed:hephaestus-api:0.1.0-SNAPSHOT")
 implementation("team.unnamed:hephaestus-reader-blockbench:0.1.0-SNAPSHOT")

 // Para Paper/Spigot
 implementation("team.unnamed:hephaestus-runtime-bukkit-api:0.1.0-SNAPSHOT")
 implementation("team.unnamed:hephaestus-runtime-bukkit-adapt-v1_20_R3:0.1.0-SNAPSHOT")

 // Para Minestom
 implementation("team.unnamed:hephaestus-runtime-minestom:0.1.0-SNAPSHOT")
}

Usando Maven? Adicione o repositório primeiro:

<repository>
 <id>unnamed-public</id>
 <url>https://repo.unnamed.team/repository/unnamed-public/</url>
</repository>

Em seguida, adicione as tags de dependência. A configuração é direta, embora você queira escolher a versão do adaptador Bukkit que corresponda à versão do Minecraft do seu servidor. A partir do início de 2026, as versões recentes incluem adaptadores para versões 1.20.x.

Uma coisa a notar: esta ainda é uma compilação snapshot (versão 0.1.0-SNAPSHOT), o que significa que a API pode mudar. É estável o suficiente para uso em produção em muitos servidores, mas se você está construindo algo crítico, fique de olho no GitHub do projeto para atualizações.

Como o Pipeline de Modelo Funciona

Criar uma entidade personalizada envolve algumas etapas, mas não são difíceis. Primeiro, projete seu modelo no Blockbench. Se você é novo em modelagem 3D, não se preocupe. O Blockbench possui uma interface focada em Minecraft que torna muito mais fácil do que ferramentas 3D tradicionais. Você pode exportar sua criação como um arquivo .json com texturas incluídas.

Hephaestus lê arquivos Blockbench JSON nativamente, então você não precisa de conversão intermediária. Carregue seu arquivo de modelo no código do seu plugin, e o mecanismo gera automaticamente um resource pack. Esse pacote gerado é enviado para jogadores conectados automaticamente (embora você também possa servi-lo de um host de arquivo se preferir).

O lado da animação é onde as coisas ficam interessantes. Blockbench permite que você keyframe animações dentro do mesmo arquivo. Hephaestus lê essas animações e as torna disponíveis através de sua API. Mas aqui está a parte da flexibilidade: você não precisa usar seu sistema de animação diretamente. A biblioteca permite que você conecte-se a animações você mesmo, portanto, você pode executar animações de forma assíncrona em uma única thread, espalhá-las entre múltiplas threads para desempenho ou sincronizá-las com eventos do jogo. Um chefe poderia balançar sua espada no ataque, voltar ao inativo quando atingido, reproduzir uma animação de morte quando derrotado. Você controla o tempo.

Integração Blockbench

O carregador Blockbench é provavelmente o recurso que você mais usará. Em vez de escrever descrições de modelos personalizados à mão, você projeta tudo visualmente e depois o carrega. Isso reduz dramaticamente o tempo de desenvolvimento, especialmente se você estiver iterando em designs.

O carregador extrai geometria (o próprio modelo) e texturas do arquivo Blockbench. Se você texturizou seu modelo no Blockbench, essas texturas vêm junto. Seus jogadores veem o modelo texturizado, não um espaço reservado cinzento sem texturas.

Geração de Resource Pack

Hephaestus gera automaticamente resource packs, o que é uma enorme vitória de qualidade de vida. Normalmente, distribuir modelos personalizados envolve criar manualmente resource packs, carregá-los em um host de arquivo e gerenciar versões. O mecanismo lida com esse código padrão. Ele cria as definições de modelo necessárias, texturas e metadados no formato correto, depois o fornece através do seu servidor. Os jogadores o baixam automaticamente quando entram, assumindo que aceitam resource packs do servidor.

Você pode personalizar a geração se necessário, mas os padrões são sensatos. Isso o liberta para se concentrar em design e gameplay em vez de logística de resource pack.

Dicas e Pegadinhas Comuns

Modelos personalizados adicionam carga de renderização do lado do cliente. Se você ficar selvagem e gerar 200 entidades personalizadas em uma área, alguns jogadores em hardware mais antigo podem ter atraso. Não é um divisor de águas, mas é bom testar em uma variedade de clientes.

Além disso, modelos personalizados só parecem corretos se o cliente tiver o resource pack carregado. A maioria dos servidores tem downloads de resource pack ativados por padrão, mas alguns jogadores os desativam manualmente. Esses jogadores verão fallbacks vanilla para suas entidades, o que pode ser perturbador. Você pode avisar os jogadores sobre isso no seu servidor MOTD se isso importar para o seu gameplay.

Incompatibilidades de versão podem ocorrer se você estiver executando um formato de modelo Blockbench mais recente do que a sua versão instalada do Hephaestus suporta. Verifique as notas de versão se atualizar Blockbench e encontrar erros de carregamento.

O sistema de animação é flexível, mas isso significa que você tem que escrever o código para disparar animações. Ao contrário de alguns sistemas de animação que são reproduzidos automaticamente em loop, Hephaestus o torna explícito sobre quando as animações são executadas. Isso é na verdade um recurso (controle total), mas significa mais código do seu lado.

Hephaestus-Engine é adequado para você?

Se Hephaestus não é sua velocidade, há outras abordagens. ModelEngine é um plugin que faz coisas semelhantes, mas se concentra mais no suporte a modelos pré-construídos e loop de animação automática. É mais simples se você quer resultados rápidos, mas menos flexível se precisar de controle personalizado. Também há alguns projetos menores focados em casos de uso específicos, como entidades de chefe personalizadas ou sistemas NPC, mas têm escopo mais estreito.

Para necessidades de skinning (se você está deixando os jogadores personalizarem a aparência de seus personagens), você também pode explorar o Minecraft Skin Creator, que pode ajudar a gerenciar skins de jogadores personalizados no seu servidor. E se você estiver gerenciando uma whitelist para seu servidor, o Minecraft Whitelist Creator simplifica o gerenciamento em massa de nomes de usuário.

Hephaestus fica em um lugar doce: é poderoso e flexível sem ser excessivamente complexo. Se você precisa de controle total sobre modelos e animações personalizadas em um servidor compatível com vanilla, vale a pena consideração séria.

Hephaestus-Engine é uma escolha sólida se você estiver executando um servidor Paper ou Minestom e quiser adicionar floreio visual sem se aprofundar em território de servidor totalmente modificado. Ainda está em desenvolvimento ativo, e a natureza snapshot da versão atual significa que está evoluindo, mas é usado em produção em servidores reais. A integração Blockbench é suave, a geração de resource pack é uma conveniência genuína, e a flexibilidade de animação é poderosa uma vez que você entende como usá-la.

A curva de aprendizado é moderada. Você precisará de conhecimento básico de Java para integrá-lo em seus plugins e alguma familiaridade com modelagem 3D (ou disposição para aprender Blockbench). Mas se isso não o intimida, você está olhando para uma ferramenta que pode fazer seu servidor parecer verdadeiramente único.