---
description: >-
  Lightweight chat manager for forge, with simple anti-spam and anti-advertising
  and anti-swearing protection, also with configuration.
---

# Project Essentials Chat

## How to Install

For start the modification, you **need installed Forge**, it is desirable that the version matches the supported versions. You can download Forge 1.14.4 from the [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.14.4.html) and Forge 1.15.2 from it [link](https://files.minecraftforge.net/maven/net/minecraftforge/forge/index_1.15.2.html). Move the downloaded mod to the `mods` folder (_installation example below_).

```
val MV = valueOf(your_minecraft_version)

.
├── assets
├── config
├── libraries
├── mods (that's how it should be)
│   ├── Project Essentials Core-MOD-1.MV.X-1.X.X.jar (mandatory)
│   ├── Project Essentials Cooldown-1.MV.X-1.X.X.jar (recommended)
│   ├── Project Essentials Permissions-1.MV.X-1.X.X.jar (recommended)
│   └── Project Essentials Chat-1.MV.X-1.X.X.jar
└── ...
```

### **Dependencies**

Also **do not forget** to install dependencies, only two types of dependencies: **mandatory** (_game will not start without a mod_) and **recommended** (_without a mod, game can start, but I recommend using it_).

#### **Download dependencies**: [Cooldown](https://github.com/ProjectEssentials/ProjectEssentials-Cooldown) · [Core](https://github.com/ProjectEssentials/ProjectEssentials-Core) · [Permissions](https://github.com/ProjectEssentials/ProjectEssentials-Permissions)

### Voila!

Now try to start the game, go to the `mods` tab, if this modification is displayed in the `mods` tab, then the mod has been **successfully installed.**

## **Commands**

| **Command**      | Description                                                                                                                                                                        | Permission                                                                | Op Level                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
| `/clear-chat`    | Clear chat for all players, if argument not received. From server console unable use command with argument. Argument type: `boolean`.                                              | `ess.chat.clear` _For clear chat for all players: `ess.chat.clear.other`_ | `2` _For clear chat for all players:_ `3` |
| `/mute`          | Mute player with reason if provided. If player already muted, then mute will be failed, but if you use `override` argument with value `true`, then player will be re-muted by you. | `ess.chat.mute`                                                           | `3`                                       |
| `/muted-players` | Send you muted players list in chat.                                                                                                                                               | `ess.chat.muted`                                                          | `3`                                       |
| `/unmute-all`    | Unmute all muted players.                                                                                                                                                          | `ess.chat.unmute.all`                                                     | `3`                                       |
| `/unmute`        | Unmute player.                                                                                                                                                                     | `ess.chat.unmute`                                                         | `3`                                       |

### **Usage examples**

| **Command**      | Examples                            |
| ---------------- | ----------------------------------- |
| `/clear-chat`    | `/... <only for you>`               |
| `/mute`          | `/... [player] <reason> <override>` |
| `/muted-players` | `/...`                              |
| `/unmute-all`    | `/...`                              |
| `/unmute`        | `/... [player]`                     |

### **Aliases**

| **Command**   | Aliases                                        |
| ------------- | ---------------------------------------------- |
| `/clear-chat` | `clear-chat`, `chat-clear`, `chatclear`, `cc`  |

## **Permissions**

| **Permission**                  | Op Level | Description                                    |
| ------------------------------- | -------- | ---------------------------------------------- |
| `ess.chat.blockedwords.bypass`  | `3`      | Allow to bypass chat blocked words.            |
| `ess.chat.blockedchars.bypass`  | `3`      | Allow to bypass chat blocked symbols.          |
| `ess.chat.messagelength.bypass` | `4`      | Allow to bypass chat max message length.       |
| `ess.chat`                      | `0`      | Allow to use chat.                             |
| `ess.chat.chatdelay.bypass`     | `3`      | Allow to bypass chat messaging delay.          |
| `ess.chat.advertising.bypass`   | `3`      | Allow to bypass chat advertising restrictions. |
| `ess.chat.color`                | `2`      | Allow to use colors and format codes in chat.  |
| `ess.chat.mention.all`          | `2`      | Allow to mention all in chat.                  |

## **Configuration**

### **Configuration location**

```
.minecraft/config/ProjectEssentials/chat.json
```

### Just in case

```
{
    "moderation": {
        "blockedWords": [
            "fuck",
            "shit"
        ],
        "blockedChars": [],
        "modifyBlockedWords": true,
        "blockedWordsMask": "**beep**",
        "maxMessageLength": 128,
        "messagingCooldownEnabled": true,
        "messagingCooldown": 5,
        "advertisingAllowed": false,
        "advertisingRegex": "((?:[a-z0-9]{2,}:\\/\\/)?(?:(?:[0-9]{1,3}\\.){3}[0-9]{1,3}|(?:[-\\w_]{1,}\\.[a-z]{2,}?))(?::[0-9]{1,5})?.*?(?=[!\"\u00A7 \n]|$))"
    },
    "messaging": {
        "messageGlobalPattern": "&8[&2GLOBAL&8] &a┃ &8[&6%player&8]&7: &f%message",
        "messageLocalPattern": "&8[&cLOCAL&8] &4┃ &8[&7%player&8]&7: &7§o%message",
        "messageCommonPattern": "&8[&7%player&8]&7: &f%message",
        "enableRangedChat": false,
        "localChatRange": 100,
        "chatEnabled": true
    },
    "mentions": {
        "mentionsEnabled": true,
        "mentionInActionBar": true,
        "mentionMessage": "&7you are mentioned by &l&7%player&7 player, in the chat.",
        "mentionAtFormat": "&c",
        "mentionNameFormat": "&b"
    },
    "events": {
        "joinMessageEnabled": true,
        "leftMessageEnabled": true,
        "advancementsEnabled": true
    }
}
```

### Configuration documentation

| Path                                  | Type           | Description                                                                                                           |
| ------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `moderation.blockedWords`             | `List<String>` | Contains blocked words.                                                                                               |
| `moderation.blockedChars`             | `List<String>` | Contains blocked chats.                                                                                               |
| `moderation.modifyBlockedWords`       | `Boolean`      | If value `true` then blocked words will be replaced on `blockedWordsMask`, if value `false` then message will't sent. |
| `moderation.blockedWordsMask`         | `String`       | Just replace swear word on it string. _(See: `modifyBlockedWords`)_                                                   |
| `moderation.maxMessageLength`         | `Int`          | Declare max message length, if message length excess this value then message will't sent.                             |
| `moderation.messagingCooldownEnabled` | `Boolean`      | If value `true`, then delay in chat will be enabled.                                                                  |
| `moderation.messagingCooldown`        | `Int`          | Declare cooldown delay. (See: `messagingCooldownEnabled`)                                                             |
| `moderation.advertisingAllowed`       | `Boolean`      | If value `false`, then messages with link will't sent.                                                                |
| `moderation.advertisingRegex`         | `String`       | Regular expression for detecting url's in message.                                                                    |
| `messaging.messageGlobalPattern`      | `String`       | Message pattern for global chat.                                                                                      |
| `messaging.messageLocalPattern`       | `String`       | Message pattern for local chat.                                                                                       |
| `messaging.messageCommonPattern`      | `String`       | Message pattern for common chat. Uses if ranged chat disabled. _(See: `enableRangedChat`)_                            |
| `messaging.enableRangedChat`          | `Boolean`      | If value `true` then ranged chat will be enabled.                                                                     |
| `messaging.localChatRange`            | `Int`          | Max range local chat in `block` (for all axis). Uses if ranged chat enabled.                                          |
| `messaging.chatEnabled`               | `Boolean`      | If `false` then nobody will send a message in chat.                                                                   |
| `mentions.mentionsEnabled`            | `Boolean`      | If `true` then players can use mentions in chat.                                                                      |
| `mentions.mentionInActionBar`         | `Boolean`      | If `true` then players will be notified about mention in action bar.                                                  |
| `mentions.mentionMessage`             | `String`       | Mention pattern message for action bar, uses if mentions in action bar enabled.                                       |
| `mentions.mentionAtFormat`            | `String`       | Pattern message for `@` symbol.                                                                                       |
| `mentions.mentionNameFormat`          | `String`       | Pattern message for after `@` symbol in message. (sorry for really bad English)                                       |
| `events.joinMessageEnabled`           | `Boolean`      | Suppress `player join` messages on server if value `false`.                                                           |
| `events.leftMessageEnabled`           | `Boolean`      | Suppress `player left` messages on server if value `false`.                                                           |
| `events.advancementsEnabled`          | `Boolean`      | Suppress `advancement get` messages on server if value `false`.                                                       |

## Muted players configuration

### **Configuration location**

```
.minecraft/config/ProjectEssentials/muted-players.json
```

### Just in case

```javascript
{
    "players": []
}
```

### Configuration documentation

| Name      | Type     | Description            |
| --------- | -------- | ---------------------- |
| `name`    | `String` | Player name who muted. |
| `mutedBy` | `String` | Muted by player name.  |
| `reason`  | `String` | Mute reason.           |

### Complete configuration example

```javascript
{
    "players": [
        {
            "name": "JopaBibBib",
            "mutedBy": "MairwunNx",
            "reason": "Mute command test."
        }
    ]
}
```

## If you have any questions or encounter a problem, be sure to open an [issue](https://github.com/ProjectEssentials/ProjectEssentials-Chat/issues/new/choose)
