ArkShield-AI

Minecraft Chat Profanity Detection Plugin Based on AI Large Language Model

© Zhumeng Fangzhou Network Technology Studio. All rights reserved.

Introduction

ArkShield-AI is a chat content moderation plugin for Minecraft Purpur 1.21.1 servers. By integrating with AI large language models (default DeepSeek), it performs intelligent profanity detection on player chat messages, supporting three detection levels, automatic muting, and manual admin muting.

Features

• AI-Powered Detection — Analyzes chat content using large language models, more accurate than traditional keyword matching
• Three Detection Levels — Simple / Normal / Strict, configurable via config file or commands
• Asynchronous Non-blocking — AI requests are processed asynchronously, no impact on server TPS
• Automatic Muting — Automatically mutes players after reaching violation threshold, configurable duration and threshold
• Manual Admin Mute/Unmute — Command-based control for flexible management
• Result Caching — Same messages won't trigger duplicate AI requests, reducing API calls
• Logging — Blocked messages can be output to console and log files
• Admin Notification — Blocked messages are notified to online admins in real-time
• Permission System — Supports bypass permission to skip detection

Requirements

Quick Start

1. Build

mvn clean package

The built artifact is located at target/ArkShield-AI-1.0.0.jar.

2. Deploy

Copy ArkShield-AI-1.0.0.jar to the server's plugins/ directory and restart the server.

3. Configure API Key

After the first run, plugins/ArkShield-AI/config.yml will be automatically generated. Edit the ai.api-key field:

ai:
  base-url: "https://api.deepseek.com/v1"
  api-key: "sk-your-api-key-here"  # Replace with your actual API Key
  model: "deepseek-chat"

Any OpenAI-compatible interface is supported—just modify base-url and api-key.

4. Restart Server

After configuration, restart the server for the plugin to take effect.

Commands

Permission Nodes

Detection Levels

Configuration File

Configuration file path: plugins/ArkShield-AI/config.yml

# AI Interface Configuration
ai:
  base-url: "https://api.deepseek.com/v1"  # API endpoint
  api-key: "sk-your-api-key-here"           # API key
  model: "deepseek-chat"                    # Model name
  enable-thinking: false                    # Thinking mode (only for reasoner)
  timeout: 15                               # Request timeout (seconds)

# Detection level (1/2/3)
level: 2

# Mute Configuration
mute:
  enabled: true               # Enable automatic muting
  violation-threshold: 3      # Violations needed to trigger mute
  duration-minutes: 10        # Mute duration (minutes)
  violation-reset-minutes: 60 # Violation count reset time (minutes)

# Message Configuration (supports & color codes)
messages:
  blocked: "&c[ArkShield] &fYour message contains inappropriate content and has been blocked."
  admin-alert: "&e[ArkShield] &fPlayer &c%player% &fsent a blocked message: &7%message%"

# Admin Notification
admin-notify:
  enabled: true
  permission: "arkshield.admin"

# Logging Configuration
logging:
  log-to-console: true
  log-to-file: true
  log-file: "blocked_messages.log"

# Cache Configuration
cache:
  enabled: true
  expire-minutes: 30
  max-size: 1000

Workflow

Player sends message
    │
    ├── Has bypass permission? ──→ Directly allowed
    │
    ├── Is muted? ──→ Blocked with remaining time提示
    │
    ├── Sender immediately sees their own message
    │
    ├── Send AI detection request asynchronously
    │       │
    │       ├── AI returns normal ──→ Broadcast message to other players
    │       │
    │       └── AI returns violation ──→ Block message
    │               ├── Notify player
    │               ├── Notify admins
    │               ├── Log to file
    │               ├── Record violation count
    │               └── Threshold reached? ──→ Auto-mute player
    │
    └── AI request fails ──→ Allow by default (no chat impact)

File Structure

ArkShield-AI/
├── pom.xml
├── README.md
└── src/main/
    ├── java/com/arkshield/ai/
    │   ├── ArkShieldAI.java           # Plugin main class
    │   ├── command/
    │   │   └── ArkShieldCommand.java  # Admin commands
    │   ├── config/
    │   │   └── ConfigManager.java     # Configuration management
    │   ├── listener/
    │   │   └── ChatListener.java      # Chat event listener
    │   └── service/
    │       ├── AIService.java         # AI interface service
    │       ├── HeartbeatService.java  # Heartbeat reporting service (for usage statistics)
    │       └── MuteService.java       # Mute management service
    └── resources/
        ├── config.yml                 # Default configuration
        └── plugin.yml                 # Plugin description

License

This project is open-sourced under the MIT License.

Copyright © 2026 Zhumeng Fangzhou Network Technology Studio