DOCSEARCHbyAlgolia
Submit Docs

BetterModel

repository·v3·Indexed 43 days ago

https://github.com/toxicity188/bettermodel

A high-performance, server-side engine for Minecraft Java Edition that enables runtime rendering and animation of BlockBench models. Optimized for Paper, Spigot, Folia, and Fabric, it provides an extensible API for implementing custom player models, advanced animations (including Molang and IK rigging), and complex visual effects using the item-display packet.

Tokens
13.8K
Snippets
49
Records
75
Agent score
56%

What's inside BetterModel

  1. What is BetterModel?

    v3

    BetterModel is a server-based engine designed for Minecraft Java Edition that provides runtime rendering and animation of BlockBench models. It is built using the item-display packet and aims to provide a more efficient, flexible, and vanilla-friendly alternative to ModelEngine.

    Key Capabilities:

    • BlockBench Support: Implements essential elements like cubes, meshes, null objects, and locators.
    • Advanced Animation: Supports model animations, Molang expressions, and Inverse Kinematics (IK) rigging.
    • Player & Armor Support: Supports player skin models and custom armor.
    • Resource Management: Features automated resource pack generation with zero reliance on core shaders.
    • Entity Features: Provides support for entity syncing and custom hitboxes (tracking animation rotation) on both client and server sides.
    • Integrations: Supports MythicMobs (including some MEG mechanics) and provides an extensible API for developers.

  2. Use global textures to share textures between models

    v3
    In BetterModel 1.14.0, you can define global textures that are shared across multiple models. This prevents duplicate texture creation and simplifies resource management. To create a global texture, prefix the texture filename with global_ (e.g., global_texture_name.png). These textures are recognized as having no namespace.
    global_texture_name.png

  3. Access platform-specific APIs via BetterModel entrypoints

    v3

    BetterModel provides dedicated entrypoints to access platform-specific functionalities:

    • Bukkit: Use BetterModelBukkit#platform() to access Bukkit-specific APIs.
    • Fabric: Use BetterModelFabric#platform() to access Fabric-specific APIs.

    Additionally, a global BetterModelEventBus is available via BetterModel#eventBus.

  4. Verify Minecraft version compatibility

    v3

    BetterModel 3.0.0+ has the following version requirements:

    • Minimum Version: Operation is only guaranteed on Minecraft servers and clients version 1.21.4 or higher. Support for 1.21.3 and below is discontinued.
    • Minecraft 26.1.x: Fully supported.
    • Mesh Elements: Experimental support for client resource pack conversion from BlockBench is available on Minecraft clients version 26.1 and above.

  8. Add BetterModel to your Gradle project

    v3

    To use the BetterModel API in a Bukkit-based plugin (Spigot, Paper, etc.), add the following to your build.gradle or build.gradle.kts. Note that you may need additional repositories for transitive dependencies if using the Fabric version.

    Important: Use compileOnly for the Bukkit API as the plugin is provided by the server environment.

    // Gradle (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
}
    // Gradle (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
}

  9. Install BetterModel modules via Gradle

    v3

    Starting from v2.0.0, the project is split into specific modules. You must select the module corresponding to your target platform. The legacy io.github.toxicity188:bettermodel package is no longer used.

    Available Modules:

    • bettermodel-api: Common API module.
    • bettermodel-bukkit-api: API for Bukkit-based environments (Spigot, Paper, etc.).
    • bettermodel-fabric: Server-side mod implementation for Fabric.
    • bettermodel-core: Internal core module (Internal use only).

    Note on Dependencies: When using bettermodel-fabric, you must include the following repositories for transitive dependencies:

    • https://maven.blamejared.com/
    • https://maven.nucleoid.xyz/
    // Release Configuration
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)
}

  11. Add BetterModel to your Maven project

    v3

    To use the BetterModel API in a Maven project, add the following to your pom.xml. For snapshots, you must include the GitHub Packages repository and provide credentials.

    <!-- Maven Release -->
<repositories>
    <repository>
        <id>central</id>
        <url>https://repo.maven.apache.org/maven2</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>io.github.toxicity188</groupId>
        <artifactId>bettermodel-bukkit-api</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

  12. Configure Gradle dependencies for BetterModel v2.0.0

    v3

    To use BetterModel v2.0.0, add the appropriate repositories and dependencies to your build.gradle.kts file.

    For Bukkit/Spigot/Paper projects, use compileOnly with bettermodel-bukkit-api. For Fabric projects, use modApi with bettermodel-fabric.

    Note: bettermodel-fabric requires additional transitive dependencies from maven.blamejared.com and maven.nucleoid.xyz.

    // Release Configuration
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)
}