Skip to content

Commit 9d80c04

Browse files
CroaBeastCroaBeast
committed
1.3.0 - Full MiniMessage Support
1 parent fc68016 commit 9d80c04

13 files changed

Lines changed: 805 additions & 865 deletions

File tree

‎.github/workflows/publish.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ jobs:
1616
- name: Checkout repository
1717
uses: actions/checkout@v4
1818

19+
- name: Checkout VNC dependency
20+
uses: actions/checkout@v4
21+
with:
22+
repository: CroaBeast/VNC
23+
path: VNC
24+
1925
- name: Set up JDK 17
2026
uses: actions/setup-java@v4
2127
with:

‎README.md‎

Lines changed: 93 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,189 +1,139 @@
1-
<p align="center">
2-
<a href="https://discord.com/invite/gzzhVqgy3b" alt="Support Server">
3-
<img alt="Discord" src="https://img.shields.io/discord/826555143398752286?style=for-the-badge&logo=discord&label=Support%20Server&color=635aea">
4-
</a>
5-
<img alt="Java 8+" src="https://img.shields.io/badge/Java-8%2B-orange?style=for-the-badge&logo=openjdk">
6-
<img alt="License GPLv3" src="https://img.shields.io/badge/License-GPLv3-blue?style=for-the-badge">
7-
</p>
1+
# PrismaticAPI
82

9-
<h1 align="center">PrismaticAPI 🌈</h1>
3+
PrismaticAPI is a Bukkit/Paper text-formatting library focused on RGB colors, gradients, rainbow effects, MiniMessage compatibility, and legacy fallback.
104

11-
<p align="center">
12-
Advanced color toolkit for <b>Bukkit / Spigot / Paper</b> plugins.<br>
13-
Gradients, rainbow effects, single RGB formats, MiniMessage-safe parsing, and legacy fallback in one place.
14-
</p>
5+
It is designed for plugin code that needs one formatting pipeline but multiple output forms:
156

16-
---
7+
- Plain legacy strings for `Player#sendMessage(...)`
8+
- Adventure components when MiniMessage is available
9+
- Automatic downsampling for older client versions through VNC
1710

18-
## ✨ Why PrismaticAPI?
11+
## Highlights
1912

20-
PrismaticAPI started as a fork of [IridiumColorAPI](https://github.com/IridiumLLC/IridiumColorAPI), then evolved with a broader parser and a more complete formatting pipeline.
13+
- Multiple RGB syntaxes in one parser
14+
- Gradient and rainbow tags
15+
- Optional MiniMessage integration
16+
- `RichText` results when you want both component and legacy output
17+
- Version-aware fallback using VNC and ViaVersion-aware player checks
2118

22-
It helps you:
19+
## Formatting pipeline
2320

24-
- Paint text with smooth gradients and rainbow effects.
25-
- Parse multiple custom RGB syntaxes in a single pass.
26-
- Keep compatibility with modern RGB and legacy 16-color clients.
27-
- Convert output to plain strings or Adventure `TextComponent`.
28-
- Strip any formatting quickly when you need clean text.
21+
`PrismaticAPI` processes text in this order:
2922

30-
---
23+
1. MiniMessage, when Adventure MiniMessage is present at runtime
24+
2. Prismatic multi-color blocks such as gradients and rainbows
25+
3. Single RGB color syntaxes
26+
4. Legacy ampersand formatting such as `&a`, `&l`, and `&r`
3127

32-
## 🧠 Processing Pipeline
28+
This keeps MiniMessage and Prismatic tags from stepping on each other while still producing a final legacy string for Bukkit APIs.
3329

34-
`PrismaticAPI.colorize(...)` processes text in this exact order:
30+
## Supported formats
3531

36-
1. MiniMessage parsing (only if MiniMessage is available at runtime)
37-
2. Multi-color formats (`gradient` and `rainbow`)
38-
3. Single-color RGB formats
39-
4. Legacy ampersand translation (`&a`, `&l`, etc.)
32+
### Single RGB colors
4033

41-
This order keeps complex tags stable and avoids conflicts between format types.
34+
- `{#ff8800}`
35+
- `%#ff8800%`
36+
- `[#ff8800]`
37+
- `<#ff8800>`
38+
- `&xff8800`
39+
- `#ff8800`
40+
- `&#ff8800`
4241

43-
---
42+
### Gradients
4443

45-
## 🎨 Supported Color Formats
44+
- `<g:ff0000>Hello</g:0000ff>`
45+
- `<gradient:ff0000>Hello</gradient:0000ff>`
46+
- `<#ff0000>Hello</#0000ff>`
47+
- `<#ff0000:#00ff00:#0000ff>Hello</gradient>`
4648

47-
All custom Prismatic formats are case-insensitive and use 6-digit hex (`RRGGBB`).
49+
### Rainbows
4850

49-
### Gradient 🟣🔵🟢
51+
- `<rainbow:1>Hello</rainbow>`
52+
- `<r:1>Hello</r>`
5053

51-
| Format | Description |
52-
| --- | --- |
53-
| `<g:RRGGBB>text</g:RRGGBB>` | Short gradient tag |
54-
| `<gradient:RRGGBB>text</gradient:RRGGBB>` | Long gradient tag |
55-
| `<#RRGGBB>text</#RRGGBB>` | Hash-style gradient tag |
56-
| `<#RRGGBB:#RRGGBB[:#RRGGBB...]>text</g>` | Multi-stop gradient with short close tag |
57-
| `<#RRGGBB:#RRGGBB[:#RRGGBB...]>text</gradient>` | Multi-stop gradient with long close tag |
54+
## Quick usage
5855

59-
Gradient tags can include internal color stops:
56+
### 1. Get a legacy string
6057

61-
- `<g:ff0000>Hello <g:00ff00>World</g:0000ff>`
62-
- `<gradient:ff0000>Hello <gradient:00ff00>World</gradient:0000ff>`
63-
- `<#ff0000>Hello <#00ff00>World</#0000ff>`
64-
65-
### Rainbow 🌈
66-
67-
| Format | Description |
68-
| --- | --- |
69-
| `<rainbow:NUMBER>text</rainbow>` | Full rainbow tag |
70-
| `<r:NUMBER>text</r>` | Short rainbow tag |
71-
72-
`NUMBER` accepts 1 to 3 digits and is parsed as the saturation value.
73-
74-
### Single Color 🎯
58+
```java
59+
String raw = "<g:ff0000>Hello</g:0000ff> &lworld";
60+
String formatted = PrismaticAPI.colorize(raw);
61+
player.sendMessage(formatted);
62+
```
7563

76-
| Format | Example |
77-
| --- | --- |
78-
| `{#RRGGBB}` | `{#ff8800}Hello` |
79-
| `%#RRGGBB%` | `%#ff8800%Hello` |
80-
| `[#RRGGBB]` | `[#ff8800]Hello` |
81-
| `<#RRGGBB>` | `<#ff8800>Hello` |
82-
| `&xRRGGBB` | `&xff8800Hello` |
83-
| `#RRGGBB` | `#ff8800Hello` |
84-
| `&#RRGGBB` | `&#ff8800Hello` |
64+
### 2. Format for a specific player
8565

86-
---
66+
```java
67+
String raw = "<rainbow:1>Chromatic</rainbow>";
68+
String formatted = PrismaticAPI.colorize(player, raw);
69+
```
8770

88-
## 🚀 Quick Usage
71+
When ViaVersion is installed, PrismaticAPI uses the player's effective version to decide whether RGB can be preserved or should be downsampled.
8972

90-
### 1. Colorize a message for a player
73+
### 3. Keep both component and legacy output
9174

9275
```java
93-
Player player = Bukkit.getPlayer("a player reference");
94-
String raw = "<g:ff0000>Hello <gradient:00ff00>world</gradient:0000ff> &l!";
95-
String colored = PrismaticAPI.colorize(player, raw);
96-
player.sendMessage(colored);
76+
RichText text = PrismaticAPI.colorizeText(player, "<#ff8800>PrismaticAPI");
77+
78+
player.sendMessage(text.asLegacy());
79+
Component component = text.component();
9780
```
9881

99-
### 2. Get an Adventure component
82+
### 4. Build colors programmatically
10083

10184
```java
102-
TextComponent component = PrismaticAPI.colorizeAsComponent("<rainbow:1>PrismaticAPI</rainbow>");
85+
String solid = PrismaticAPI.applyColor(new Color(255, 136, 0), "Hello", false);
86+
String gradient = PrismaticAPI.applyGradient("Hello", Color.RED, Color.BLUE, false);
87+
String rainbow = PrismaticAPI.applyRainbow("Hello", 1.0f, false);
10388
```
10489

105-
### 3. Strip formatting
90+
## Useful API entry points
10691

107-
```java
108-
String raw = "&#00ff99Clean &lthis <rainbow:1>text</rainbow>";
109-
String plain = PrismaticAPI.stripAll(raw);
110-
```
92+
- `colorize(String)` returns a formatted legacy string
93+
- `colorize(Player, String)` returns a formatted legacy string tailored to that player
94+
- `colorizeText(...)` returns `RichText`
95+
- `applyColorText(...)`, `applyGradientText(...)`, and `applyRainbowText(...)` return `RichText`
96+
- `stripBukkit(...)`, `stripSpecial(...)`, `stripRGB(...)`, and `stripAll(...)` remove formatting in different levels
97+
- `getStartColor(...)` and `getEndColor(...)` inspect the formatted output
11198

112-
---
113-
114-
## 🧰 API Highlights
115-
116-
| Method | Purpose |
117-
| --- | --- |
118-
| `colorize(Player, String)` | Full pipeline with client legacy detection |
119-
| `colorize(String)` | Full pipeline without player context |
120-
| `colorizeAsComponent(...)` | Returns Adventure `TextComponent` |
121-
| `applyGradient(...)` | Programmatic gradient application |
122-
| `applyRainbow(...)` | Programmatic rainbow application |
123-
| `stripBukkit(...)` | Removes `&`/`§` legacy color markers |
124-
| `stripSpecial(...)` | Removes formatting markers (`k-o`, `r`, etc.) |
125-
| `stripRGB(...)` | Removes custom Prismatic RGB formats |
126-
| `stripAll(...)` | Removes all known formatting |
127-
128-
---
129-
130-
## 📦 Installation
131-
132-
Replace `${version}` with your target release.
133-
134-
### Maven
135-
136-
```xml
137-
<repositories>
138-
<repository>
139-
<id>croabeast-repo</id>
140-
<url>https://croabeast.github.io/repo/</url>
141-
</repository>
142-
</repositories>
143-
144-
<dependencies>
145-
<dependency>
146-
<groupId>me.croabeast</groupId>
147-
<artifactId>PrismaticAPI</artifactId>
148-
<version>${version}</version>
149-
<scope>compile</scope>
150-
</dependency>
151-
</dependencies>
152-
```
99+
## MiniMessage behavior
153100

154-
### Gradle
101+
MiniMessage support is optional at runtime. If Adventure MiniMessage is available, PrismaticAPI will:
155102

156-
```groovy
157-
repositories {
158-
maven {
159-
url "https://croabeast.github.io/repo/"
160-
}
161-
}
103+
- deserialize standard MiniMessage tags
104+
- preserve Prismatic gradient/rainbow sections by masking and restoring them safely
105+
- downsample RGB output to named colors when a legacy target requires it
162106

163-
dependencies {
164-
implementation "me.croabeast:PrismaticAPI:${version}"
165-
}
166-
```
107+
If MiniMessage is not present, the library still processes Prismatic formats and legacy codes normally.
108+
109+
## Requirements
167110

168-
---
111+
- Java 8+
112+
- Bukkit / Spigot / Paper API on the classpath
113+
- Adventure MiniMessage is optional
114+
- ViaVersion is optional
169115

170-
## ✅ Compatibility Notes
116+
## Coordinates
171117

172-
- Java target: `1.8`
173-
- API base: Spigot `1.16.5` (compile dependency)
174-
- Legacy fallback: enabled for old clients (and ViaVersion-aware when available)
175-
- MiniMessage integration: optional at runtime
118+
If you publish the artifact to your own repository or consume it from a local build, the coordinates are:
176119

177-
---
120+
```text
121+
groupId: me.croabeast
122+
artifactId: PrismaticAPI
123+
version: 1.3.0
124+
```
178125

179-
## 🙏 Credits
126+
## Local development
180127

181-
- Original inspiration: [IridiumColorAPI](https://github.com/IridiumLLC/IridiumColorAPI)
182-
- Maintained and expanded by **CroaBeast**
128+
This project expects the `VNC` project to exist either:
183129

184-
---
130+
- next to this repository as `../VNC`
131+
- or inside this repository as `VNC`
185132

186-
## 📄 License
133+
The build automatically compiles the sibling `VNC` jar before compiling PrismaticAPI.
187134

188-
This project is licensed under the **GNU GPL v3**.
135+
## Build
189136

137+
```bash
138+
./gradlew jar
139+
```

0 commit comments

Comments
 (0)