Adventure

Co-authored-by: zml <zml@stellardrift.ca>
Co-authored-by: Jake Potrebic <jake.m.potrebic@gmail.com>
Co-authored-by: Yannick Lamprecht <yannicklamprecht@live.de>

paper-api/src/main/java/io/papermc/paper/chat/ChatRenderer.java

@@ -0,0 +1,70 @@
+package io.papermc.paper.chat;
+
+import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.text.Component;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A chat renderer is responsible for rendering chat messages sent by {@link Player}s to the server.
+ */
+@NullMarked
+@FunctionalInterface
+public interface ChatRenderer {
+
+    /**
+     * Renders a chat message. This will be called once for each receiving {@link Audience}.
+     *
+     * @param source the message source
+     * @param sourceDisplayName the display name of the source player
+     * @param message the chat message
+     * @param viewer the receiving {@link Audience}
+     * @return a rendered chat message
+     */
+    @ApiStatus.OverrideOnly
+    Component render(Player source, Component sourceDisplayName, Component message, Audience viewer);
+
+    /**
+     * Create a new instance of the default {@link ChatRenderer}.
+     *
+     * @return a new {@link ChatRenderer}
+     */
+    static ChatRenderer defaultRenderer() {
+        return new ViewerUnawareImpl.Default((source, sourceDisplayName, message) -> Component.translatable("chat.type.text", sourceDisplayName, message));
+    }
+
+    @ApiStatus.Internal
+    sealed interface Default extends ChatRenderer, ViewerUnaware permits ViewerUnawareImpl.Default {
+    }
+
+    /**
+     * Creates a new viewer-unaware {@link ChatRenderer}, which will render the chat message a single time,
+     * displaying the same rendered message to every viewing {@link Audience}.
+     *
+     * @param renderer the viewer unaware renderer
+     * @return a new {@link ChatRenderer}
+     */
+    static ChatRenderer viewerUnaware(final ViewerUnaware renderer) {
+        return new ViewerUnawareImpl(renderer);
+    }
+
+    /**
+     * Similar to {@link ChatRenderer}, but without knowledge of the message viewer.
+     *
+     * @see ChatRenderer#viewerUnaware(ViewerUnaware)
+     */
+    interface ViewerUnaware {
+
+        /**
+         * Renders a chat message.
+         *
+         * @param source the message source
+         * @param sourceDisplayName the display name of the source player
+         * @param message the chat message
+         * @return a rendered chat message
+         */
+        @ApiStatus.OverrideOnly
+        Component render(Player source, Component sourceDisplayName, Component message);
+    }
+}

paper-api/src/main/java/io/papermc/paper/chat/ViewerUnawareImpl.java

@@ -0,0 +1,38 @@
+package io.papermc.paper.chat;
+
+import net.kyori.adventure.audience.Audience;
+import net.kyori.adventure.text.Component;
+import org.bukkit.entity.Player;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@ApiStatus.Internal
+@NullMarked
+sealed class ViewerUnawareImpl implements ChatRenderer, ChatRenderer.ViewerUnaware permits ViewerUnawareImpl.Default {
+    private final ViewerUnaware unaware;
+    private @Nullable Component message;
+
+    ViewerUnawareImpl(final ViewerUnaware unaware) {
+        this.unaware = unaware;
+    }
+
+    @Override
+    public Component render(final Player source, final Component sourceDisplayName, final Component message, final Audience viewer) {
+        return this.render(source, sourceDisplayName, message);
+    }
+
+    @Override
+    public Component render(final Player source, final Component sourceDisplayName, final Component message) {
+        if (this.message == null) {
+            this.message = this.unaware.render(source, sourceDisplayName, message);
+        }
+        return this.message;
+    }
+
+    static final class Default extends ViewerUnawareImpl implements ChatRenderer.Default {
+        Default(final ViewerUnaware unaware) {
+            super(unaware);
+        }
+    }
+}