ArkShield-AI

Minecraft Chat Profanity Detection Plugin Based on AI Large Language Model

---

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 Detection — Analyzes chat content using large language models, more accurate than traditional keyword matching
• Detection Levels — Simple / Normal / Strict, configurable via config file or commands
• Asynchronous Processing — AI requests are processed asynchronously, no impact on server TPS
• Auto Mute — Automatically mutes players after reaching violation threshold, configurable duration and threshold
• Admin Mute/Unmute — Command-based control for flexible management
• 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

Item	Requirement
Server	Purpur 1.21.1
Java	JDK 21
Build Tool	Maven

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

Command	Description	Permission
/arkshield reload	Reload configuration file	arkshield.admin
/arkshield status	View plugin runtime status	arkshield.admin
/arkshield level <1|2|3>	Set detection level	arkshield.admin
/arkshield mute <player> [duration]	Manually mute a player (duration in minutes)	arkshield.admin
/arkshield unmute <player>	Manually unmute a player	arkshield.admin

Permission Nodes

Permission	Description	Default
arkshield.admin	Allows use of admin commands	OP
arkshield.bypass	Bypass AI chat detection	false

Detection Levels

Level	Name	Detection Scope
1	Simple	Violence threats, explicit content, severe personal attacks
2	Normal	+ Racial discrimination, malicious spam (Default)
3	Strict	+ Advertising, political sensitivity, negative诱导, offensive language

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.

By using this plugin, you agree to our Privacy Policy and Terms of Service.

By using this project, you agree that our plugin will send a heartbeat packet to our server to track the number of users.

Copyright © 2026 DreamArk Network Technology Studio