Skip to main content

​
Quick start

Solve your first research puzzle in minutes.

​
Prepare the game

1

Install and activate the resource pack

Make sure the custom resource pack is installed and active in your Minecraft settings.
The bot cannot recognize puzzles without the required resource pack.
2

Set up the research table

  1. Open a Research Table in-game
  2. Place an unsolved Research Notes item in the table
  3. Make sure only the initially given aspects are on the board
The puzzle board should be clean - no aspects placed except the starting ones provided by the research notes.
3

Position your game window

  • Ensure the game window is on your main screen
  • The window should be large enough for clear recognition
  • Hide any tooltips covering the puzzle board
  • Consider hiding NEI if it overlaps (default GTNH keybind: O)

​
Run the bot

1

Open a terminal

Navigate to the project folder and open a terminal:
cd path/to/thaumcraft4-research-bot
You can use Windows Terminal, PowerShell, or Command Prompt.
2

Start the bot

Run the main command:
uv run main
The bot will automatically:
  1. Bring the game window to the foreground
  2. Take a screenshot
  3. Parse the puzzle board
  4. Generate an optimal solution
  5. Place aspects using mouse control
3

Watch the magic happen

The bot will log its progress:
MODE= None
Saving sample image, Board hash is a3f5c2
Starting solve computation
Time taken to compute solution: 0.342 seconds
Total solution cost: 12
The mouse will move automatically to place aspects. Don’t move your mouse during this process.

​
Emergency stop

If the mouse control goes wrong, smash your mouse into the top-left corner of the screen for an emergency stop.

​
Process next board

After the bot finishes placing aspects:
1

Complete the research

The puzzle should now be solved. Complete the research in-game if needed.
2

Load next puzzle

  1. Put in the next unsolved Research Notes
  2. Press Enter in the terminal to solve the next board
  3. Or press r to retry placing aspects for the current solution

​
Using test mode

Test the bot without performing any mouse actions: 
uv run main test
This mode:
  • Reads from debug_input.png instead of taking a screenshot
  • Parses and solves the puzzle
  • Skips all mouse clicks and window actions
  • Saves the solution render to debug_render.png
Test mode is useful for verifying puzzle recognition and solver performance without affecting your game.

​
Configuration

Create a config.toml file in the project root to customize behavior: 
# Thaumcraft 4 Research Bot Configuration

[general]
# Title (or beginning of title) of the game window
game-window-title = "GT: New Horizons"

# Global hotkey to process the next board
next-board-hotkey = "ctrl+r"

# Disable aspects (pretend they don't exist)
disabled-aspects = []

[aspect-costs]
# Override default aspect costs
# Lower costs are preferred by the solver
# Example: if you have lots of instrumentum
instrumentum = 1
The config file is automatically created with defaults on first run if it doesn’t exist.

​
Understanding aspect costs

The solver minimizes total aspect cost when generating solutions:
  • Primal aspects (aer, aqua, terra, ignis, ordo, perditio) cost 1 by default
  • Compound aspects cost the sum of their components
    • victus = aqua + terra = 2
    • herba = terra + victus = 3
    • instrumentum = humanus + ordo = higher cost
Customize costs in config.toml to reflect your actual inventory: 
[aspect-costs]
# If you have abundant instrumentum, make it cheaper
instrumentum = 1

​
Advanced: Test all mode

Benchmark the solver on multiple puzzles: 
uv run main test_all
This runs the solver on all images in the test_inputs/ folder and reports:
  • Parse time
  • Solve time
  • Solution cost
Useful for validating that all board types can be solved.

​
Troubleshooting

Update the game-window-title in config.toml to match your actual window title.
  • Verify the custom resource pack is active
  • Ensure the game window is fully visible on the main screen
  • Check that no tooltips are covering the puzzle board
  • Make sure the window is large enough
Large boards with 7+ starting aspects can take longer. Consider:
  • Using test mode to pre-validate the puzzle
  • Waiting patiently (it will complete)
  • Checking if there are any disabled aspects that could simplify the solution
Currently there’s no built-in speed control. The default speed is tested to work consistently on most systems.

​
Next steps

You’re ready to automate all your Thaumcraft research! The bot will:
  • Save screenshots of each puzzle to test_inputs/ for debugging
  • Generate debug renders showing the solution path
  • Remember you can press r to retry or Enter to continue

Report issues

Found a bug? Include the generated debug_input.png when reporting issues on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us