hChatFilter is an advanced moderation plugin that filters player text across multiple server systems.
The plugin can check regular chat, configured commands, signs, books, anvil rename text and item display text. It combines local rule-based filtering, anti-spam, anti-caps, IP detection, text normalization, punishment profiles, violation storage and optional AI moderation.
AI moderation is fully optional. Local rules can work without AI, while suspicious cases can be sent to OpenRouter, Ollama or a custom OpenAI-compatible HTTP provider when enabled.
Main Features

• Checks chat messages.
• Checks configured command messages.
• Checks sign text.
• Checks book title, author and pages.
• Checks anvil rename text.
• Checks item display names and lore.
• Rule-based filtering through rules.yml.
• Replacement, delete and block rule modes.
• Anti-spam with multiple detection methods.
• Anti-caps with configurable behavior.
• IP address and advertising detection.
• Advanced text normalization for bypass protection.
• Optional AI moderation.
• SQLite and MySQL violation storage.
• Punishment profiles with staged actions.
• DiscordSRV support.
• Developer API and moderation events.
• Folia support.

How It Works
When a player sends or creates text, hChatFilter processes it through enabled modules.
The plugin normalizes the text, checks it against configured local rules, applies spam and caps checks, detects IP addresses and decides whether the content should be allowed, changed, blocked or sent to AI review.
If a violation is detected, the plugin can execute configured actions, store the violation and apply punishment profiles depending on the violation category and previous history.
Text Sources
The plugin can check these sources:

• Chat messages.
• Private messages and other configured commands.
• Broadcast commands.
• Signs.
• Books.
• Anvil item names.
• Item display names and lore.

Command text can be extracted using command rules. For example, private message commands can skip the target player argument and check only the actual message text.
Text Normalization
Before rules are checked, the plugin can normalize text to detect bypass attempts.
Supported normalization options include:

• Unicode NFKC normalization.
• Zero-width character removal.
• Control character removal.
• Lowercase conversion.
• Confusable character replacement.
• Separator removal for compact checks.
• Repeated character compression.
• Russian to Latin transliteration.
• Latin to Russian transliteration.
• Normalization cache.

This helps detect messages with mixed alphabets, hidden symbols, extra separators and repeated letters.
Rule Checks
Rules are configured in rules.yml.
Each rule can define:

• Enable state.
• Category.
• Severity.
• Sources where the rule works.
• AI mode.
• Rule behavior.
• Matching mode.
• Word list or regex patterns.

Supported matching logic includes:

• contains
• compact
• regex
• advertising
• fuzzy matching

The rule behavior can replace matched text, delete content or block the message depending on the selected mode.
Anti-Spam
hChatFilter includes several anti-spam checks.

• Message cooldown.
• Burst message detection.
• Repeated message detection.
• Similar message detection.
• Character flood detection.
• Optional command spam checks.

Spam warnings can decay over time, and repeated spam stages can trigger different actions.
Anti-Caps
The anti-caps module can detect excessive uppercase usage.
Configurable settings include:

• Minimum message length.
• Maximum caps percentage.
• Ignored words.
• Reaction mode.
• Violation category.
• Severity.

Reaction modes can include converting the message to lowercase, blocking it or only warning the player.
AI Moderation
AI moderation can be enabled for suspicious messages.
Supported providers:

• OpenRouter.
• Ollama.
• Custom OpenAI-compatible HTTP API.

The AI module supports:

• Request queue limits.
• Requests-per-second limit.
• Concurrent request limit.
• Timeout configuration.
• Circuit breaker.
• AI verdict cache.
• Fallback behavior on errors.
• Fallback behavior on queue overflow.
• Approved-message publishing.

AI provider settings and API keys are configured directly in ai.yml.
Punishments and Actions
hChatFilter uses punishment profiles with stages.
Default profile examples include:

• toxic
• advertising
• server-insult

Each stage can execute its own actions. This allows you to warn, notify, mute or run console commands depending on the violation type and player history.
The plugin can also execute actions for different moderation events, such as:

• Forbidden word detected.
• Message blocked.
• Text replacement applied.
• UTF symbols detected.
• Caps detected.
• Spam detected.
• AI moderation queued.
• AI moderation approved.
• AI moderation rejected.
• AI moderation error.
• IP address detected.
• Sign, book, anvil or item filter triggered.

Storage
Violation data can be stored using:

• SQLite.
• MySQL.

Stored violations are used for lookup, statistics and punishment tracking.
DiscordSRV
If DiscordSRV is installed, hChatFilter can check Discord-to-Minecraft messages before they appear in the Minecraft chat.
This behavior can be enabled or disabled in the configuration.
Developer API
hChatFilter includes a public API and moderation events.
Available API areas include:

• Custom rules.
• Message context.
• Player violation profile.
• Filter results.
• AI moderation event.
• Pre-filter event.
• Post-filter event.
• Pre-punishment event.

This allows other plugins to interact with the moderation system.
Configuration
Main configuration files:
Files
Modules
Main modules can be enabled or disabled separately:
Storage Settings
Storage type can be selected in config.yml:
MySQL can also be configured if external storage is required.
Commands
Command Description
Permissions
Granular Bypass Examples
Requirements

• Java 17 or newer.
• Minecraft 1.16 or newer.
• Spigot, Paper, Purpur or Folia.

Optional integrations:

• DiscordSRV.
• MySQL.
• OpenRouter.
• Ollama.
• Custom OpenAI-compatible HTTP API.

Installation

1. Place hChatFilter.jar into your server's plugins folder.
2. Restart the server.
3. Open the generated plugin folder.
4. Configure config.yml and rules.yml.
5. Configure ai.yml if AI moderation is needed.
6. If AI moderation is enabled, put the API key directly in ai.yml.
7. Restart the server or use /hchatfilter reload.

Configuration folder:
Notes

• AI moderation is optional.
• Local rules can work without AI.
• DiscordSRV is optional.
• SQLite works by default for local storage.
• MySQL is available for external storage.
• Folia is supported.