Chat Moderator – AI-Assisted Chat Moderation for Paper 1.21

A lightweight, free, AI-assisted chat moderation plugin for Paper 1.21 Minecraft servers. ChatMod combines fast regex/language filtering with an optional offline ONNX-based classifier to accurately moderate toxic, hateful, sexual, and harassing messages without paid APIs.

Features

Hybrid moderation: regex + optional RoBERTa ONNX AI
Identity-aware hate detection (no API keys required)
Language detection and blocking
Tunable thresholds, punishments, and strict mode
Admin tools for review, training, and status
Persistent stats with autosave (SQLite/MySQL) and auto-migration
File/DB logging and review tools
Performance-optimized with async classification and caching
Works fully offline (no paid APIs)
Highly configurable and extensible

Installation

Drop ChatModer.jar into your server plugins/ directory
Restart the server to generate plugins/ChatModer/config.yml
(Optional) Add an ONNX model folder under plugins/ChatModer/models/ and point the config to the ONNX file

AI Model Setup (Hugging Face RoBERTa)

ChatModer supports Hugging Face RoBERTa ONNX models, e.g. protectai/unbiased-toxic-roberta-onnx.

Create a folder like:

plugins/ChatModer/models/unbiased-toxic-roberta-onnx/

Put these files inside:

model_quantized.onnx (recommended) or model.onnx
config.json (contains id2label/label2id)
tokenizer.json (preferred), or vocab.json + merges.txt
Optional: tokenizer_config.json, special_tokens_map.json

Config snippet:

moderation:
  ai:
    enabled: true
    model_path: plugins/ChatModer/models/unbiased-toxic-roberta-onnx/model_quantized.onnx
    max_sequence_length: 128
    async_threads: 2
    timeout_ms: 500

The tokenizer/config are auto-loaded from the same folder as the ONNX.

Label Mapping

obscene -> profanity
insult/threat -> harassment
sexual_explicit -> sexual
identity_attack -> hate
toxicity/severe_toxicity boost profanity/harassment slightly
Identity-only labels (e.g., black, muslim) are not flagged by themselves; they serve as context when combined with insult/toxicity

Modes

regex: Only regex/wordlist heuristics
ai-only: Only ONNX model (if enabled); still uses language blocking and whitelist
hybrid (recommended): Combine regex + AI; AI score can be weighted via moderation.ai.weight

moderation:
  enabled: true
  mode: hybrid   # regex | ai-only | hybrid
  ai:
    enabled: true
    weight: 0.8

Database & Autosave

Stats are persisted to SQLite by default or MySQL if configured. The plugin can auto-migrate existing SQLite stats to MySQL.

database:
  type: sqlite
  sqlite_file: plugins/ChatModer/data.db
  mysql:
    host: 127.0.0.1
    port: 3306
    database: chatmoder
    user: root
    password: "secret"
    useSSL: false
  sqlite_migrate_file: plugins/ChatModer/data.db

stats:
  autosave_seconds: 300

Thresholds & Punishments

Fine-tune moderation sensitivity and actions per category.

thresholds:
  profanity: 0.7
  harassment: 0.6
  hate: 0.6
  sexual: 0.7
  spam: 0.8

punishments:
  profanity: block         # warn | tempmute | kick | tempban | block | command:<cmd>
  harassment: warn
  hate: tempmute
  sexual: block
  spam: block

Logging & Review

File logs: JSONL written to plugins/ChatModer/logs/flags.log
DB logs: SQLite/MySQL flags table (optional)
Review: /chatmod review <player> reads from DB if enabled, else file logs. Supports legacy pretty-printed logs and compact JSONL.

Commands

/chatmod toggle — Enable/disable moderation.
/chatmod status — Live stats overview.
/chatmod review <player> — Review recent flagged messages.
/chatmod whitelist add|remove <word> — Manage whitelist.
/chatmod strict reload — Reload strict list.
/chatmod train add|capture|fromlog|words|stats|export — Dataset tools.
/chatmod stats reset confirm — Clear in-memory stats and persist immediately.

Training Workflow (Optional)

Capture: record recent messages as context for training
From log: mine flagged logs into a dataset
Words: word frequency analysis
Stats: training dataset stats
Export: outputs dataset.jsonl ready for fine-tuning

All tools are available under /chatmod train ....

Strict Mode

For immediate blocks (e.g., high-severity tokens), enable strict rules and reload them without a restart:

/chatmod strict reload

Permissions

chatmod.admin — Access to admin commands
chatmod.bypass — Bypass moderation
chatmod.review — Access review tools

Performance

Regex-only mode for minimal overhead
AI runs asynchronously and uses a quantized ONNX model on CPU
Token and message caching to reduce repeated work

Privacy

All processing is local. No external API calls are made unless you enable webhooks.

Compatibility

Paper 1.21 (most modern forks should work)
Java 17+
SQLite included; MySQL requires valid credentials

Troubleshooting

ONNX model not loading: Check moderation.ai.model_path and ensure config.json and tokenizer.json (or vocab.json + merges.txt) are in the same directory.
Classification timeout: Increase moderation.ai.timeout_ms or reduce max_sequence_length.
High CPU: Use model_quantized.onnx and keep max_sequence_length at 128/256.
Review shows no entries: Ensure logging is enabled (file or DB) and that your logs aren’t empty.

Support

Open an issue on the project repository with logs, configs, and steps to reproduce. Provide model details if you use a custom model.

Chat Moderator - LOCAL AI