Variants API

The Variants API is a feature introduced in Bestium v3.0.0 and lives in the cz.jeme.bestium.api.inject.variant package.
It allows you to define multiple visual or functional variants for your custom entities (such as cold, temperate, warm), and configure the logic that determines which variant is used when the entity spawns.

---

Creating entity variants

To create a new variant, use one of the static factory methods in the EntityVariant interface. Each method requires a variant ID ([a-z0-9_-.]) and a .bbmodel file as input:

fromModelUrl(String, URL)

Loads the model from a remote or local URL.

fromModelFile(String, File)

Loads the model from a file on disk.

fromModelResource(String, PluginBootstrap, String)

Loads the model as a resource bundled inside your plugin JAR.

Which method should I use?

fromModelResource is the most practical and commonly used method, it allows you to bundle the .bbmodel file in your plugin’s jar.

All of these methods return an UnboundEntityVariant, which is not yet tied to a specific entity.

You can register the variant to an EntityInjection.Builder using:

• addVariant(UnboundEntityVariant)
  Adds a single variant.
• addVariants(...)
  Adds multiple variants at once (overloaded versions exist).

---

Configuring variant selection

To control which variant is selected when an entity spawns, you can define a VariantRule.

You can implement your own custom rule (using a lambda), but there is already a lot of builtin useful static methods:

first()

Always selects the first registered variant. This is the default behavior when no rule is set.

always(String)

Always selects the specific variant by ID.

random()

Picks a random variant from those registered.

weighted(Map<String, Integer>)

Selects a variant based on weighted chance. Pass a map where keys are variant IDs and values are integer weights. Higher weight = higher chance.

ifBiome(BiomeFilter, String)

Uses the specified variant only if the current biome passes the provided BiomeFilter.
For more on biome filters, see the Biome API.

ifWorld(Key, String)

Uses the variant only if the entity spawns in a world matching the given key.

firstMatch(VariantRule...)

Tries multiple variant rules in order and returns the first one that successfully picks a variant.
This is useful for combining logic.

Example

Example EntityInjection.Builder variant configuration for our capybara may look like this:

Kotlin

EntityInjection.builder(...)
...
.addVariants(
    EntityVariant.fromModelResource(
        "normal",
        this,
        "models/capybara/normal.bbmodel"
    ),
    EntityVariant.fromModelResource(
        "blue",
        this,
        "models/capybara/blue.bbmodel"
    )
)
.setVariantRule(
    VariantRule.firstMatch(
        VariantRule.ifBiome(
            BiomeFilter.tag(Key.key("minecraft:spawns_cold_variant_farm_animals")),
            "blue"
        ),
        VariantRule.always("normal")
    )
)

Java

EntityInjection.builder(...)
...
.addVariants(
    EntityVariant.fromModelResource(
        "normal",
        this,
        "models/capybara/normal.bbmodel"
    ),
    EntityVariant.fromModelResource(
        "blue",
        this,
        "models/capybara/blue.bbmodel"
    )
)
.setVariantRule(
    VariantRule.firstMatch(
        VariantRule.ifBiome(
            BiomeFilter.tag(Key.key("minecraft:spawns_cold_variant_farm_animals")),
            "blue"
        ),
        VariantRule.always("normal")
    )
)