BotBlocker

A Minecraft Bukkit/Spigot plugin and Fabric mod designed to limit bot intrusion!
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Versions of the Project
3. Functionality
   • Initialization
   • Player Join
   • Player Quit
   • Commands
   • Permissions
   • Configuration Files
4. Getting Started
   • Prerequisites
   • Installation
5. Usage
6. Compiling this plugin
7. Contributing
8. License
9. Contact
10. Acknowledgments

About The Project

BotBlocker is a solution for Minecraft servers designed to limit bot intrusion. It is available for both Bukkit/Spigot Minecraft servers and as a Fabric mod. If a user logs out too quickly after joining (indicating they might be a bot), the user is banned. This approach limits the number of login attempts from each UUID, effectively mitigating the consequences of a bot attack.

As of version 1.4.0 BotBlocker supports integration with:

• BanManager
• LuckPerms

Built With

• 
• Bukkit/Spigot

(back to top)

Versions of the Project

Bukkit/Spigot BotBlocker

Fabric BotBlocker

(back to top)

Functionality

Initialization

When the server starts, BotBlocker initializes its configuration files (config.yml and players.yml). The initial default time limit for joining and leaving is set to 5 seconds. A message indicating the mod has successfully loaded with the set time limit is logged to the console.

Player Join

When a player joins, if BotBlocker is enabled and the player is not already exempt from BotBlocker's checks, the mod/plugin records the player's UUID and the current time.

Player Quit

When a player quits, BotBlocker calculates the duration of their connection. If this time is less than the set time limit and BotBlocker is enabled, the player is considered a bot. They get banned and a ban entry is added to the players.yml file. A disconnect message is sent to the player and a message is logged to the console. If the player stays longer than the time limit, they are deemed a legitimate player. Their UUID is added to the players.yml file as exempt.

Commands

• /BotBlocker enable - Enable the BotBlocker plugin.
• /BotBlocker disable - Disable the BotBlocker plugin.
• /BotBlocker status - Show wether BotBlocker is enabled or disabled.
• /BotBlocker setTimeLimit [seconds] - Set the time limit for detecting bots. Default is 5 seconds.
• /BotBlocker getTimeLimit - Display the configured time limit for detecting bots.
• /BotBlocker setBanMessage [message] - Set the ban message.
• /BotBlocker getBanMessage - Display the configured ban message.

Permissions

• botblocker.enable - Allows the user to enable the BotBlocker plugin.
• botblocker.disable - Allows the user to disable the BotBlocker plugin.
• botblocker.status - Allows the user to see whether BotBlocker is enabled or disabled.
• botblocker.settimelimit - Allows the user to set the time limit for detecting bots.
• botblocker.gettimelimit - Allows the user to display the configured time limit for detecting bots.
• botblocker.setbanmessage - Allows the user to set the ban message.
• botblocker.getbanmessage - Allows the user to display the configured ban message.

Configuration Files

BotBlocker maintains its configuration and the list of player UUIDs in config.yml and players.yml files, respectively.

Note

Players identified as legitimate are marked as such in the players.yml file and are not checked again in the future. If BotBlocker is disabled, it stops checking players for potential bot activity.

(back to top)

Getting Started

To get this plugin up and running on your server, follow these steps:

Prerequisites

• Java 18 or later
• A Bukkit/Spigot server

Installation

1. Download the latest BotBlocker .jar file from the releases page.
2. Move the downloaded .jar file to the plugins/ directory in your server.
3. Restart your server. This will generate a default configuration file.

(back to top)

Usage

Once installed and enabled, BotBlocker works in the background without any intervention. If needed, you can adjust the bot protection parameters in the generated config.yml file.

(back to top)

Compiling this plugin

To compile BotBlocker for Bukkit/Spigot yourself, follow these steps:

1. Make sure you have Maven installed on your system. You can download it from https://maven.apache.org/download.cgi and find installation instructions at https://maven.apache.org/install.html.

2. Clone this repository.

3. Open your terminal or command prompt.

4. Navigate to the root directory of the cloned repository.

   cd path/to/BotBlocker
   

5. Execute the Maven build command:

   mvn clean package
   

   • The clean command will remove any previous build outputs to ensure a fresh build.
   • The package command will compile your code and package it into a JAR file.

6. After the build completes, you can find the compiled JAR file in the target directory of the project.

7. The JAR file will be named following the convention BotBlocker-M.m.p.jar, where M.m.p is the version number following Semantic Versioning.

8. You can now deploy this JAR file to your Bukkit/Spigot server's plugins folder.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE for more information.

(back to top)

Contact

Aitor Astorga Saez de Vicuña - a.astorga.sdv@gmail.com

Project Link: https://github.com/BotBlocker-Minecraft

(back to top)

Acknowledgments

• https://github.com/othneildrew/Best-README-Template

(back to top)