Skip to main content

​
Installation

Get the bot up and running on your system.

​
Prerequisites

1

Python version

Python 3.12 or higher is required.Check your Python version:
python --version
2

Operating system

Windows is required for screenshot and mouse control functionality.
Linux is not supported due to platform-specific requirements for window management and input control.
3

Minecraft setup

You need:
  • Minecraft 1.7.10
  • Thaumcraft 4 installed
  • A modpack that uses Thaumcraft 4 (tested with GTNH)

​
System requirements

  • Display: Main screen with sufficient resolution for the Minecraft window
  • RAM: Standard Python runtime requirements
  • Disk space: Minimal (< 100 MB for dependencies)

​
Install uv

uv is a fast Python package manager and runner that simplifies dependency management. Install uv following the official documentation: 
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
The bot uses uv to automatically manage dependencies and the Python environment. You don’t need to create a virtual environment manually.

​
Download the project

1

Get the source code

Download the latest release or clone the repository:
git clone https://github.com/leumasme/thaumcraft4-research-bot.git
cd thaumcraft4-research-bot
Or download and unzip the source code into a new folder.
2

Verify project structure

Your project folder should contain:
  • src/ - Main source code
  • pyproject.toml - Project configuration
  • README.md - Documentation

​
Dependencies

The project uses the following key dependencies (automatically installed by uv): 
[project]
requires-python = ">=3.12"
dependencies = [
    "pillow>=10.4.0",      # Image processing
    "pyautogui>=0.9.54",   # Mouse control
    "numpy>=2.2.0",        # Numerical operations
    "keyboard>=0.13.5",    # Keyboard input
]

​
Install the resource pack

A custom resource pack is required for the pixel-based puzzle recognition to work correctly.
The resource pack provides visual markers that help the bot identify puzzle elements:
  1. Download the required resource pack from the project repository
  2. Install it in your Minecraft instance
  3. Activate it in the game settings
Make sure the resource pack is active before running the bot, or puzzle recognition will fail.

​
Verify installation

Test that everything is set up correctly: 
uv run main test
If uv is installed correctly, it will download dependencies and run in test mode. You should see output indicating it’s looking for debug_input.png.

​
Next steps

Quick start guide

Learn how to solve your first research puzzle

Build docs developers (and LLMs) love

Get started for freeTalk to us