# 💬 Chat

Flexible, fully customizable chat with channels, auto-moderation, mentions, join/quit messages, death messages, and a lot more!

## Commands & Permissions

* [Commands](/sunlight/general/commands.md#chat-module) link.
* [Permissions](/sunlight/general/permissions.md#chat-module) link.

## Features

* ✅ **Event Priority**. Change chat event priority to resolve possible compatibility issues.
* ✅ **Text Components** (aka JSON). Insert hover and click components at any part of chat messages.
* ✅ **Disable Reports**. Completely disable reports system from your server, including annoying verification nofitication.
* ✅ **Join & Quit Messages**. Display custom join and quit messages based on player ranks.
* ✅ **Death Messages**. Display custom death messages based on death cause, including mob/player and weapon names.
* ✅ **Announcer**. Broadcast custom messages with fixed intervals and based on player ranks.
* ✅ **Channels**. Create custom chat channels, such as local, global, trade, staff, etc.
* ✅ **Message Format**. Create custom message format based on player ranks.
* ✅ **Private Messages**. Send private messages to other players.
* ✅ **Mentions**. Ping a player or role in chat just like in discord.
* ✅ **Spy Mode**. See every chat messages in all channels, all executed commands, and private messages.
* ✅ **AntiCaps**. Force lower case a message if it contains too much upper case characters.
* ✅ **AntiSpam**. Prevent players from sending similar messages/commands in a short period of time.
* ✅ **Chat Rules**. Prevent, replace, or censor certain messages based on regex rules.
* ✅ **Item Display**. Display item in hand in chat.

## Configuration

### Text Components

When enabling `Use_Components` option, all chat messages will be sent as components instead of a plain text. 

While **it's recommended to keep that option** on `true` for the best experience, it **may** cause compatibility issues with other plugins that uses chat events. 

**If you're experiencing issues**, try to change the `Event_Priority` setting.

### Disable Reports

If you want to disable reports system introduced in 1.19, set `Disable_Reports` option on `true`.

Also you must have set `enforce-secure-profile` on `false` in **server.properties**.

{% hint style="warning" %}
You must have **ProtocolLib** or **PacketEvents** installed for this feature to work.
{% endhint %}

### Format

In chat config file, there is `Format` section. This is where you define format for the chat messages.

It consists of two sections: `Components` and `List`.

**Components** ones exist purely to help you organize elements of the chat format since they can be pretty long, especially when using **hover** and **click** tags.

**List** is simply a list of your custom formats based on player ranks.

One more important thing is `Format` channel option in the **channels.yml** config file. This is where you use `%format%` and `%message%` placeholders to insert your custom name & message format.

#### Manual

Consider the following example:

```yaml
  Components:
    msg:
      Text: '<hover:show_text:"<i><lgray>Message was sent at: <white>%localtime_time_HH:MM:ss%</white></lgray></i>"><gray>%message%</gray></hover>'
    player_info:
      Text: '<hover:show_text:"<gray>(Click to send private message)</gray>"><click:suggest_command:"/tell %player_name% ">%player_display_name%</click></hover>'
    rank_owner:
      Text: <hover:show_text:'<lgray>This player is the server <lyellow>Owner</lyellow></lgray>'>%player_prefix%</hover>
    rank_member:
      Text: <hover:show_text:'<lgray>Consider <lgreen>/donate</lgreen> to get special ranks</lgray>'><click:run_command:"/donate">%player_prefix%</click></hover>
```

There are 4 components: `msg`, `player_info`, `rank_owner` and `rank_member`. Every component has a placeholder that equals to their name: **%msg%** for `msg`, **%player\_info%** for `player_info` and so on.

**Note that** `msg` **component contains the** `%message%` **placeholder.**

Now we can insert them in actual chat format:

```yaml
  List:
    owner:
      Priority: 10
      Name: '%rank_owner%%player_info%: '
      Message: '%msg%'
      Ranks:
      - owner
      - admin
    default:
      Priority: 0
      Name: '%rank_member%%player_info%: '
      Message: '%msg%'
      Ranks:
      - '*'
```

As seen above, there are 2 different chat formats: the `owner` one for players with permission groups **owner** and **admin**, and the `default` one for players with **any (\*)** rank.

Note that `owner` format has **greater** **priority** than `default` one. When multiple formats are available for a player, the one with the greatest priority is used. So players with **owner** and **admin** ranks will always use the `owner` format and not the `default` one, because `default` one is also applicable to them (any rank).

{% hint style="danger" %}
When creating custom formats, make sure that `Message` option **always contains** the **%message%** placeholder, either from a component placeholder or directly in that field.
{% endhint %}

And now we can insert our custom format in the `Format` option of the **channels.yml** config file:

```yaml
local:
  Name: <cyan>Local</cyan>
  <...> # Some other settings here.
  Format: <gray>[%channel_name%]</gray> %format%%message%
```

There are 2 format placeholders available to use:

* **%format%** - Everything from the `Name` field.
* **%message%** - Everything from the `Message` field.

Don't be confused by two **%message%** placeholders. The one in channel's `Format` will insert text from the `Message` option, that **should contain** other **%message%** placeholder that will be replaced later with the original text sent by a player.

### DiscordSRV

There is built-in support for the **DiscordSRV** plugin for chat messages and channels. All you need is to add all chat channels to the DiscordSRV configuration:

```yaml
Channels: {"global": "1280498103090151530", "local": "1280498103090151531", "trade": "1280498103090151532"}
```

To allow users send chat messages from Discord -> Server while not logged in, they must have their game account linked with the discord account: `/discord link`. This is required to simulate chat message using offline player data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nightexpress.gitbook.io/sunlight/modules/chat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.