Skip to main content

​
Requirements

Building BetterHud requires Java 21 Eclipse Adoptium. Other Java distributions may work but are not officially supported.

​
Prerequisites

1

Install Java 21

Download and install Java 21 Eclipse Adoptium from adoptium.netVerify installation:
java -version
You should see output indicating Java 21.
2

Clone the Repository

Clone the BetterHud repository from GitHub:
git clone https://github.com/toxicity188/BetterHud.git
cd BetterHud
3

Verify Gradle Wrapper

The project includes a Gradle wrapper, so you don’t need to install Gradle separately.On Linux/Mac:
./gradlew --version
On Windows:
gradlew.bat --version

​
Build Tasks

BetterHud provides several Gradle tasks for building different platform variants and artifacts.

​
Build All Platforms

Build all available platform jars (Bukkit, Velocity, Fabric) plus source and javadoc jars: 
./gradlew build
This is the most common build command. It produces all platform jars and documentation.
Output files (in build/libs/):
  • BetterHud-bukkit-VERSION.jar - Bukkit/Spigot/Paper/Folia plugin
  • BetterHud-velocity-VERSION.jar - Velocity proxy plugin
  • BetterHud-fabric-VERSION.jar - Fabric server-side mod
  • BetterHud-VERSION-sources.jar - Source code jar
  • BetterHud-VERSION-javadoc.jar - API documentation

​
Platform-Specific Builds

Build only the platform you need:
Build only the Bukkit plugin:
./gradlew pluginJar
Output: bootstrap/bukkit/build/libs/BetterHud-bukkit-VERSION.jar
This jar works on Bukkit, Spigot, Paper, and Folia servers running Minecraft 1.20.4 to 1.21.11.

​
Documentation & Sources

​
Build Source Code Jar

Generate a jar containing all source files: 
./gradlew sourcesJar
Output: build/libs/BetterHud-VERSION-sources.jar
Source jars are useful for IDE integration and debugging when developing plugins that use BetterHud’s API.

​
Build Javadoc Documentation

Generate API documentation using Dokka: 
./gradlew javadocJar
Output: build/libs/BetterHud-VERSION-javadoc.jar Extract and view the documentation: 
# Extract javadoc jar
unzip build/libs/BetterHud-VERSION-javadoc.jar -d docs/

# Open in browser
open docs/index.html
BetterHud uses Dokka to generate Kotlin-friendly documentation with enhanced formatting.

​
Generate Dokka HTML Documentation

Generate browsable HTML documentation without packaging: 
./gradlew dokkaGenerate
Output: build/dokka/html/ Open build/dokka/html/index.html in your browser to view the documentation.

​
Development Tasks

​
Running a Test Server

BetterHud includes a task to run a Paper test server with the plugin automatically loaded: 
./gradlew runServer
This will:
  1. Download Paper server for the configured Minecraft version
  2. Set up a test server environment
  3. Install BetterHud and dependency plugins (ViaVersion, ViaBackwards, PlaceholderAPI, Skript)
  4. Start the server
The server will run in run/ directory. Use stop in the server console to shut it down.

​
Clean Build Artifacts

Remove all build outputs and start fresh: 
./gradlew clean
Then rebuild: 
./gradlew clean build

​
Build Configuration

​
Understanding the Build Structure

BetterHud uses a multi-module Gradle project structure: 
BetterHud/
├── bootstrap/           # Platform-specific implementations
│   ├── bukkit/         # Bukkit/Paper/Folia
│   ├── velocity/       # Velocity proxy
│   └── fabric/         # Fabric server
├── api/                # Public API modules
│   ├── standard-api/   # Platform-agnostic API
│   ├── bukkit-api/     # Bukkit-specific API
│   └── fabric-api/     # Fabric-specific API
├── dist/               # Distribution & core modules
└── build.gradle.kts    # Root build configuration

​
Key Build Files

​
build.gradle.kts

The root build file defines:
  • Multi-platform build tasks
  • Source and javadoc jar generation
  • Publishing configuration for Modrinth and Hangar
  • Test server setup
Key tasks defined here:
  • build - Build all platforms
  • pluginJar - Build Bukkit only
  • fabricJar - Build Fabric only
  • velocityJar - Build Velocity only
  • sourcesJar - Package source code
  • javadocJar - Generate and package API docs
  • runServer - Run test Paper server
  • modrinthPublish - Publish to Modrinth (requires API token)

​
Gradle Properties

The build reads version and configuration from gradle.properties and version catalogs. Key properties:
  • minecraft_version - Target Minecraft version
  • version - BetterHud version

​
Publishing (Maintainers Only)

Publishing tasks require API tokens and are intended for project maintainers only.

​
Publish to Modrinth

Publish all platform builds to Modrinth: 
export MODRINTH_API_TOKEN="your_token_here"
./gradlew modrinthPublish

​
Publish to Hangar

Publish to PaperMC’s Hangar: 
export HANGAR_API_TOKEN="your_token_here"
./gradlew hangarPublish
The build automatically determines if it’s a snapshot or release based on the COMMIT_MESSAGE environment variable.

​
Troubleshooting Build Issues

​
Build Fails with Java Version Error

Error: “Unsupported class file major version” or “Java version mismatch”
Solution: Ensure you’re using Java 21: 
java -version
If you have multiple Java versions, set JAVA_HOME: 
export JAVA_HOME=/path/to/java-21
./gradlew build

​
Gradle Daemon Issues

If builds are failing mysteriously, try stopping the Gradle daemon: 
./gradlew --stop
./gradlew clean build

​
Dependency Download Failures

If dependencies fail to download:
  1. Check your internet connection
  2. Try clearing Gradle cache: 
    rm -rf ~/.gradle/caches
./gradlew build --refresh-dependencies

​
Out of Memory Errors

If the build runs out of memory, increase Gradle’s heap size: Create/edit gradle.properties in the project root: 
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g

​
Next Steps

After building BetterHud:

Install the Plugin

Learn how to install your freshly built plugin on a server

Contributing Guide

Want to contribute? Read our contribution guidelines

API Development

Build plugins that integrate with BetterHud

Report Issues

Found a build problem? Report it on GitHub

Build docs developers (and LLMs) love

Get started for freeTalk to us