Skip to main content
The Research Bot can be built into a standalone executable for distribution, or run directly from source for development.

​
Prerequisites

​
Required Software

1

Install Python 3.12+

The project requires Python 3.12 or later.
winget install Python.Python.3.12
2

Install uv

uv is a fast Python package manager and runner.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
3

Clone the Repository

git clone https://github.com/leumasme/thaumcraft4-research-bot.git
cd thaumcraft4-research-bot
Or download and extract the ZIP from GitHub.

​
Running from Source

​
Quick Start

The fastest way to run the bot: 
uv run main
The uv run command automatically:
  1. Creates a virtual environment
  2. Installs dependencies
  3. Runs the bot

​
Runtime Dependencies

From pyproject.toml:7-12: 
[project]
requires-python = ">=3.12"
dependencies = [
    "pillow>=10.4.0",
    "pyautogui>=0.9.54",
    "numpy>=2.2.0",
    "keyboard>=0.13.5",
]
PackagePurpose
pillowImage processing and screenshot analysis
pyautoguiMouse control and window interaction
numpyNumerical operations for image data
keyboardGlobal hotkey detection
All dependencies are automatically installed by uv run. You don’t need to install them manually.

​
Development Setup

​
Installing Dev Dependencies

For code formatting, linting, and building: 
uv sync --dev
This installs additional development tools from pyproject.toml:14-20: 
[tool.uv]
dev-dependencies = [
    "black>=24.8.0",
    "isort>=5.13.2",
    "nuitka>=2.8.9",
    "ruff>=0.6.7",
]
ToolPurpose
blackCode formatter
isortImport statement organizer
nuitkaPython to C compiler for building executables
ruffFast Python linter

​
Code Formatting

Format all Python files: 
uv run black src/
uv run isort src/

​
Linting

Check code quality: 
uv run ruff check src/
Auto-fix issues: 
uv run ruff check --fix src/

​
Project Structure

thaumcraft4-research-bot/
├── src/
│   ├── __main__.py          # Entry point and main logic
│   ├── utils/
│   │   ├── config.py        # Configuration management
│   │   ├── aspects.py       # Aspect cost calculation
│   │   ├── grid.py          # Hex grid data structures
│   │   ├── finder.py        # Image recognition
│   │   ├── window.py        # Window management
│   │   ├── mouseactions.py  # Mouse control
│   │   ├── renderer.py      # Debug visualization
│   │   └── log.py           # Logging utilities
│   └── solvers/
│       └── ringsolver.py    # Research puzzle solver
├── pyproject.toml           # Project configuration
├── config.toml              # User configuration (auto-generated)
├── debug_input.png          # Latest screenshot
├── debug_render.png         # Solution visualization
└── test_inputs/             # Saved test boards

​
Building Executables

​
Using Nuitka

Nuitka compiles Python to C for better performance and standalone distribution. From README.md:90-91: 
uv run -m nuitka --python-flag=-m --output-dir=dist --mode=onefile --lto=yes src

​
Build Options Explained

OptionDescription
--python-flag=-mRun as module (enables __main__.py)
--output-dir=distOutput directory for the executable
--mode=onefileCreate a single executable file
--lto=yesEnable link-time optimization for smaller size
srcSource directory to compile

​
Build Process

1

Compilation

Nuitka compiles Python to C, then to machine code. This takes several minutes:
Nuitka: Starting compilation...
Nuitka: Compiling module 'src'
Nuitka: Compiling module 'src.utils.config'
...
2

Linking

All dependencies are bundled into a single executable:
Nuitka: Creating single file from dist/src.dist
Nuitka: Using onefile compression: yes
3

Output

The final executable appears in dist/:
dist/
└── src.exe          # Windows
    or src.bin       # Linux
    or src.app       # macOS
Building executables requires a C compiler:
  • Windows: Visual Studio or MinGW-w64
  • Linux: gcc (usually pre-installed)
  • macOS: Xcode Command Line Tools

​
Advanced Build Options

For smaller executables: 
uv run -m nuitka --python-flag=-m --output-dir=dist --mode=onefile --lto=yes \
  --remove-output --assume-yes-for-downloads src
For debugging builds: 
uv run -m nuitka --python-flag=-m --output-dir=dist --mode=standalone \
  --enable-console --debug src
Use --mode=standalone instead of --mode=onefile for faster startup times. This creates a directory with the executable and dependencies instead of a single file.

​
Distribution

​
Pre-built Releases

Download official releases from GitHub Releases. From README.md:79-80:
To run as a non-technical user:
Download and run the .exe from the releases page

​
Creating Releases

1

Build the executable

uv run -m nuitka --python-flag=-m --output-dir=dist --mode=onefile --lto=yes src
2

Test the executable

./dist/src.exe  # Windows
./dist/src.bin  # Linux
./dist/src.app  # macOS
3

Package dependencies

Include the resource pack and README:
zip release.zip dist/src.exe README.md resource-pack/
4

Upload to GitHub

Create a new release on GitHub and attach the ZIP file.

​
Testing Builds

​
Verify Functionality

Test the built executable in all modes: 
./dist/src.exe

​
Performance Comparison

Compare performance between source and compiled:
MetricSource (uv run)Compiled (Nuitka)
Startup time~2-3 seconds<1 second
Solve timeSameSame
File sizeN/A~50-80 MB

​
Troubleshooting

​
Common Build Errors

Problem: Pillow not bundled correctlySolution: Ensure Pillow is in dependencies and rebuild:
uv sync
uv run -m nuitka --python-flag=-m --output-dir=dist --mode=onefile --lto=yes src
Problem: No C compiler installedSolution: Install a C compiler:
  • Windows: Install Visual Studio with C++ tools
  • Linux: sudo apt install build-essential
  • macOS: xcode-select --install
Problem: Antivirus flags the executable as suspiciousSolution: This is common with Nuitka builds. Add an exclusion or use code signing for distribution.
Problem: Bundled dependencies are largeSolution: Use standalone mode for faster startup:
uv run -m nuitka --python-flag=-m --output-dir=dist --mode=standalone --lto=yes src

​
Runtime Issues

Problem: config.toml not found Solution: The executable creates config.toml in the current working directory. Run from a writable location.
Problem: Performance degradation Solution: Nuitka builds should be faster. Check if antivirus is scanning the executable on each run.

​
Platform-Specific Notes

​
Windows

  • Requires Visual Studio 2017 or later for building
  • Executable name: src.exe
  • Default console application (window appears)

​
Linux

  • Not officially supported (no screenshot/mouse libraries tested)
  • Build may work but runtime will fail
  • See README.md:47-48 for Linux limitation

​
macOS

  • Not officially supported
  • Requires code signing for distribution
  • May need additional permissions for screen capture
No Linux/macOS Support: The bot uses Windows-specific libraries (pygetwindow, pyautogui) that don’t work reliably on other platforms.

​
Continuous Integration

For automated builds, use GitHub Actions:
.github/workflows/build.yml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - name: Install uv
        run: pip install uv
      - name: Build
        run: uv run -m nuitka --python-flag=-m --output-dir=dist --mode=onefile --lto=yes src
      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: executable
          path: dist/src.exe
Use GitHub Actions to automatically build executables on every commit or release tag.

Build docs developers (and LLMs) love

Get started for freeTalk to us