https://github.com/hypoxic127/fh6-afk
๐๏ธ Fully automated super wheel farming bot for Forza Horizon 6, powered by Computer Vision & Virtual Gamepad
https://github.com/hypoxic127/fh6-afk
afk-farming automation bot computer-vision forza-horizon-6 opencv python
Last synced: 23 days ago
JSON representation
๐๏ธ Fully automated super wheel farming bot for Forza Horizon 6, powered by Computer Vision & Virtual Gamepad
- Host: GitHub
- URL: https://github.com/hypoxic127/fh6-afk
- Owner: hypoxic127
- Created: 2026-05-24T13:10:42.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-02T00:34:34.000Z (28 days ago)
- Last Synced: 2026-06-02T01:19:07.173Z (28 days ago)
- Topics: afk-farming, automation, bot, computer-vision, forza-horizon-6, opencv, python
- Language: Python
- Homepage:
- Size: 13 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ๐๏ธ FH6 AutoBot โ A Never-Ending AFK Farming Machine
**๐ Language: English | [ไธญๆ](README_zh-CN.md)**
[](https://github.com/hypoxic127/FH6-AFK/actions/workflows/ci.yml)
[](https://github.com/hypoxic127/FH6-AFK/actions/workflows/release.yml)
> A fully automated, infinite-loop Skill Points farming system for **Forza Horizon 6**.
> Powered by **Computer Vision (OpenCV + Tesseract OCR)** and **Virtual Gamepad (ViGEmBus)**, achieving **zero human intervention** closed-loop farming.
> Comes with a **Cyberpunk-styled Web UI** dashboard for remote monitoring and one-click control.
---
## ๐ Table of Contents
- [โจ Features](#-features)
- [๐ Workflow](#-workflow)
- [๐ ๏ธ Tech Stack](#๏ธ-tech-stack)
- [๐ Getting Started](#-getting-started)
- [๐ Usage](#-usage)
- [๐ Project Structure](#-project-structure)
- [๐งช Testing & CI](#-testing--ci)
- [๐ Technical Details](#-technical-details)
- [๐ค Contributing](#-contributing)
- [๐ License](#-license)
---
## โจ Features
| Feature | Description |
|:--------|:------------|
| ๐ **4-Stage Auto Loop** | Farm โ Buy โ Upgrade โ Sell, infinite loop, sleep & farm |
| ๐๏ธ **Computer Vision State Machine** | Color histogram + OCR hybrid detection, identifies 10+ game UI states |
| ๐ฎ **Virtual Gamepad** | ViGEmBus simulates Xbox 360 controller, native-level input |
| ๐ฅ๏ธ **Web UI Dashboard** | Glassmorphism UI + real-time logs + QR code mobile monitoring |
| โน๏ธ **Instant Stop** | Thread injection technology, bot stops immediately on button click |
| ๐ฐ **Super Wheelspin Counter** | Automatically tracks upgrade macro executions |
| ๐ฆ **One-Click Build** | PyInstaller single-file `.exe`, no Python required |
| ๐งช **95 Test Cases** | Ruff linting + Pytest coverage, GitHub Actions CI |
---
## ๐ Workflow
```
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ
โ ๐๏ธ Farm โโโโโโถโ ๐ Buy โโโโโโถโ โก Upgrade โโโโโโถโ ๐๏ธ Sell โ
โ Skill Pointsโ โ Cars โ โ Cars โ โ Cars โ
โโโโโโโโฌโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโฌโโโโโโโ
โ โ
โ โป๏ธ Infinite Loop โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
| Stage | State Constant | Description |
|:-----:|:---------------|:------------|
| 1๏ธโฃ | `STATE_FARM_POINTS` | OCR scans skill points โ auto-enters EventLab to farm up to 999 |
| 2๏ธโฃ | `STATE_BUY_CARS` | Five-step visual navigation โ batch-purchase 33 Subaru Impreza 22B-STIs |
| 3๏ธโฃ | `STATE_UPGRADE_CARS` | Select each car with NEW tag โ spend skill points on skill tree |
| 4๏ธโฃ | `STATE_TRASH_CARS` | Batch-remove upgraded Imprezas (keeping S2 main car) |
---
## ๐ ๏ธ Tech Stack
| Category | Technology | Purpose |
|:---------|:-----------|:--------|
| **Vision Engine** | OpenCV, Tesseract OCR | Image processing, text recognition, color detection |
| **Numerics** | NumPy | Histogram comparison, image matrix operations |
| **Screen Capture** | MSS | High-performance cross-platform screenshots |
| **Gamepad** | VGamepad + ViGEmBus | Virtual Xbox 360 controller input |
| **Web Server** | Flask + Flask-SocketIO | Real-time Web UI control panel |
| **Frontend** | Vanilla JS + CSS3 | Glassmorphism dashboard, WebSocket live logs |
| **Testing** | Pytest + Ruff | Unit testing + code quality checks |
| **Packaging** | PyInstaller | One-click single-file executable build |
| **CI/CD** | GitHub Actions | Automated testing + Release publishing |
---
## ๐ Getting Started
### ๐ Prerequisites
> โ ๏ธ The following software must be installed before running
| Software | Version | Download | Notes |
|:---------|:--------|:---------|:------|
| **Python** | 3.10+ | [python.org](https://www.python.org/downloads/) | Check "Add to PATH" during install |
| **Tesseract OCR** | 5.x | [Download](https://github.com/UB-Mannheim/tesseract/releases) | Check "Add to PATH" during install |
| **ViGEmBus** | Latest | [Download](https://github.com/ViGEm/ViGEmBus/releases) | **Reboot required** after install |
### ๐ฅ Installation
```bash
# 1. Clone the repository
git clone https://github.com/hypoxic127/FH6-AFK.git
cd FH6-AFK
# 2. One-click install (auto-creates venv + installs dependencies)
python setup.py
# 3. Launch (Web UI mode)
python main_bot.py --web
```
### ๐ฎ In-Game Preparation
Before starting the bot, ensure the following:
1. **Game language must be set to English** โ OCR depends on English text
2. **Windowed mode** โ Windowed or Borderless Windowed (recommended: 2560ร1440)
3. **Purchase main car** โ `1998 Subaru Impreza 22B-STI Version`
4. **Install S2 tune** โ Any S2-class tune (PI badge = blue)
5. **Favorite the EventLab blueprint** โ Share code `890169683`
6. **Enable Auto-Steering** โ Go to `Settings โ Difficulty โ Auto-Steering: ON`. The bot relies on auto-steering for autonomous driving in EventLab
> **โ ๏ธ Important:** The S2 **blue PI badge** on the main car is the sole indicator the program uses to distinguish "keep" vs "deletable" cars. Make sure your main car has an S2 tune applied.
---
## ๐ Usage
### ๐ Web UI Mode (Recommended)
```bash
python main_bot.py --web # Default port 6800
python main_bot.py --web --port 8080 # Custom port
```
Open `http://localhost:6800` in your browser to access the control panel:
- ๐ฏ **Live Status** โ Current stage, loop count, runtime, super wheelspin count
- ๐ **Progress Bar** โ Visual 4-stage progress indicator
- โ๏ธ **Stage Selector** โ Start from any stage via dropdown
- ๐ **Live Log Terminal** โ Syntax-highlighted real-time log stream
- ๐ฑ **QR Remote Monitoring** โ Scan QR code to monitor from your phone
### ๐ป Terminal Mode
```bash
python main_bot.py
```
| Option | Function | When to Use |
|:------:|:---------|:------------|
| `[0]` | ๐ Auto loop (full cycle) | Main menu โ full 4-stage infinite loop |
| `[1]` | ๐๏ธ Farm Skill Points | Main menu โ enter EventLab |
| `[2]` | ๐ Buy Cars | Main menu โ batch purchase Imprezas |
| `[3]` | โก Upgrade Cars | Main menu โ spend skill points |
| `[4]` | ๐๏ธ Sell Cars | In garage, Subaru brand selected |
| `[5]` | โญ๏ธ Skip Buy loop | When garage already has un-upgraded cars |
### ๐ฆ Build Executable
```bash
python packaging/build.py
```
Produces `dist/FH6AutoBot.exe` โ portable, no Python needed (Tesseract & ViGEmBus still required).
> **๐ก Tip:** Push a git tag (e.g. `git tag v1.2.0 && git push --tags`) to auto-trigger GitHub Actions build and publish to the Releases page.
---
## ๐ Project Structure
```
FH6_AutoBot/
โ
โโโ main_bot.py # ๐ Entry point (Terminal / Web UI)
โ
โโโ engine/ # ๐ง Perception Engine
โ โโโ ocr.py # Computer vision (OCR + color detection)
โ โโโ state_detect.py # Game state detector (histogram + OCR hybrid)
โ โโโ event_bus.py # Event bus (log/state push to Web UI)
โ โโโ runtime.py # PyInstaller runtime path resolution
โ โโโ utils.py # Logging / window ops / gamepad / MSS capture
โ
โโโ macro/ # ๐ฎ Macro Operations
โ โโโ master_loop.py # Master state machine (4-stage loop engine)
โ โโโ core.py # Infrastructure: screenshots, logging, constants
โ โโโ navigation.py # Menu navigation / visual braking / return-to-garage
โ โโโ purchase.py # 5-step Impreza purchase navigation
โ โโโ garage.py # Garage grid: select / delete / main car nav
โ โโโ upgrade.py # Upgrade macro (Cannot Afford detection)
โ
โโโ farm/ # ๐ EventLab Farming
โ โโโ skills.py # Visual state machine (auto-drive + finish detection)
โ
โโโ web/ # ๐ Web UI Control Panel
โ โโโ server.py # Flask + SocketIO server
โ โโโ state_manager.py # Global state manager
โ โโโ static/ # Frontend assets
โ โโโ index.html # Dashboard page
โ โโโ style.css # Cyberpunk theme styles
โ โโโ app.js # WebSocket client logic
โ
โโโ packaging/ # ๐ฆ Build & Packaging
โ โโโ build.py # One-click PyInstaller build script
โ โโโ FH6AutoBot.spec # PyInstaller spec (--onefile)
โ โโโ hook_utf8.py # Runtime hook (Windows UTF-8 fix)
โ
โโโ tests/ # ๐งช Unit Tests (95 cases)
โโโ tools/ # ๐ง Dev utilities (not packaged)
โ
โโโ .github/workflows/
โ โโโ ci.yml # CI (Ruff check + Pytest)
โ โโโ release.yml # Release (PyInstaller โ GitHub Release)
โ
โโโ setup.py # โ๏ธ One-click environment setup
โโโ requirements.txt # ๐ Python dependencies
โโโ ruff.toml # ๐ Ruff linter config
โโโ pytest.ini # ๐งช Pytest config
```
---
## ๐งช Testing & CI
```bash
# Run all tests
python -m pytest
# Lint check
python -m ruff check .
# Format check
python -m ruff format --check .
```
| CI Job | Trigger | Description |
|:-------|:--------|:------------|
| **Lint** | Push / PR | Ruff lint + format validation |
| **Test** | Push / PR | 95 test cases (ubuntu-latest) |
| **Release** | `v*` tag | PyInstaller build โ GitHub Release |
---
## ๐ Technical Details
### ๐๏ธ Visual State Detection
- **Histogram + OCR Hybrid** โ `StateDetector` uses color distribution features for fast candidate screening, then OCR for precise verification
- **PI Badge Color Detection** โ HSV color space analysis: blue = S2 main car (keep), orange = deletable
### ๐ค OCR Strategy
- **Dual PSM Mode** โ Uses PSM 8 (single word) + PSM 7 (single line), picks the result with most digits
- **OTSU Adaptive Thresholding** โ Prevents single-digit zero-padding errors
- **Zero Skill Points Fallback** โ Detects "No Skill Points Available" text
### ๐ฏ Garage Grid Navigation
- **Typewriter Traversal** โ Column by column, top to bottom (3รN grid)
- **Triple Verification** โ OCR keywords (2/3 match) + NEW yellow tag + LEGENDARY orange rarity
- **Cannot Afford Detection** โ Auto-dismisses popup, stops purchasing
### ๐ฆ Build & Packaging
- **PyInstaller --onefile** โ Single ~44MB executable
- **Runtime Path Layer** โ `engine/runtime.py` unified path resolution (dev/packaged dual-mode)
- **UTF-8 Console Fix** โ `hook_utf8.py` resolves Chinese log garbling on Windows
---
## ๐ค Contributing
Contributions are welcome! Please follow this workflow:
1. **Fork** this repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a **Pull Request**
### Development Standards
- ๐ Code style: PEP 8 (enforced by Ruff)
- ๐ท๏ธ Commit format: [Conventional Commits](https://www.conventionalcommits.org/) (`feat` / `fix` / `docs` / `refactor` / `chore`)
- โ
All PRs must pass CI checks (Lint + Test)
---
## ๐ License
This project is for **learning and personal use** only.
---
**If this project helps you, please give it a โญ Star!**
Made with โค๏ธ by [hypoxic127](https://github.com/hypoxic127)