# 💬 Chat

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

## Commands & Permissions

* [Commands](https://nightexpress.gitbook.io/sunlight/general/commands#chat-module) link.
* [Permissions](https://nightexpress.gitbook.io/sunlight/general/permissions#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.