https://github.com/toxicity188/bettermodel
Modern Bedrock model engine for Minecraft Java Edition
https://github.com/toxicity188/bettermodel
blockbench bukkit-plugin fabric-mod fabric-server folia-plugin java kotlin minecraft minecraft-mod minecraft-model minecraft-plugin modelengine paper-plugin resource-pack spigot-plugin
Last synced: about 1 month ago
JSON representation
Modern Bedrock model engine for Minecraft Java Edition
- Host: GitHub
- URL: https://github.com/toxicity188/bettermodel
- Owner: toxicity188
- License: mit
- Created: 2024-12-17T16:51:37.000Z (over 1 year ago)
- Default Branch: v2
- Last Pushed: 2026-02-08T00:49:08.000Z (about 1 month ago)
- Last Synced: 2026-02-08T09:24:32.623Z (about 1 month ago)
- Topics: blockbench, bukkit-plugin, fabric-mod, fabric-server, folia-plugin, java, kotlin, minecraft, minecraft-mod, minecraft-model, minecraft-plugin, modelengine, paper-plugin, resource-pack, spigot-plugin
- Language: Kotlin
- Homepage: https://modrinth.com/plugin/bettermodel
- Size: 5.81 MB
- Stars: 243
- Watchers: 2
- Forks: 40
- Open Issues: 34
-
Metadata Files:
- Readme: README.md
- Changelog: changelog/2.0.1.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# BetterModel
*- Modern Bedrock model engine for Minecraft Java Edition -*
[](https://central.sonatype.com/artifact/io.github.toxicity188/bettermodel-api)
[](https://www.codefactor.io/repository/github/toxicity188/bettermodel)
[](https://modrinth.com/plugin/bettermodel/versions)
[](https://github.com/toxicity188/BetterModel/issues)
[](https://bstats.org/plugin/bukkit/BetterModel/24237)
* * *
* * *
(In BlockBench / In Minecraft)
# ✨ Introduction
**BetterModel** is a server-based engine that provides runtime BlockBench model rendering & animating for Minecraft Java Edition.
It implements **fully server-side 3D models** by using an item display entity packet.
- Importing Generic BlockBench model `.bbmodel`
- Auto-generating resource pack
- Playing animation
- Syncing with base entity
- Custom hit box
- 12-limb player animation
In-Game Screenshots
## 🚀 Key Features & Focus
BetterModel aims to be a reliable engine that provides stable, high-quality animations for Paper-based high-traffic servers.
- **Stability First**: We take a conservative approach to feature expansion. By avoiding the implementation of features that are difficult to maintain or have limited use cases, we focus on providing a stable API and ensuring overall operational safety.
- **Performance Optimized**: Our goal is to minimize runtime computation, memory footprint, and network overhead. Through asynchronous design and optimized packet handling, we ensure the engine runs efficiently even under heavy server loads.
- **Tailored for Large-scale Servers**: We provide essential features specifically designed for high-population servers and MMORPG content creation.
- **Per-player Animation**: Individual animation control tailored to each player's perspective.
- **Player Model Animation**: Support for sophisticated 12-limb animations based on player models.
## 📚 Wiki
[](https://github.com/toxicity188/BetterModel/wiki)
[](https://deepwiki.com/toxicity188/BetterModel)
## 🛠️ Build info
[](https://www.minecraft.net/en-us/download/server)
[](https://adoptium.net/)
#### Build
[](https://gradle.org/)
`./gradlew build`: Builds all jars
`./gradlew shadowJar`: Builds plugin jar
`./gradlew javadocJar`: Builds javadoc jar
`./gradlew runServer`: Runs Paper test server with test plugin
#### Library
- [Kotlin stdlib](https://github.com/JetBrains/kotlin): modern functional programming
- [semver4j](https://github.com/vdurmont/semver4j): semver parser
- [cloud](https://github.com/Incendo/cloud-minecraft): command
- [adventure](https://github.com/KyoriPowered/adventure): component
- [stable player display](https://github.com/bradleyq/stable_player_display): player animation
- [caffeine](https://github.com/ben-manes/caffeine): concurrent map cache
- [DynamicUV](https://github.com/toxicity188/DynamicUV): player model
- [ArmorModel](https://github.com/toxicity188/ArmorModel): armor in player model
- [molang-compiler](https://github.com/Ocelot5836/molang-compiler): compiling and evaluating molang expression
- [libby](https://github.com/AlessioDP/libby): runtime library downloader
#### Tested Bukkit Server Platform
- [Paper](https://papermc.io/downloads/paper)
- [Purpur](https://purpurmc.org/download/purpur)
- [Spigot](https://www.spigotmc.org/)
- [Folia](https://papermc.io/downloads/folia)
- [Leaf](https://www.leafmc.one/download)
- [Canvas](https://canvasmc.io/downloads/canvas)
#### Tested Mod Server Platform
- [Fabric Loader](https://fabricmc.net/)
## 💻 API
[](https://central.sonatype.com/artifact/io.github.toxicity188/bettermodel)
> [!NOTE]\
> For more detailed API specifications, please refer to our [GitHub Wiki](https://github.com/toxicity188/BetterModel/wiki/API-example).
Gradle (Kotlin)
#### Release
```kotlin
repositories {
mavenCentral()
maven("https://maven.blamejared.com/") // For transitive dependency in bettermodel-fabric
maven("https://maven.nucleoid.xyz/") // For transitive dependency in bettermodel-fabric
}
dependencies {
compileOnly("io.github.toxicity188:bettermodel-bukkit-api:VERSION") // bukkit(spigot, paper, etc) api
//modApi("io.github.toxicity188:bettermodel-fabric:VERSION") // mod(fabric)
}
```
#### Snapshot
```kotlin
repositories {
maven("https://maven.pkg.github.com/toxicity188/BetterModel") {
credentials {
username = YOUR_GITHUB_USERNAME
password = YOUR_GITHUB_TOKEN
}
}
maven("https://maven.blamejared.com/") // For transitive dependency in bettermodel-fabric
maven("https://maven.nucleoid.xyz/") // For transitive dependency in bettermodel-fabric
}
dependencies {
compileOnly("io.github.toxicity188:bettermodel-bukkit-api:VERSION-SNAPSHOT") // bukkit(spigot, paper, etc) api
//modApi("io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT") // mod(fabric)
}
```
Gradle (Groovy)
#### Release
```groovy
repositories {
mavenCentral()
maven 'https://maven.blamejared.com/' // For transitive dependency in bettermodel-fabric
maven 'https://maven.nucleoid.xyz/' // For transitive dependency in bettermodel-fabric
}
dependencies {
compileOnly 'io.github.toxicity188:bettermodel-bukkit-api:VERSION' // bukkit(spigot, paper, etc) api
//modApi 'io.github.toxicity188:bettermodel-fabric:VERSION' // mod(fabric)
}
```
#### Snapshot
```groovy
repositories {
maven {
url "https://maven.pkg.github.com/toxicity188/BetterModel"
credentials {
username = YOUR_GITHUB_USERNAME
password = YOUR_GITHUB_TOKEN
}
}
maven 'https://maven.blamejared.com/' // For transitive dependency in bettermodel-fabric
maven 'https://maven.nucleoid.xyz/' // For transitive dependency in bettermodel-fabric
}
dependencies {
compileOnly 'io.github.toxicity188:bettermodel-bukkit-api:VERSION-SNAPSHOT' // bukkit(spigot, paper, etc) api
//modApi 'io.github.toxicity188:bettermodel-fabric:VERSION-SNAPSHOT' // mod(fabric)
}
```
Maven
#### Release
```xml
central
https://repo.maven.apache.org/maven2
io.github.toxicity188
bettermodel-bukkit-api
VERSION
provided
```
#### Snapshot
```xml
github
https://maven.pkg.github.com/toxicity188/BetterModel
io.github.toxicity188
bettermodel-api
VERSION-SNAPSHOT
provided
io.github.toxicity188
bettermodel-bukkit-api
VERSION-SNAPSHOT
provided
```
Example code
#### Gets some model or limb
```java
BetterModel.model("demon_knight"); //A model file in BetterModel/models (for general model with saving)
BetterModel.limb("steve"); //A model file in BetterModel/players (for player model with no saveing)
BetterModel.modelOrNull("demon_knight"); //general model or null
BetterModel.limbOrNull("steve"); //player model or null
```
#### Creates model (entity)
```java
EntityTracker tracker = BetterModel.model("demon_knight")
.map(r -> r.getOrCreate(BukkitAdapter.adapt(entity))) //Gets or creates entity tracker by this renderer to some entity.
.orElse(null);
```
```java
EntityTracker tracker = BetterModel.model("demon_knight")
.map(r -> r.create(BukkitAdapter.adapt(entity), TrackerModifier.DEFAULT, t -> t.update(TrackerUpdateAction.tint(0x0026FF)))) //Creates entity tracker with pre-spawn task.
.orElse(null);
```
#### Creates model (dummy)
```java
DummyTracker tracker = BetterModel.model("demon_knight")
.map(r -> r.create(BukkitAdapter.adapt(location))) //Creates some dummy tracker to this location.
.orElse(null);
```
```java
DummyTracker tracker = BetterModel.limb("steve")
.map(r -> r.create(BukkitAdapter.adapt(location), ModelProfile.of(BukkitAdapter.adapt(player)))) //Creates some dummy tracker to this location and player's skin profile.
.orElse(null);
```
#### Update some tracker's display data
```java
BetterModel.model("demon_knight")
.map(r -> r.create(BukkitAdapter.adapt(entity), TrackerModifier.DEFAULT, t -> {
t.update(TrackerUpdateAction.tint(rgb)); //Tint
t.update(TrackerUpdateAction.enchant(true), bone -> true); //Enchant with predicate
}))
.ifPresent(tracker -> tracker.update(TrackerUpdateAction.composite( //Composite
TrackerUpdateAction.brightness(15, 15) //Brightness
TrackerUpdateAction.billboard(Display.Billboard.CENTER) //Billboard
)));
}
```
## 💬 Community
[](https://discord.com/invite/rePyFESDbk)
## 💖 Support
[](https://buymeacoffee.com/toxicity188)
[](https://github.com/sponsors/toxicity188)
[](https://www.paypal.com/paypalme/toxicity188?country.x=KR&locale.x=en_US)