WT Cruise

Local desktop cruise-assist for War Thunder. It reads the upper-left HUD indicated airspeed with a calibrated screen crop, OpenCV preprocessing, and EasyOCR, then adjusts throttle through simulated mouse-wheel input.

Default controls:

• F8: toggle cruise assist
• F9: lower target speed by 10 km/h
• F10: raise target speed by 10 km/h
• Esc: quit

The normal user path is the desktop app. It provides setup guidance, OCR region calibration, one-click start/stop, live status, GPU mode, and advanced PD/control tuning.

Setup

With conda, a typical setup is:

conda create -n wt-cruise python=3.11 -y
conda activate wt-cruise
cd D:\Project\warthunder
pip install -e .

EasyOCR depends on PyTorch. The default setting is CPU OCR (ocr_easyocr_gpu: false) because it works on machines without NVIDIA CUDA. If pip install -e . does not install a working PyTorch build for your machine, install CPU torch and torchvision first, then run pip install -e . again.

GPU OCR is optional. Only enable ocr_easyocr_gpu when the user has installed a CUDA PyTorch build that matches their GPU driver. A CUDA build is not portable across all users, so public packaged builds should be made from a CPU-only PyTorch environment.

Tesseract remains available as an optional backend, but the default backend is EasyOCR.

Open the desktop app:

wt-cruise-app

The old settings command opens the same app:

wt-cruise-settings

or:

wt-cruise --settings

The command-line runner is still available. It prints the active config path, OCR backend, GPU mode, crop rectangle, target speed, control parameters, hotkeys, and debug log path before opening the legacy overlay.

Run the CLI with EasyOCR GPU mode for this launch:

wt-cruise --gpu

Force CPU mode for this launch:

wt-cruise --cpu

Configuration

Most users should edit settings in wt-cruise-app. config.yaml remains available for manual editing:

• target_speed_kmh: starting target speed.
• speed_step_kmh: F9/F10 target adjustment step.
• ocr_region: screen crop in left/top/width/height pixels. Tune this to tightly cover the indicated airspeed value, not the entire HUD.
• ocr_interval_ms: OCR/control period. 250-500 ms is a practical starting range.
• ocr_backend: default easyocr. Optional fallback: tesseract.
• ocr_easyocr_gpu: whether EasyOCR should use GPU mode. Default is false for broad compatibility; GPU requires a matching CUDA PyTorch install.
• ocr_tesseract_cmd: optional full path to tesseract.exe.
• ocr_tesseract_psm: Tesseract page segmentation mode. 7 means single text line and is the default for the HUD speed crop.
• full_throttle_margin_kmh: when target minus actual is at least this value, use strong throttle-up scrolls.
• deadband_kmh: no wheel output while speed error is within this range.
• wheel_scale: global multiplier for all wheel output.
• max_accel_scrolls: strong acceleration scroll cap per control tick.
• max_trim_scrolls: near-target throttle-up scroll cap per control tick.
• max_decel_scrolls: overspeed throttle-down scroll cap per control tick.
• pd_enabled: enables PD control.
• pd_kp: proportional gain applied to current speed error.
• pd_kd: derivative gain applied to error rate.
• pd_accel_kd: optional derivative gain when error is rising.
• pd_decel_kd: optional derivative gain when error is falling. The current default values preserve the previous lookahead behavior because old lookahead maps directly to Kd when Kp=1.0.

The app includes a screenshot-based calibration tool. It freezes the screen, lets you drag a rectangle around the speed number, previews the crop, tests OCR, and saves global screen coordinates to ocr_region.

OCR Debugging

The OCR logic does not search the whole screen. It captures the fixed rectangle from ocr_region, preprocesses that crop with OpenCV, runs EasyOCR in digit-only detection mode, then selects the leftmost valid 2-4 digit number inside ocr_min_speed_kmh and ocr_max_speed_kmh. This handles cases like 696 66 by using 696 and ignoring the later false block.

To verify the crop from the CLI before loading EasyOCR models, run this while the game HUD is visible:

wt-cruise --debug-capture debug_ocr

Open debug_ocr/ocr_crop.png and confirm it tightly contains only the indicated airspeed value, for example 1450 km/h. Open debug_ocr/ocr_processed.png to see the preprocessed image that OCR receives. If either image includes altitude, speed, throttle percentage, labels, or too much sky/background, adjust ocr_region in config.yaml.

For a direct EasyOCR-only test, run:

wt-easyocr-test --output debug_easyocr

It refreshes continuously in the terminal, saves the latest debug_easyocr/easyocr_raw_crop.png and debug_easyocr/easyocr_input.png, then recognizes the whole crop as one text line and prints the parsed speed. Use Ctrl+C to stop.

For one capture only:

wt-easyocr-test --once --output debug_easyocr

To inspect EasyOCR's own detected text blocks, use:

wt-easyocr-test --detect-blocks --output debug_easyocr

To record the actual cruise-control decisions:

wt-cruise --debug-log logs\cruise.csv

The log includes raw OCR speed, smoothed control speed, target speed, current error, PD output, error rate, cooldown state, controller mode, wheel output, and the reason when no output is sent.

Each debug run overwrites the selected log file with a fresh header, so use a new filename when comparing tuning sessions.

Packaging

The project includes a PyInstaller helper for a Windows portable app folder:

.\scripts\build_windows_exe.ps1

The output is dist\WT-Cruise\WT-Cruise.exe plus a dist\WT-Cruise\libs\ dependency folder. The script also creates dist\WT-Cruise-portable.zip; users can unzip it and run WT-Cruise.exe directly. EasyOCR model files are not bundled; first run may download them into the user cache.

Build release packages from a CPU-only PyTorch environment. The build script detects CUDA PyTorch and stops by default so the public exe is not tied to one user's CUDA setup. If you intentionally want a CUDA-specific private build, set WT_CRUISE_ALLOW_CUDA_BUILD=1 before running the script.

Assumptions

• War Thunder is running in borderless window mode.
• Throttle is bound to mouse wheel.
• Mouse wheel up increases throttle; mouse wheel down decreases throttle.
• The first version only reads the upper-left HUD indicated airspeed.

Tests

Controller tests do not require live OCR:

pytest

The reference-image OCR test is skipped automatically when OCR dependencies are not installed.