Injecting an entity

After completing the project setup, creating a bootstrapper and writing your entity class, you’re ready to register your entity injection in your bootstrapper’s bootstrap() function. This is done using:

Kotlin

Bestium.injector().register(Supplier<EntityInjection>)

Java

Bestium.injector().register(Supplier<EntityInjection>);

The Supplier provides an EntityInjection instance. Since this registration happens very early in server startup (before Bukkit or CraftBukkit are initialized) you can’t create the EntityInjection immediately. The Supplier is only resolved once the internals are ready.

EntityInjection interface

An EntityInjection is created using:

Kotlin

EntityInjection.builder(...).build()

Java

EntityInjection.builder(...).build();

Required arguments

You must provide four required parameters:

1. A unique entity key, use your plugin namespace and a unique entity name:

   Kotlin

   Key.key("my_plugin", "capybara")

   Java

   Key.key("my_plugin", "capybara")

2. The entity class you’ve created:

   Kotlin

   Capybara::class.java

   Java

   Capybara.class

3. A factory constructing the entity from an EntityType and a Level, usually the constructor reference of your entity:

   Kotlin

   ::Capybara

   Java

   Capybara::new

4. A convert function that converts our NMS entity into a Bukkit type. This is usually the constructor of a CraftBukkkit entity wrapper class and depends on the base abstract class you extended:

   Base Bestium class	CraftBukkit wrapper class
   CustomAbstractFish	CraftFish
   CustomAbstractGolem	CraftGolem
   CustomAbstractSchoolingFish	PaperSchoolableFish
   CustomAbstractVillager	CraftAbstractVillager
   CustomAgeableMob	CraftAgeable
   CustomAgeableWaterCreature	missing, use CraftAgeable
   CustomAmbientCreature	CraftAmbient
   CustomAnimal	CraftAnimals
   CustomEntity	CraftEntity
   CustomLivingEntity	CraftLivingEntity
   CustomMob	CraftMob
   CustomMonster	CraftMonster
   CustomPathfinderMob	CraftCreature
   CustomShoulderRidingEntity	missing, use CraftTameableAnimal
   CustomTamableAnimal	CraftTameableAnimal
   CustomWaterAnimal	CraftWaterMob

   Our capybara extends CustomAnimal, so we reference the constructor of CraftAnimals:

   Kotlin

   ::CraftAnimals

   Java

   CraftAnimals::new

Additional configuration

After the required parameters, you can chain several additional methods:

backingType(EntityType)

Determines the entity our capybara ‘disguises as’. This is what the client will see.

Kotlin

.backingType(EntityType.PIG)

Java

.backingType(EntityType.PIG)

Defaults to: EntityType.SILVERFISH

attributes(AttributeSupplier.Builder)

Defines the default entity attributes, you should call the static attributes method created earlier.

Kotlin

.attributes(Capybara.createAttributes())

Java

.attributes(Capybara.createAttributes())

Defaults to: LivingEntity.createLivingAttributes() if the entity is living entity otherwise to null

mobCategory(MobCategory)

Sets the category this mob belongs to, this defines whether the mob is friendly or hostile, how many instances there can be per chunk, whether it persists in world or how far from the player it despawns.

Mob category	Description	Max per chunk	Friendly	Persistent	Despawn distance
MONSTER	monsters like Zombies or Skeletons	70	false	false	128
CREATURE	friendly mobs like Sheep or Villagers	10	true	true	128
AMBIENT	ambient surface creatures like Bats	15	true	false	128
AXOLOTLS	axolotls	5	true	false	128
WATER_CREATURE	friendly water mobs like Dolphins and Squids	5	true	false	128
UNDERGROUND_WATER_CREATURE	friendly water mobs underground like Glow Squids	5	true	false	128
WATER_AMBIENT	ambient water creatures like Cods and Salmon	20	true	false	64
MISC	entities that don’t naturally spawn like Boats, TNT or Projectiles	-	true	true	128

Our capybara is a friendly mob, so we use CREATURE:

Kotlin

.mobCategory(MobCategory.CREATURE)

Java

.mobCategory(MobCategory.CREATURE)

Defaults to: MobCategory.MISC

model(PluginBootstrap, String)

Sets the entity model displayed if BetterModel is installed on the server. The file must be a .bbmodel (BlockBench model) bundled inside the plugin’s JAR:

Kotlin

.model(this, "capybara.bbmodel")

Java

.model(this, "capybara.bbmodel")

Defaults to: no model

Don’t have a model yet?

If you don’t have a model yet, you can use the capybara from the Bestium Example plugin licenced under the GNU General Public License.

model(File)

Sets the entity model displayed if BetterModel is installed on the server. The file must be a .bbmodel (BlockBench model) file provided as an external java.io.File.

Defaults to: no model

Final example

The final capybara injection registration looks like this:

Kotlin

MyPluginBootstrapper.kt

override fun bootstrap(context: BootstrapContext) {
    Bestium.injector().register {
        EntityInjection.builder(
            Key.key("my_plugin", "capybara"),
            Capybara::class.java,
            ::Capybara,
            ::CraftAnimals
        )
        .backingType(EntityType.PIG)
        .attributes(Capybara.createAttributes())
        .mobCategory(MobCategory.CREATURE)
        .model(this, "capybara.bbmodel")
        .build()
    }
}

Java

MyPluginBootstrapper.java

@Override
public void bootstrap(BootstrapContext context) {
    Bestium.injector().register(() -> EntityInjection.builder(
                            Key.key("my_plugin", "capybara"),
                            Capybara.class,
                            Capybara::new,
                            CraftAnimals::new
                    )
                    .backingType(EntityType.PIG)
                    .attributes(Capybara.createAttributes())
                    .mobCategory(MobCategory.CREATURE)
                    .model(this, "capybara.bbmodel")
                    .build()
    );
}