Package cz.jeme.bestium.api.inject.variant

Interface VariantRule

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface VariantRule
A functional interface with one method used to determine which variant an entity will have after spawning.

Before implementing this interface, check the static factory methods, a suitable implementation may already exist.

To combine multiple variant rules into one, see firstMatch(VariantRule...).

  • Method Summary

    Modifier and Type
    Method
    Description
    static VariantRule
    always(String variantId)
    Returns a variant rule that always returns the rule with the provided variant ID.
    @Nullable BoundEntityVariant
    apply(@Unmodifiable Map<String,BoundEntityVariant> variants, EntitySpawnContext context)
    Picks the variant to apply to an entity upon spawning.
    static VariantRule
    first()
    Returns a rule that selects the first variant registered for an entity.
    static VariantRule
    firstMatch(VariantRule... rules)
    Combines multiple variant rules into a single rule by evaluating them in order, from first to last.
    static VariantRule
    ifBiome(BiomeFilter filter, String variantId)
    Returns a rule that returns the provided variant only if the provided biome filter tests positive on the biome of the entity's spawn location.
    static VariantRule
    ifTemperature(org.apache.commons.lang3.DoubleRange temperatureRange, String variantId)
    Returns a rule that returns the provided variant only if the temperature of the entity's spawn location is in the provided temperature range.
    static VariantRule
    ifWorld(Key worldKey, String variantId)
    Returns a rule that returns the provided variant only if the provided world key matches the one of the entity's spawn location.
    static VariantRule
    ifWorlds(Set<Key> worldKeys, String variantId)
    Returns a rule that returns the provided variant only if one of the provided world keys matches the one of the entity's spawn location.
    static VariantRule
    none()
    Returns a variant rule that always returns null, no variant (model) will be applied.
    static VariantRule
    random()
    Returns a rule that randomly selects one of the available variants.
    static VariantRule
    weighted(Map<String,@Positive Integer> weights)
    Returns a rule that selects a variant based on weighted chances.

  • Method Details

    • apply

      @Nullable BoundEntityVariant apply(@Unmodifiable Map<String,BoundEntityVariant> variants, EntitySpawnContext context)
      Picks the variant to apply to an entity upon spawning.

      The returned BoundEntityVariant must be one of the values in the provided variants map. If a variant is returned that does not exist in this map, an exception will be thrown.

      The variants map may be empty.

      Only the data exposed by the context should be used in this method. Accessing other properties of the entity may be unsafe at this stage.

      Parameters:
      variants - an unmodifiable map of variant IDs to bound variants
      context - a safe snapshot of contextual data from the spawning entity
      Returns:
      the variant to apply, or null if no variant (model) should be applied

    • first

      static VariantRule first()
      Returns a rule that selects the first variant registered for an entity. If no variants are available, returns null.

      This is the default VariantRule used when no rule is provided in entity injection.

      Note: Unless this entity has no variants, this rule will never return null. Passing it to firstMatch(VariantRule...) will result in all following rules being ignored.

      Returns:
      a rule that always selects the first available variant or null if none are available

    • random

      static VariantRule random()
      Returns a rule that randomly selects one of the available variants. If no variants are available, returns null.

      Note: Unless this entity has no variants, this rule will never return null. Passing it to firstMatch(VariantRule...) will result in all following rules being ignored.

      Returns:
      a rule that selects a random variant

    • weighted

      static VariantRule weighted(Map<String,@Positive Integer> weights)
      Returns a rule that selects a variant based on weighted chances.

      For example: 

      
 VariantRule.weighted(Map.of(
     "normal", 10,
     "rare", 1
 ));
      In this case, the "normal" variant is 10× more likely to be selected than "rare". Only the variants explicitly listed in the chance map may be selected. Unlisted variants and variants with weight less than or equal to 0 are silently ignored.

      Note: This rule will never return null, passing it to firstMatch(VariantRule...) will result in all following rules being ignored.

      Note: If the rule attempts to select a non-existent variant ID from the provided map, an IllegalArgumentException is thrown.

      Parameters:
      weights - a map of variant IDs to their selection weight (positive integers)
      Returns:
      a chance based rule
      Throws:
      IllegalArgumentException - if the weights map is empty

    • none

      static VariantRule none()
      Returns a variant rule that always returns null, no variant (model) will be applied.
      Returns:
      a variant rule always returning null

    • always

      static VariantRule always(@Namespace String variantId)
      Returns a variant rule that always returns the rule with the provided variant ID.

      Note: This rule will never return null, passing it to firstMatch(VariantRule...) will result in all following rules being ignored.

      Note: If the variant ID does not exist and this rule is applied, an IllegalArgumentException is thrown.

      Parameters:
      variantId - the ID of the variant to apply
      Returns:
      a variant rule always returning a variant matching the provided ID

    • ifBiome

      static VariantRule ifBiome(BiomeFilter filter, @Namespace String variantId)
      Returns a rule that returns the provided variant only if the provided biome filter tests positive on the biome of the entity's spawn location. If the biome does not match, null is returned.

      For example: 

      
 VariantRule.ifBiome(BiomeFilter.key(Key.key("minecraft:plains")), "normal");

      You may omit the "minecraft:" namespace for vanilla biomes.

      This rule is designed to be chained using firstMatch(VariantRule...).

      Note: If the variant ID does not exist and this rule is applied, an IllegalArgumentException is thrown.

      Parameters:
      filter - the biome filter to test
      variantId - the ID of the variant to apply
      Returns:
      a biome based rule

    • ifWorld

      static VariantRule ifWorld(Key worldKey, @Namespace String variantId)
      Returns a rule that returns the provided variant only if the provided world key matches the one of the entity's spawn location. If the world does not match, null is returned.

      For example: 

      
 VariantRule.ifWorld(Key.key("minecraft:overworld"), "normal");

      You may omit the "minecraft:" namespace for vanilla worlds.

      This rule is designed to be chained using firstMatch(VariantRule...).

      Note: If the variant ID does not exist and this rule is applied, an IllegalArgumentException is thrown.

      Parameters:
      worldKey - the world key to match
      variantId - the ID of the variant to apply
      Returns:
      a world based rule
      See Also:

    • ifWorlds

      static VariantRule ifWorlds(Set<Key> worldKeys, @Namespace String variantId)
      Returns a rule that returns the provided variant only if one of the provided world keys matches the one of the entity's spawn location. If the world does not match, null is returned.

      For example: 

      
 VariantRule.ifWorlds(Set.of(
    Key.key("minecraft:the_end"),
    Key.key("minecraft:the_nether")
 ), "normal");

      You may omit the "minecraft:" namespace for vanilla worlds.

      This rule is designed to be chained using firstMatch(VariantRule...).

      Note: If the variant ID does not exist and this rule is applied, an IllegalArgumentException is thrown.

      Parameters:
      worldKeys - the world keys to match
      variantId - the ID of the variant to apply
      Returns:
      a world based rule
      See Also:

    • ifTemperature

      static VariantRule ifTemperature(org.apache.commons.lang3.DoubleRange temperatureRange, @Namespace String variantId)
      Returns a rule that returns the provided variant only if the temperature of the entity's spawn location is in the provided temperature range. If not, null is returned.

      For example: 

      
 VariantRule.ifTemperature(DoubleRange.of(Double.MIN_VALUE, 0.5), "cold");

      You may also use the predefined ranges in BiomeTemperature.

      This rule is designed to be chained using firstMatch(VariantRule...).

      Note: If the variant ID does not exist and this rule is applied, an IllegalArgumentException is thrown.

      Parameters:
      temperatureRange - the temperature range when the variant is applied
      variantId - the ID of the variant to apply
      Returns:
      a temperature based rule
      See Also:

    • firstMatch

      static VariantRule firstMatch(VariantRule... rules)
      Combines multiple variant rules into a single rule by evaluating them in order, from first to last.

      The first rule that returns a non-null BoundEntityVariant will be used. All subsequent rules are ignored. This creates layered fallback logic where more specific rules are prioritized.

      Variant rules can be categorized into two types:

      Important: A rule that never returns null (like always(String)) should only be used as the final rule in the chain, acting as a fallback. Using a non-null rule earlier in the sequence will prevent any following rules from being evaluated.

      Example (complex) usage: 

      
 VariantRule.firstMatch(
    // complicated custom rule:
    // if the entity is named BOB, apply "bob" variant
    (variants, ctx) -> {
       Component name = ctx.getEntity().customName();
       if (name == null) return null;
       String nameStr = PlainTextComponentSerializer.plainText().serialize(name);
       return nameStr.equalsIgnoreCase("bob") ? variants.get("bob") : null;
    },
    // apply "desert" variant in deserts
    VariantRule.ifBiome(Key.key("minecraft:desert"), "desert"),
    // apply "jungle" variant in jungles
    VariantRule.ifBiomes(Set.of(
       Key.key("minecraft:jungle"),
       Key.key("minecraft:bamboo_jungle"),
       Key.key("minecraft:sparse_jungle"),
    ), "jungle"),
    // apply "warm" variant warm biomes other than desert and jungle
    VariantRule.ifTemperature(BiomeTemperature.WARM, "warm"),
    // apply "cold" variant in cold biomes
    VariantRule.ifTemperature(BiomeTemperature.COLD, "cold"),
    // fallback: apply "normal" variant in all other biomes
    VariantRule.always("normal")
 )
      Parameters:
      rules - the variant rules to evaluate in order
      Returns:
      a VariantRule returning the first non-null variant