Troubleshooting Guide¶

This guide helps you solve common issues with the Visual Aim Assist Tool.

Table of Contents¶

Antivirus Issues
Detection Problems
Performance Issues
Aiming Issues
Triggerbot Problems
Build Errors
General Issues

Antivirus Issues¶

Problem: Antivirus flags the tool as malware¶

Symptoms: - Windows Defender shows "Trojan:Win32/Wacatac.B!ml" - Other antivirus software blocks or quarantines the executable - Cannot run the tool without it being deleted

Solutions:

Add an exclusion (see Security Information for detailed instructions)
Verify it's a false positive:
Review the source code in this repository
Compile from source yourself
Submit to VirusTotal and review behavioral analysis
Report the false positive to your antivirus vendor

Use Windows Defender specific steps:

# Temporarily disable real-time protection (not recommended long-term)
Set-MpPreference -DisableRealtimeMonitoring $true

# Re-enable after adding exclusion
Set-MpPreference -DisableRealtimeMonitoring $false

Detection Problems¶

Problem: Tool doesn't detect any colors¶

Possible Causes & Solutions:

Wrong window title
Check the window setting in config.json
It should partially match your game window title
Try running the game in windowed or borderless windowed mode
Incorrect colors
Verify the color codes match what's on screen
Use a color picker tool to get exact hex values
Increase tolerance value (try 100-150)
Color space mismatch
Try different color_space values: "bgr", "rgb", or "hsv"
BGR is typically correct for OpenCV captures
FOV too small
Increase fov value to search a larger area
Enable debug overlay to see the FOV circle
Area filters too restrictive
Lower min_area if targets are small
Raise max_area if targets are being filtered out
Debug overlay not showing anything
Ensure debug: true in config
Check console output for errors
Verify the game window is not minimized

Problem: Detects wrong objects/background¶

Solutions:

Tighten color matching
Decrease tolerance value
Be more specific with color codes
Adjust area filters
Increase min_area to ignore small noise
Decrease max_area to ignore large background elements
Use HSV color space
HSV can be more selective than BGR/RGB
Adjust tolerance_h, tolerance_s, tolerance_v independently

Performance Issues¶

Problem: Tool causes lag or stuttering¶

Solutions:

Reduce target FPS
```
{
    "target_fps": 60
}
```
Decrease FOV
```
{
    "fov": 150
}
```
Disable debug overlay
```
{
    "debug": false
}
```
Lower resolution
Run game at lower resolution
Smaller frames = faster processing
Close other applications
Free up CPU resources
Especially other screen capture software

Problem: High CPU usage¶

Solutions:

Set appropriate FPS limit
Don't use target_fps: 0 (unlimited) unless necessary
60-120 FPS is usually sufficient
Optimize detection parameters
Smaller FOV = less pixels to process
Stricter color tolerance = fewer contours to analyze
Check for memory leaks
Restart the tool periodically
Update to latest version if available

Aiming Issues¶

Problem: Aim is too jumpy/jittery¶

Solutions:

Increase smoothness
```
{
    "smoothness": 0.8
}
```
Reduce max strength
```
{
    "max_strength": 0.02
}
```

Enable steady aim

{
    "steady_aim": true,
    "steady_dist": 30.0
}

Add minimum strength floor
```
{
    "min_strength": 0.01
}
```

Problem: Aim is too slow/sluggish¶

Solutions:

Decrease smoothness
```
{
    "smoothness": 0.4
}
```
Increase max strength
```
{
    "max_strength": 0.08
}
```
Increase target FPS
```
{
    "target_fps": 144
}
```

Problem: Aim misses the target¶

Solutions:

Adjust offset values

{
    "offset_x": 0.0,
    "offset_y": 0.0
}

Positive offset_y aims lower
Negative offset_y aims higher

Fine-tune lead prediction

{
    "lead": 0.0  // Disable for stationary targets
}

Check calibration
Ensure game sensitivity is consistent
Test in controlled environment first

Problem: Aim goes to wrong target¶

Solutions:

Adjust scoring priorities
The tool typically selects closest to crosshair
Reduce FOV to limit candidate targets
Improve color specificity
More specific colors = fewer false targets
Use multiple specific colors if needed

Adjust area filters

{
    "min_area": 50,
    "max_area": 500
}

Triggerbot Problems¶

Problem: Triggerbot doesn't fire¶

Solutions:

Check if enabled
Press F2 to toggle
Verify triggerbot: true in config
Adjust trigger distance
```
{
    "trigger_dist": 20.0
}
```
Increase if it's not firing soon enough
Decrease for more precision
Check trigger button
Ensure you're holding the correct mouse button
Default is right click ("trigger": "right")
Verify detection is working
Enable debug overlay
Confirm targets are being detected

Problem: Triggerbot fires too fast/slow¶

Solutions:

Adjust trigger delay

{
    "trigger_delay": 50  // milliseconds
}

Lower = faster fire rate
Higher = slower fire rate
Match to your weapon's fire rate
Check game limitations
Some games have internal fire rate limits
Server tick rate may affect perceived fire rate

Build Errors¶

Problem: CMake cannot find dependencies¶

Windows:

# Ensure vcpkg is properly integrated
vcpkg integrate install

# Specify toolchain explicitly
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Linux:

# Install missing dependencies
sudo apt-get install libopencv-dev nlohmann-json3-dev

# Or for Fedora
sudo dnf install opencv-devel nlohmann-json-devel

Problem: OpenCV not found¶

Solutions:

Verify installation

# Linux
pkg-config --modversion opencv4

# Windows (vcpkg)
vcpkg list

Specify OpenCV directory
```
cmake .. -DOpenCV_DIR=/path/to/opencv
```

Problem: X11 errors on Linux¶

Solutions:

Install X11 development libraries

sudo apt-get install libx11-dev libxext-dev libxtst-dev

Ensure XShm is available
Most modern X11 installations include it
Check with xdpyinfo | grep SHM

General Issues¶

Problem: Tool crashes on startup¶

Solutions:

Check config file syntax
Validate JSON syntax at jsonlint.com
Ensure all required fields are present
Run as administrator (Windows)
Right-click → Run as Administrator
Some systems require elevated privileges for input simulation
Check console output
Error messages often indicate the problem
Look for missing dependencies or permission issues
Try default config
Delete/rename existing config.json
Let the tool generate a fresh one

Problem: Hotkeys don't work¶

Solutions:

Check for conflicts
Other software may be intercepting F1-F4
Try closing other applications
Run as administrator
Global hotkeys may require elevated privileges
Verify application is running
Check task manager for the process
Look for console output

Problem: Config changes don't take effect¶

Solutions:

Restart the application
Most config changes require a restart
Close completely (F4) and relaunch
Check config file location
Ensure you're editing the correct config.json
Check both executable directory and AppData/.config locations
Validate JSON syntax
Malformed JSON may cause silent failures
Use a JSON validator

Still Having Issues?¶

If you've tried all the above and still have problems:

Check the repository issues - Someone may have reported the same problem
Review recent updates - A recent change may have introduced a bug
Gather information:
Console output/error messages
Your configuration file
System specifications
Steps to reproduce
Open a new issue with the gathered information

Quick Reference Table¶

Symptom	First Thing to Try
Antivirus flag	Add exclusion, verify source
No detection	Check window title, increase tolerance
Jumpy aim	Increase smoothness, reduce max_strength
Slow aim	Decrease smoothness, increase max_strength
Triggerbot not firing	Increase trigger_dist, check F2 toggle
High CPU usage	Lower target_fps, reduce fov, disable debug
Build fails	Install dependencies, check paths
Crashes on startup	Validate config JSON, run as admin

Additional Resources¶

Configuration Guide - Understand all settings
Usage Guide - Learn how to use features
Building Guide - Compile from source
Security Information - Antivirus false positive details