> For the complete documentation index, see [llms.txt](https://pepper-scripts.gitbook.io/pepper-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pepper-scripts.gitbook.io/pepper-scripts-docs/docs/de/tools-ui/pepper-chat.md).

# Pepper Chat

Kostenloser Chat mit Reitern für Alle, OOC und Team – mit Werkzeugen, die dein Team direkt im Chatfenster bedient.

{% hint style="success" %}
✅ **Pepper Chat holen:** <https://shop.pepperscripts.de/package/7729477>
{% endhint %}

{% hint style="info" %}
🧪 **Getestet auf unserem Dev-Server:** Wir testen alle Skripte selbstverständlich permanent auf unserem eigenen Dev-Server „Pepper Scripts“.
{% endhint %}

Kostenlos und Open Source: <https://github.com/PepperScripts/pepper\\_chat>

## Überblick

Pepper Chat ersetzt den Standard-Chat. Deine Spieler wechseln zwischen den Reitern Alle, OOC und Team, und dein Team schaltet per Rechtsklick stumm, löscht Nachrichten und sendet Ankündigungen direkt im Chatfenster – ohne Befehle zu tippen. Spam-Schutz und Wortfilter prüfen jede Nachricht auf dem Server, Stummschaltungen liegen in der Datenbank und überstehen den Neustart, alles landet im Tagesprotokoll.

### Features

* Reiter: **Alle**, **OOC** und **Team** (den Team-Reiter sehen nur Teamler)
* Team-Werkzeuge direkt im Chatfenster, ohne Befehle:
  * Rechtsklick auf eine Nachricht: Spieler stummschalten (10 min, 1 Std., 24 Std., dauerhaft) oder Nachricht löschen
  * Knöpfe: Ankündigung an alle, Langsam-Modus, Liste der Stummgeschalteten, Chat leeren
* Ankündigungen erscheinen im Chat und als Banner oben am Bildschirm
* Team-Abzeichen vor dem Namen (Admin, Mod), Farben und Texte in der Config
* Spam-Schutz: Wartezeit, Wiederholungsprüfung und Flood-Sperre; Wortfilter, der zensiert oder blockiert
* Stummschaltungen liegen in der Datenbank und überstehen einen Neustart
* Protokoll in eine Tagesdatei und auf Wunsch an einen Discord-Webhook
* Befehlsvorschläge beim Tippen, Eingabeverlauf (Pfeiltasten), Zeichenzähler
* Ersetzt den Standard-Chat (`provide 'chat'`): `chat:addMessage`, `chat:addSuggestion`, Vorlagen und `exports.chat` laufen weiter
* Deutsch und Englisch dabei

## Voraussetzungen

| Abhängigkeit                                    | Pflicht/optional | Wofür                                                                                   | Link                                                             |
| ----------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| FiveM-Server (`fx_version 'cerulean'`, Lua 5.4) | Pflicht          | Läuft die Ressource                                                                     | <https://docs.fivem.net/docs/server-manual/setting-up-a-server/> |
| oxmysql                                         | Pflicht          | Tabelle `pepper_chat_mutes` für Stummschaltungen                                        | <https://github.com/overextended/oxmysql>                        |
| MySQL/MariaDB-Datenbank                         | Pflicht          | Wird über oxmysql angesprochen, Tabelle legt das Script selbst an                       | –                                                                |
| ESX Legacy, QBCore oder Qbox                    | optional         | Team-Rollen aus der Gruppe (ESX) bzw. den Rechten (QBCore/Qbox); ohne Framework per ACE | –                                                                |
| OneSync                                         | nicht nötig      | –                                                                                       | –                                                                |

## Installation

1. Ordner `pepper_chat` in deinen `resources`-Ordner legen. **Den Ordnernamen nicht umbenennen** – Exports und NUI-Aufrufe hängen am Namen `pepper_chat`.
2. In der `server.cfg` die Zeile `ensure chat` (Standard-Chat) **entfernen** und Pepper Chat nach `oxmysql` starten:

   ```
   ensure oxmysql
   # ensure chat   ← entfernen
   ensure pepper_chat
   ```
3. Server neu starten. Die Tabelle `pepper_chat_mutes` wird beim ersten Start automatisch angelegt. Willst du sie von Hand anlegen, importiere `install/pepper_chat.sql` in deine Datenbank.
4. `Config.Locale = 'de'` und deine Team-Gruppen (`Config.Staff`) in der `config.lua` einstellen.

### Erster Test

1. Im Spiel **T** drücken – das Chatfenster mit den Reitern öffnet sich. Eine Nachricht schreiben und mit **Enter** senden.
2. **Tab** wechselt den Reiter (ohne offene Vorschläge), `/ooc Hallo` schreibt in den OOC-Kanal.
3. Als Teamler: Rechtsklick auf eine Nachricht – das Menü zum Stummschalten und Löschen erscheint, dazu der Reiter **Team** und die Werkzeug-Knöpfe.
4. In der Server-Konsole `say Test` eingeben – die Zeile erscheint bei allen im Chat.
5. Prüfe, ob im Ordner `logs/` eine Datei `chat-JJJJ-MM-TT.log` entstanden ist.

## Konfiguration

| Datei                                | Steuert                                                                                                                        |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `config.lua`                         | Sprache, Taste, Kanäle, Anzeige, Aussehen, Banner, Team-Rollen, Befehlsnamen, angezeigter Name (wird an die Spieler geschickt) |
| `config_server.lua`                  | Protokoll und Webhook, Spam-Schutz, Wortfilter (nur auf dem Server, nie an Spieler)                                            |
| `locales/de.json`, `locales/en.json` | Alle Texte im Chat und in der Oberfläche                                                                                       |
| `html/style.css`                     | Aussehen des Chatfensters                                                                                                      |

### Grundlagen und Anzeige

| Option                     | Standard                                     | Beschreibung                                                                      |
| -------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------- |
| `Config.Locale`            | `'en'`                                       | Sprache `'de'` oder `'en'`                                                        |
| `Config.OpenKey`           | `'t'`                                        | Taste zum Öffnen; Spieler ändern sie unter Einstellungen → Tastenbelegung → FiveM |
| `Config.Channels`          | `{ global = true, ooc = true, team = true }` | Kanäle an/aus                                                                     |
| `Config.DefaultChannel`    | `'global'`                                   | In welchen Kanal der Reiter „Alle“ schreibt                                       |
| `Config.ShowIds`           | `true`                                       | Server-ID hinter dem Namen                                                        |
| `Config.ShowTime`          | `true`                                       | Uhrzeit vor der Nachricht                                                         |
| `Config.MaxLength`         | `200`                                        | Höchstlänge einer Nachricht                                                       |
| `Config.MaxMessages`       | `100`                                        | So viele Nachrichten bleiben im Verlauf                                           |
| `Config.FadeAfter`         | `12`                                         | Sekunden bis zum Ausblenden, `0` = nie                                            |
| `Config.JoinLeaveMessages` | `false`                                      | „ist beigetreten / hat den Server verlassen“ im Chat                              |

### Aussehen und Banner

```lua
Config.UI = { left = 1.2, top = 4.0, width = 31, height = 17, scale = 1.0, accent = '#E5484D' }
Config.AnnouncementBanner = { enabled = true, duration = 8 }
```

| Option                       | Standard                       | Beschreibung                                              |
| ---------------------------- | ------------------------------ | --------------------------------------------------------- |
| `Config.UI.left` / `top`     | `1.2` / `4.0`                  | Position in Prozent des Bildschirms                       |
| `Config.UI.width` / `height` | `31` / `17`                    | Größe in Textzeilen-Einheiten                             |
| `Config.UI.scale`            | `1.0`                          | Gesamtgröße, `1.0` = normal                               |
| `Config.UI.accent`           | `'#E5484D'`                    | Akzentfarbe (aktiver Reiter, Knöpfe)                      |
| `Config.AnnouncementBanner`  | `enabled = true, duration = 8` | Ankündigung zusätzlich als Banner oben, Dauer in Sekunden |

### Team-Rollen

```lua
Config.Staff = {
    { key = 'admin', label = 'Admin', color = '#E5484D', groups = { 'superadmin', 'admin', 'god' } },
    { key = 'mod', label = 'Mod', color = '#4C9AFF', groups = { 'mod', 'moderator', 'support' } },
}
```

Die erste passende Rolle gewinnt (oben = höher). Geprüft werden das ACE-Recht `pepperchat.<key>`, die ESX-Gruppe (`getGroup`), QBCore-Rechte (`HasPermission`) und ACE-Gruppen gleichen Namens (Qbox). `label` und `color` bilden das Abzeichen vor dem Namen.

| Option                 | Standard                   | Beschreibung                                                                     |
| ---------------------- | -------------------------- | -------------------------------------------------------------------------------- |
| `Config.SlowModeSteps` | `{ 0, 5, 10, 30, 60 }`     | Auswahl im Team-Menü für den Langsam-Modus (Sekunden)                            |
| `Config.MuteSteps`     | `{ 10, 60, 1440, 0 }`      | Auswahl im Rechtsklick-Menü (Minuten, `0` = dauerhaft)                           |
| `Config.Commands`      | siehe „Befehle und Rechte“ | Befehlsnamen ohne Schrägstrich                                                   |
| `Config.GetName`       | `GetPlayerName(source)`    | Welcher Name im Chat steht – hier dein Framework für den Charakternamen abfragen |

### Protokoll, Spam-Schutz und Wortfilter (`config_server.lua`)

| Option                                         | Standard   | Beschreibung                                                            |
| ---------------------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `ServerConfig.Log.file`                        | `true`     | Tagesdatei `logs/chat-JJJJ-MM-TT.log` im Ressourcenordner               |
| `ServerConfig.Log.webhook`                     | `''`       | Discord-Webhook-URL, `''` = aus (Erwähnungen mit `@` werden entschärft) |
| `ServerConfig.Spam.cooldown`                   | `1000`     | Millisekunden zwischen zwei Nachrichten                                 |
| `ServerConfig.Spam.duplicateWindow`            | `10`       | Gleiche Nachricht erst nach so vielen Sekunden wieder                   |
| `ServerConfig.Spam.floodCount` / `floodWindow` | `6` / `10` | So viele Nachrichten in so vielen Sekunden gelten als Flood             |
| `ServerConfig.Spam.floodMute`                  | `60`       | Danach so viele Sekunden stumm                                          |
| `ServerConfig.Filter.mode`                     | `'censor'` | `'censor'` (Sternchen), `'block'` (Nachricht verwerfen) oder `'off'`    |
| `ServerConfig.Filter.words`                    | leer       | Liste der gefilterten Wörter (Groß-/Kleinschreibung egal)               |

Spam-Schutz und Langsam-Modus gelten nicht fürs Team, der Wortfilter nicht im Team-Kanal.

## Für Entwickler

```lua
-- Client
exports.pepper_chat:setVisible(false)                       -- Chat ausblenden, z. B. für eine Zwischensequenz
TriggerEvent('chat:addMessage', { color = { 255, 196, 107 }, args = { 'Bank', 'Du hast 500 $ erhalten.' } })
-- Server
TriggerClientEvent('chat:addMessage', source, { args = { 'Server', 'Willkommen!' } })
exports.pepper_chat:addMessage(-1, { args = { 'Server', 'Neustart um 18 Uhr.' } })
```

Wie beim Standard-Chat können andere Ressourcen auf dem Server das Event `chatMessage` abfangen (`CancelEvent()`) oder mit `registerMessageHook` Nachrichten ändern und abbrechen. Farbcodes `^0`–`^9` funktionieren in Nachrichten von Scripts; aus Spielernachrichten werden sie entfernt.

## Befehle und Rechte

| Befehl                             | Wer                | Was                                                |
| ---------------------------------- | ------------------ | -------------------------------------------------- |
| `/ooc [Text]`                      | alle               | Nachricht in den OOC-Kanal                         |
| `/team [Text]`                     | Team               | Nachricht in den Team-Chat                         |
| `/announce [Text]`                 | Team               | Ankündigung an alle (Chat + Banner)                |
| `/chatclear`                       | Team               | Leert den Chat für alle                            |
| `/chatmute [ID] [Minuten] [Grund]` | Team               | Spieler stummschalten, `0` = dauerhaft             |
| `/chatunmute [ID]`                 | Team               | Stummschaltung aufheben (Spieler muss online sein) |
| `/chatslow [Sekunden]`             | Team               | Langsam-Modus, `0` = aus (höchstens 600)           |
| `say [Text]`                       | nur Server-Konsole | Zeile als „Konsole“ in den Chat                    |

Alle Namen änderst du in `Config.Commands`. Die Team-Befehle funktionieren auch in der Server-Konsole.

**Wer gehört zum Team?** Die erste passende Rolle in `Config.Staff`:

* **ESX:** die Gruppe des Spielers (`admin`, `superadmin`, `mod` …)
* **QBCore / Qbox:** das Recht des Spielers (`god`, `admin`, `mod`)
* **Ohne Framework:** in der `server.cfg`

  ```
  add_ace group.admin pepperchat.admin allow
  add_ace group.moderator pepperchat.mod allow
  ```

**Tasten im Chatfenster:** **T** öffnen (änderbar), **Enter** senden, **Esc** schließen, **Tab** Vorschlag übernehmen bzw. Reiter wechseln, **Pfeil hoch/runter** Eingabeverlauf oder Vorschläge, **Bild hoch/runter** im Verlauf blättern, Rechtsklick (nur Team) Menü für Nachricht und Spieler.

## Exports und Events

| Seite  | Name                                                                                                                        | Wirkung                                                    |
| ------ | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Client | `exports.pepper_chat:setVisible(bool)`                                                                                      | Chat ein-/ausblenden                                       |
| Client | `exports.pepper_chat:addMessage(msg)` / `addSuggestion(name, help, params)`                                                 | Wie beim Standard-Chat                                     |
| Client | Events `chat:addMessage`, `chatMessage`, `chat:addSuggestion(s)`, `chat:removeSuggestion`, `chat:addTemplate`, `chat:clear` | Verträglich mit dem Standard-Chat                          |
| Server | `exports.pepper_chat:addMessage(target, msg)`                                                                               | Nachricht an einen Spieler oder `-1` = alle                |
| Server | `exports.pepper_chat:registerMessageHook(fn)`                                                                               | Spielernachrichten vor dem Verteilen ändern oder abbrechen |
| Server | Event `chatMessage(source, name, text)`                                                                                     | Mitlesen, mit `CancelEvent()` abbrechen                    |

## FAQ

### Der Chat öffnet sich doppelt oder gar nicht – was tun?

Meist läuft noch der Standard-Chat oder ein anderer Chat. Entferne `ensure chat` (und andere Chat-Ressourcen) aus der `server.cfg`. Pepper Chat meldet sich per `provide 'chat'` als Ersatz an, es darf nur einer laufen.

### Läuft mein anderes Script, das `chat` voraussetzt, weiter?

Ja. Durch `provide 'chat'` gelten Abhängigkeiten auf `chat` als erfüllt, und die Events `chat:addMessage`, `chat:addSuggestion`, `chatMessage` und Vorlagen (`chat:addTemplate`) werden verstanden.

### Brauche ich eine Datenbank?

Ja, für die Stummschaltungen über oxmysql. Die Tabelle `pepper_chat_mutes` legt das Script beim Start selbst an; von Hand geht es mit `install/pepper_chat.sql`.

### Ich bin Admin, sehe aber den Team-Reiter nicht?

Prüfe, ob deine Gruppe (ESX) bzw. dein Recht (QBCore/Qbox) in `groups` einer Rolle in `Config.Staff` steht, oder setze ohne Framework `add_ace group.admin pepperchat.admin allow`. Die Rolle wird bis zu 30 Sekunden zwischengespeichert – nach einer Änderung neu verbinden.

### Wie zeige ich den Charakternamen statt des FiveM-Namens?

Ändere `Config.GetName` in der `config.lua`: Die Funktion läuft auf dem Server und bekommt die `source`. Dort fragst du dein Framework ab und gibst den Namen zurück (höchstens 40 Zeichen werden angezeigt).

### Wie ändere ich Farben und Position?

Akzentfarbe, Position, Größe und Skalierung stehen in `Config.UI`, die Farben der Team-Abzeichen in `Config.Staff` (`color`). Für tiefere Änderungen passt du `html/style.css` an.

### Wie ändere ich die Texte?

Alle Texte stehen in `locales/de.json` bzw. `locales/en.json`. Mit `Config.Locale` wählst du die Sprache.

### Bleiben Stummschaltungen nach einem Neustart erhalten?

Ja. Sie liegen in der Datenbank, gebunden an die Rockstar-Lizenz des Spielers. Abgelaufene werden beim Start gelöscht. Hat ein Spieler keine Lizenz-Kennung, gilt die Stummschaltung nur für die aktuelle Sitzung.

### Wie hebe ich eine Stummschaltung für einen Spieler auf, der offline ist?

Über das Team-Menü im Chat: Die Liste der Stummgeschalteten zeigt alle aktiven Einträge, dort hebst du sie auf. `/chatunmute [ID]` funktioniert nur für Spieler, die gerade online sind.

### Wie richte ich den Discord-Webhook ein?

Trage die Webhook-URL in `config_server.lua` bei `ServerConfig.Log.webhook` ein. Die Zeilen werden gesammelt und etwa alle 5 Sekunden gebündelt gesendet. Die Datei liegt nur auf dem Server und wird nie an Spieler geschickt.

### Warum kommen Spielernachrichten ohne Farbe an?

Farbcodes `^0`–`^9` und Steuerzeichen werden aus Spielernachrichten auf dem Server entfernt. In Nachrichten deiner Scripts (`chat:addMessage`) funktionieren sie weiter.

### Ein Spieler tippt einen Befehl, den es nicht gibt – landet das im Chat?

Nein. Unbekannte Befehle werden nicht als Nachricht an alle verteilt; der Spieler bekommt einen Hinweis.

### Wie update ich Pepper Chat?

Ordner ersetzen und vorher `config.lua`, `config_server.lua` und geänderte Sprachdateien sichern. Die Datenbank bleibt erhalten. Änderungen stehen in der `CHANGELOG.md` im Ressourcen-Ordner.

## Support

Ticket in unserem [Discord](https://discord.gg/6NaFJWKDYu) (Kategorie „Script Support“) öffnen und den Kauf vorher mit `/verify` verknüpfen.

## Changelog

Aktuelle Version **1.0.0** (erste Version). Alle Änderungen stehen in der `CHANGELOG.md` im Ressourcen-Ordner.