feat: allow custom colors in LegacyComponentSerializer

api/src/main/java/net/kyori/adventure/text/format/NamedTextColor.java

@@ -34,8 +34,6 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
-import static java.util.Objects.requireNonNull;
-
 /**
  * The named text colours in Minecraft: Java Edition.
  *
@@ -237,39 +235,7 @@ public final class NamedTextColor implements TextColor {
       return (NamedTextColor) any;
     }
 
-    requireNonNull(any, "color");
-
-    float matchedDistance = Float.MAX_VALUE;
-    NamedTextColor match = VALUES.get(0);
-    for (int i = 0, length = VALUES.size(); i < length; i++) {
-      final NamedTextColor potential = VALUES.get(i);
-      final float distance = distance(any.asHSV(), potential.asHSV());
-      if (distance < matchedDistance) {
-        match = potential;
-        matchedDistance = distance;
-      }
-      if (distance == 0) {
-        break; // same colour! whoo!
-      }
-    }
-    return match;
-  }
-
-  /**
-   * Returns a distance metric to the other colour.
-   *
-   * <p>This value is unitless and should only be used to compare with other text colours.</p>
-   *
-   * @param self the base colour
-   * @param other colour to compare to
-   * @return distance metric
-   */
-  private static float distance(final @NotNull HSVLike self, final @NotNull HSVLike other) {
-    // weight hue more heavily than saturation and brightness. kind of magic numbers, but is fine for our use case of downsampling to a set of colors
-    final float hueDistance = 3 * Math.min(Math.abs(self.h() - other.h()), 1f - Math.abs(self.h() - other.h()));
-    final float saturationDiff = self.s() - other.s();
-    final float valueDiff = self.v() - other.v();
-    return hueDistance * hueDistance + saturationDiff * saturationDiff + valueDiff * valueDiff;
+    return TextColor.nearestColorTo(VALUES, any);
   }
 
   private final String name;

api/src/main/java/net/kyori/adventure/text/format/TextColor.java

@@ -23,6 +23,7 @@
  */
 package net.kyori.adventure.text.format;
 
+import java.util.List;
 import java.util.stream.Stream;
 import net.kyori.adventure.util.HSVLike;
 import net.kyori.adventure.util.RGBLike;
@@ -32,6 +33,8 @@
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.Range;
 
+import static java.util.Objects.requireNonNull;
+
 /**
  * A color which may be applied to a {@link Style}.
  *
@@ -261,6 +264,34 @@ public interface TextColor extends Comparable<TextColor>, Examinable, RGBLike, S
     );
   }
 
+  /**
+   * Find the colour nearest to the provided colour.
+   *
+   * @param values the colours for matching
+   * @param any colour to match
+   * @param <C> the color type
+   * @return nearest named colour. will always return a value
+   * @since 4.14.0
+   */
+  static <C extends TextColor> @NotNull C nearestColorTo(final @NotNull List<C> values, final @NotNull TextColor any) {
+    requireNonNull(any, "color");
+
+    float matchedDistance = Float.MAX_VALUE;
+    C match = values.get(0);
+    for (int i = 0, length = values.size(); i < length; i++) {
+      final C potential = values.get(i);
+      final float distance = TextColorImpl.distance(any.asHSV(), potential.asHSV());
+      if (distance < matchedDistance) {
+        match = potential;
+        matchedDistance = distance;
+      }
+      if (distance == 0) {
+        break; // same colour! whoo!
+      }
+    }
+    return match;
+  }
+
   @Override
   default void styleApply(final Style.@NotNull Builder style) {
     style.color(this);

api/src/main/java/net/kyori/adventure/text/format/TextColorImpl.java

@@ -23,7 +23,9 @@
  */
 package net.kyori.adventure.text.format;
 
+import net.kyori.adventure.util.HSVLike;
 import org.jetbrains.annotations.Debug;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 @Debug.Renderer(text = "asHexString()")
@@ -56,4 +58,21 @@ public int hashCode() {
   public String toString() {
     return this.asHexString();
   }
+
+  /**
+   * Returns a distance metric to the other colour.
+   *
+   * <p>This value is unitless and should only be used to compare with other text colours.</p>
+   *
+   * @param self the base colour
+   * @param other colour to compare to
+   * @return distance metric
+   */
+  static float distance(final @NotNull HSVLike self, final @NotNull HSVLike other) {
+    // weight hue more heavily than saturation and brightness. kind of magic numbers, but is fine for our use case of downsampling to a set of colors
+    final float hueDistance = 3 * Math.min(Math.abs(self.h() - other.h()), 1f - Math.abs(self.h() - other.h()));
+    final float saturationDiff = self.s() - other.s();
+    final float valueDiff = self.v() - other.v();
+    return hueDistance * hueDistance + saturationDiff * saturationDiff + valueDiff * valueDiff;
+  }
 }

text-serializer-legacy/src/main/java/net/kyori/adventure/text/serializer/legacy/CharacterAndFormat.java

@@ -0,0 +1,225 @@
+/*
+ * This file is part of adventure, licensed under the MIT License.
+ *
+ * Copyright (c) 2017-2023 KyoriPowered
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package net.kyori.adventure.text.serializer.legacy;
+
+import java.util.List;
+import java.util.stream.Stream;
+import net.kyori.adventure.text.format.NamedTextColor;
+import net.kyori.adventure.text.format.TextDecoration;
+import net.kyori.adventure.text.format.TextFormat;
+import net.kyori.examination.Examinable;
+import net.kyori.examination.ExaminableProperty;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Unmodifiable;
+
+/**
+ * A combination of a {@code character} and a {@link TextFormat}.
+ *
+ * @since 4.14.0
+ */
+@ApiStatus.NonExtendable
+public interface CharacterAndFormat extends Examinable {
+  /**
+   * Character and format pair representing {@link NamedTextColor#BLACK}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat BLACK = characterAndFormat('0', NamedTextColor.BLACK);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_BLUE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_BLUE = characterAndFormat('1', NamedTextColor.DARK_BLUE);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_GREEN}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_GREEN = characterAndFormat('2', NamedTextColor.DARK_GREEN);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_AQUA}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_AQUA = characterAndFormat('3', NamedTextColor.DARK_AQUA);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_RED}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_RED = characterAndFormat('4', NamedTextColor.DARK_RED);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_PURPLE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_PURPLE = characterAndFormat('5', NamedTextColor.DARK_PURPLE);
+  /**
+   * Character and format pair representing {@link NamedTextColor#GOLD}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat GOLD = characterAndFormat('6', NamedTextColor.GOLD);
+  /**
+   * Character and format pair representing {@link NamedTextColor#GRAY}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat GRAY = characterAndFormat('7', NamedTextColor.GRAY);
+  /**
+   * Character and format pair representing {@link NamedTextColor#DARK_GRAY}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat DARK_GRAY = characterAndFormat('8', NamedTextColor.DARK_GRAY);
+  /**
+   * Character and format pair representing {@link NamedTextColor#BLUE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat BLUE = characterAndFormat('9', NamedTextColor.BLUE);
+  /**
+   * Character and format pair representing {@link NamedTextColor#GREEN}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat GREEN = characterAndFormat('a', NamedTextColor.GREEN);
+  /**
+   * Character and format pair representing {@link NamedTextColor#AQUA}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat AQUA = characterAndFormat('b', NamedTextColor.AQUA);
+  /**
+   * Character and format pair representing {@link NamedTextColor#RED}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat RED = characterAndFormat('c', NamedTextColor.RED);
+  /**
+   * Character and format pair representing {@link NamedTextColor#LIGHT_PURPLE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat LIGHT_PURPLE = characterAndFormat('d', NamedTextColor.LIGHT_PURPLE);
+  /**
+   * Character and format pair representing {@link NamedTextColor#YELLOW}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat YELLOW = characterAndFormat('e', NamedTextColor.YELLOW);
+  /**
+   * Character and format pair representing {@link NamedTextColor#WHITE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat WHITE = characterAndFormat('f', NamedTextColor.WHITE);
+
+  /**
+   * Character and format pair representing {@link TextDecoration#OBFUSCATED}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat OBFUSCATED = characterAndFormat('k', TextDecoration.OBFUSCATED);
+  /**
+   * Character and format pair representing {@link TextDecoration#BOLD}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat BOLD = characterAndFormat('l', TextDecoration.BOLD);
+  /**
+   * Character and format pair representing {@link TextDecoration#STRIKETHROUGH}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat STRIKETHROUGH = characterAndFormat('m', TextDecoration.STRIKETHROUGH);
+  /**
+   * Character and format pair representing {@link TextDecoration#UNDERLINED}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat UNDERLINED = characterAndFormat('n', TextDecoration.UNDERLINED);
+  /**
+   * Character and format pair representing {@link TextDecoration#ITALIC}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat ITALIC = characterAndFormat('o', TextDecoration.ITALIC);
+
+  /**
+   * Character and format pair representing {@link Reset#INSTANCE}.
+   *
+   * @since 4.14.0
+   */
+  CharacterAndFormat RESET = characterAndFormat('r', Reset.INSTANCE);
+
+  /**
+   * Creates a new combination of a {@code character} and a {@link TextFormat}.
+   *
+   * @param character the character
+   * @param format the format
+   * @return a new character and format pair.
+   * @since 4.14.0
+   */
+  static @NotNull CharacterAndFormat characterAndFormat(final char character, final @NotNull TextFormat format) {
+    return new CharacterAndFormatImpl(character, format);
+  }
+
+  /**
+   * Gets an unmodifiable list of character and format pairs containing all default vanilla formats.
+   *
+   * @return am unmodifiable list of character and format pairs containing all default vanilla formats
+   * @since 4.14.0
+   */
+  @Unmodifiable
+  static @NotNull List<CharacterAndFormat> defaults() {
+    return CharacterAndFormatImpl.Defaults.DEFAULTS;
+  }
+
+  /**
+   * Gets the character.
+   *
+   * @return the character
+   * @since 4.14.0
+   */
+  char character();
+
+  /**
+   * Gets the format.
+   *
+   * @return the format
+   * @since 4.14.0
+   */
+  @NotNull TextFormat format();
+
+  @Override
+  default @NotNull Stream<? extends ExaminableProperty> examinableProperties() {
+    return Stream.of(
+      ExaminableProperty.of("character", this.character()),
+      ExaminableProperty.of("format", this.format())
+    );
+  }
+}