From e56f3fb4164718ef8f40878007440fda1a4c6374 Mon Sep 17 00:00:00 2001
From: Ollie <69084614+olijeffers0n@users.noreply.github.com>
Date: Wed, 24 Jan 2024 23:28:37 +0000
Subject: [PATCH] Async Chat Event Docs

---
 config/sidebar.paper.ts                       |  1 +
 .../dev/api/event-api/player-chat-event.md    | 50 +++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/paper/dev/api/event-api/player-chat-event.md

diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts
index 888a851ba..f22966559 100644
--- a/config/sidebar.paper.ts
+++ b/config/sidebar.paper.ts
@@ -122,6 +122,7 @@ const paper: SidebarsConfig = {
                 "dev/api/event-api/event-listeners",
                 "dev/api/event-api/custom-events",
                 "dev/api/event-api/handler-lists",
+                "dev/api/event-api/player-chat-event",
               ],
             },
             {
diff --git a/docs/paper/dev/api/event-api/player-chat-event.md b/docs/paper/dev/api/event-api/player-chat-event.md
new file mode 100644
index 000000000..987676238
--- /dev/null
+++ b/docs/paper/dev/api/event-api/player-chat-event.md
@@ -0,0 +1,50 @@
+---
+slug: /dev/player-chat-event
+description: A guide to explain Paper's Chat Event.
+---
+
+# Player Chat Event
+
+The `AsyncChatEvent` is fired when a player sends a chat message. This event is fired asynchronously and allows you to
+make modifications to the message before it is sent to other players.
+
+## `AsyncChatEvent`
+
+:::danger[Thread Safety]
+
+This event is fired asynchronously so all logic must be thread-safe.
+
+:::
+
+### `AsyncChatEvent#message()`
+
+This method returns the message that the player sent. The message can be modified by calling `AsyncChatEvent#message(Component)`.
+This method returns the component that the player sent, but it may have been modified by other plugins. If you want to
+get the original message that the player sent, you can call `AsyncChatEvent#originalMessage()`.
+
+### `AsyncChatEvent#signedMessage()`
+
+This method returns the `SignedMessage` that the player has sent and contains information like the timestamp, signature 
+and whether it can be deleted. To delete a message, you can call `Server#deleteMessage(SignedMessage)`. This will replace
+the message in the chat with a message saying that the message has been deleted.
+
+### `AsyncChatEvent#renderer()`
+
+This method returns the `ChatRenderer` that will be used to render the message. You can replace this renderer by calling
+`AsyncChatEvent#renderer(ChatRenderer)`. The renderer is used to render the message into a `Component` that can be sent
+to the player. Here is one example of how you can use this method to replace the renderer:
+
+```java
+event.renderer((source, sourceName, message, viewer) ->
+  Component.translatable("chat.type.text.narrate", sourceName, message)
+));
+```
+This example will replace the renderer with one that will render the message as a narrated message. For example, if the
+player sent the message `PaperMC`, the message would be rendered as `PlayerName says PaperMC` instead of 
+`<PlayerName> PaperMC`. If you do not require the viewer, you can use a `viewerUnaware` renderer instead:
+
+```java
+event.renderer(ChatRenderer.viewerUnaware((source, sourceName, message) ->
+  //...
+));
+```