Botcraft
Botcraft is a cross-platform C++ library to create bots that connect and interact with Minecraft servers with (optional) integrated OpenGL renderer
Install / Use
/learn @adepierre/BotcraftREADME
This is a "learn-by-doing" pet project I develop on my free time when I feel like it. I share the code for people that might be interested but it's more a "shared private repo" than a real open source community project. I usually try to push updates on master every first week of each month, and as soon as they are ready for new Minecraft version support updates.
Precompiled binaries of the library and examples can be found in the latest release for both Windows and Linux. To compile it yourself, you can check the Building section.
Content
- Features
- Dependencies
- Building and testing
- Examples
- ProtocolCraft
- Clients
- Connection
- Mod support
- License
Features
Main features are listed below. To see the evolution of the project, check the changelog.
- Connection to minecraft server (both offline "cracked" mode and online connection with ~~Mojang or~~ Microsoft account)
- DNS server name resolution with and without SRV record
- All official releases from 1.12.2 to 1.21.11 supported
- Compression
- Signed chat system for 1.19+ versions
- Vanilla physics and collisions (wiki page for details)
- World data
- Full entity support (type, data, metadata and attributes)
- (Optional) Rendering of all the blocks (including entity-blocks like chests, banners...) and entities (bounding box only)
- Bot programming with a behaviour tree system (wiki page for details)
- Extremely resource efficient (CPU/RAM) bots (<5 Mb for AFK bots, <60 Mb for other bots in headless mode)
- Bot control with mouse and keyboard
- Custom framework to easily test the bot behaviours on a vanilla server (wiki page for details)
Available bot behaviours includes:
- Pathfinding (including ladder/scaffolding climbing, see wiki page)
- Block breaking (including with correct tool/haste effects)
- Inventory managing (including interactions with chest/anvil/brewing stand...)
- Block placing (vanilla or mid-air)
- Entity interactions
- Item use (fishing rods, food eating...)
- Block interaction (button, lever, bed...)
- Villager trading (only for versions 1.14+)
- Crafting
Not supported
- Anti-cheat evasion: Botcraft actions/movements are most of the time vanilla-like, but not human-like. Only use Botcraft on your own servers or ask permission first if you don't want your account to be banned.
- Modded servers: Botcraft aims to be compatible with vanilla server first. When possible, modded servers are also (partially) supported, but given the large diversity of servers and mods, Botcraft does not aim to work on every possible server/mod combination. See mod support section for details.
- Rendering and UI may not work on macOS due to platform incompatibility. Everything can run fine even with GUI enable, but macOS will not display the rendering window, making it pointless. I recommend using
BOTCRAFT_USE_OPENGL_GUI=OFFon macOS.
Nice gifs
Example with 10 survival bots collaborating on a pixel art build. They are all in survival, so they have to pick the right blocks in the chests, eat food and obviously can't fly. There is no global supervision, and they can't communicate with each other.
Complex pathfinding example. The bot has to climb through various blocks as well as fall in water or vines.
Integrated behaviour explorer UI. It supports navigation (translation, zoom, subtree hiding), current and previous nodes status indicator, breakpoints and step by step mode for easy debugging. For more details, see the behaviour system wiki page.
Other gifs/videos can be found in the Visuals folder.
Dependencies
The code is cross-platform and requires a C++17 compiler, as well as git and CMake. I try to keep the number of external libraries for the core part of the library very low (currently only one is mandatory, plus two optionals for additional features). This is less true for the rendering part or testing. Dependencies are included either directly(*) or as git submodules(†). All libraries marked as optional are automatically enabled/disabled based on cmake options.
You don't have to clone recursively, download nor install any of them: the cmake build system is made to do that for you automatically for each dependency that is not already found on your system. The only exceptions are Java, to launch the test server if enabled, and doxygen to generate the doc. They need to be installed on your system manually.
- asio† for low-level TCP
Optional dependencies (additional features support):
Optional dependencies (rendering):
- glad* for OpenGL stuff
- glfw† for OpenGL window creation
- glm† for math stuff
- imgui† with node-editor† extension for additional UI display
- rectpack2D† for texture packing
- stb_image* for texture loading and screenshot saving
Optional dependencies (testing)
- catch2† for tests management
- subprocess.h* to launch the vanilla test server
- Java 8 for Minecraft < 1.17, 17 for Minecraft < 1.20.5, 21 for Minecraft 1.20.5+ to run the vanilla test server
Optional dependencies (doc generation)
- doxygen for documentation generation
- doxygen-awesome-css* for documentation layout
Building and testing
To build the library yourself, with both encryption and compression support, but without OpenGL rendering support:
git clone https://github.com/adepierre/Botcraft.git
cd Botcraft
mkdir build
cd build
cmake -DBOTCRAFT_GAME_VERSION=latest -DCMAKE_BUILD_TYPE=Release -DBOTCRAFT_BUILD_EXAMPLES=ON -DBOTCRAFT_BUILD_TESTS=ON -DBOTCRAFT_BUILD_TESTS_ONLINE=ON -DBOTCRAFT_COMPRESSION=ON -DBOTCRAFT_ENCRYPTION=ON -DBOTCRAFT_USE_OPENGL_GUI=OFF ..
cmake --build . --config Release
# Run all tests (optional)
ctest -C Release
# Build doc (optional)
cmake --build . --target doc_doxygen
At this point, you should have all the examples compiled and ready to run, the tests performed and the documentation generated. Please note that you don't have to clone recursively or download and install the dependencies manually, cmake will automatically take care of these steps based on your build configuration and what is already installed on your machine. On Windows with Visual, you can also use cmake-gui and then compile the .sln directly from Visual. For a detailed Windows building tutorial, see this wiki page.
You can use this template for an example of how to setup a botcraft project. In case you need help, you can try to ask on the community discord server.
There are several cmake options you can modify:
- BOTCRAFT_GAME_VERSION [1.XX.X or latest]
- BOTCRAFT_BUILD_EXAMPLES [ON/OFF]
- BOTCRAFT_BUILD_TESTS [ON/OFF]
- BOTCRAFT_BUILD_TESTS_ONLINE [ON/OFF] To build additional tests. Requires BOTCRAFT_COMPRESSION and java to launch a local vanilla server.
- BOTCRAFT_OUTPUT_DIR [PATH] Base output build path. Binaries, assets and libs will be created in subfolders of this path (default: top project dir)
- BOTCRAFT_COMPRESSION [ON/OFF] Add compression ability, must be ON to connect to a server with compression enabled
- BOTCRAFT_ENCRYPTION [ON/OFF] Add encryption ability, must be ON to connect to a server in online mode
- BOTCRAFT_USE_OPENGL_GUI [ON/OFF] If ON, botcraft will be compiled with the OpenGL GUI enabled
- BOTCRAFT_USE_IMGUI [ON/OFF] If ON, additional information will be displayed on the GUI (need BOTCRAFT_USE_OPENGL_GUI to be ON)
- BOTCRAFT_WINDOWS_BETTER_SLEEP [ON/OFF] If ON, thread sleep durations will be more accurate (only for Windows 10/11, no effect on other OS)
- BOTCRAFT_USE_PR
