add number format api

Signed-off-by: David Mayr <davidliebtkekse@gmail.com>

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/BlankFormatImpl.java

@@ -0,0 +1,5 @@
+package io.papermc.paper.scoreboard.numbers;
+
+record BlankFormatImpl() implements NumberFormat {
+    public static final BlankFormatImpl INSTANCE = new BlankFormatImpl();
+}

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/FixedFormat.java

@@ -0,0 +1,20 @@
+package io.papermc.paper.scoreboard.numbers;
+
+import net.kyori.adventure.text.Component;
+import net.kyori.adventure.text.ComponentLike;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A scoreboard number format that replaces the score number with a chat component.
+ */
+@NullMarked
+public interface FixedFormat extends NumberFormat, ComponentLike {
+
+    /**
+     * The component shown instead of the number for a score
+     *
+     * @return the chat component
+     */
+    Component component();
+
+}

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/FixedFormatImpl.java

@@ -0,0 +1,13 @@
+package io.papermc.paper.scoreboard.numbers;
+
+import net.kyori.adventure.text.Component;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+record FixedFormatImpl(Component component) implements FixedFormat {
+
+    @Override
+    public Component asComponent() {
+        return this.component();
+    }
+}

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/NumberFormat.java

@@ -0,0 +1,61 @@
+package io.papermc.paper.scoreboard.numbers;
+
+import net.kyori.adventure.text.ComponentLike;
+import net.kyori.adventure.text.format.Style;
+import net.kyori.adventure.text.format.StyleBuilderApplicable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Describes a scoreboard number format that applies custom formatting to scoreboard scores.
+ */
+@NullMarked
+public interface NumberFormat {
+
+    /**
+     * Creates a blank scoreboard number format that removes the score number entirely.
+     *
+     * @return a blank number format
+     */
+    static NumberFormat blank() {
+        return BlankFormatImpl.INSTANCE;
+    }
+
+    /**
+     * Gets an un-styled number format.
+     *
+     * @return an un-styled number format
+     */
+    static StyledFormat noStyle() {
+        return StyledFormatImpl.NO_STYLE;
+    }
+
+    /**
+     * Creates a scoreboard number format that applies a custom formatting to the score number.
+     *
+     * @param style the style to apply on the number
+     * @return a styled number format
+     */
+    static StyledFormat styled(final Style style) {
+        return new StyledFormatImpl(style);
+    }
+
+    /**
+     * Creates a scoreboard number format that applies a custom formatting to the score number.
+     *
+     * @param styleBuilderApplicables the style to apply on the number
+     * @return a styled number format
+     */
+    static StyledFormat styled(final StyleBuilderApplicable... styleBuilderApplicables) {
+        return styled(Style.style(styleBuilderApplicables));
+    }
+
+    /**
+     * Creates a scoreboard number format that replaces the score number with a chat component.
+     *
+     * @param component the component to replace the number with
+     * @return a fixed number format
+     */
+    static FixedFormat fixed(final ComponentLike component) {
+        return new FixedFormatImpl(component.asComponent());
+    }
+}

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/StyledFormat.java

@@ -0,0 +1,20 @@
+package io.papermc.paper.scoreboard.numbers;
+
+import net.kyori.adventure.text.format.Style;
+import net.kyori.adventure.text.format.StyleBuilderApplicable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A scoreboard number format that applies a custom formatting to the score number.
+ */
+@NullMarked
+public interface StyledFormat extends NumberFormat, StyleBuilderApplicable {
+
+    /**
+     * The style that is being applied to the number in the score
+     *
+     * @return the style to apply
+     */
+    Style style();
+
+}

paper-api/src/main/java/io/papermc/paper/scoreboard/numbers/StyledFormatImpl.java

@@ -0,0 +1,14 @@
+package io.papermc.paper.scoreboard.numbers;
+
+import net.kyori.adventure.text.format.Style;
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+record StyledFormatImpl(Style style) implements StyledFormat {
+    static final StyledFormat NO_STYLE = new StyledFormatImpl(Style.empty());
+
+    @Override
+    public void styleApply(final Style.Builder style) {
+        style.merge(this.style);
+    }
+}