Troubleshooting

• Don’t move your mouse while the bot is placing aspects
• Ensure the game window remains focused
• Check that the game window is on your main screen
• Verify the window isn’t at negative screen coordinates

1. Game window is not on the main screen
2. Window was moved/resized after screenshot was taken
3. GUI scale in Minecraft doesn’t match expected size
4. Window is at negative screen coordinates

• Move the game window to your primary monitor
• Let the bot maximize the window automatically (don’t resize manually)
• Keep the window maximized during operation
• Check debug_render.png to see if aspect positions were detected correctly

• Reduce Minecraft lag (lower graphics settings, close background apps)
• Modify timing delays in src/utils/mouseactions.py:10-22:

def drag_mouse_from_to(window_base_coords, start, end):
    # Increase these sleep values for slower movement
    sleep(0.03)  # Try 0.05 or 0.1
    gui.mouseDown()
    sleep(0.03)  # Try 0.05 or 0.1
    gui.moveTo(end_x, end_y)
    sleep(0.03)  # Try 0.05 or 0.1

• Move the game window to positive coordinates (preferably on the main screen)
• Let the bot reposition the window automatically (it moves it to 10, 10)
• Ensure the game window is on your primary monitor

1. Verify the resource pack is installed:
   • Copy minecraft_resource_pack/ to .minecraft/resourcepacks/
   • Activate “Thaumcraft Research Bot Textures” in Minecraft
2. Check the debug_render.png file:
   • It should show detected aspect positions
   • If aspects are missing, the resource pack may not be active
3. Ensure tooltips aren’t covering the board:
   • Hide NEI (press O in GTNH)
   • Move your mouse away from the puzzle board before starting
4. Check board detection:
   • The puzzle should only have initially given aspects (no manually placed ones)
   • Empty hexagons must be clearly visible

• Game window is minimized
• Window is on a secondary monitor not being captured
• Screenshot permissions issue

• Ensure game window is maximized and visible
• Move window to primary monitor
• Run the terminal/IDE as administrator (Windows permissions)
• Check that the game window matches game-window-title in config

Exception: Wrong number of game windows: 0

1. Check your game window title (look at the window’s title bar)
2. Update config.toml:
   [general]
   game-window-title = "Your Exact Window Title"
   
3. Remember: The setting matches the beginning of the title, not the whole thing

game-window-title = "GT: New Horizons"

Exception: Wrong number of game windows: 2

• Close extra Minecraft instances
• Make your game-window-title more specific
• Ensure only one Minecraft window is open

1. Completely stop the bot (Ctrl+C)
2. Edit config.toml
3. Restart with uv run main

tomllib.TOMLDecodeError: Invalid TOML

• Strings not in quotes: game-window-title = GT: New Horizons ❌
• Correct: game-window-title = "GT: New Horizons" ✓
• Missing brackets in arrays: disabled-aspects = "caelum", "tabernus" ❌
• Correct: disabled-aspects = ["caelum", "tabernus"] ✓
• Wrong section syntax: general ❌
• Correct: [general] ✓

• Small boards (2-4 aspects): < 1 second
• Medium boards (5-6 aspects): 1-5 seconds
• Large boards (7-8 aspects): 5-30 seconds
• Very large boards (9+ aspects): 30+ seconds to minutes

• Be patient - the solver will eventually find a solution
• Check debug_render.png to see if the board was parsed correctly
• Consider solving very large puzzles manually

1. Check the terminal output for error messages
2. Look at debug_render.png - it shows how the board was interpreted
3. Verify debug_input.png is a clear screenshot of the puzzle

• Board wasn’t parsed correctly (holes detected wrong)
• Disabled aspects that are required for the solution
• Board has aspects manually placed (should only have initial aspects)

• The debug_input.png file
• The debug_render.png file
• The terminal error output
• Your config.toml (especially disabled-aspects)

Duplicate coordinate (x, y) found in solution!
Invalid solution detected! Some hexes have multiple aspects assigned!

1. Check debug_render.png to see the invalid solution
2. Report this on GitHub with:
   • debug_input.png
   • debug_render.png
   • Terminal output
3. Try running again with r (retry) or process the next board

1. Aspects are in a different position than expected
2. Resource pack isn’t working for those specific aspects
3. Tooltip is covering the aspect

• Check debug_render.png to see which aspects were detected
• Ensure all aspects are visible (no tooltips covering them)
• Verify resource pack is active
• Try researching a simpler aspect first to verify detection works

“When crafting an aspect we never had before, the screen positions of other aspects may change, which can break this!” (see src/utils/mouseactions.py:53)

• Craft missing aspects manually before starting
• Answer “n” when asked about automatic crafting
• Ensure you have all compound aspects in your inventory

1. Answer “y” when prompted
2. Watch the first few crafts carefully
3. If positions get misaligned, stop and restart

1. Install uv following the official guide
2. On Windows, you may need to restart your terminal
3. Verify installation: uv --version

“No Linux Support - I don’t want to deal with finding a universal way of taking screenshots and performing mouse input”

• Screenshot libraries behave differently on Linux
• Mouse control varies by window manager/compositor
• Would require significant additional development

ModuleNotFoundError: No module named 'pyautogui'

• Use uv run main (not python main.py)
• uv automatically installs dependencies
• If issues persist, delete .venv folder and try again

• Run terminal as administrator (Windows)
• Check folder permissions
• Ensure the project folder isn’t read-only
• Close image viewers that might have the files locked