Skip to main content

​
Overview

BetterModel provides full support for Bukkit-based server platforms including Bukkit, Spigot, Paper, and Purpur. The plugin automatically detects your platform and optimizes its behavior accordingly.

Spigot

Standard Bukkit API implementation with NMS adapters

Paper

Enhanced performance with Paper’s modern scheduler and APIs

Purpur

Full Paper compatibility with additional Purpur-specific hooks

Folia

Region-based multithreading support (see dedicated page)

​
Platform Detection

BetterModel automatically detects your server platform at runtime:
Platform Detection
public interface BetterModelBukkit extends BetterModelPlatform {
    boolean IS_FOLIA = classExists("io.papermc.paper.threadedregions.RegionizedServer");
    boolean IS_PURPUR = classExists("org.purpurmc.purpur.PurpurConfig");
    boolean IS_PAPER = IS_PURPUR || IS_FOLIA || 
        classExists("io.papermc.paper.configuration.PaperConfigurations");
}
The detection hierarchy ensures Paper forks (Purpur, Folia) are properly identified.

​
Installation

1

Choose the correct JAR

Download the appropriate JAR file for your platform:
  • Paper/Purpur/Folia: Use bettermodel-paper-VERSION.jar
  • Spigot/Bukkit: Use bettermodel-spigot-VERSION.jar
Using the wrong JAR will cause the plugin to refuse to load. Paper-based servers must use the Paper JAR.
2

Install dependencies

BetterModel automatically downloads required libraries at runtime using Libby.For Paper platforms, dependencies are loaded via Paper’s plugin loader:
Paper Loader
public final class BetterModelLoader implements PluginLoader {
    @Override
    public void classloader(PluginClasspathBuilder classpathBuilder) {
        var lib = new MavenLibraryResolver();
        lib.addRepository(new RemoteRepository.Builder(
            null, "default",
            "https://maven-central.storage-download.googleapis.com/maven2"
        ).build());
        // Libraries loaded from paper-library file
        classpathBuilder.addLibrary(lib);
    }
}
For Spigot, libraries are declared in plugin.yml:
plugin.yml
libraries:
  - com.vdurmont:semver4j:3.1.0
  - org.incendo:cloud-core:2.0.0
  # ... other dependencies
3

Place in plugins folder

Copy the JAR to your server’s plugins/ directory and restart.
4

Verify installation

Check console for the load message:
[BetterModel] Plugin is loaded. (XXX ms)
[BetterModel] Minecraft version: 1.21.11, NMS version: v1_21_R7
[BetterModel] Platform: Paper

​
Platform-Specific Features

​
Paper Advantages

When running on Paper-based platforms, BetterModel gains access to:
Paper’s async scheduler with better thread safety:
Async Scheduling
override fun asyncTask(runnable: Runnable) = 
    Bukkit.getAsyncScheduler().runNow(PLUGIN) {
        runnable.run()
    }.wrap()

override fun asyncTaskLater(delay: Long, runnable: Runnable) = 
    Bukkit.getAsyncScheduler().runDelayed(PLUGIN, {
        runnable.run()
    }, (delay * 50).coerceAtLeast(1), TimeUnit.MILLISECONDS).wrap()
Dependencies loaded before plugin initialization, avoiding classloading issues.
Access to Paper-specific events for better entity management.

​
Spigot Limitations

On Spigot/Bukkit platforms:
Spigot Scheduler: Uses legacy BukkitScheduler API
Spigot Scheduler
override fun asyncTask(runnable: Runnable) = 
    Bukkit.getScheduler().runTaskAsynchronously(PLUGIN, runnable).wrap()

override fun asyncTaskLater(delay: Long, runnable: Runnable) = 
    Bukkit.getScheduler().runTaskLaterAsynchronously(
        PLUGIN, runnable, delay
    ).wrap()
Both implementations use the same ModelTask interface, ensuring API consistency across platforms.

​
Configuration

The plugin creates a BetterModel/ directory in your plugins folder: 
plugins/
└── BetterModel/
    ├── config.yml          # Main configuration
    ├── models/             # .bbmodel files for entities
    ├── players/            # .bbmodel files for player models
    └── resource-pack/      # Generated resource pack

​
Server Platform in Code

Your plugins can detect the current platform:
Detecting Platform
BetterModelBukkit platform = BetterModelBukkit.platform();

if (BetterModelBukkit.IS_PAPER) {
    // Paper-specific optimizations
    platform.scheduler().asyncTask(() -> {
        // Async work with Paper's scheduler
    });
} else {
    // Fallback to Spigot scheduler
    platform.scheduler().asyncTask(() -> {
        // Same API, different implementation
    });
}

​
API Usage

​
Adding the Dependency

repositories {
    mavenCentral()
}

dependencies {
    compileOnly("io.github.toxicity188:bettermodel-bukkit-api:2.2.0")
}

​
Basic Usage Example

Creating Models
import kr.toxicity.model.api.BetterModel;
import kr.toxicity.model.api.bukkit.platform.BukkitAdapter;
import kr.toxicity.model.api.tracker.EntityTracker;
import org.bukkit.entity.Entity;

public class ModelExample {
    public void spawnModel(Entity entity) {
        // Create entity tracker
        EntityTracker tracker = BetterModel.model("demon_knight")
            .map(renderer -> renderer.getOrCreate(
                BukkitAdapter.adapt(entity)
            ))
            .orElse(null);
        
        if (tracker != null) {
            // Model successfully attached to entity
            tracker.animate("idle", AnimationModifier.DEFAULT);
        }
    }
}

​
Soft Dependencies

BetterModel integrates with popular plugins:

MythicMobs

Custom model mechanics and conditions

Citizens

NPC model traits and commands

SkinsRestorer

Player skin integration for models

Nexo

Custom item model integration
These are automatically detected and loaded if present:
plugin.yml (Spigot)
softDepend:
  - MythicMobs
  - Citizens
  - SkinsRestorer
paper-plugin.yml (Paper)
dependencies:
  server:
    MythicMobs:
      required: false
      load: BEFORE
    Citizens:
      required: false
      load: BEFORE

​
Supported Minecraft Versions

Current Support: Minecraft 1.21 - 1.21.11BetterModel uses NMS (Net Minecraft Server) adapters for each Minecraft version:
  • v1_21_R1 through v1_21_R7 for different 1.21.x releases
  • Automatically selects the correct adapter at runtime
The plugin will refuse to load on unsupported Minecraft versions.

​
Troubleshooting

Error: “You’re using Paper, so you have to use Paper jar!”Solution: Download the correct JAR from Modrinth:
  • Paper/Purpur/Folia: bettermodel-paper-VERSION.jar
  • Spigot/Bukkit: bettermodel-spigot-VERSION.jar
The Spigot version explicitly checks and refuses to load on Paper:
Spigot Validation
override fun onEnable() {
    if (IS_PAPER) {
        warn("You're using Paper, so you have to use Paper jar!")
        return Bukkit.getPluginManager().disablePlugin(this)
    }
    super.onEnable()
}
Error: “Unsupported Minecraft version”Solution: Ensure you’re running Minecraft 1.21-1.21.11. The plugin will not load on older or newer versions.
Check your config.yml for resource pack settings:
pack-type: folder  # or 'zip', 'server'
  • folder: Generate to plugins/BetterModel/resource-pack/
  • zip: Generate as .zip file
  • server: Use with Paper’s built-in resource pack hosting

​
Next Steps

Folia Support

Learn about Folia’s region-based threading

Fabric Platform

Explore the Fabric mod implementation

API Examples

See complete API usage examples

Installation

Install BetterModel on your server

Build docs developers (and LLMs) love

Get started for freeTalk to us