Building Custom Minecraft Entities with Hephaestus-Engine

Ever dreamed of filling your Minecraft server with custom creatures that actually look different? Not retextures or resource packs that swap existing mobs, but entirely new entities with unique models and animations. That's where Hephaestus-Engine comes in. It's a Java library that lets you design and deploy custom models directly to vanilla-compatible servers, no special launcher or hacks required.

What This Project Does

Hephaestus-Engine is a custom model and animation library built for Minecraft: Java Edition servers. It sits between your server code and the player's client, allowing you to create entities that wear custom 3D models instead of the default Steve or Creeper look. The project supports popular server platforms like Paper, Spigot, Minestom, and Bukkit, so whether you're running a small modded survival server or a massive PvP arena, there's a compatible version.

The library handles something that's normally painful to do in vanilla Minecraft: it automatically generates the resource pack that clients need to see your custom models, then serves it when players join. You design your models in Blockbench (a free, web-based 3D editor), export them, and feed them to Hephaestus. The engine does the rest.

Why Custom Models Matter on Your Server

Standard Minecraft mobs are fine if you're running vanilla. But the moment you want a custom boss fight, a unique NPC vendor, or just a signature creature that makes your server memorable, you hit a wall. You can't easily change how an entity looks without either installing a mod (which breaks vanilla compatibility) or relying on invisible armor stands with crafty item display stands (which is janky and laggy).

Hephaestus solves this by letting you define what a custom entity looks like and how it moves, then handles all the networking magic that makes clients see it. Your players don't need to install anything extra. If they're on vanilla Java Edition with the resource pack you're serving, they'll see your custom models as if they were part of the game.

A practical example: imagine a tower defense minigame where waves of increasingly complex mechanical enemies attack players. Without custom models, you're stuck using default mobs with creative item displays attached. With Hephaestus, you can design actual mechanical creatures in Blockbench, animate them walking forward, give them unique attack animations, and deploy them as real entities on the server.

Getting Hephaestus-Engine Set Up

Installation depends on your build system. The project hosts its artifacts on a custom Maven repository, so you'll need to point your build tool at it.

If you're using Gradle (the recommended approach), add the unnamed repository to your build.gradle.kts:

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

Then add the core dependency and any adapters you need:

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

 // For 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")

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

Using Maven? Add the repository first:

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

Then add the dependency tags. The setup is straightforward, though you'll want to pick the Bukkit adapter version that matches your server's Minecraft version. As of early 2026, recent releases include adapters for 1.20.x versions.

One thing to note: this is still a snapshot build (version 0.1.0-SNAPSHOT), which means the API might shift. It's stable enough for production use on many servers, but if you're building something critical, keep an eye on the project's GitHub for updates.

How the Model Pipeline Works

Creating a custom entity involves a few steps, but they're not hard. First, design your model in Blockbench. If you're new to 3D modeling, don't worry. Blockbench has a Minecraft-focused interface that makes it much easier than traditional 3D tools. You can export your creation as a .json file with textures included.

Hephaestus reads Blockbench JSON files natively, so you don't need intermediate conversion. Load your model file in your plugin code, and the engine auto-generates a resource pack. That generated pack gets sent to connecting players automatically (though you can also serve it from a file host if you prefer).

The animation side is where things get interesting. Blockbench lets you keyframe animations inside the same file. Hephaestus reads those animations and makes them available through its API. But here's the flexibility part: you don't have to use its animation system directly. The library lets you hook into animations yourself, so you could run animations asynchronously in a single thread, spread them across multiple threads for performance, or synchronize them with game events. A boss could swing its sword on attack, snap back to idle when hit, play a death animation when defeated. You control the timing.

Blockbench Integration

The Blockbench loader is probably the feature you'll use most. Instead of writing out custom model descriptions by hand, you design everything visually, then load it. This cuts development time dramatically, especially if you're iterating on designs.

The loader pulls both geometry (the model itself) and textures from the Blockbench file. If you've textured your model in Blockbench, those textures come along for the ride. Your players see the textured model, not a gray untextured placeholder.

Resource Pack Generation

Hephaestus auto-generates resource packs, which is a huge quality-of-life win. Normally, distributing custom models involves hand-crafting resource packs, uploading them to a file host, and managing versions. The engine handles that boilerplate. It creates the necessary model definitions, textures, and metadata in the correct format, then serves it through your server. Players download it automatically when they join, assuming they accept server resource packs.

You can customize the generation if needed, but the defaults are sensible. This frees you to focus on design and gameplay instead of resource pack logistics.

Tips and Common Gotchas

Custom models add client-side rendering load. If you go wild and spawn 200 custom entities in one area, some players on older hardware might lag. It's not a dealbreaker, but it's good to test on a variety of clients.

Also, custom models only look right if the client has the resource pack loaded. Most servers have resource pack downloads enabled by default, but some players manually disable them. Those players will see vanilla fallbacks for your entities, which might be jarring. You can warn players about this in your server MOTD if it matters for your gameplay.

Version mismatches can happen if you're running a newer Blockbench model format than your installed version of Hephaestus supports. Check the release notes if you upgrade Blockbench and encounter loading errors.

The animation system is flexible, but that means you've to write the code to trigger animations. Unlike some animation systems that auto-play on loop, Hephaestus makes you explicit about when animations run. This is actually a feature (total control), but it means more code on your end.

Is Hephaestus-Engine Right for You?

If Hephaestus isn't your speed, there are a few other approaches. ModelEngine is a plugin that does similar things but focuses more on pre-built model support and automatic animation looping. It's simpler if you want quick results, but less flexible if you need custom control. There's also a handful of smaller projects focused on specific use cases, like custom boss entities or NPC systems, but they're narrower in scope.

For skinning needs (if you're letting players customize the appearance of their characters), you might also explore the Minecraft Skin Creator, which can help manage custom player skins on your server. And if you're managing a whitelist for your server, the Minecraft Whitelist Creator simplifies bulk username management.

Hephaestus sits in a sweet spot: it's powerful and flexible without being overly complex. If you need full control over custom models and animations on a vanilla-compatible server, it's worth serious consideration.

Hephaestus-Engine is a solid choice if you're running a Paper or Minestom server and want to add visual flair without forking into full modded server territory. It's still under active development, and the snapshot nature of the current release means it's evolving, but it's used in production on real servers. The Blockbench integration is smooth, the resource pack generation is a genuine convenience, and the animation flexibility is powerful once you understand how to use it.

The learning curve is moderate. You'll need basic Java knowledge to integrate it into your plugins, and some familiarity with 3D modeling (or willingness to learn Blockbench). But if those don't intimidate you, you're looking at a tool that can make your server feel truly unique.