Clash of Clans Bot

Click for Demo Video

Automated Features (Both Villages)

• Resource collection 💰
• Hero upgrades 👑
• Building upgrades 🧱
• Laboratory upgrades 🔬
• Assistant assignment ⏩️
• Normal attacks ⚔️
• Full upgrade priority control 🚦
• Multiple accounts 👥

Quality of Life Features

• View bot status on desktop or web app 🚦
• Resume / pause bot execution from desktop or web app ⏯️
• iPhone shortcut to auto resume / pause bot when CoC is opened by user ⏯️
• Telegram and web app notifications 🔔
• Automatic CoC app updates 🔼
• Automatic BlueStacks instance launch / shutdown 🔌

Dependencies

1. Android Debug Bridge
   • Add to system path
     • Verify with: adb --version
2. BlueStacks
   • Device profile: Samsung Galaxy S22 Ultra
   • Display resolution: 1920 x 1080
   • Frame rate: 60 (NOTE: Inconsistent touch events at lower fps)
   • Enable Android Debug Bridge in "Advanced" settings
   • In Multi-Instance Manager, rename instances to match instance IDs in configs.py (the default ID is main, see steps 3 and 6 in Custom Setup Instructions for more details)
   • Install Clash of Clans from Google Play
     • Default troop deployment size
     • Standard or XL scenery

Default Setup Instructions

1. Install and configure external dependencies

2. Download the latest release for your OS

   Note: Prebuilt releases are minimally configured and only support standard features. To set up the bot with custom configurations, see Custom Setup Instructions.

   Note: Prebuilt releases generally will not have the most up-to-date features and may contain unpatched bugs. To stay up to date, it is suggested to run from source.

   • Releases are built for MacOS (Apple Silicon) and Windows only
   • GUI and CLI versions are available with each release

3. MacOS users must allow the app/binary to run by going to "Settings > Privacy & Security" and clicking "Open Anyways"

Custom Setup Instructions (Recommended)

1. Install and configure external dependencies

2. Install python dependencies with setup.py

3. Enter user configurations in configs.py

   ❗️ Important: setup.py creates configs.py from configs.template.py

   ❗️ Important: By default, all capabilities are enabled. Many configurations can be overridden in real time if using the desktop or web app.

   Note: If using priority upgrades, instructions for defining upgrade priorities can be found in configs.py.

   Note: To configure Telegram notifications, first set up a Telegram bot and send /start. Enter the API token generated during the setup process for TELEGRAM_BOT_TOKEN.

   Note: If local OCR is too slow, you can offload it to groq. Just make an account and set up an API key to use for GROQ_API_KEY in configs.py. The free tier will hit the token rate limit after a while after which the bot will fallback to local OCR.

4. Start web app: python app/app.py

   💡 Tip: It is recommended to host the web app on pythonanywhere using the provided wsgi.py template and this tutorial. Free accounts can host a single web app for an extendable period of 1 month (the bot can automatically extend hosting). If you want to enable automatic pythonanywhere hosting extension, enter your pythonanywhere username and passowrd into PA_USERNAME and PA_PASSWORD respectively in configs.py.

   ❗️ Important: If hosting from a personal device, configure port forwarding as necessary

   • Each bot instance can be accessed at WEB_APP_URL/<instance_id> (the default instance ID is main)
   • View a demo of the web app here

5. Setup iPhone shortcut:

   ❗️ Important: iOS will terminate long running shortcuts after about 30-60 mins (there's no reported limit so times may vary). To ensure the bot is paused for longer, it is suggested to set the shortcut to "run after confirmation" so that the pause duration can be set arbitrarily high through the web app when desired.

   Note: An older version of the shortcut is provided that does not require Scriptable, but is incapable of handling request errors

   • Download Scriptable and create a new script named "CoC Bot Script" with the contents of CoC_Bot_Script.js
   • Open the provided shortcut
   • Enter your WEB_APP_URL into the url item of the Dictionary
   • Add your instance ids to the ids array in the Dictionary (main is added by default)
   • Create an Automation task that runs when CoC opens and is set to run immediately

6. Start the bot: python src/main.py

   ❗️ Important: By default, the bot is configured to start and stop its BlueStacks instance automatically. If this behavior is undesired or causing issues, just set AUTO_START_BLUESTACKS = False in configs.py

   Note: On MacOS, if DISABLE_DEVICE_SLEEP = True in configs.py, the user password is required to toggle the disablesleep flag in power management settings

   💡 Tip: The BlueStacks window can be minimized without disrupting the bot as all interactions are handled through Android Debug Bridge

   💡 Tip: If not using the bot for development purposes, it can be built into an executable or desktop app for convenience using build.sh. The desktop app GUI or command-line arguments can be used to specify the instance to run if using multiple bot instances. View a demo of the desktop app here.

   • To run bots for multiple accounts just create additional BlueStacks instances with BlueStacks' multi-instance manager (ensuring BlueStacks instance names match bot instance IDs), set up the instance as usual, and append new instance names to INSTANCE_IDS in configs.py. Specify the instance to run using the --id flag (e.g. python src/main.py --id main).

Miscellaneous

• Please report issues in the Issues Tab
• For help with setup or usage, open a discussion in Q&A
• Suggest new features in Ideas