DS Word Filter - Complete Documentation
Installation
System Requirements

• Minecraft Server: 1.21 or higher
• Server Software: Bukkit, Spigot, or Paper
• Java Version: 17+ (recommended)
• RAM: Minimum 512MB available
• Storage: 50MB free space

Step-by-Step Installation

1. Download the Plugin
   
2. Install the Plugin
   
3. Start the Server
   
4. Verify Installation
   
   [INFO]: [DSWordFilter] Plugin successfully loaded!
   [INFO]: [DSWordFilter] The ultimate chat moderation solution!

Configuration
Main Configuration (config.yml)
# Basic Filter Settings
enable-filter: true # Enable/disable the entire filter system
log-violations: true # Log blocked messages to console
warning-cooldown-ms: 3000 # Cooldown between warnings (milliseconds)
case-sensitive: false # Case-sensitive word matching
whole-words-only: false # Match whole words only

# AI Moderator Configuration
ai:
enabled: false # Enable AI-powered moderation
api-key: 'your-openai-api-key-here' # OpenAI API key
api-url: ' https://api.openai.com/v1/chat/completions'
model: 'gpt-3.5-turbo' # AI model to use
calls-per-hour: 50 # Maximum API calls per hour

# Advanced Settings
advanced:
trust-system-enabled: true # Enable player trust system
suspicious-pattern-detection: true # Enable pattern detection
url-detection: true # Detect URLs in messages
discord-invite-detection: true # Detect Discord invites
excessive-caps-threshold: 0.6 # Threshold for excessive capitals (60%)
repeated-char-threshold: 5 # Threshold for repeated characters

# Debug Options
debug:
ai-requests: false # Log AI requests
pattern-matching: false # Log pattern matches
trust-level-changes: false # Log trust level changes

Language Configuration (lang.yml)
# Plugin Messages
plugin:
enabled: "DS Word Filter plugin loaded successfully!"
disabled: "DS Word Filter plugin disabled!"

# Warning Messages
warning:
message: "&cWarning: Inappropriate language detected!"

# Command Messages
command:
no-permission: "You don't have permission to use this command!"
reload:
success: "Configuration reloaded successfully!"

# Trust Levels
trust:
reliable: "Reliable"
average: "Average"
suspicious: "Suspicious"
risky: "Risky"

File Structure
plugins/DSWordFilter/
├── config.yml # Main configuration file
├── lang.yml # Language translations
├── banned-words.txt # List of banned words/phrases
├── suspicious-patterns.txt # Patterns that trigger AI checks
├── allowed-content.txt # Always-allowed content
└── README.md # Plugin documentation

Word Lists
banned-words.txt
# Traditional banned words
spam
advertisement
inappropriate_word

# Multi-word phrases work too
bad phrase example
another banned phrase

suspicious-patterns.txt
# Patterns that trigger AI evaluation
free
money
server
discord
join
cheap
buy

allowed-content.txt
# Your server's official content
MyServer.com
discord.gg/myserver
official website
server store

Commands
Administrative Commands

Command Description Permission Usage
/wordfilter Show help menu wordfilter.admin /wordfilter
/wordfilter status Display plugin status wordfilter.admin /wordfilter status
/wordfilter reload Reload configuration wordfilter.admin /wordfilter reload
/wordfilter toggle Enable/disable filter wordfilter.admin /wordfilter toggle
AI Commands

Command Description Permission Usage
/wordfilter ai Show AI status wordfilter.admin /wordfilter ai
/wordfilter ai test <message> Test AI moderation wordfilter.admin /wordfilter ai test hello world
Trust System Commands

Command Description Permission Usage
/wordfilter trust <player> Check player's trust level wordfilter.admin /wordfilter trust Steve
Command Examples
# Check plugin status
/wordfilter status

# Test AI with a message
/wordfilter ai test "Join my discord server!"

# Check a player's trust level
/wordfilter trust PlayerName

# Reload all configurations
/wordfilter reload

Permissions
Permission Nodes

Permission Description Default
wordfilter.admin Full plugin administration OP
wordfilter.bypass Bypass all filtering false
wordfilter.ai.bypass Bypass only AI filtering false
Permission Examples
# permissions.yml (with a permission plugin)
groups:
admin:
permissions:
- wordfilter.admin

moderator:
permissions:
- wordfilter.admin

vip:
permissions:
- wordfilter.ai.bypass

trusted:
permissions:
- wordfilter.bypass

AI Setup
Getting OpenAI API Key

1. Visit OpenAI: Go to platform.openai.com
2. Create Account: Sign up or log in
3. Generate API Key: Navigate to API keys section
4. Set Billing: Add payment method (required for API usage)
5. Copy Key: Copy your API key (starts with sk-)

Configuring AI
ai:
enabled: true
api-key: 'sk-your-actual-api-key-here'
model: 'gpt-3.5-turbo' # Recommended for cost efficiency
calls-per-hour: 50 # Adjust based on your server size

AI Model Options

Model Cost Speed Quality Recommended For
gpt-3.5-turbo Low Fast Good Most servers
gpt-4 High Slow Excellent Premium servers
gpt-4-turbo Medium Medium Excellent Large servers
Cost Estimation
Small Server (50 players): ~$5-10/month
Medium Server (200 players): ~$15-25/month
Large Server (500+ players): ~$30-50/month

Trust System
How Trust Levels Work
The trust system assigns each player a score from 0-100:

• 0-19: Risky (All messages checked)
• 20-49: Suspicious (Enhanced checking)
• 50-79: Average (Normal checking)
• 80-100: Reliable (AI checks bypassed)

Trust Level Changes
// Positive behavior: +1 trust
- Message passes AI check
- No violations for extended period

// Negative behavior: -10 trust
- Message blocked by traditional filter
- Message blocked by AI filter
- Pattern violations

Monitoring Trust Levels
# Check individual player
/wordfilter trust PlayerName

# View trust statistics
/wordfilter status

Pattern Detection
Built-in Patterns
The plugin automatically detects:

1. URLs: http, https, www, .com, .net, etc.
2. Discord Invites: discord.gg, discord.com/invite
3. Excessive Capitals: >60% uppercase letters
4. Repeated Characters: 5+ consecutive identical characters

Custom Patterns
Add custom patterns to suspicious-patterns.txt:

# Advertising keywords
free
money
cheap
discount
sale

# Server promotion
server
join
play
community

# Social media
youtube
twitch
instagram

Pattern Configuration
advanced:
url-detection: true # Enable URL detection
discord-invite-detection: true # Enable Discord invite detection
excessive-caps-threshold: 0.6 # 60% threshold for capitals
repeated-char-threshold: 5 # 5+ repeated characters

Troubleshooting
Common Issues
Plugin Not Loading
# Check Java version
java -version # Should be 17+

# Check server version
# In server console: /version

AI Not Working
# Verify API key in config.yml
ai:
enabled: true
api-key: 'sk-...' # Must start with 'sk-'

# Check API quota
/wordfilter ai # Shows remaining calls

High False Positives
# Adjust sensitivity
whole-words-only: true # More precise matching
case-sensitive: false # Less strict
ai:
calls-per-hour: 100 # Allow more AI checks

Log Analysis
# View recent logs
tail -f logs/latest.log | grep "DSWordFilter"

# Search for specific errors
grep "ERROR" logs/latest.log | grep "DSWordFilter"

Support
Getting Help

1. Check Documentation: Read this guide thoroughly
2. Search Issues: Look for similar problems
3. Discord Support: Contact @david3553
4. Spigot Profile: Visit daveston1's profile

Reporting Bugs
Include this information:

• Server version (/version)
• Plugin version
• Error logs
• Configuration files
• Steps to reproduce

Feature Requests
Submit detailed suggestions including:

• Use case description
• Expected behavior
• Benefits to community
• Technical considerations

Last updated: 2024 | DS Word Filter v1.0-SNAPSHOT