Contributing Guide

Welcome Contributors!

Thank you for your interest in contributing to BetterHud! This guide will help you get started with contributing code, documentation, and other improvements to the project.

BetterHud is an open-source project, and contributions from the community are what make it better!

Ways to Contribute

There are many ways to contribute to BetterHud:

Report Bugs

Found a bug? Report it on GitHub Issues with detailed reproduction steps.

Suggest Features

Have an idea for improvement? Create a feature request.

Fix Issues

Browse open issues and submit pull requests with fixes.

Improve Documentation

Help improve guides, fix typos, or add missing information.

Write Tests

Add unit tests or integration tests to improve code quality.

Share Examples

Create example HUD configurations or integration plugins.

Getting Started

1. Fork and Clone

Fork the Repository

Visit github.com/toxicity188/BetterHud and click the “Fork” button to create your own copy.

Clone Your Fork

Clone your forked repository to your local machine:

git clone https://github.com/YOUR_USERNAME/BetterHud.git
cd BetterHud

Add Upstream Remote

Add the original repository as an upstream remote:

git remote add upstream https://github.com/toxicity188/BetterHud.git

This allows you to sync your fork with the latest changes.

2. Set Up Development Environment

Install Java 21

BetterHud requires Java 21 Eclipse Adoptium for development.Download from adoptium.netVerify installation:

java -version

Install an IDE

Recommended IDEs for Kotlin development:

IntelliJ IDEA (recommended) - Excellent Kotlin support
Eclipse with Kotlin plugin
VS Code with Kotlin extension

Import Project

Open the BetterHud project in your IDE:

IntelliJ IDEA: File → Open → Select the BetterHud directory
The IDE should automatically detect it as a Gradle project

Build the Project

Verify everything works by building the project:

./gradlew build

If the build succeeds, you’re ready to start developing!

Development Workflow

Creating a Feature Branch

Always create a new branch for your changes:

# Update your fork with latest changes
git fetch upstream
git checkout master
git merge upstream/master

# Create a new branch for your feature
git checkout -b feature/my-new-feature

Use descriptive branch names:

feature/add-animation-system for new features
fix/resource-pack-generation for bug fixes
docs/update-api-examples for documentation
refactor/improve-hud-rendering for refactoring

Making Changes

Write Code

Make your changes to the codebase. Follow the coding style used in the project:

Use Kotlin coding conventions
Follow existing code formatting
Add comments for complex logic
Keep functions focused and concise

Test Your Changes

Test your changes thoroughly:

# Build the project
./gradlew build

# Run test server (for Bukkit changes)
./gradlew runServer

Ensure:

Your changes work as expected
No existing functionality is broken
No compilation errors or warnings

Commit Your Changes

Commit with clear, descriptive messages:

git add .
git commit -m "Add animation interpolation system

- Implement cubic bezier interpolation
- Add configuration options for animation curves
- Update API documentation"

Good commit messages:

Start with a verb (Add, Fix, Update, Remove)
Are concise but descriptive
Explain why, not just what

Submitting a Pull Request

Push to Your Fork

Push your branch to your GitHub fork:

git push origin feature/my-new-feature

Create Pull Request

Go to your fork on GitHub
Click “Compare & pull request” for your branch
Fill out the pull request template
Provide a clear title and description
Reference any related issues (e.g., “Fixes #123”)

Address Review Feedback

Project maintainers will review your PR and may request changes.To update your PR:

# Make requested changes
git add .
git commit -m "Address review feedback"
git push origin feature/my-new-feature

The PR will automatically update with your new commits.

Code Guidelines

Kotlin Style

BetterHud is written in Kotlin. Follow these guidelines:

Naming
Formatting
Documentation
Best Practices

// Classes: PascalCase
class HudRenderer { }

// Functions: camelCase
fun renderHudElement() { }

// Properties: camelCase
val playerName: String

// Constants: SCREAMING_SNAKE_CASE
const val MAX_HUD_ELEMENTS = 100

// Private properties: camelCase with underscore prefix
private val _internalCache = mutableMapOf()

Indentation: 4 spaces (not tabs)
Line length: Prefer ≤120 characters
Blank lines: Use to separate logical sections
Braces: Opening brace on same line

fun exampleFunction(param: String): Int {
    if (param.isEmpty()) {
        return 0
    }
    
    return param.length
}

Use KDoc for public APIs:

/**
 * Renders a HUD element for the specified player.
 *
 * @param player The player to render for
 * @param element The HUD element to render
 * @return True if rendering succeeded, false otherwise
 * @throws IllegalStateException if player is offline
 */
fun renderElement(player: Player, element: HudElement): Boolean {
    // Implementation
}

Prefer immutability (val over var)
Use Kotlin’s null-safety features
Leverage extension functions when appropriate
Use when instead of long if-else chains
Prefer data classes for DTOs

// Good: Immutable, null-safe
data class HudConfig(
    val enabled: Boolean,
    val elements: List<HudElement>,
    val updatePeriod: Int = 20
)

// Extension function for readability
fun Player.showHud(element: HudElement) {
    // Implementation
}

API Compatibility

When modifying public APIs, ensure backward compatibility or clearly document breaking changes.

Don’t remove public methods/classes without deprecation
Use @Deprecated annotation with replacement suggestions
Maintain API compatibility within major versions

@Deprecated(
    message = "Use renderElement() instead",
    replaceWith = ReplaceWith("renderElement(player, element)"),
    level = DeprecationLevel.WARNING
)
fun oldRenderMethod(player: Player, element: HudElement) {
    renderElement(player, element)
}

Reporting Issues

When reporting bugs or issues, please include:

Detailed Description - What happened vs. what you expected

Reproduction Steps - Step-by-step instructions to reproduce

Environment Information - OS, server version, platform, BetterHud version

Error Logs - Full stack traces and relevant log output

Configuration Files - Relevant YAML configs if applicable

Screenshots/Videos - Visual evidence when helpful

What NOT to Report

Please don’t create issues for:

Unsupported platforms (Bedrock, ArcLight, etc.)
Closed-source mod support (Optifine, ItemsAdder)
Modified client issues (Feather, etc.)
Very old versions (≤1.16.5)
Personal server configuration problems
Feature requests without clear use cases

See the bug report template for required information.

Feature Requests

When suggesting features:

Describe the Use Case - Why is this feature needed?
Provide Examples - How would it work? Include mockups if possible
Consider Alternatives - Have you tried existing features?
Be Realistic - Is this feasible for server-side implementation?

The more detailed and well-thought-out your feature request, the more likely it is to be implemented!

Features We Cannot Accept

Some features are outside BetterHud’s scope:

Bedrock/Geyser support
Client-side only features (e.g., 144 FPS HUD)
Closed-source plugin/mod integration
Significant performance-degrading features
Features requiring modified clients
Support for very legacy versions

See the feature request template for more details.

Testing

Manual Testing

Before submitting a PR:

Build the project: ./gradlew build
Test on a server: Use ./gradlew runServer or test on a real server
Test all platforms: If changes affect multiple platforms, test each
Test edge cases: Try unusual configurations or scenarios
Verify no regressions: Ensure existing features still work

Automated Testing

If you’re adding significant new functionality, consider adding tests:

class HudRendererTest {
    @Test
    fun testElementRendering() {
        val renderer = HudRenderer()
        val result = renderer.renderElement(mockPlayer, mockElement)
        assertTrue(result)
    }
}

Documentation

Updating Documentation

If your changes affect user-facing features:

Update relevant documentation pages
Add examples for new features
Update API documentation (KDoc comments)
Include changelog entry

Writing Good Documentation

Be Clear
Show Examples
Explain Why

Write in simple, clear language:Good:

Set enabled: true to activate the HUD element.

Bad:

The activation of the HUD element is accomplished via the modification of the enabled configuration parameter to a boolean true value.

Include practical examples:

# Example HUD configuration
my_hud:
  enabled: true
  elements:
    - health_bar
    - mana_display

Don’t just explain what, explain why:Good:

Set async-processing: true to improve server performance by processing HUD updates on a separate thread. This prevents HUD rendering from blocking the main server thread.

Bad:

Set async-processing: true to enable async processing.

Community

Get Help

Need help contributing?

Discord: Ask in discord.com/invite/rePyFESDbk
GitHub Discussions: Start a discussion on GitHub
Issues: Comment on related issues

Code of Conduct

When participating in the BetterHud community:

Be respectful and professional

Welcome newcomers and help them learn

Accept constructive criticism gracefully

Focus on what’s best for the project

Give credit where credit is due

Recognition

Contributors are recognized in:

GitHub’s contributor list
Release notes for significant contributions
Project documentation

Every contribution, no matter how small, is valued and appreciated!

License

By contributing to BetterHud, you agree that your contributions will be licensed under the same license as the project. Check the LICENSE file for details.

Questions?

If you have questions about contributing:

Check this guide and the Building Guide
Search existing GitHub issues and discussions
Ask in the Discord server
Create a GitHub discussion

Thank you for contributing to BetterHud!

Community

Development

​Welcome Contributors!

​Ways to Contribute

Report Bugs

Suggest Features

Fix Issues

Improve Documentation

Write Tests

Share Examples

​Getting Started

​1. Fork and Clone

​2. Set Up Development Environment

​Development Workflow

​Creating a Feature Branch

​Making Changes

​Submitting a Pull Request

​Code Guidelines

​Kotlin Style

​API Compatibility

​Reporting Issues

​What NOT to Report

​Feature Requests

​Features We Cannot Accept

​Testing

​Manual Testing

​Automated Testing

​Documentation

​Updating Documentation

​Writing Good Documentation

​Community

​Get Help

​Code of Conduct

​Recognition

​License

​Questions?

Build docs developers (and LLMs) love

Welcome Contributors!

Ways to Contribute

Getting Started

1. Fork and Clone

2. Set Up Development Environment

Development Workflow

Creating a Feature Branch

Making Changes

Submitting a Pull Request

Code Guidelines

Kotlin Style

API Compatibility

Reporting Issues

What NOT to Report

Feature Requests

Features We Cannot Accept

Testing

Manual Testing

Automated Testing

Documentation

Updating Documentation

Writing Good Documentation

Community

Get Help

Code of Conduct

Recognition

License

Questions?