AlphaGame 是一個基於 行為克隆（Behavioral Cloning, BC） 與 時空特徵深度學習（X3D Spatiotemporal Architecture） 的遊戲自動化遊玩框架。
透過即時截取遊戲視窗畫面並記錄玩家的操作按鍵，將遊戲操作轉換為多標籤分類問題（Multi-Label Classification）。模型能夠學習畫面幀序列（Video Frames）與操作行為之間的映射關係，實現視覺導向的遊戲 AI 自動遊玩。
- 時空特徵學習 (X3D Network)：採用預訓練 X3D 網路處理連續遊戲畫面幀序列，精準擷取動態視覺特徵與時間軸變化。
- 多標籤行為預測 (Multi-Label Action Space)：支援同時按下多個按鍵（例如：同時移動 + 攻擊/跳躍），貼近真實遊戲操作。
- 重複動作懲罰機制 (Repeat Action Penalty)：在推論階段加入懲罰機制，防止 AI 陷入死循環或重複無效動作。
- 資料質量防呆與檢查工具：提供資料集檢查機制與採集資料合併工具，確保訓練集的視覺與標籤對齊。
alphagame/
├── data/ # 存放錄製的遊戲畫面與標籤資料
├── check_data.py # 資料集正確性檢查工具
├── collect_data.py # 遊戲畫面截取與玩家操作記錄腳本
├── merge_data.ipynb # 多份採集資料的合併與清洗 Notebook
├── model_def.py # 神經網路模型架構定義 (X3D / Backbone)
├── train_x3d_multilabel.py # 多標籤 X3D 模型訓練主腳本
├── train.ipynb # 模型訓練與實驗 Notebook
├── inference_loop.py # 即時遊戲視窗推論與自動按鍵控制迴圈
├── best_model.pth # 最佳訓練權重檔
└── model.pth # 階段模型權重檔
請確保系統已安裝 Python 3.8+ 與 PyTorch (CUDA 支援)。
# 複製專案
git clone https://github.com/skywalker0803r/alphagame.git
cd alphagame
# 安裝依賴套件
pip install torch torchvision opencv-python pillow pyautogui pynput mss numpy pytorchvideo注意：如需使用 GPU 加速推論與訓練，請依據您的 CUDA 版本安裝適當的 PyTorch。
完整運作流程分為四個階段：資料採集 ➔ 資料檢查與清洗 ➔ 模型訓練 ➔ 推論自動遊玩。
啟動採集腳本後，視窗會自動擷取指定遊戲區域畫面（預設監聽時間間隔約為 0.2s），並同步記錄對應的按鍵狀態。
python collect_data.py資料會自動存入
data/目錄中。
在開始訓練前，確保採集到的畫面與標籤無遺漏或錯位。
# 執行資料檢查工具
python check_data.py若採集了多個不同時段的遊戲資料，可透過 merge_data.ipynb 進行合併與防呆處理。
使用採集好的資料對 X3D 模型進行訓練：
python train_x3d_multilabel.py- 訓練過程包含 進度條顯示 (tqdm) 與 Loss 追蹤。
- 訓練完成後，會自動儲存權重至
best_model.pth。
將遊戲視窗置於前端，執行推論主迴圈。AI 將即時截取視窗畫面、預測按鍵動作，並透過模擬按鍵控制遊戲角色。
python inference_loop.py- 重複動作懲罰 (Repeat Action Penalty)：推論迴圈內建防卡死邏輯，若模型連續輸出相同的無效操作，會自動降低該動作之信心度權重。
- 採集頻率控制：預設採集與推論延遲設定為
0.2s，可根據不同遊戲類型（如 RPG、動作遊戲）在腳本中調整幀率（FPS）。
本專案僅供學術研究、AI 行為克隆實驗與個人學習使用。請勿用於任何違反遊戲服務條款（Terms of Service）之商業或線上多人對戰行為。