{"id":49017681,"url":"https://github.com/1337xcode/aimbuddy","last_synced_at":"2026-05-31T19:00:55.042Z","repository":{"id":349812375,"uuid":"1182972202","full_name":"1337Xcode/AimBuddy","owner":"1337Xcode","description":"A fully on‑device Android‑native aim assistant that helps visually impaired players detect and track opponents in realtime","archived":false,"fork":false,"pushed_at":"2026-04-16T22:00:41.000Z","size":1936,"stargazers_count":9,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-19T02:45:29.669Z","etag":null,"topics":["ai","ai-aim-assistant","ai-aimbot","ai-aimbot-android","aimbot","aimbuddy","android","esp","machine-learning","object-detection","yolov26"],"latest_commit_sha":null,"homepage":"https://1337xcode.github.io/AimBuddy","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1337Xcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T06:23:19.000Z","updated_at":"2026-04-16T22:00:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1337Xcode/AimBuddy","commit_stats":null,"previous_names":["1337xcode/aimbuddy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/1337Xcode/AimBuddy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1337Xcode%2FAimBuddy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1337Xcode%2FAimBuddy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1337Xcode%2FAimBuddy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1337Xcode%2FAimBuddy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1337Xcode","download_url":"https://codeload.github.com/1337Xcode/AimBuddy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1337Xcode%2FAimBuddy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33744447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-aim-assistant","ai-aimbot","ai-aimbot-android","aimbot","aimbuddy","android","esp","machine-learning","object-detection","yolov26"],"created_at":"2026-04-19T02:36:02.732Z","updated_at":"2026-05-31T19:00:54.977Z","avatar_url":"https://github.com/1337Xcode.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AimBuddy\n\nAimBuddy is an AI-based Android aim assistant for real-time screen capture, object detection, target tracking, visual guidance overlays, and optional assisted input.\n\n## Project in Brief\n\n- **Platform**: Android (arm64-v8a)\n- **App stack**: Kotlin + Jetpack Compose + native C++ (JNI)\n- **Inference**: NCNN runtime with Vulkan GPU acceleration (YOLOv26n)\n- **Training**: Python pipeline with Ultralytics, PyTorch, and NCNN export\n\n## Runtime Modes\n\n| Mode | Backend | Requires | Features |\n|------|---------|----------|----------|\n| Visual Assist | none | - | Screen capture, YOLO inference, target tracking, ESP overlays |\n| Assisted Input (root) | `uinput` virtual touchscreen | Root access | ESP + low-latency touch injection that runs **in parallel with the user's finger** (separate input stream, real touchscreen is never grabbed) |\n| Assisted Input (non-root) | Shizuku `injectInputEvent` | Shizuku service + permission | Same parallel-touch behavior with no root, using a virtual deviceId so the aim contact dispatches alongside physical touches |\n\nIf neither backend is available, the app stays in Visual Assist Mode and the menu still loads.\n\n### Feature Highlights\n\n- **Simultaneous user + aim touch** on both backends so you can move and aim at the same time.\n- **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.\n- **Chinese (中文) UI** language in addition to English. Drop a CJK TTF at `app/src/main/assets/fonts/cjk.ttf` to render glyphs.\n- **Event-driven aim loop** - first touch lands within one inference cycle of target acquisition; no polling.\n- **Velocity lead prediction** scaled to the measured pipeline delay, so running targets are actually led instead of trailed.\n- **Adaptive crop** that shrinks under GPU pressure to keep `\u003c 10ms` inference.\n\n## How It Works\n\n```mermaid\nflowchart LR\n    A[Screen Capture] --\u003e B[Frame Buffer]\n    B --\u003e C[YOLO Inference]\n    C --\u003e D[Target Tracker]\n    D --\u003e E[Aim Controller]\n    E --\u003e F[Touch Injection]\n    C --\u003e G[ESP Overlay]\n    D --\u003e G\n```\n\n1. **Capture**: MediaProjection captures the game screen at 1280x720.\n2. **Detect**: YOLOv26n runs on the GPU via NCNN to detect enemies.\n3. **Track**: DeepSORT-style tracker maintains target identity across frames.\n4. **Aim**: PD controller steers aim with velocity lead and jitter suppression.\n5. **Render**: ESP overlay draws boxes, snap lines, and an ImGui settings menu.\n\n## Device Requirements\n\n### Runtime (Android Device)\n\n| Item | Minimum | Recommended |\n|------|---------|-------------|\n| Android | 11 (API 30) | 13+ |\n| ABI | arm64-v8a | Snapdragon 888+ |\n| Graphics | OpenGL ES 3.1 | OpenGL ES 3.2 + Vulkan |\n| RAM | 6 GB | 8 GB+ |\n| Storage | 2 GB free | 5 GB+ free |\n| Root *or* Shizuku | Not required for ESP | Either one enables aim assist |\n\n### Training (Windows PC)\n\n| Item | Minimum | Recommended |\n|------|---------|-------------|\n| OS | Windows 10 64-bit | Windows 11 64-bit |\n| Python | 3.10 to 3.12 | 3.11 |\n| CPU | 4 cores | 8+ cores |\n| RAM | 8 GB | 16 GB+ |\n| Storage | 15 GB free | 30 GB+ free |\n| GPU | CPU-only supported | NVIDIA with CUDA 12.1 |\n\n## Quick Start\n\n### 1. Build and Install\n\n```powershell\n./gradlew.bat clean assembleDebug\n./gradlew.bat installDebug\n```\n\nPrerequisites:\n- Android SDK 35\n- Android NDK 29.0.13113456 rc1\n- CMake 3.22.1\n- Java 11+\n\n### 2. First Launch\n\n1. Open AimBuddy on your device.\n2. Grant overlay permission when prompted.\n3. Pick a backend for aim assist (optional):\n   - Approve root access for the `uinput` backend, or\n   - Install Shizuku, start the service, and grant the Shizuku permission for the non-root backend. See [docs/ShizukuSetup.md](docs/ShizukuSetup.md) for a step-by-step beginner guide.\n   - Skip both to run in visual-assist mode (ESP only).\n4. Grant MediaProjection screen capture permission.\n5. The overlay appears with ESP boxes and a floating settings icon.\n\n### 3. Train Your Own Model (Optional)\n\n```powershell\ncd training\nscripts\\00_automate.bat\n```\n\nThis single command runs: env setup -\u003e frame extraction -\u003e **teacher auto-labelling** -\u003e negative mining (if you've dropped frames into `raw_frames/negatives/`) -\u003e stable train/valid/test split -\u003e dataset validation -\u003e training at `imgsz=640` with strong augmentations -\u003e NCNN export at `imgsz=256` -\u003e deploy to `app/src/main/assets/models/` -\u003e 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.\n\nThe only manual touch points are:\n1. Drop gameplay video into `training/videos/`.\n2. (Optional) Drop no-enemy frames into `training/raw_frames/negatives/`.\n3. 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).\n\nSee the [Training Guide](docs/Training.md) for the per-step scripts and the bigger explanation of why this works.\n\n## Build Details\n\n### Debug Build\n\n```powershell\n./gradlew.bat clean assembleDebug\n```\n\n### Release Build\n\n```powershell\n./gradlew.bat clean assembleRelease\n```\n\n### Manual APK Install\n\n```powershell\nadb install -r app/build/outputs/apk/debug/app-debug.apk\n```\n\n## Training and Export\n\nFrom the repository root:\n\n```powershell\ncd training\nscripts\\07_run_full_pipeline.bat\n```\n\nThis runs environment setup, dataset validation, training, and NCNN export.\n\nKey outputs:\n\n| Output | Location |\n|--------|----------|\n| Reports | `training/outputs/reports/` |\n| Weights | `training/outputs/runs/detect/train/weights/` |\n| NCNN export | `training/outputs/export/` |\n| Deployment target | `app/src/main/assets/models/` |\n\nIndividual scripts:\n\n```powershell\nscripts\\00_automate.bat          REM End-to-end: videos -\u003e NCNN -\u003e deploy\nscripts\\01_setup_environment.bat\nscripts\\02_extract_frames.bat\nscripts\\03_validate_dataset.bat\nscripts\\04_train_adaptive.bat\nscripts\\05_train_manual.bat\nscripts\\06_export_ncnn.bat\nscripts\\07_run_full_pipeline.bat\nscripts\\08_auto_label.bat        REM Teacher (yolov8x) labels raw_frames\nscripts\\09_mine_negatives.bat    REM Adds empty-label samples\nscripts\\10_active_learning.bat   REM Surfaces next-iter review pool\n```\n\n## Releases (CI)\n\nReleases are fully automated by `.github/workflows/release.yml`. The workflow runs whenever a push to `master` modifies `CHANGELOG.md`. It:\n\n1. Reads the top non-Unreleased `## [x.y.z] - YYYY-MM-DD` heading from `CHANGELOG.md`.\n2. Skips if `v\u003cversion\u003e` already tagged or if `aimbuddy.versionName` in `gradle.properties` does not match.\n3. Builds the release APK on `ubuntu-latest` with JDK 17, Android SDK 35, NDK 29, CMake 3.22.1, and a Gradle cache.\n4. Signs the APK if these repository secrets are configured (otherwise produces an unsigned APK):\n   - `KEYSTORE_BASE64` (base64-encoded JKS upload keystore)\n   - `KEYSTORE_PASSWORD`\n   - `KEY_ALIAS`\n   - `KEY_PASSWORD`\n5. Creates a GitHub Release tagged `v\u003cversion\u003e` with the changelog section as release notes and the APK attached.\n\nTo 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.\n\n## Documentation\n\n| Document | Contents |\n|----------|----------|\n| [Architecture](docs/Architecture.md) | System design, threading, data flow, module reference, input-injection backends |\n| [Shizuku Setup](docs/ShizukuSetup.md) | Step-by-step setup for the non-root touch backend |\n| [Settings Guide](docs/SettingsGuide.md) | Every setting explained, presets, tuning workflow |\n| [Performance](docs/Performance.md) | Pipeline targets, adaptive crop, memory budget, overlay render cap |\n| [Training](docs/Training.md) | Dataset workflow, auto-labelling, active learning, NCNN export |\n| [Troubleshooting](docs/Troubleshooting.md) | Build, runtime, and training issue resolution |\n| [Changelog](CHANGELOG.md) | Versioned history of behavior changes |\n| [Contributing](CONTRIBUTING.md) | Code standards, PR process, validation requirements |\n\n## Repository Layout\n\n```\napp/                    Android app and native runtime\n    src/main/\n        java/           Kotlin sources (MainActivity, services)\n        cpp/            C++ native code\n            aimbot/     Target tracker, aim controller\n            detector/   YOLO inference (NCNN)\n            input/      Touch injection (uinput)\n            renderer/   ESP overlay, ImGui menu\n            utils/      Settings, math, logging\n        assets/models/  NCNN model files\ntraining/               Python training pipeline\n    scripts/            Batch scripts for each step\n    config/             Training configuration\n    dataset/            Training data (not committed)\n    outputs/            Reports, weights, exports\ndocs/                   Technical documentation\n```\n\n## External Credits\n\n### Android App and Runtime\n- [AndroidX Core/AppCompat](https://developer.android.com/jetpack/androidx)\n- [Material Components for Android](https://github.com/material-components/material-components-android)\n- [Jetpack Compose](https://developer.android.com/jetpack/compose)\n- [AndroidSVG](https://bigbadaboom.github.io/androidsvg/)\n- [NCNN](https://github.com/Tencent/ncnn)\n- [Dear ImGui](https://github.com/ocornut/imgui)\n\n### Training and Export\n- [Ultralytics](https://github.com/ultralytics/ultralytics)\n- [PyTorch](https://pytorch.org/)\n- [TorchVision](https://pytorch.org/vision/stable/index.html)\n- [OpenCV](https://opencv.org/)\n- [NumPy](https://numpy.org/)\n- [ONNX](https://onnx.ai/)\n- [ONNX Runtime](https://onnxruntime.ai/)\n\nSee `training/requirements.txt` and `app/build.gradle` for exact dependency versions.\n\n## License\n\nThis project is released under the AimBuddy Community Free Use License v1.0.\n\nKey terms:\n- Free use, modification, and redistribution are allowed.\n- Selling or commercial monetization is not allowed.\n- Derivative works must remain free and use the same license.\n- Attribution to the original project is required.\n- Software is provided as-is with no warranty and no liability.\n\nSee [LICENSE](LICENSE) for full terms.\n\n## Legal and Usage Notice\n\nUse this project only in authorized environments and only where local law, platform policy, and software terms allow such testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1337xcode%2Faimbuddy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1337xcode%2Faimbuddy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1337xcode%2Faimbuddy/lists"}