Hephaestus Engine

When creating models using the vanilla Minecraft client, be aware of specific rotation constraints for cubes. Cube rotations are restricted to a specific set of angles: -45º, -22.5º, 0º, 22.5º, or 45º.

Note that this restriction does not apply to bone rotations, which can use arbitrary angles.

To create a Model instance, you use a ModelReader. A ModelReader uses a ModelDataCursor to assign a custom_model_data property to every bone within the model.

Important: You should use a single ModelDataCursor instance for an entire resource pack. This ensures that every bone across all models maintains unique custom_model_data properties, preventing collisions.

// Create a single cursor to be shared across your resource pack
ModelDataCursor modelDataCursor = new ModelDataCursor(0);

// Pass the shared cursor to your reader
ModelReader reader = BBModelReader.blockbench(modelDataCursor);

To use hephaestus-engine with Minestom, you must include the hephaestus-runtime-minestom subproject in your dependencies. You can create and track a view using MinestomModelEngine.minestom().createViewAndTrack(...), which requires a Model, a Minestom Instance, and a Pos (position).

Model model = ...;
ModelEntity view = MinestomModelEngine.minestom().createViewAndTrack(
        model,
        instance, // Instance
        position  // Pos
);

To use hephaestus-engine in a Maven project, add the unnamed-public repository to your pom.xml. Then, add the hephaestus-api dependency.

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

<dependency>
    <groupId>team.unnamed</groupId>
    <artifactId>hephaestus-api</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

Once you have a ResourcePack instance (from the creative library), use MinecraftResourcePackWriter.minecraft() to export it to the filesystem. You can either write the pack to a .zip file or to a plain directory.

ResourcePack resourcePack = ...;

// write the resource-pack to a ZIP file...
MinecraftResourcePackWriter.minecraft().writeToZipFile(new File("resource-pack.zip"), resourcePack);

// or write it to a directory...
MinecraftResourcePackWriter.minecraft().writeToDirectory(new File("resource-pack"), resourcePack);

Hephaestus-engine uses the creative library to interact with resource pack data. You can convert a collection of Model objects and their bones into creative item models by using ModelWriter. Specify a namespace (e.g., "mynamespace") to organize the generated assets.

Collection<Model> models = ...;

// creative's ResourcePack
ResourcePack resourcePack = ...;

// write our models to the resource-pack using the "mynamespace" namespace
ModelWriter.resource("mynamespace").write(tree, models);

To load a .bbmodel file into a Model instance, initialize a BBModelReader with a ModelDataCursor and call the read method with a File object.

ModelReader reader = BBModelReader.blockbench(new ModelDataCursor(0));
Model model = reader.read(new File("model.bbmodel"));

// do something with 'model'

The BBModelReader provides implementations for reading models in the Blockbench .bbmodel format. You can initialize it either without a cursor (using default behavior) or with a specific ModelDataCursor to manage bone data properties.

// Option 1: Basic reader without a custom cursor
ModelReader reader = BBModelReader.blockbench();

// Option 2: Reader with an assigned ModelDataCursor
ModelDataCursor modelDataCursor = new ModelDataCursor(0);
ModelReader reader = BBModelReader.blockbench(modelDataCursor);

Animations are managed via the AnimationController.

1. Queue an animation: Use view.animationPlayer().queue(animation) to add a ModelAnimation to the playback queue. Animations can be retrieved from the model using Model#animations().
2. Stop animations: Use AnimationController#clearQueue() to stop all currently queued animations.

public void animate(BaseModelView<?> view) {
    // walkAnimation is a ModelAnimation instance that can
    // be obtained from Model#animations()
    view.animationPlayer().queue(walkAnimation);
}