https://github.com/thenolle/textapi
A high-performance text formatting and parsing system for Spigot 1.21+ servers
https://github.com/thenolle/textapi
api bungeecord library minecraft minecraft-plugin minimessage nolly paper plugin spigot
Last synced: 5 days ago
JSON representation
A high-performance text formatting and parsing system for Spigot 1.21+ servers
- Host: GitHub
- URL: https://github.com/thenolle/textapi
- Owner: thenolle
- License: wtfpl
- Created: 2026-06-17T10:28:31.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-06-17T10:50:23.000Z (about 1 month ago)
- Last Synced: 2026-06-17T12:20:14.796Z (about 1 month ago)
- Topics: api, bungeecord, library, minecraft, minecraft-plugin, minimessage, nolly, paper, plugin, spigot
- Language: Kotlin
- Homepage: https://mc.thenolle.com/plugins/textapi
- Size: 95.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
README
# TextAPI
TextAPI is a high-performance text formatting and parsing system for Spigot 1.21+ servers.
It provides a MiniMessage-like syntax with placeholders, colors, gradients, rainbow effects, hover/click events, runtime tag and gradient registration with full handler control, and a fully extensible API.
---
## Features
* Custom tag-based parser
* Placeholder system
* Runtime placeholder registration/unregistration
* Runtime tag registration with full style handler control
* Runtime gradient registration with custom color stops
* Click and hover events
* Insertion events
* Gradient rendering (2+ color stops)
* Rainbow rendering with phase support
* Pride gradient presets (14 built-in)
* Token-level parser API
* Legacy string output
* Component output
* Full debug command suite with live test runner
* TPS placeholder support
* Tab-complete enabled `/textapi` command
---
## Installation
### Build
```bash
mvn clean package
```
### Install
Place the generated jar inside:
```text
/plugins/TextAPI-1.0.6.jar
```
Restart the server.
---
## Using TextAPI
TextAPI can be consumed through:
* Local Maven install
* GitHub Packages
---
## Option 1 — Local Install
Build and install locally:
```bash
mvn clean install
```
Dependency:
```xml
com.nolly.mc
textapi
1.0.6
provided
```
---
## Option 2 — GitHub Packages
### Repository
```xml
github
https://maven.pkg.github.com/thenolle/textapi
```
### Dependency
```xml
com.nolly.mc
textapi
1.0.6
provided
```
### Authentication
`~/.m2/settings.xml`
```xml
github
github
central
https://repo.maven.apache.org/maven2
github
https://maven.pkg.github.com/thenolle/textapi
true
github
YOUR_GITHUB_USERNAME
YOUR_GITHUB_TOKEN
```
---
## Gradle (Groovy)
```gradle
repositories {
maven {
url = uri("https://maven.pkg.github.com/thenolle/textapi")
credentials {
username = System.getenv("GITHUB_ACTOR")
password = System.getenv("GITHUB_TOKEN")
}
}
}
dependencies {
compileOnly 'com.nolly.mc:textapi:1.0.6'
}
```
---
## Gradle (Kotlin)
```kts
repositories {
maven {
url = uri("https://maven.pkg.github.com/thenolle/textapi")
credentials {
username = System.getenv("GITHUB_ACTOR")
password = System.getenv("GITHUB_TOKEN")
}
}
}
dependencies {
compileOnly("com.nolly.mc:textapi:1.0.6")
}
```
---
## Configuration
```yml
command:
enabled: true
```
---
## Commands
### Main Command
```text
/textapi
```
### Subcommands
```text
/textapi parse
/textapi preview
/textapi components
/textapi tokens
/textapi test
/textapi examples
/textapi placeholders
/textapi tags
/textapi gradients
/textapi register placeholder
/textapi register tag <#hex|colorname> [bold] [italic] [underline] [strikethrough] [obfuscated]
/textapi register gradient <#hex1> <#hex2> [#hex3 ...]
/textapi unregister placeholder
/textapi unregister tag
/textapi unregister gradient
```
### Command Reference
| Subcommand | Description |
|---|---|
| `parse ` | Render and send a message |
| `preview ` | Show raw input, parsed string, and live render side by side |
| `components ` | Dump each component with color and decoration flags |
| `tokens ` | Dump the token list produced by the parser |
| `test` | Run a full in-game feature test covering every system (player only) |
| `examples` | Print quick usage examples |
| `placeholders` | List all registered placeholder keys |
| `tags` | List all registered custom tags |
| `gradients` | List all registered custom gradients with a live preview bar |
| `register placeholder` | Register a static placeholder at runtime |
| `register tag` | Register a custom tag with color and decoration flags |
| `register gradient` | Register a named gradient with 2+ hex color stops |
| `unregister placeholder` | Remove a registered placeholder |
| `unregister tag` | Remove a registered custom tag |
| `unregister gradient` | Remove a registered custom gradient |
---
## Syntax Guide
### Colors
```txt
Red
Gold
Green
<#ff5500>Hex Color#ff5500>
Color Alias
```
### Gradients
```txt
Two Stop
Three Stop
```
### Rainbow
```txt
Rainbow Text
Phase Shifted Rainbow
```
### Decorations
```txt
Bold
Italic
Underline
Strike
Magic
```
### Disable Decorations
```txt
Bold
Not Bold!bold>
Bold Again
```
### Hover Events
```txt
Hover Me
Danger!>Hover Me
```
### Click Events
```txt
Run Command
Suggest Command
Open URL
Copy
```
### Insertions
```txt
Shift-Click Me
```
### Combined Events
```txt
Go home!>Spawn
```
### Reset
```txt
Red Back to default
```
### Escaping
```txt
\ is not parsed as a tag
```
### Placeholders
```txt
Hello {player}
Online: {server_online}
TPS: {server_tps}
```
---
## Pride Gradients
```txt
Pride
Trans
Bisexual
Lesbian
Nonbinary
Pansexual
Asexual
Aromantic
Genderfluid
Agender
Intersex
Polyamorous
Demisexual
Genderqueer
```
---
## Built-in Placeholders
### Player
* `{player}`
* `{player_name}`
* `{player_uuid}`
* `{player_display}`
* `{player_world}`
* `{player_x}`
* `{player_y}`
* `{player_z}`
* `{player_ping}`
* `{player_gamemode}`
* `{player_health}`
* `{player_food}`
* `{player_level}`
* `{player_exp}`
* `{player_ip}`
* `{player_locale}`
* `{player_online}`
### Server
* `{server_name}`
* `{server_version}`
* `{server_motd}`
* `{server_online}`
* `{server_max}`
* `{server_tps}`
### Time
* `{time}`
* `{date}`
* `{datetime}`
* `{timestamp}`
### Misc
* `{newline}`
* `{prefix}`
---
## API Usage
### Parsing
```kt
val text = TextAPI.parse("Hello {player}", player)
```
### Components
```kt
val components = TextAPI.components("Hello", player)
```
### Sending Messages
```kt
TextAPI.send(player, "Hello")
```
### Tokens
```kt
val tokens = TextAPI.tokens("Hello")
```
---
## Placeholder Registration
### Register
```kt
TextAPI.registerPlaceholder("rank") { player ->
if (player?.isOp == true) "Admin" else "User"
}
```
Usage:
```txt
Hello {rank}
```
### Unregister
```kt
TextAPI.unregisterPlaceholder("rank")
```
### List (API)
```kt
val keys: Set = TextAPI.registeredPlaceholders()
```
---
## Tag Registration
Tags are registered with a `TagHandler` that receives the current `TextStyle` and optional tag arguments, and returns the modified `TextStyle` to apply.
### Register — simple color
```kt
TextAPI.registerTag("vip") { style, _ ->
style.copy(color = ChatColor.of("#ffd700"), bold = true)
}
```
### Register — color + decorations
```kt
TextAPI.registerTag("danger") { style, _ ->
style.copy(color = ChatColor.RED, bold = true, italic = true)
}
```
### Register — argument-aware
```kt
// Usage: text
TextAPI.registerTag("highlight") { style, args ->
val color = args?.let { TextTag.resolveColor(it) }
style.copy(color = color, underlined = true)
}
```
Usage:
```txt
VIP Player
Warning!
Highlighted
```
### Unregister
```kt
TextAPI.unregisterTag("vip")
```
### List (API)
```kt
val tags: Set = TextAPI.registeredTags()
```
### Register via command
```text
/textapi register tag vip #ffd700 bold
/textapi register tag danger red bold italic
```
> The command supports color + decoration flags only. For argument-aware tags, register from code.
---
## Gradient Registration
Named gradients behave exactly like built-in pride gradients and the `` tag — they expand per character with smooth color interpolation.
### Register
```kt
TextAPI.registerGradient("sunset", listOf("#ff6600", "#ff0099", "#aa00ff"))
TextAPI.registerGradient("ocean", listOf("#00c6ff", "#0072ff"))
TextAPI.registerGradient("fire", listOf("#ff0000", "#ff6600", "#ffff00"))
```
Usage:
```txt
Hello sunset world
Deep ocean text
```
### Unregister
```kt
TextAPI.unregisterGradient("sunset")
```
### List (API)
```kt
val gradients: Set = TextAPI.registeredGradient()
```
### Register via command
```text
/textapi register gradient sunset #ff6600 #ff0099 #aa00ff
/textapi register gradient ocean #00c6ff #0072ff
```
> Minimum 2 stops. The command also renders an immediate preview bar on registration.
---
## Performance Notes
* Single-pass tokenization
* Linear parsing complexity
* Linear gradient expansion
* Linear rainbow expansion
* Cached placeholder resolution per render context
* Rolling TPS history buffer
* No reflection
* Minimal allocations during rendering
---
## Permissions
```text
com.nolly.mc.textapi.command
```
Default:
```text
op
```
---
## Compatibility
* Spigot 1.21+
* Java 21+
* Kotlin 2.4+
* Bungee Chat Component API
---
## License
