AutoClash: 一个基于Python的部落冲突(Clash of Clans)自动化脚本

本项目是一个功能强大的自动化脚本（机器人），专为在 macOS 平台上通过安卓模拟器（如 MuMu模拟器）运行的《部落冲突》而设计。它利用计算机视觉和GUI自动化技术，模拟人类玩家的操作，以自动执行游戏中的各种重复性任务。 与直接在安卓设备内部运行的脚本（例如使用 Auto.js 等框架或需要 Root 权限的方案）相比，该架构具有优势如下：

• 强大的开发环境: 我们可以在 macOS 上利用成熟的 Python 生态，包括强大的 IDE、调试器以及 OpenCV、PyAutoGUI 等库。这使得开发、测试和维护的效率远高于在移动设备上编码。

• 卓越的计算能力: Mac 的 CPU 和内存性能远超任何移动设备。这使得脚本能够执行复杂、实时的计算机视觉任务（如多尺度模板匹配和 OCR），而不会拖慢游戏或脚本自身。设备内脚本则常因性能瓶颈导致运行不稳定。

• 无需 Root 权限: 需要深度控制的设备内脚本通常要求安卓设备被“Root”。这一过程不仅会使设备失去保修，还会带来严重的安全风险，并可能导致银行等高安全应用无法运行。本方案仅需 macOS 上标准、安全且可逆的权限设置。

• “黑盒”操作，无法被直接检测： 脚本运行在宿主操作系统（macOS）上，而游戏运行在一个被虚拟化技术隔离的虚拟机（模拟器）中。二者之间存在一道“虚拟化边界”。脚本与游戏的所有交互，都通过模拟用户的鼠标点击、键盘输入，以及读取屏幕像素来完成。对于游戏本身而言，这些操作与一个真实玩家坐在电脑前用鼠标玩游戏，在输入层面上没有任何区别。游戏无法（也不应该）跨越虚拟化边界来扫描macOS的进程列表，因此从根本上杜绝了被“进程检测”导致封号的风险。

当然，这种架构也存在明显的劣势，需要完全占用一台电脑，无法实现多开运行。

综上所述，本项目采用的是一种“以成本换安全”的策略，通过利用更强大的硬件资源，实现了一种更稳定、更隐蔽、也更难被检测到的自动化方案。

核心功能

这个脚本通过对指定区域截图并进行处理，能够智能识别当前游戏场景并执行相应操作。

• 全自动多账号管理:

  • 可配置账号列表，实现无人值守的顺序登录和切换。
  • 自动处理登录过程中的各种弹窗，如“欢迎回来”确认、突袭奖励领取等。

• 部落都城突袭 (Clan Capital):

  • 自动进入部落都城，并判断剩余突袭次数。
  • 智能寻找可攻击的都城区域，优先攻击子城，再攻击主城。
  • 进入攻击后，通过颜色识别（HSV）定位可部署区域。
  • 自动检测并部署所有兵种和法术，直到用完或战斗结束。
  • 战斗结束后自动重启游戏，确保流程稳定，进行一次突袭做准备。

• 部落对战 (Clan War):

  • 自动进入部落战地图，并智能筛选出可以攻击的、未被摧毁的村庄。
  • 自动执行部落战攻击，采用与都城突袭类似的智能部署策略。
  • 支持自动加入指定部落以参加部落战。

• 家乡进攻获取资源 (Home Village Farming):

  • 自动在家乡寻找对手进行攻击。
  • 通过边缘检测（HSV识别红色禁区）分析战场，生成安全的、随机化的下兵点。
  • 全自动部署所有英雄和部队，完成一轮资源掠夺。

• 智能资源管理:

  • 自动识别并出售多余的魔法物品（如资源药水、时光钟楼药水等），换取宝石。

• 鲁棒的自动化流程:

  • 状态机设计：脚本能持续监控游戏画面，判断当前处于登录、家乡、都城还是战斗等状态，并调用相应的功能模块。
  • 智能识别与部署：兵种和数量通过模板匹配和OCR识别，部署位置通过高级视觉算法动态生成，而非写死的坐标。
  • 人性化模拟：鼠标移动采用带缓动效果的曲线，并加入随机延迟和偏移，以更好地模拟人类操作。
  • 安全退出机制：通过全局键盘监听，按下 ESC 键即可安全、优雅地停止脚本运行。

技术栈详解

本项目综合运用了多种Python库和技术，以实现复杂的自动化流程。

• 计算机视觉 (Computer Vision):

  • OpenCV (cv2): 项目的核心。用于图像处理、模板匹配、颜色空间（HSV）转换和轮廓检测。
    • 多尺度模板匹配: 通过 findTargetSingle 和 findTemplateMulti 函数，在不同缩放比例下精确查找按钮、图标和单位等视觉元素，以适应不同分辨率和UI缩放。
    • 颜色分割 (HSV): 用于在都城或家乡战斗中，精确识别出可部署的绿色区域或不可部署的红色边界，是智能部署的基础。
    • 非极大值抑制 (NMS): 在查找多个目标时，用于消除重叠的检测框，确保每个目标只被识别一次。

• 图形用户界面自动化 (GUI Automation):

  • PyAutoGUI: 用于模拟鼠标的移动、点击、拖拽和键盘输入，是执行所有游戏内操作的基础。

• 光学字符识别 (OCR):

  • Tesseract (pytesseract) 与 Pillow (PIL): 用于识别屏幕上的文本。例如，检测特定按钮上的文字（“进攻”、“确认”），或读取兵种数量。

• macOS原生交互:

  • PyObjC (Quartz): 用于与macOS的窗口管理器直接交互，以准确获取模拟器窗口的位置和尺寸。
  • subprocess 模块: 调用macOS的原生命令行工具：
    • screencapture: 高效、精确地截取指定窗口区域的图像。
    • osascript: 执行AppleScript命令，用于将模拟器窗口激活并置于最前。

• 多线程与输入监听:

  • threading: 用于在后台运行主逻辑，同时不阻塞其他任务。
  • pynput: 创建一个独立的线程来监听全局键盘事件，实现了优雅的 ESC 退出功能。

项目结构

.
├── AutoClash.py         # 主控制程序，状态机和总逻辑
├── Main.py              # 程序入口
|
├── Environments/        # 各个游戏场景的逻辑封装
│   ├── BasicEnv.py      # 基础环境类，提供通用方法
│   ├── HomeVillage.py   # 家乡场景逻辑
│   ├── ClanCapital.py   # 部落都城场景逻辑
│   ├── HomeAttack.py    # 家乡攻击逻辑
│   ├── ClanWar.py       # 部落对战逻辑
│   └── ...
|
├── Detections/          # 计算机视觉与识别相关模块
│   ├── DetectionTarget.py # 核心：多尺度模板匹配和NMS
│   ├── DetectionBoundary.py # 边缘和部署区域检测
│   ├── DetectionOCR.py    # OCR文本识别
│   └── ...
|
├── Utils/               # 实用工具模块
│   ├── WindowTools.py   # 封装与macOS窗口交互的函数
│   ├── AutoOperations.py# 封装模拟鼠标/键盘操作的函数
│   └── ...
|
├── res/                 # 存放所有用于模板匹配的图片资源
└── cache/               # 存放临时文件，如屏幕截图

功能演示 (Demonstration)

下面的 GIF 展示了 AutoClash 脚本在实际运行中的发起进攻掠夺资源功能，并通过退出后台快速结束游戏动画。过程经过3倍速处理。

代码仓库：

https://github.com/guokezhen999/AutoClash