基於 YOLOv11n 的 2D 遊戲輔助瞄準系統，專為研究與教學用途設計。

⚠️ 免責聲明: 本系統僅供研究、教學與技術展示用途，不鼓勵、不支援任何形式的遊戲作弊行為。

• 🎯 即時敵人偵測: 使用 YOLOv11n 模型進行高效能目標偵測
• 🖱️ 平滑準星移動: PD 控制器 + α-β 平滑演算法，避免瞬移
• 🖼️ 透明 Overlay: 顯示偵測框、FPS、延遲等資訊
• ⚡ 低延遲: GPU 推論 ~3ms，端到端延遲 <100ms
• ⚙️ 可調參數: 透過 YAML 設定檔自訂控制器行為

• 作業系統: Windows 10/11 或 Linux (X11)
• Python: 3.8+
• GPU: NVIDIA GPU (可選，支援 CUDA 12.x)
• CPU: 支援純 CPU 模式（自動偵測）
• 螢幕解析度: 1920×1080

Linux:

cd /path/to/AimAssistSystem
python3 -m venv venv
source venv/bin/activate

Windows:

cd C:\path\to\AimAssistSystem
python -m venv venv
venv\Scripts\activate

pip install -r requirements.txt

將訓練好的模型 best.pt 放入 model/ 目錄：

AimAssistSystem/
└── model/
    └── best.pt

# 檢查是否有 GPU（沒有也可以運行）
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

python main.py

系統會自動偵測硬體並選擇最佳配置：

• 有 NVIDIA GPU → 使用 config.yaml (GPU 優化)
• 無 GPU / 僅 CPU → 使用 config_cpu.yaml (CPU 優化)

# 自動偵測（推薦）
python main.py

# 強制使用 GPU 配置
python main.py --config config.yaml

# 強制使用 CPU 配置
python main.py --config config_cpu.yaml

# 不顯示 Overlay（除錯用）
python main.py --no-overlay

1. 開啟瀏覽器，進入 ZombsRoyale.io
2. 將遊戲設為全螢幕 (1920×1080)
3. 執行 python main.py
4. 按 T 開啟 Aim Assist
5. 系統會自動偵測敵人並平滑移動滑鼠

系統提供兩種預設配置：

controller:
  kp: 0.25        # 比例係數
  kd: 0.08        # 微分係數
  alpha: 0.7      # 平滑係數
  dead_zone: 3    # 死區半徑
  max_speed: 50   # 最大移動速度

detection:
  device: "cuda"  # 使用 GPU

controller:
  kp: 0.35        # 較高，補償低幀率
  kd: 0.05        # 較低，減少抖動
  alpha: 0.5      # 較低，更即時反應
  dead_zone: 5    # 較大，避免抖動
  max_speed: 80   # 較高，補償低幀率

detection:
  device: "cpu"   # 使用 CPU

AimAssistSystem/
├── main.py              # 主程式入口
├── config.yaml          # GPU 用戶設定檔
├── config_cpu.yaml      # CPU 用戶設定檔（自動偵測）
├── requirements.txt     # Python 依賴
├── SPEC.md              # 系統規格文件
│
├── model/               # 模型目錄
│   └── best.pt          # YOLOv11n 權重檔
│
├── core/                # 核心模組
│   ├── capture.py       # 螢幕擷取
│   ├── detector.py      # YOLO 推論
│   ├── target_selector.py  # 目標選擇
│   ├── controller.py    # PD 控制器
│   └── mouse_control.py # 滑鼠控制
│
├── overlay/             # UI 模組
│   └── hud.py           # 透明 Overlay
│
├── utils/               # 工具模組
│   ├── coordinate.py    # 座標轉換
│   └── logger.py        # 日誌記錄
│
└── logs/                # 日誌輸出

CPU 模式下 FPS 較低，但系統已針對低幀率優化控制器參數。

系統會自動在 logs/ 目錄產生 CSV 日誌，包含：

• 每幀偵測數量
• 推論時間
• 總延遲
• FPS

可用於後續效能分析與研究。

確認模型檔案存在於 model/ 目錄：

# Linux
ls -la model/best.pt

# Windows
dir model\best.pt

# 檢查 NVIDIA 驅動
nvidia-smi

# 確認 PyTorch CUDA 版本相容
python -c "import torch; print(torch.version.cuda)"

確保在有 X11 顯示的環境下執行：

echo $DISPLAY  # 應該顯示 :0 或類似值

確認以系統管理員身分執行，部分遊戲的反作弊可能會阻擋 Overlay。

本專案僅供學術研究與教學用途。