Getting Started

This guide will help you integrate MessageAPI into your Minecraft Paper plugin project.

Requirements

Installation

📦 Latest version: JitPack Version (replace LATEST_VERSION below with the version shown on the badge)

Maven

Add the JitPack repository and MessageAPI dependency to your pom.xml:

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

<dependencies>
    <dependency>
        <groupId>com.github.KubawGaming</groupId>
        <artifactId>MessageAPI</artifactId>
        <version>LATEST_VERSION</version>
    </dependency>
</dependencies>

Gradle (Groovy)

Add the JitPack repository and MessageAPI dependency to your build.gradle:

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.KubawGaming:MessageAPI:LATEST_VERSION'
}

Gradle (Kotlin DSL)

Add the JitPack repository and MessageAPI dependency to your build.gradle.kts:

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

dependencies {
    implementation("com.github.KubawGaming:MessageAPI:LATEST_VERSION")
}
💡 Note: Always use the actual version number shown on the JitPack badge above. LATEST_VERSION is just a placeholder.

Relocation (Paper 1.17-1.19)

If you're targeting Paper versions between 1.17 and 1.19, you need to relocate the Adventure API to avoid conflicts:

Maven (with Maven Shade Plugin)

For Maven, use the maven-shade-plugin with the appropriate relocation:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.5.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <relocations>
                            <relocation>
                                <pattern>net.kyori</pattern>
                                <shadedPattern>me.kubaw208.messageapi.libs.kyori</shadedPattern>
                            </relocation>
                        </relocations>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Gradle (Groovy)

plugins {
    id 'com.gradleup.shadow' version '8.3.3'
}

shadowJar {
    relocate "net.kyori", "me.kubaw208.messageapi.libs.kyori"
}

Gradle (Kotlin DSL)

plugins {
    id("com.gradleup.shadow") version "8.3.3"
}

tasks.shadowJar {
    relocate("net.kyori", "me.kubaw208.messageapi.libs.kyori")
}
📌 Important: Relocation is only required for Paper 1.17-1.19. For Paper 1.20+, Adventure API is already included in the server and relocation is optional.

Troubleshooting

MessageAPI not initializing

Make sure you call Message.init(this) in your plugin's onEnable() method before using any message types.

Messages not displaying colors

Ensure you're using MiniMessage formatting tags (e.g., <green>, <#FF5555>) instead of legacy color codes (e.g., &a, &c).

Version placeholder

If you see LATEST_VERSION in your code examples, remember to replace it with the actual version number from the JitPack badge above (e.g., 1.0.2). Do not use LATEST in production — always pin a specific version.

JitPack not resolving the dependency

Make sure your build system has internet access and that you've added the JitPack repository correctly. Clean your local cache if needed (~/.m2/repository for Maven, or ~/.gradle/caches for Gradle).

Need more help? Open an issue on GitHub.