python main.py --vortex --browser chrome --force-primary

What it does:

• Positions Vortex and Chrome windows
• Scans primary monitor only
• Handles modern green download buttons
• Clicks through Vortex dialogs automatically

Best for: Clean single-monitor setups

python main.py --vortex --browser firefox --legacy

What it does:

• Uses legacy button templates
• Handles "Staging" and "Understood" dialog buttons
• Works with older Nexus Mods layout
• Compatible with Firefox

Best for: Users on older Nexus Mods UI or with legacy template preferences

python main.py --window-title "Wabbajack" --force-primary

What it does:

• Brings Wabbajack window to foreground
• Detects Wabbajack-specific download buttons
• Monitors primary display
• Handles Wabbajack download flow

Best for: Wabbajack modlist installations

python main.py --force-primary

What it does:

• Detects Website and Wabbajack download buttons only
• No Vortex integration (direct browser downloads)
• Monitors primary display
• Simpler workflow for non-Vortex users

Best for: Users downloading mods directly through browser without Vortex, or Wabbajack installations

python main.py --vortex --browser chrome --debug-frame-dir ./debug_frames --verbose

What it does:

• Saves every detection frame as PNG
• Draws bounding boxes around detected buttons
• Prints detailed state machine logs
• Helps diagnose false positives/negatives

Best for: Debugging detection issues or multi-monitor setups

python main.py --min-matches 12 --ratio 0.70 --click-delay 3.0

What it does:

• Requires 12 SIFT feature matches (stricter)
• Uses 0.70 Lowe ratio threshold
• Waits 3 seconds between scan iterations
• Reduces false positives

Best for: High-accuracy requirements or avoiding misclicks

python main.py --vortex --browser chrome

What it does:

• Captures entire virtual desktop (all monitors)
• Detects buttons anywhere on screen
• Positions windows automatically

Best for: Multi-monitor setups where windows may be on any display

Possible Causes:

• Windows are minimized or occluded
• Wrong button templates for your Nexus Mods UI version
• Detection threshold too strict

Solutions:

1. Ensure browser and Vortex windows are visible and not minimized
2. Try lowering --min-matches threshold:

   python main.py --min-matches 5

3. Check if you need --legacy flag for old Nexus Mods UI
4. Enable debug mode to see what's being detected:

   python main.py --debug-frame-dir ./debug --verbose

5. Verify windows are on the monitor being scanned (try --force-primary)

Possible Causes:

• Detection threshold too lenient
• Similar UI elements matching templates
• Multiple monitors with ambiguous content

Solutions:

1. Increase strictness with --min-matches:

   python main.py --min-matches 12

2. Lower the ratio threshold:

   python main.py --ratio 0.65

3. Use --force-primary to limit scan area
4. Review debug frames to identify false matches:

   python main.py --debug-frame-dir ./debug

Cause: Full automation requires Windows with pywin32

Solutions:

• On Windows: Ensure pywin32 is installed:

  pip install pywin32

• On macOS/Linux: Use simulation mode for testing:

  python main.py --simulate

• Alternative: Run in a Windows VM or container

Solutions:

1. Reinstall all dependencies:

   pip install -r requirements.txt --force-reinstall

2. Verify Python version (3.9+ required):

   python --version

3. Check for missing packages:

   python validate.py

4. Ensure virtual environment is activated

Possible Causes:

• Windows not running or title mismatch
• Fullscreen mode interfering
• Multi-monitor confusion

Solutions:

1. Manually position windows before starting NexusAutoDL
2. Use exact window title substring with --window-title:

   python main.py --window-title "Nexus Mods - Google Chrome"

3. Ensure windows are in windowed mode (not fullscreen)
4. On multi-monitor setups, manually move windows to primary display
5. Check window manager logs with --verbose

Possible Causes:

• DPI scaling issues on Windows
• Window moved between detection and click
• Incorrect coordinate transformation

Solutions:

1. Disable Windows DPI scaling for Python:
   • Right-click python.exe → Properties → Compatibility
   • Check "Override high DPI scaling behavior"
2. Increase --click-delay to ensure pages load:

   python main.py --click-delay 3.0

3. Keep windows stationary during operation
4. Report issue with debug frames