TextAPI

Actively searching a graphist for the logo
DM me on discord if interested: nolly__

TextAPI is a Kotlin-first Spigot API/library for advanced text parsing, formatting, and rendering. It combines MiniMessage-style tags, PlaceholderAPI-like placeholders, gradients, ✨ effects, hover/click/insertion events, and runtime extensibility into a single high-performance system.

!Example

Overview

TextAPI is designed for plugin developers who want rich in-game text without heavy complexity. It can be used as a dependency in other plugins, or standalone if you want to test and explore its features through the built-in debug command. The focus is on clean DX, strong UX, and predictable rendering behavior.

It supports built-in colors, hex colors, decorations, gradients, ✨ presets, placeholders, legacy string output, and component output. On top of that, developers can register and unregister custom placeholders, custom tags, and custom gradients at runtime without touching the renderer internals.

What it does

TextAPI parses a compact markup syntax and turns it into either legacy-formatted text or Bungee chat components. It supports:

• Named colors and hex colors
• Decorations like bold, italic, underline, strikethrough, and obfuscated
• Gradients with multiple color stops
• ✨ text with phase control
• Hover and click actions
• Insertions
• Placeholder expansion
• Runtime custom tags with handler callbacks
• Runtime custom gradients with named presets

The result is a flexible formatting engine that feels like a cleaner, lighter, and more extensible alternative to mixing multiple text systems together.

Performance

Performance is a core design goal. TextAPI uses a single-pass tokenizer, a stack-based renderer, and lightweight context resolution to keep parsing fast and predictable. Gradients and ✨ effects are expanded only when needed, and placeholder lookups are resolved through a normalized registry instead of reflection or heavy dynamic inspection.

The rendering pipeline is built to minimize unnecessary allocations while still preserving nested formatting, event support, and style inheritance. A custom TPS tracker powers live server timing placeholders without relying on external dependencies. The end result is a fast API that stays practical for real-time in-game use.

Developer experience

The API is built to be easy to learn and easy to extend. Developers can:

• Parse strings directly
• Get components for chat output
• Send messages to players
• Inspect tokens for debugging
• Register and unregister placeholders at runtime
• Register and unregister tags at runtime
• Register and unregister gradients at runtime

The command system is intentionally powerful too, so the project can be tested standalone in-game without writing extra integration code. That makes it useful both as a dependency and as a developer tool during experimentation.

Built-in content

TextAPI ships with a broad default feature set:

• Player placeholders
• Server placeholders
• Time placeholders
• TPS placeholders
• 14 ✨ gradient presets
• Common text decorations
• Hover and click interactions
• Reset and escape handling
• Component and legacy outputs

This gives developers a lot out of the box while still leaving room for custom behavior when needed.

Extensibility model

Custom tags are handler-based, which means a tag can modify style dynamically and can react to arguments. Custom gradients are registered by name with color stop lists, making them easy to define and reuse. Placeholders can also be registered with player-aware resolvers, making the API suitable for dynamic content such as ranks, prefixes, placeholders from other systems, or per-player metadata.

Testing and debugging

For direct testing, TextAPI includes a comprehensive in-game debug command that can:

• Render messages
• Dump components
• Dump tokens
• List placeholders, tags, and gradients
• Register and unregister runtime content
• Preview gradients
• Run a full feature test set in-game

That makes it easy to validate syntax, inspect output, and verify new runtime registrations without leaving the server.

Summary

TextAPI is what you get when you combine MiniMessage-style formatting and PlaceholderAPI-style dynamic content into a Kotlin-based Spigot library, then optimize it for fast parsing, clean extensibility, and developer-friendly runtime control.