1.4.0 - Adventure Support Rework

Author: CroaBeast

README.md

@@ -1,33 +1,45 @@
 # PrismaticAPI
 
-PrismaticAPI is a Bukkit/Paper text-formatting library focused on RGB colors, gradients, rainbow effects, MiniMessage compatibility, and legacy fallback.
+PrismaticAPI is a Bukkit/Paper text-formatting library for RGB colors, gradients, rainbows, MiniMessage-aware parsing and legacy-safe fallback.
 
-It is designed for plugin code that needs one formatting pipeline but multiple output forms:
+Version `1.4.0` reorganizes the public API around two facades backed by the same formatting engine:
 
-- Plain legacy strings for `Player#sendMessage(...)`
-- Adventure components when MiniMessage is available
-- Automatic downsampling for older client versions through VNC
+- `PrismaticAPI.legacy()` returns `Formatter<String>`
+- `PrismaticAPI.adventure()` returns `Formatter<Component>`
 
-## Highlights
+The old top-level methods such as `PrismaticAPI.colorize(...)` and `PrismaticAPI.applyGradient(...)` still exist and now delegate to `legacy()` for compatibility.
 
-- Multiple RGB syntaxes in one parser
-- Gradient and rainbow tags
-- Optional MiniMessage integration
-- `RichText` results when you want both component and legacy output
-- Version-aware fallback using VNC and ViaVersion-aware player checks
+## What Changed In 1.4.0
 
-## Formatting pipeline
+- Added `PrismaticAPI.legacy()` as the always-safe string formatter facade.
+- Added `PrismaticAPI.adventure()` as the optional Adventure formatter facade.
+- Added `PrismaticAPI.isAdventureAvailable()` to guard Adventure-only code paths.
+- Removed `RichText`.
+- Removed `colorizeText(...)`, `applyColorText(...)`, `applyGradientText(...)` and `applyRainbowText(...)`.
+- Kept the existing legacy top-level helpers as compatibility delegates to `legacy()`.
 
-`PrismaticAPI` processes text in this order:
+## Features
 
-1. MiniMessage, when Adventure MiniMessage is present at runtime
-2. Prismatic multi-color blocks such as gradients and rainbows
-3. Single RGB color syntaxes
-4. Legacy ampersand formatting such as `&a`, `&l`, and `&r`
+- One formatting engine for legacy strings and Adventure components.
+- Multiple single-color RGB syntaxes.
+- Gradient and rainbow tags.
+- Optional MiniMessage support at runtime.
+- Player-aware legacy fallback through VNC/ViaVersion support.
+- Safe startup on runtimes where Adventure is not present.
 
-This keeps MiniMessage and Prismatic tags from stepping on each other while still producing a final legacy string for Bukkit APIs.
+## Coordinates
+
+```text
+groupId:    me.croabeast
+artifactId: PrismaticAPI
+version:    1.4.0
+```
 
-## Supported formats
+Add the repository that hosts your published artifact, then depend on `me.croabeast:PrismaticAPI:1.4.0`.
+
+If your plugin calls `PrismaticAPI.adventure()`, keep the Adventure API on your compile classpath and ensure the required Adventure runtime classes are present when the plugin starts.
+
+## Supported Syntax
 
 ### Single RGB colors
 
@@ -51,86 +63,158 @@ This keeps MiniMessage and Prismatic tags from stepping on each other while stil
 - `<rainbow:1>Hello</rainbow>`
 - `<r:1>Hello</r>`
 
-## Quick usage
+### Legacy formatting
+
+- `&a`
+- `&l`
+- `&n`
+- `&r`
+
+### MiniMessage
+
+When Adventure MiniMessage is present at runtime, standard MiniMessage tags can be mixed with Prismatic syntax in the same string.
+
+## Formatting Pipeline
 
-### 1. Get a legacy string
+PrismaticAPI processes text in this order:
+
+1. MiniMessage, when the Adventure runtime is available.
+2. Prismatic multi-color blocks such as gradients and rainbows.
+3. Single RGB syntaxes.
+4. Legacy Bukkit formatting such as `&a`, `&l` and `&r`.
+
+This lets MiniMessage and Prismatic tags coexist without forcing Adventure to be present on every runtime.
+
+## API Overview
+
+### `PrismaticAPI.legacy()`
+
+`legacy()` returns `Formatter<String>`, which is always safe to use. It emits Bukkit/Bungee-compatible color-code strings.
 
 ```java
 String raw = "<g:ff0000>Hello</g:0000ff> &lworld";
-String formatted = PrismaticAPI.colorize(raw);
+String formatted = PrismaticAPI.legacy().colorize(player, raw);
 player.sendMessage(formatted);
 ```
 
-### 2. Format for a specific player
+### `PrismaticAPI.adventure()`
+
+`adventure()` returns `Formatter<Component>` and uses the same Prismatic parser to build Adventure components.
+
+Always guard this call when Adventure is optional:
 
 ```java
-String raw = "<rainbow:1>Chromatic</rainbow>";
-String formatted = PrismaticAPI.colorize(player, raw);
+if (PrismaticAPI.isAdventureAvailable()) {
+    Component component = PrismaticAPI.adventure().colorize(player, "<#ff8800>PrismaticAPI");
+}
 ```
 
-When ViaVersion is installed, PrismaticAPI uses the player's effective version to decide whether RGB can be preserved or should be downsampled.
+If Adventure is not available and you call `PrismaticAPI.adventure()` anyway, the method throws `IllegalStateException` with a controlled error message instead of crashing with `NoClassDefFoundError`.
+
+### Top-level compatibility methods
 
-### 3. Keep both component and legacy output
+The classic entry points still work:
 
 ```java
-RichText text = PrismaticAPI.colorizeText(player, "<#ff8800>PrismaticAPI");
+String formatted = PrismaticAPI.colorize(player, "<rainbow:1>Chromatic</rainbow>");
+String gradient = PrismaticAPI.applyGradient("Hello", Color.RED, Color.BLUE, false);
+```
 
-player.sendMessage(text.asLegacy());
-Component component = text.component();
+These methods delegate to the `legacy()` facade.
+
+## Important Behavior Notes
+
+### `colorize(String)` is conservative
+
+`PrismaticAPI.colorize(String)` and `PrismaticAPI.legacy().colorize(String)` call the formatter without a `Player` context.
+
+That means PrismaticAPI cannot know whether the receiver supports hex colors, so it falls back to legacy-safe output.
+
+If you want player-aware RGB preservation, call:
+
+```java
+String formatted = PrismaticAPI.legacy().colorize(player, raw);
 ```
 
-### 4. Build colors programmatically
+If you want exact RGB output without a player capability check, use the explicit color methods with `legacy = false`:
 
 ```java
-String solid = PrismaticAPI.applyColor(new Color(255, 136, 0), "Hello", false);
-String gradient = PrismaticAPI.applyGradient("Hello", Color.RED, Color.BLUE, false);
-String rainbow = PrismaticAPI.applyRainbow("Hello", 1.0f, false);
+String solid = PrismaticAPI.legacy().applyColor(new Color(255, 136, 0), "Hello", false);
+String gradient = PrismaticAPI.legacy().applyGradient("Hello", Color.RED, Color.BLUE, false);
+String rainbow = PrismaticAPI.legacy().applyRainbow("Hello", 1.0f, false);
 ```
 
-## Useful API entry points
+### Adventure is optional
 
-- `colorize(String)` returns a formatted legacy string
-- `colorize(Player, String)` returns a formatted legacy string tailored to that player
-- `colorizeText(...)` returns `RichText`
-- `applyColorText(...)`, `applyGradientText(...)`, and `applyRainbowText(...)` return `RichText`
-- `stripBukkit(...)`, `stripSpecial(...)`, `stripRGB(...)`, and `stripAll(...)` remove formatting in different levels
-- `getStartColor(...)` and `getEndColor(...)` inspect the formatted output
+PrismaticAPI can run perfectly fine without Adventure on the classpath as long as you stay on `legacy()` or the compatibility methods.
 
-## MiniMessage behavior
+`PrismaticAPI.adventure()` requires these classes at runtime:
 
-MiniMessage support is optional at runtime. If Adventure MiniMessage is available, PrismaticAPI will:
+- `net.kyori.adventure.text.Component`
+- `net.kyori.adventure.text.minimessage.MiniMessage`
+- `net.kyori.adventure.text.minimessage.tag.resolver.TagResolver`
+- `net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer`
 
-- deserialize standard MiniMessage tags
-- preserve Prismatic gradient/rainbow sections by masking and restoring them safely
-- downsample RGB output to named colors when a legacy target requires it
+### MiniMessage support is shared
 
-If MiniMessage is not present, the library still processes Prismatic formats and legacy codes normally.
+Both facades use the same parsing pipeline. If MiniMessage is available:
 
-## Requirements
+- standard MiniMessage tags are deserialized first
+- Prismatic gradients and rainbows are preserved safely during MiniMessage parsing
+- output is downsampled when the target must remain legacy-safe
 
-- Java 8+
-- Bukkit / Spigot / Paper API on the classpath
-- Adventure MiniMessage is optional
-- ViaVersion is optional
+If MiniMessage is not available, Prismatic-specific formatting and legacy color codes still work normally.
 
-## Coordinates
+## Migration From 1.3.x
 
-If you publish the artifact to your own repository or consume it from a local build, the coordinates are:
+### Before
 
-```text
-groupId:    me.croabeast
-artifactId: PrismaticAPI
-version:    1.3.0
+```java
+String legacy = PrismaticAPI.colorize(player, raw);
+RichText text = PrismaticAPI.colorizeText(player, raw);
+Component component = text.component();
+```
+
+### After
+
+```java
+String legacy = PrismaticAPI.colorize(player, raw);
+
+if (PrismaticAPI.isAdventureAvailable()) {
+    Component component = PrismaticAPI.adventure().colorize(player, raw);
+}
 ```
 
-## Local development
+Migration summary:
+
+- Replace `RichText` usage with `PrismaticAPI.adventure()`.
+- Replace `colorizeText(...)` with `PrismaticAPI.adventure().colorize(...)`.
+- Replace `applyColorText(...)`, `applyGradientText(...)` and `applyRainbowText(...)` with the corresponding `adventure()` methods.
+- Keep existing legacy string code unchanged if you only need Bukkit-style strings.
+
+## Useful Utility Methods
+
+Both facades expose the same helper methods:
+
+- `fromString(...)`
+- `stripBukkit(...)`
+- `stripSpecial(...)`
+- `stripRGB(...)`
+- `stripAll(...)`
+- `startsWithColor(...)`
+- `getStartColor(...)`
+- `getEndColor(...)`
+
+These methods are useful for inspecting or cleaning already-formatted strings without duplicating parsing logic in downstream plugins.
+
+## Local Development
 
 This project expects the `VNC` project to exist either:
 
 - next to this repository as `../VNC`
 - or inside this repository as `VNC`
 
-The build automatically compiles the sibling `VNC` jar before compiling PrismaticAPI.
+The build compiles the sibling `VNC` jar before compiling PrismaticAPI.
 
 ## Build
 

build.gradle.kts

@@ -6,7 +6,7 @@ plugins {
 }
 
 group = "me.croabeast"
-version = "1.3.0"
+version = "1.4.0"
 
 val vncProjectDir = listOf("../VNC", "VNC")
     .map(::file)