Project Setup

To use Bestium, you need to start with a working Paper plugin setup. Your build must use either Gradle Kotlin DSL or Gradle Groovy DSL. Maven cannot be used, because paperweight-userdev does not support Maven.

You can write your plugin code in either Java or Kotlin. Kotlin is recommended for its expressiveness, but fully optional.

Add dependencies

To use Bestium in your plugin project, you’ll need two dependencies:

• paperweight-userdev — for access to Minecraft internals (NMS).
• Bestium API — for using Bestium’s entity injection tools.

Your Gradle build configuration should look something like this:

Gradle Kotlin DSL

build.gradle.kts

plugins {
    id("io.papermc.paperweight.userdev") version "2.0.0-beta.17"
}

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("cz.jeme:bestium:1.1.0")
    paperweight.paperDevBundle("MINECRAFT_VER-R0.1-SNAPSHOT")
}

Gradle Groovy DSL

build.gradle

plugins {
    id 'io.papermc.paperweight.userdev' version '2.0.0-beta.17'
}

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'cz.jeme:bestium:1.1.0'
    paperDevBundle 'MINECRAFT_VER-R0.1-SNAPSHOT'
}

Replace MINECRAFT_VER with the Minecraft version Bestium requires.

Verify your setup

Once your build is synced, you should be able to import main Bestium class:

Kotlin

import cz.jeme.bestium.api.Bestium

Java

import cz.jeme.bestium.api.Bestium;

Converting to a Paper plugin

To use Bestium, your plugin must be a Paper plugin.

This means replacing your plugin.yml with a paper-plugin.yml.

Why switch?

Paper plugins support additional features like bootstrappers, which let you run code early in the server initialization process.

Follow this guide to migrate from Bukkit to Paper plugin format.

Creating a Bootstrapper

Bootstrappers allow you to run code very early in the Minecraft server’s startup sequence. This is essential for registering custom entities with Bestium before datapacks (and biomes) are loaded.

To use a bootstrapper:

1. Implement the PluginBootstrap interface:
   Kotlin

   MyPluginBootstrapper.kt

   package com.example.myplugin
   
   import io.papermc.paper.plugin.bootstrap.BootstrapContext
   import io.papermc.paper.plugin.bootstrap.PluginBootstrap
   
   @Suppress("UnstableApiUsage")
   internal class MyPluginBootstrapper : PluginBootstrap {
       override fun bootstrap(context: BootstrapContext) {
           // Here the injection will happen
       }
   }

   Java

   MyPluginBootstrapper.java

   package com.example.myplugin;
   
   import io.papermc.paper.plugin.bootstrap.BootstrapContext;
   import io.papermc.paper.plugin.bootstrap.PluginBootstrap;
   
   @SuppressWarnings("UnstableApiUsage")
   public class MyPluginBootstrapper implements PluginBootstrap {
       @Override
       public void bootstrap(BootstrapContext context) {
           // Here the injection will happen
       }
   }

2. Register your class:

   paper-plugin.yml

   bootstrapper: com.example.myplugin.MyPluginBootstrapper