CapsWarn

A comprehensive Spigot/Paper Minecraft plugin that detects excessive capital letter usage in chat messages and manages a flexible warning point system to discourage caps spam.

Author: RGBToaster
Version: 1.1.3
Source: https://git.basicsites.ddns.net/RGBToaster/capswarn

Description

CapsWarn is designed to maintain a pleasant chat environment by automatically detecting and handling messages with excessive capital letters. The plugin features a sophisticated warning point system with automatic expiration, configurable punishment thresholds, and full admin control through commands and permissions.

Key Features

• Intelligent Caps Detection: Detects both consecutive uppercase letters and percentage-based caps spam
• Warning Point System: Persistent storage with configurable expiration times
• Flexible Punishment: Configurable thresholds for warnings, mutes, and bans
• Admin Tools: Complete command suite for managing player warnpoints
• Highly Configurable: Detailed configuration with color code support and placeholders
• External Plugin Integration: Supports integration with popular punishment plugins like AdvancedBan
• Automatic Cleanup: Expired warnpoints are automatically removed
• Player Notifications: Players are notified when receiving or losing warnpoints

Documentation

Project Structure

The plugin is organized into several key components:

src/main/java/com/rgbtoaster/capswarn/
├── CapsWarn.java           - Main plugin class
├── ConfigManager.java      - Configuration handler
├── WarnPointManager.java   - Warning point system logic
├── ChatListener.java       - Chat event listener
└── CapsCommand.java        - Command executor

src/main/resources/
├── config.yml              - Plugin configuration
└── plugin.yml              - Plugin metadata

Core Components

1. CapsWarn.java - Main Plugin Class

The main entry point for the plugin. This class handles plugin initialization, sets up all managers and listeners on enable, processes the /caps command and routes to appropriate handlers.

Command Handlers:

• handleListCommand() - Shows warnpoints for players
• handleAddCommand() - Adds warnpoints to players
• handleRemoveCommand() - Removes warnpoints from players
• handleReloadCommand() - Reloads the configuration

Key Methods:

• onEnable() - Initializes plugin, loads config and data
• onCommand() - Routes commands to appropriate handlers
• colorize(String) - Translates ampersand color codes to Minecraft format

2. ConfigManager.java - Configuration Handler

Manages all configuration values and provides a centralized API for accessing settings.

Configuration Categories:

• Detection Settings: getCapsLimit(), getCapsPercentLimit()
• Action Settings: shouldBlockMessage(), shouldNotifyAdmins()
• Warnpoint Settings: getWarnPointKeepTime(), threshold getters
• Messages: getMessage(String) with placeholder support
• Permissions: getPermission(String) for permission nodes
• Commands: getCommand(String) for punishment commands

Time Parsing: The parseTime() method converts human-readable time strings into milliseconds:

• m = minutes
• h = hours
• d = days

Example: "3h" becomes 10800000 milliseconds (3 hours)

3. WarnPointManager.java - Warning Point System

The core of the warnpoint system, handling storage, expiration, and punishment execution.

Key Features:

• Data Persistence: Saves and loads warnpoints to warnpoints.yml
• Expiration Tracking: Each warnpoint has a given time and expiration time
• Automatic Cleanup: Background task removes expired points every minute
• Punishment Thresholds: Automatically executes configured commands at thresholds
• Player Notifications: Notifies players when points are added, removed, or expired

Data Structure:

PlayerName:
  - given: 1234567890000
    expire: 1234578690000
  - given: 1234567891000
    expire: 1234578691000

Key Methods:

• addWarnPoints(String, int) - Adds points and checks thresholds
• removeWarnPoints(String, int) - Removes points from player
• getWarnPoints(String) - Gets current active point count
• showWarnPoints(Sender, String) - Displays detailed point information
• startCleanupTask() - Starts background cleanup task

Punishment Logic: The checkPunishmentThresholds() method checks points in order:

1. Ban threshold (highest priority)
2. Mute threshold
3. Warn threshold (lowest priority)

Only one punishment is executed per check to prevent stacking.

4. ChatListener.java - Chat Event Handler

Monitors player chat messages and detects caps spam in real-time.

Detection Algorithm:

1. Preprocessing: Removes non-alphabetic characters for accurate analysis
2. Consecutive Caps Check: Counts the longest streak of uppercase letters
3. Percentage Check: Calculates the ratio of uppercase to total letters
4. Threshold Comparison: Triggers if BOTH thresholds are exceeded

Event Flow:

Player sends message
    ↓
Bypass check (caps.admin.bypass)
    ↓
Caps detection algorithm
    ↓
If spam detected:
    ├── Block message (optional)
    ├── Add warnpoint (optional)
    ├── Notify player
    └── Notify admins (optional)

Key Methods:

• onPlayerChat(AsyncPlayerChatEvent) - Main event handler
• detectCapsSpam(String, ConfigManager) - Detection algorithm

5. CapsCommand.java - Command Executor

Handles all player commands including help menu, listing, adding, and removing warnpoints.

Key Methods:

• onCommand() - Routes commands to appropriate handlers
• showHelpMenu() - Displays formatted help with all commands, version, and source
• handleList() - Shows warnpoints
• handleAdd() - Adds warnpoints
• handleRemove() - Removes warnpoints
• handleReload() - Reloads configuration
• onTabComplete() - Provides tab completion

Configuration System

The config.yml file is divided into logical sections:

Detection Settings:

caps-limit: 5
caps-percent-limit: 80

Action Settings:

block-message: true
notify-admins: true
collect-warnpoints: true

Warnpoint Thresholds:

warnpoints-until-warn: 3
warnpoints-until-mute: 5
warnpoints-until-ban: -1

Messages: All messages support:

• Color codes with ampersand
• Placeholders: {PLAYER}, {remWP}, {tookWP}, {tookPlayer}, {permNeeded}, {dateGiven}, {dateExpire}, {timeLeft}

Commands

Command	Description	Permission
/caps list	View your own warnpoints	caps.player.listpoints
/caps list player	View another player's warnpoints	caps.player.listpoints.others
/caps add player points	Add warnpoints to a player	caps.admin.givepoints
/caps remove player points	Remove warnpoints from a player	caps.admin.takepoints
/caps reload	Reload the plugin configuration	caps.admin.reload

Aliases: /capswarn, /cw

Permissions

Admin Permissions

• caps.admin.* - All admin permissions
• caps.admin.givepoints - Add warnpoints to players
• caps.admin.takepoints - Remove warnpoints from players
• caps.admin.reload - Reload configuration
• caps.admin.notify - Receive caps detection notifications
• caps.admin.bypass - Bypass caps detection entirely

Player Permissions

• caps.player.* - All player permissions
• caps.player.listpoints - View own warnpoints (default: true)
• caps.player.listpoints.others - View other players' warnpoints (default: op)

External Plugin Integration

CapsWarn supports integration with popular punishment plugins through configurable commands:

Example with AdvancedBan:

commands:
  warn: "advancedban:warn {PLAYER} Excessive Caps usage"
  mute: "advancedban:tempmute {PLAYER} 10m Caps abuse"
  ban: "advancedban:tempban {PLAYER} 30m Continued caps abuse"

Example with LiteBans:

commands:
  warn: "warn {PLAYER} Excessive capital letters in chat"
  mute: "tempmute {PLAYER} 10m Caps spam"
  ban: "tempban {PLAYER} 30m Persistent caps abuse"

Placeholders in Commands:

• {PLAYER} - The player's name
• {remWP} - Remaining warnpoints the player has

Data Storage

Warnpoints are stored in plugins/CapsWarn/warnpoints.yml in the following format:

PlayerName:
  - given: 1704067200000
    expire: 1704078000000
  - given: 1704067300000
    expire: 1704078100000

The file is automatically:

• Created on first plugin load
• Saved when warnpoints are modified
• Saved during plugin shutdown
• Cleaned of expired points every minute

Building from Source

Requirements:

• Java 8 or higher
• Maven 3.6+

Build Steps:

git clone https://git.basicsites.ddns.net/RGBToaster/capswarn.git
cd CapsWarn
mvn clean package

The compiled JAR will be in target/capswarn-1.1.3.jar

Installation

1. Download or compile the plugin JAR file
2. Place capswarn-1.1.3.jar in your server's plugins/ folder
3. Restart your server or load the plugin with a plugin manager
4. Edit plugins/CapsWarn/config.yml to customize settings
5. Run /caps reload to apply changes

License

This project is licensed under the GNU General Public License version 2 (GPL-2.0).

You can view the full license text in the LICENSE file.

What This Means

• You can use this plugin freely on your server
• You can modify and distribute your own versions
• You must keep the same GPL-2.0 license on modifications
• You must provide source code for any distributed modifications
• No warranty is provided with this software

For more information about GPL-2.0, visit: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html

How to Support

Contributing to CapsWarn

We welcome contributions from the community! Here's how you can help improve CapsWarn:

Report Bugs

Found a bug? Please open an issue with:

• A clear, descriptive title
• Steps to reproduce the issue
• Expected vs. actual behavior
• Your Minecraft/Paper version
• CapsWarn version
• Any relevant console errors or logs

Suggest Features

Have an idea for improvement? Open a feature request including:

• A clear description of the feature
• Why it would be useful
• How it should work
• Any relevant examples or mockups

Submit Pull Requests

Ready to contribute code? Follow these steps:

1. Fork the repository on Gitea
2. Create a feature branch from main:

   git checkout -b feature/your-feature-name
   

3. Make your changes following our coding standards:
   • Use proper Java naming conventions
   • Add comments for complex logic
   • Follow the existing code style
   • Test your changes thoroughly
4. Commit your changes with clear commit messages:

   git commit -m "Add: new feature description"
   

5. Push to your fork:

   git push origin feature/your-feature-name
   

6. Open a Pull Request with:
   • A clear title and description
   • Reference any related issues
   • Explanation of what changed and why
   • Screenshots or videos if applicable

Improve Documentation

Documentation improvements are always appreciated:

• Fix typos or unclear explanations
• Add examples or use cases
• Translate documentation to other languages
• Create video tutorials or guides

Testing

Help us test new features:

• Try out development builds
• Report compatibility issues
• Verify bug fixes
• Test on different server software (Spigot, Paper, etc.)

Join the Discussion

• Share your server's experience with CapsWarn
• Help other users with questions
• Provide feedback on proposed changes
• Participate in feature discussions

Coding Standards

When contributing code, please follow these guidelines:

Java Style:

• Use 4 spaces for indentation (no tabs)
• Opening braces on the same line
• Descriptive variable and method names
• JavaDoc comments for public methods
• Keep methods focused and concise

Commit Messages:

• Use prefixes: Add:, Fix:, Update:, Remove:, Docs:
• Keep the first line under 72 characters
• Add detailed description if needed

Testing:

• Test on a local server before submitting
• Verify the plugin loads without errors
• Test all affected commands and features
• Check console for warnings or errors

Code of Conduct

By contributing to CapsWarn, you agree to:

• Be respectful and constructive
• Welcome newcomers to the project
• Accept constructive criticism gracefully
• Focus on what's best for the community
• Show empathy towards other contributors

Support

If you need help with CapsWarn:

• Check this README for documentation
• Open an issue for bugs or questions
• Join our community discussions
• Contact the maintainers

Credits

Developed by: RGBToaster

Built with:

• Paper API - Minecraft server software
• Maven - Build automation

Changelog

Version 1.1.3 (Current)

• Fixed warnpoint removal bug where deleted points persisted in memory and file
• Improved help menu with formatted command display
• Updated version and source repository information

Version 1.0.0

• Initial release
• Caps detection system
• Warning point management
• Configurable thresholds and commands
• Data persistence
• Full command system
• Permission-based access control

Minecraft Version: 1.16+
Java Version: 8+