API

A full example of the steps described below can be found here

Folder Structure

Models Folder

bbmodel/ is where you put your custom models. In the demo server you can see that models/ can be found, and within the folder there is a file with the name steve.bbmodel, for the steve model.

Generating a Resource Pack

FileUtils.copyDirectory(BASE_PATH.resolve("resourcepack_template").toFile(), BASE_PATH.resolve("resourcepack").toFile());

First start by copying a template resource pack. This is your server resource pack which you plan on adding the models to. Feel free to use the resource pack in the demo server

var config = PackBuilder.Generate(BASE_PATH.resolve("bbmodel"), BASE_PATH.resolve("resourcepack"), MODEL_PATH);
FileUtils.writeStringToFile(BASE_PATH.resolve("model_mappings.json").toFile(), config.modelMappings(), Charset.defaultCharset());

This will generate a model_mappings.json file which is used in the following steps.

This step will add necessary files to your resource pack. After this step is complete, you must zip the resource pack before sending it to clients.

Loading your Models

Reader mappingsData = new InputStreamReader(new FileInputStream(BASE_PATH.resolve("model_mappings.json").toFile()));
ModelEngine.loadMappings(mappingsData, MODEL_PATH);

Specify where your models are located, and where your mapping file is.

Creating a Model

The example below can be found in the test folder.

public class Minimal extends GenericModelImpl {
    @Override
    public String getId() {
        return "steve.bbmodel";
    }

    public void init(@Nullable Instance instance, @NotNull Pos position) {
        super.init(instance, position, 2.5f);
    }
}

To create a model you must define the model ID. This is the name of the folder that the model is inside of. For example, in the demo server there is a folder models/steve.bbmodel, and this ID is steve.bbmodel.

Spawning Multipart Entities

Multipart entities can now be spawned.

var model = new Minimal();
model.init(instance, pos);

Start by creating a new instance of the model that you would like to spawn. In this example we call new Minimal() to create the minimal example.

Next, initiate the model. This will spawn the entity in the instance and position specified.

Animating the Multipart Entity

Creating an Animation Handler

This will create the animation handler and link it to the provided model.

var animationHandler = new AnimationHandlerImpl(model);  
animationHandler.playRepeat("dab");

Running Animations

void playRepeat(String animation);

This can be used to play an animation multiple times. animation name is the name of the animation.

void stopRepeat(String animation);

This is used to stop an animation that is repeating.

void playOnce(String animation, Consumer cb);

This plays an animation once, then runs the code from a callback when the animation is complete.

Destroying a Multipart Entity

model.destroy();
animationHandler.destroy();

When you remove a multipart entity, you must remove the model and animation handler. If you don't destroy these objects, the model will continue to be rendered and animated after the master entity death.

States

By default three model states exist - hit, invisible and normal. States define what texture is used when the model is drawn. hit is a variant of the normal texture with a red filter added. Invisible is a state where the model is not shown. States can be set with model.setState(String state); An example of how to use states can be found here