️ ZeGuard — Advanced Chat Guard for Paper 1.21.8

ZeGuard is a powerful, production-ready chat management and word-filter
plugin for Paper servers. It gives administrators full control over the
chat: lock it, clear it, filter banned words with leet-speak detection,
run automatic punishment commands, and manage everything from a clean
in-game GUI — all with PlaceholderAPI support baked in.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✨ FEATURES AT A GLANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CHAT CONTROL
• Open / close the global chat instantly
• Clear chat (sends N blank lines, configurable)
• Broadcast coloured announcements to all online players
• Players with zeguard.bypass can still chat while locked

WORD FILTER (words.yml)
• Five detection modes per word:
BLOCK — cancel the message, warn the sender
REPLACE — swap the word with *** (or custom text)
WARN — let the message pass but notify the sender
COMMAND — silently trigger a command list
ALL — BLOCK + COMMAND simultaneously
• Case-insensitive matching
• Word-boundary toggle (word_boundary: true/false per entry)
• Leet-speak detection (@ → a, 3 → e, 1 → i, 0 → o, 5 → s, + → t)
• Global whitelist (e.g. "aptalca" bypasses the "aptal" filter)

⚙️ COMMAND SYSTEM
• Each filtered word can trigger a custom command list
• Execution modes: CONSOLE | PLAYER | BOTH
• Per-command delay in ticks (delay: 0 → instant)
• Full placeholder support in command strings:
{player} {uuid} {message} {word} {world}
+ all PlaceholderAPI placeholders

⚠️ WARNING SYSTEM
• Per-player warning counter stored in RAM
• Configurable threshold actions:
3 warns → kick
5 warns → ban 1 day
(fully customisable in config.yml)
• Reset modes: GUNLUK (daily) | MANUEL | HICBIR

PLACEHOLDERAPI INTEGRATION (soft-depend)
%zeguard_chat_durum% → "Açık" / "Kapalı"
%zeguard_filtre_sayisi% → total banned-word count
%zeguard_temizleme_sayisi% → total clear count
%zeguard_uyari_<player>% → warning count for a player

️ ADMIN GUI (/zeguard gui)
• 3-row inventory panel
• One-click chat toggle (LIME / RED wool)
• One-click chat clear
• Opens paginated filter list

FILTER LIST GUI (/zeguard filtreler)
• Paginated (max 6 rows per page, 36 words per page)
• Each word shown as a PAPER item with full details
• Left-click any word to remove it instantly

ASYNC LOGGING
• Writes timestamped entries to plugins/ZeGuard/logs/zeguard.log
• Runs on a dedicated background thread — zero main-thread I/O
• Log format:
[2025-01-15 14:32:11] [ENGEL] Neony: "mesaj" → kelime: "kufur1"
[2025-01-15 14:32:15] [REPLACE] Steve: "aptal şey" → "*** şey"
[2025-01-15 14:33:00] [CHAT-KAPANDI] Yönetici: Neony
[2025-01-15 14:36:00] [KOMUT] Neony → "mute Neony 5m" (konsol)


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Aliases: /zg /guard /chatguard

/zeguard ac — Open the chat
/zeguard kapat — Close the chat
/zeguard temizle — Clear the chat
/zeguard durum — Show current status
/zeguard gui — Open admin GUI
/zeguard filtreler — Open filter list GUI
/zeguard reload — Reload config.yml + words.yml
/zeguard uyari <player> — Show a player's warning count
/zeguard uyarisifirla <player> — Reset a player's warnings
/zeguard test <word> — Test if a word triggers the filter
/zeguard ekle <word> <mod> — Add a word on-the-fly
/zeguard sil <word> — Remove a word on-the-fly

All commands support TAB-completion.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PERMISSIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

zeguard.admin — Access to all commands (default: op)
zeguard.bypass — Skip filter & chat-lock (default: false)


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONFIGURATION FILES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

plugins/ZeGuard/
├── config.yml — prefix, messages, warn thresholds, log settings
├── words.yml — banned words, modes, commands, whitelist
└── logs/
└── zeguard.log

Example words.yml entry:

filtreler:
kufur1:
mod: ALL
leet: true
word_boundary: false
uyari_ekle: true
komutlar:
- mod: CONSOLE
komut: "mute {player} 5m"
gecikme: 0
- mod: CONSOLE
komut: "broadcast <red>{player} küfür etti!"
gecikme: 0

whitelist:
- "aptallık"
- "aptalca"


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚙️ REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Paper 1.21.8+
• Java 21+
• PlaceholderAPI (optional — soft-depend)


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
INSTALLATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Drop ZeGuard-1.0.0.jar into your /plugins/ folder.
2. (Re)start the server.
3. Edit plugins/ZeGuard/config.yml and words.yml to your liking.
4. Run /zeguard reload — no restart needed.


━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LINKS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Author website : https://neonyy.zya.me
Plugin version : 1.0.0
Source API : Paper 1.21.8