AimBuddy

AimBuddy is an AI-based Android aim assistant for real-time screen capture, object detection, target tracking, visual guidance overlays, and optional assisted input.

Project in Brief

• Platform: Android (arm64-v8a)
• App stack: Kotlin + Jetpack Compose + native C++ (JNI)
• Inference: NCNN runtime with Vulkan GPU acceleration (YOLOv26n)
• Training: Python pipeline with Ultralytics, PyTorch, and NCNN export

Runtime Modes

If neither backend is available, the app stays in Visual Assist Mode and the menu still loads.

Feature Highlights

• Simultaneous user + aim touch on both backends so you can move and aim at the same time.
• Streamer mode - toggle in the ESP tab sets FLAG_SECURE so the overlay disappears from screen recordings, screenshots, and screen mirroring while staying visible on your own screen.
• Chinese (中文) UI language in addition to English. Drop a CJK TTF at app/src/main/assets/fonts/cjk.ttf to render glyphs.
• Event-driven aim loop - first touch lands within one inference cycle of target acquisition; no polling.
• Velocity lead prediction scaled to the measured pipeline delay, so running targets are actually led instead of trailed.
• Adaptive crop that shrinks under GPU pressure to keep < 10ms inference.

How It Works

flowchart LR
    A[Screen Capture] --> B[Frame Buffer]
    B --> C[YOLO Inference]
    C --> D[Target Tracker]
    D --> E[Aim Controller]
    E --> F[Touch Injection]
    C --> G[ESP Overlay]
    D --> G

1. Capture: MediaProjection captures the game screen at 1280x720.
2. Detect: YOLOv26n runs on the GPU via NCNN to detect enemies.
3. Track: DeepSORT-style tracker maintains target identity across frames.
4. Aim: PD controller steers aim with velocity lead and jitter suppression.
5. Render: ESP overlay draws boxes, snap lines, and an ImGui settings menu.

Device Requirements

Runtime (Android Device)

Training (Windows PC)

Quick Start

1. Build and Install

./gradlew.bat clean assembleDebug
./gradlew.bat installDebug

Prerequisites:

• Android SDK 35
• Android NDK 29.0.13113456 rc1
• CMake 3.22.1
• Java 11+

2. First Launch

1. Open AimBuddy on your device.
2. Grant overlay permission when prompted.
3. Pick a backend for aim assist (optional):
   • Approve root access for the uinput backend, or
   • Install Shizuku, start the service, and grant the Shizuku permission for the non-root backend. See docs/ShizukuSetup.md for a step-by-step beginner guide.
   • Skip both to run in visual-assist mode (ESP only).
4. Grant MediaProjection screen capture permission.
5. The overlay appears with ESP boxes and a floating settings icon.

3. Train Your Own Model (Optional)

cd training
scripts\00_automate.bat

This single command runs: env setup -> frame extraction -> teacher auto-labelling -> negative mining (if you've dropped frames into raw_frames/negatives/) -> stable train/valid/test split -> dataset validation -> training at imgsz=640 with strong augmentations -> NCNN export at imgsz=256 -> deploy to app/src/main/assets/models/ -> active-learning sweep that surfaces the next batch of frames worth labelling. State checkpoints at each step so re-running resumes from the last failure.

The only manual touch points are:

1. Drop gameplay video into training/videos/.
2. (Optional) Drop no-enemy frames into training/raw_frames/negatives/.
3. Spot-check training/dataset/train/labels/ after the auto-label step and delete obviously-wrong boxes (Roboflow / labelImg take minutes vs the hours of from-scratch labelling).

See the Training Guide for the per-step scripts and the bigger explanation of why this works.

Build Details

Debug Build

./gradlew.bat clean assembleDebug

Release Build

./gradlew.bat clean assembleRelease

Without a configured release keystore this signs with your local debug key and prints a warning. Such an APK is fine for local testing but must not be shared. See Release Signing.

Manual APK Install

adb install -r app/build/outputs/apk/debug/app-debug.apk

If an install fails with "App not installed as package conflicts with an existing package", a build of com.aimbuddy signed with a different certificate is still registered on the device. Remove it for every user profile and retry:

adb uninstall com.aimbuddy
adb shell pm uninstall --user 0 com.aimbuddy
adb shell pm list packages -u | findstr aimbuddy   REM should print nothing

The last command also lists uninstalled-but-retained packages, which are the usual cause when you are sure the app is not installed.

Release Signing

Android identifies an installed app by the pair (applicationId, signing certificate). Every published AimBuddy APK must therefore be signed with one fixed key. If the certificate changes between releases, users cannot upgrade and the installer reports a package conflict.

Generate the key once and keep it safe (losing it means every user must uninstall before their next update):

keytool -genkeypair -v -keystore upload.jks -alias aimbuddy `
        -keyalg RSA -keysize 4096 -validity 10000

Local release builds. Create keystore.properties in the repo root (git-ignored):

storeFile=upload.jks
storePassword=<store password>
keyAlias=aimbuddy
keyPassword=<key password>

CI. The workflow feeds the same key to Gradle through AIMBUDDY_KEYSTORE_FILE, AIMBUDDY_KEYSTORE_PASSWORD, AIMBUDDY_KEY_ALIAS, and AIMBUDDY_KEY_PASSWORD, populated from the repository secrets listed below. Base64-encode the keystore for the KEYSTORE_BASE64 secret:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("upload.jks")) | Set-Clipboard

Each release run prints the signer's SHA-256 fingerprint to the job summary. Compare it against the previous release. It must be identical.

Training and Export

From the repository root:

cd training
scripts\07_run_full_pipeline.bat

This runs environment setup, dataset validation, training, and NCNN export.

Key outputs:

Individual scripts:

scripts\00_automate.bat          REM End-to-end: videos -> NCNN -> deploy
scripts\01_setup_environment.bat
scripts\02_extract_frames.bat
scripts\03_validate_dataset.bat
scripts\04_train_adaptive.bat
scripts\05_train_manual.bat
scripts\06_export_ncnn.bat
scripts\07_run_full_pipeline.bat
scripts\08_auto_label.bat        REM Teacher (yolov8x) labels raw_frames
scripts\09_mine_negatives.bat    REM Adds empty-label samples
scripts\10_active_learning.bat   REM Surfaces next-iter review pool

Releases (CI)

Releases are fully automated by .github/workflows/release.yml. The workflow runs whenever a push to master modifies CHANGELOG.md. It:

1. Reads the top non-Unreleased ## [x.y.z] - YYYY-MM-DD heading from CHANGELOG.md.
2. Skips if v<version> already tagged or if aimbuddy.versionName in gradle.properties does not match.
3. Builds the release APK on ubuntu-latest with JDK 17, Android SDK 35, NDK 29, CMake 3.22.1, and a Gradle cache.
4. Signs the APK with the upload keystore. These repository secrets are required, and the job fails rather than publishing an unsigned or debug-signed APK that users could not upgrade:
   • KEYSTORE_BASE64 (base64-encoded JKS upload keystore)
   • KEYSTORE_PASSWORD
   • KEY_ALIAS
   • KEY_PASSWORD
5. Verifies the APK signature and prints the certificate SHA-256 to the job summary.
6. Creates a GitHub Release tagged v<version> with the changelog section as release notes and the APK attached.

To cut a release: bump aimbuddy.versionName (and aimbuddy.versionCode) in gradle.properties, add a new ## [x.y.z] - YYYY-MM-DD heading to CHANGELOG.md, push to master. The workflow handles everything else.

Documentation

Repository Layout

app/                    Android app and native runtime
    src/main/
        java/           Kotlin sources (MainActivity, services)
        cpp/            C++ native code
            aimbot/     Target tracker, aim controller
            detector/   YOLO inference (NCNN)
            input/      Touch injection (uinput)
            renderer/   ESP overlay, ImGui menu
            utils/      Settings, math, logging
        assets/models/  NCNN model files
training/               Python training pipeline
    scripts/            Batch scripts for each step
    config/             Training configuration
    dataset/            Training data (not committed)
    outputs/            Reports, weights, exports
docs/                   Technical documentation

External Credits

Android App and Runtime

• AndroidX Core/AppCompat
• Material Components for Android
• Jetpack Compose
• AndroidSVG
• NCNN
• Dear ImGui

Training and Export

• Ultralytics
• PyTorch
• TorchVision
• OpenCV
• NumPy
• ONNX
• ONNX Runtime

See training/requirements.txt and app/build.gradle for exact dependency versions.

License

This project is released under the AimBuddy Community Free Use License v1.0.

Key terms:

• Free use, modification, and redistribution are allowed.
• Selling or commercial monetization is not allowed.
• Derivative works must remain free and use the same license.
• Attribution to the original project is required.
• Software is provided as-is with no warranty and no liability.

See LICENSE for full terms.

Legal and Usage Notice

Use this project only in authorized environments and only where local law, platform policy, and software terms allow such testing.

Release signing fix, correct in-app version reporting, and a 61% smaller APK.

Fixed

• Installing a release APK failed with "App not installed as package conflicts with an existing package". The release build type was signed with signingConfigs.debug, whose keystore is per-machine and is regenerated from scratch on a clean CI runner, so every build carried a different signing certificate. Android keys an installed app on (applicationId, certificate), so no two AimBuddy APKs could be installed over one another. Release builds now use a dedicated, stable keystore supplied through keystore.properties or the AIMBUDDY_KEYSTORE_* environment variables.
• The ImGui window title and the Info tab reported v0.0.0-dev in every build. Gradle passed AIMBUDDY_VERSION to CMake as a cache variable, which the compiler never sees, and CMakeLists.txt never promoted it to a preprocessor define, so utils/i18n.h always fell through to its default. CMake now defines it for the compiler and warns if Gradle fails to supply it.

Performance

• Release APK shrank from 32.59 MB to 12.66 MB. proguard-rules.pro carried a blanket -keep class androidx.compose.** { *; }, which disabled R8 shrinking across every Compose artifact and pinned the whole of material-icons-extended into the dex. The app references nine icons; dex dropped from 21.64 MB to 2.07 MB with all nine retained.
• Dropped v1 (JAR) signing. It is only consulted below API 24 and minSdk is 30, so its per-entry digests in MANIFEST.MF and CERT.SF were roughly 93 KB of dead weight. v2 and v3 remain enabled.

Changed

• The release workflow now requires the signing secrets and fails instead of publishing an unsigned or debug-signed APK, verifies the APK signature after building, and prints the signer's SHA-256 fingerprint to the job summary so certificate drift is caught before release.
• Release assets are named AimBuddy-v<version>.apk; the misleading -signed/-unsigned suffix is gone.
• Local release builds without a configured keystore still fall back to the debug key for convenience, but now warn that the APK must not be distributed; the same fallback is a hard error when CI is set.

Upgrade note

• Because earlier APKs were signed with throwaway keys, this release cannot be installed over an existing AimBuddy build. Uninstall the old version first (adb uninstall com.aimbuddy, or long-press the app icon → Uninstall). Subsequent releases will upgrade in place.