Language: 简体中文 / English

DolphinBot-Reloaded

✨ A lightweight, reliable, intelligent MC bot for general minecraft server, with high-scalability and performance. It integrated plugin loaders like bukkit and easy-used interface styled APIs, allows you to customize event handles. ✨

📖Docs · 🐛Submit Suggestion/Bug

Why DolphinBot?

• High reliability, low network utilization, auto-reconnect when disconnected, long term running with no worries for losing connection.
• High programmability, DolphinBot implemented a SpringBoot-like finite StateMachines, allows you to easily configure multiple login-process for different servers.
• High extensibility, DolphinBot embedded a mature DolphinAPI that contains variety of packet listeners, event systems and easy-used event handlers based on mc protocol lib, It integrates a bukkit-like plugin API, allowing you to develop custom plugins at very short time.
• Advanced logging system, DolphinAPI also implemented TextComponent serializer to parse rich colors and styles for server messages, with more useful debug information.
• High performance, DolphinBot allows you to start multiple bot instances at single client with low CPU and Memory usage.
• Easy to use, directly run, you can put the bot profile(s) into config file instead of defining on command-line, fast start.

Shortcuts: Custom plugin developing guideline

Features:

• Easy to register custom commands starting with ! by using CommandBuilder DolphinAPIs.
• Can hot-inject plugins during the connection of server.
• Bypassing human verification in most servers including 2b2t.xin.
• Supporting to configure the bot clusters, and start at once.
• Supporting colourful console logging strings expression colorizeText("&6Hello &lWorld").
• Automatic answer questions in 2b2t.xin for speeding up login process.
• Supporting to configure proxy settings for multiple bots.

Screenshots:

Running on Windows server 2019:

Introduction:

Features category:

• Hot-Reloading Plugin
• Terminal Interactions
• Packet Debugger
• Proxy Settings

Implemented Event APIs:

• Programmable State Machine
• Command System
• Packet Handlers
• Event Handler System
  • Player Events
• Force Unicode Chat

Interactions in Terminal

• You can send in-game messages or execute commands form the dolphin bot terminal.

• Built-in commands:

• Terminal Commands	Description
  reload <Plugin Name> <bot name (optional)>	Hot-reloading a specified plugin
  load <PLugin Name> <bot name (optional)>	Hot-loading a specified plugin
  respawn	Respawn the bot when in game.
  license (l, lic)	Show the license on the terminal
  help (h, ?)	Show the Command menu and usages for each command

• For these commands, you can press TAB to complete automatically.

Getting Started

In this section, you will understand below how-tos:

• 1. How to directly start a single bot with command-line.
• 2. How to specify bot profile with config file without command-line.
• 3. How to start multiple bot simultaneously with proxy settings
• 4. How to configure advanced options
• 5. How to make a custom plugin

1. Download the Client
   Download the jar archive file: DolphinBot-[version]-full.jar.

Important

Requirements: Java version >= 17

2. Configuration of the Bot

Configuring Profile

There are two different ways to set bot config:

• If you want to quickly start for simplicity, you can use Command-line setting
• If you would like to start multiple bot at once, and access advanced options, you can use Config file setting

1. Command-line Setting
   In-game profile should be defined on below boot command-line.
   An example of argument list:

   java -jar "DolphinBot-[version]-full.jar" --username=[username] --password=[password] --skin-recorder=[enable/disable]

   Command Lines	Description
   --username	in-game displaying name of bot.
   --password	password for login or register.
   --auto-reconnect	whether reconnect to server when got kicked or disconnect by some reasons.
   --skin-recorder	whether automatic capture and save online players' skins.
   --server	target server address.
   --port	target server port.

   Example:

   java -jar "DolphinBot-[version]-full.jar" --username=[username] --password=[password] --server=0.0.0.0 --port=25565

   java -jar "DolphinBot-[version]-full.jar" --username=Dolphin1 --password=123 --server=2b2t.xin --port=25565 --owner=Melibertan

   

Note

Command-line has high authority than config file, meaning that if options are duplicated, will only recognize command-line, and ignore config file one.

Tip

Optionally, you can specify more option by adding argument:
--owner : Specifying only who can use this bot.

Example:
--owner=Melibertan, of course, you also can define multiple names. For each owner name, should be split with ";".
Example:
--owner=owner1;owner2;owner3;...

Config File Setting

Config files include functional config mc.bot.config.json and profile config bot.profiles.json
You can also move above profile arguments into config file bot.profiles.json following below formats, all config values in it will be loaded. DolphinBot will apply command-line options first, duplicated options in config file will be ignored.
To specify the path of config file is optional, Use option --config-file to locate config directory or file.
For example:

java -jar "DolphinBot-[version].jar" --config-file=path/to/config.json

If the path you specified is a directory instead of a file, Dolphin will extract config file as default config in this directory.

java -jar "DolphinBot-[version].jar" --config-file=path/to/config_directory

If the --config-file parameter is absented, DolphinBot will create a default file on jar directory.

java -jar "DolphinBot-[version].jar"

multiple bot & proxy settings
In the profile config file, you can create profiles field in bot.profiles.json to specify multiple bot profiles to log to a server.

Note

Some servers may prohibit multiple bots started on same IP, the proxy settings is aimed to help you to run multiple bots from different network environments or requiring distinct egress IPs.

To configure proxy settings for each bot, you need to edit proxy field. An example shown below:

Warning

Defining multiple bots may trigger the anti-bot or anti-cheat, and some servers with strict policy may prohibit it.

{
   "profiles": {
      "bot#1": {
         "name": "Player494",
         "password": "123example",
         "owner": ["player_name"],
         "enabled_plugins": [
            "QuestionAnswerer",
            "MessageDisplay",
            "HumanVerify"
         ],
         "proxy": {
            "enabled": false,
            "info": {
               "address": "XX.XXX.XXX.XX",
               "port": 8081,
               "type": "SOCKS4",
               "username": "",
               "password": ""
            }
         }
      },
      "bot#2": {
         "name": "Player495",  
         "password": "password",
         "owner": ["player_name", "other_owner"],
         "enabled_plugins": [
            "HumanVerify"
         ],
         "proxy": {
            "enabled": false,
            "info": {"...": "..."}
         }
      },
      "bot#3": {"...": "..."}
   }
}

1. enabled_plugins field represents which plugins should enable on the bot.

2. proxy fields (optional) represents a proxy configurations for each bot, field enabled marks whether activate this proxy setting,
   and field info contains:

   field	Description
   address	Remote IP address or host name of proxy server.
   port	Proxy server port.
   type	Proxy mode. (HTTP, SOCKS4, SOCKS5)

Tip

"username", "password" is optional, if the remote proxy server require to auth, then you need to add these.

In this case, if you want to load bot#1 as your single bot, you should add below argument:

java -jar "DolphinBot-[version].jar" --config-file=path/to/config_directory --profiles="bot#1"

java -jar "DolphinBot-[version].jar" --profiles="bot#1"

If you want to start multiple bot simultaneously, specify multiple profile name as a list in option --profiles, for each profile name, should be split with ";".

Examples:

java -jar "DolphinBot-[version].jar" --profiles="bot#1;bot#2;bot#3;..."

Note

If the --profiles option is absented, it will load all bots in profile config by default.

Owners:
If you want to limit a bot can be only use by specified player(s) you can put player names into owner as list.
Example:

{
   "profiles": {
      "bot#1": {
         "name": "Player494",
         "password": "123example",
         "owner": [
            "owner1", 
            "owner2",
            "owner3"
         ],
         "enabled_plugins": [ "QuestionAnswerer", "MessageDisplay", "HumanVerify" ],
         "proxy": {
            "enabled": false,
            "info": {
               "address": "XX.XXX.XXX.XX",
               "port": 8081, 
               "type": "SOCKS4",
               "username": "",
               "password": ""
            }
         }
      }
   }
}

Advanced Configurations (optional)

If you want to access more advanced configs, you can edit mc.bot.config.json.
Every single config option is equilibrium to option that defined by command line, and all config value including unrecognized option will be parsed, so you can add your customize config options.
An example for configuring this file:

{
  "server": "2b2t.xin",
  "port": 25565,
  "auto-reconnect": true,
  "packet-filter-delay": 0,
  "msg-send-delay": 0,
  "max-chunk-view": 12,
  "anti-AFK": true,
  "language": "zh",
  "connect-timing-out": 2000,
  "reconnect-delay": 5000,
  "debug-settings": {
    "enable-packet-debug": false,
    "packet-warning": true
  },
  "other": {
    "enable-skin-recorder": false
  }
}

Config Options:

Config	Description
server	For defining server address.
port	For defining server port.
auto-reconnecting	Whether reconnect to server when got kicked or disconnect by some reasons.
enable-skin-recorder	Whether enable skin recorder.
packet-filter-delay	Max receiving delay(millis) between every target packet.
max-chunk-view	Max scale of chunk packet receiving.
connect-timing-out	How long millis does it take to determine a connection time out.
reconnect-delay	Min delay(millis) for cooling down when reconnect a server.
msg-send-delay	The delay of sending in-game messages.
enable-packet-debug	Whether enable packet debugger.
packet-warning	Showing packet errors or not.
language	The UI locale settings. (Supports zh, en languages currently)
anti-AFK	Whether bypassing AFK（Away From Keyboard) detection.

Hot Swapping Plugins In-Game

Dolphin bot supports you to hot-reload and hot-load (hot injection) plugins in server, without quit the entire client and reconnecting to server. You can send !reload <pluginName> dolphin command in server chat.
Alternatively, you can type reload plugin.jar in the terminal to hot-reload plugins.

FAQ

• Can I make my plugin for dolphin bot?
  Yes, DolphinBot has an easy used plugin system, aggregating bukkit-like API, here is the Full guideline for development.

• Is it difficult to configure the config files?
  No, the initial config is highly sufficient to use for most cases.

• How do I put issues or request features?
  Open an issue bar on GitHub Issues. Detailed steps or reproduce are appreciated.

• Can I join the DolphinBot development?
  Sure! you can become the second contributor of DolphinBot team! you can join at any time freely.

Our First Contributor:

1. huangdihd - (Fixed a critical bug in commit(#372990a)

Community

• Encountered a bug? issues and suggestions are welcome!
  My Bilibili space: https://m.bilibili.com/space/386644641
• If you like DolphinBot, a star helps a lot!

License

GPL-3.0 or later, see the full LICENSE.

By NeonAngelThreads, coding with ❤️