Getting Started

To better understand the design of ByteLib and how it works, a good place to start is to review the core design principles of the library. If you're not interested in the technical details, you can safely skip that topic.

ByteLib is built on top of the experimental Paper Plugin API. This API requires some manual configuration from developers, so ByteLib provides clear documentation for the setup process.

Adding ByteLib to your Project

ByteLib can be added to your project through either JitPack, GitHub Packages, or via the release JAR file. Instructions are provided below for all three methods using Gradle or Maven.

JitPack is a free service that offers just-in-time (JIT) compiling & packaging of Java projects. It's an easy way to publish your projects without setting up complex CI/CD pipelines.

To use JitPack, first add the JitPack repository to your Gradle repositories list

                        repositories {
                            maven("https://jitpack.io")
                        }
                    

After adding the JitPack repository, add ByteLib as an implementation dependency, replacing ByteLib-1.1.3 with whatever version of ByteLib you're wanting to add. At the time of writing, 1.1.3 is the latest version

            dependencies {
                implementation("com.github.TerrorByteTW:ByteLib:ByteLib-1.1.3")
            }
        

To use JitPack, first add the JitPack repository to your Maven repositories list

                        <repositories>
                            <repository>
                                <id>jitpack.io</id>
                                <url>https://jitpack.io</url>
                            </repository>
                        </repositories>
                    

After adding the JitPack repository, add ByteLib as a dependency, replacing ByteLib-1.1.3 with whatever version of ByteLib you're wanting to add. At the time of writing, 1.1.3 is the latest version.

            <dependency>
                <groupId>com.github.TerrorByteTW</groupId>
                <artifactId>ByteLib</artifactId>
                <version>ByteLib-1.1.3</version>
            </dependency>
        

GitHub Packages is GitHub's own package repository. ByteLib publishes each release build to GitHub Packages automatically. GitHub Packages is a little more complicated to set up, and only release builds are available through it, so if you need snapshot builds or do not want to deal with authentication, use another method.

To use GitHub Packages with Gradle, first add the GitHub Packages repository to your project's repositories block.

                            repositories {
                                maven {
                                    name = "GitHubPackages"
                                    url = uri("https://maven.pkg.github.com/TerrorByteTW/ByteLib")

                                    credentials {
                                        username =
                                            project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
                                        password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
                                    }
                                }
                            }
                        

After adding the repository, add ByteLib as a dependency, replacing ByteLib-1.1.3 with whatever version of ByteLib you want to use. At the time of writing, 1.1.3 is the latest version.

            dependencies {
                implementation("com.github.TerrorByteTW:ByteLib:ByteLib-1.1.3")
            }
        

If you attempt to download the library now, you will receive an authentication error. To authenticate with GitHub Packages, add your GitHub username and PAT to your gradle.properties file, typically located at USER_HOME\.gradle\gradle.properties.

                            gpr.user=YOUR_USERNAME
gpr.key=YOUR_AUTH_TOKEN
                        

For more information on creating a Personal Access Token (PAT), see this article: Creating a personal access token. The token must have the read:packages scope, at minimum.

To use GitHub Packages, first add the GitHub Packages repository to your Maven repositories list.

                            <repositories>
                                <repository>
                                    <id>github</id>
                                    <name>GitHub TerrorByteTW Apache Maven Packages</name>
                                    <url>https://maven.pkg.github.com/TerrorByteTW/ByteLib</url>
                                    <releases>
                                        <enabled>true</enabled>
                                    </releases>
                                    <snapshots>
                                        <enabled>true</enabled>
                                    </snapshots>
                                </repository>
                            </repositories>
                        

After adding the GitHub Packages repository, add ByteLib as dependency, replacing ByteLib-1.1.3 with whatever version of ByteLib you're wanting to add. At the time of writing, 1.1.3 is the latest version.

            <dependency>
                <groupId>com.github.TerrorByteTW</groupId>
                <artifactId>ByteLib</artifactId>
                <version>ByteLib-1.1.3</version>
            </dependency>
        

If you attempt to download the library now, you will receive an authentication error. To authenticate with GitHub Packages, add your PAT to your settings.xml, typically located at USER_HOME\.m2\settings.xml.

                            <servers>
                                <server>
                                    <id>github</id>
                                    <username>YOUR_USERNAME</username>
                                    <password>YOUR_AUTH_TOKEN</password>
                                </server>
                            </servers>
                        

For more information on creating a Personal Access Token (PAT), see this article: Creating a personal access token. The token must have the read:packages scope, at minimum.

If you do not want to use JitPack or GitHub Packages, you may use a compiled JAR file obtained by either building ByteLib yourself from source, or by downloading it from the GitHub Releases page. Note that doing so will also require you to add the JavaDocs and Sources to your IDE separately to get proper debugging and inline documentation. Instructions for doing so vary between IDEs and will not be provided.

To use a compiled ByteLib JAR file, add the file as a dependency. No repository is necessary.

                            dependencies {
                                implementation(files("path/to/ByteLib-1.1.3.jar"))
                            }
                        

Maven does not have a native files() method like Gradle does. To add ByteLib as a dependency, you must first install it using the mvn CLI tool.

                            mvn install:install-file \
                              -Dfile=path/to/ByteLib-1.1.3.jar \
                              -DgroupId=com.github.TerrorByteTW \
                              -DartifactId=ByteLib \
                              -Dversion=ByteLib-1.1.3 \
                              -Dpackaging=jar
                        

After the JAR is installed into your local Maven repository, you may add it like a normal dependency.

            <dependency>
                <groupId>com.github.TerrorByteTW</groupId>
                <artifactId>ByteLib</artifactId>
                <version>ByteLib-1.1.3</version>
            </dependency>
        

Using ByteLib

Just adding ByteLib to your project does not grant you the ability to use its APIs. Every plugin using ByteLib will require some additional setup before ByteLib is actually "utilized". Namely, your plugin must be bootstrapped and the plugin loader must be configured.

Review the Bootstrapping topic to learn how to bootstrap your plugin to use ByteLib.
Review the Plugin Loader documentation to learn how the Paper PluginLoader works in ByteLib.
Create the required configuration files used by the Config API, which are required for ByteLib-powered plugins to load.

ByteLib APIs

ByteLib provides several APIs that simplify plugin development. All APIs are designed with Dependency Injection at their core, making them easy to integrate anywhere in your plugin.

Explore the following topics to learn more about each API.

Config API

The Config API is a mandatory, opinionated, lightweight wrapper around the BoostedYAML library that simplifies interacting with configuration files.

The API also includes utilities for handling translations and provides native support for MiniMessage.

Lifecycles API

The Lifecycles API allows ByteLib plugins to define any number of onLoad, onEnable, and onDisable lifecycle hooks.

This allows developers to keep their main plugin class thin while separating responsibilities into dedicated lifecycle components.

Lifecycle handlers can also be executed in a defined order when required.

Commands API

The Commands API allows developers to easily create and register Brigadier commands for their plugin.

While conceptually similar to Brigadier, ByteLib's API provides a more opinionated interface for command creation and includes additional utilities for common command patterns.

Like all ByteLib systems, the Commands API integrates directly with Google Guice Dependency Injection.

SQLite API

One of ByteLib's most powerful features is the SQLite API, which allows developers to easily create and interact with SQLite databases in a type-safe, object-oriented manner.

The API preserves the flexibility of raw SQL while providing higher-level tools for common database interactions.

23 April 2026