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

1. Drop ChatModer.jar into your server plugins/ directory
2. Restart the server to generate plugins/ChatModer/config.yml
3. (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.