ColorParser

A simple utility library for adding MiniMessage support with Adventure to your plugin/mod on any platform, with extensive support for placeholder systems like PlaceholderAPI and MiniPlaceholders.

---

🌟 Features

• Simple API for parsing strings into Adventure components
• Backwards compatibility for legacy color codes like § & &
• Built-in support for placeholder systems like PlaceholderAPI and MiniPlaceholders
• Extension to the default MiniMessage Tags with new useful additions

🛠️ Supported Platforms

Platform Support

Platform	Minimum Version	Supported Versions	Notes
Velocity	3.0.0	3.0.0+	-
Paper	1.16.5	1.16.5+	-
Bukkit	1.7.10	1.7.10+	Use on platforms/versions that do not natively support Adventure
Sponge	8 (1.16.5)	8+	-

Placeholder Support

Platform	PlaceholderAPI	MiniPlaceholders	Notes
Bukkit	✅ All versions	❌ Not supported	-
Paper	✅ All versions	✅ 1.19.4+	MiniPlaceholders requires Paper 1.19.4 or higher
Velocity	❌ Not supported (Use MiniPlaceholders)	✅ All versions	MiniPlaceholders can provide PlaceholderAPI placeholders on Velocity
Sponge	❌ Not supported (Use MiniPlaceholders)	✅ All versions	-

Version Matrix

Platform Version	PlaceholderAPI	MiniPlaceholders
Bukkit 1.7.10+	✅	❌
Paper 1.16.5 - 1.19.3	✅	❌
Paper 1.19.4+	✅	✅
Velocity 3.0.0+	❌	✅
Sponge 8+	❌	✅

❓ Why Make This?

ColorParser was created from a place of frustration. Although Adventure/MiniMessage is great and incredibly powerful, implementing its usage in an actual project can be cumbersome, tedious, and in many cases result in some extremely verbose code.

Trying to provide consistent PlaceholderAPI and MiniPlaceholders support, backwards compatibility for legacy color codes, and more, significantly compounds this unfortunate effect. Eventually, what was originally a simple single class Builder became a library that has grown with my own needs over time.

The premise is and has always been simple. We want to take our locale/translation strings and parse them into Components with as little code as possible, while still providing rich API for those who need it. After all, what server administrator doesn't want their plugins' messages to be customizable to the maximum.

📦 Installation

Please read the full installation instructions in the documentation here.

The paper, velocity, bukkit & sponge modules transitively include common. Additionally you should shade the library into your plugin jar.

Gradle Kotlin DSL

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.milkdrinkers:colorparser-paper:VERSION")
    implementation("io.github.milkdrinkers:colorparser-velocity:VERSION")
    implementation("io.github.milkdrinkers:colorparser-bukkit:VERSION")
}

Maven

<project>
    <dependencies>
        <dependency>
            <groupId>io.github.milkdrinkers</groupId>
            <artifactId>colorparser-paper</artifactId>
            <version>VERSION</version>
        </dependency>
        <dependency>
            <groupId>io.github.milkdrinkers</groupId>
            <artifactId>colorparser-velocity</artifactId>
            <version>VERSION</version>
        </dependency>
        <dependency>
            <groupId>io.github.milkdrinkers</groupId>
            <artifactId>colorparser-bukkit</artifactId>
            <version>VERSION</version>
        </dependency>
    </dependencies>
</project>

Usage Example 🚀

// Parses the content of a MiniMessage string into a component
Component message = ColorParser.of("<#00ff00><hover:show_text:'<red>test'>R G B!")
    .build();

Component message1 = ColorParser.of("<green><player> Teleported to you.")
    .with("player", player.getName()) // Parses the placeholder <player> with the player's name
    .build();

Component message2 = ColorParser.of("<green><player> Teleported to you.")
    .with("player", Component.text("Lorem Ipsum")) // Parses the placeholder <player> with an Adventure Component
    .build();

Component message3 = ColorParser.of("<green><player> Teleported to you.")
    .with("player", "<red><bold>Lorem Ipsum") // Parses the placeholder <player> with MiniMessage string
    .build();

Component message = ColorParser.of("&6So<green>me &5String &4Here")
    .legacy() // Parses legacy color codes like § and &, into their MiniMessage equivalents
    .build();

Component message = ColorParser.of("Your Displayname is: %player_displayname%")
    .papi(player) // Parses all PlaceholderAPI placeholders in the string
    .mini(player) // Parses MiniPlaceholders in the string
    .build();

📚 Documentation

• Javadoc
• Documentation
• Maven Central
• MiniMessage Format
• MiniMessage Previewer
• Adventure Documentation

---

🔨 Building from Source

git clone https://github.com/milkdrinkers/ColorParser.git
cd colorparser
./gradlew publishToMavenLocal

---

🔧 Contributing

Contributions are always welcome! Please make sure to read our Contributor's Guide for standards and our Contributor License Agreement (CLA) before submitting any pull requests.

We also ask that you adhere to our Contributor Code of Conduct to ensure this community remains a place where all feel welcome to participate.

---

📝 Licensing

You can find the license the source code and all assets are under here. Additionally, contributors agree to the Contributor License Agreement (CLA) found here.

---

❤️ Acknowledgments

• Adventure: The creator and contributors of Kyori Adventure for creating and maintaining the adventure collection of libraries.
• CubBossa: For their excellent translations library TinyTranslations from which many of the ideas for new default tags were inspired.
• 4drian3d: For creating and maintaining the MiniPlaceholders plugin/mod providing placeholder support on multiple platforms.
• extendedclip & contributors: For creating and maintaining PlaceholderAPI providing placeholder support on Bukkit based platforms.