Smart Drop Bot

A Python automation bot for SoundMap that uses ADB and OpenCV template matching to automate map drops and quest rerolling on an Android device.

Features

• Drop mode — automatically opens map drops and collects rewards, stopping when coins run out
• Quest mode — rerolls quests until a tradeable quest is found, then accepts and collects it
• Epic hunting mode — sub-mode of quest that quicksells non-epic/non-lyrics songs and stops when an epic or lyrics is detected

---

How it works

The bot runs on your computer (Linux, Windows, or macOS) and controls your Android phone remotely via ADB (Android Debug Bridge). It takes screenshots from the phone, uses OpenCV template matching to find buttons on screen, and sends taps back to the phone automatically. You do not need to touch the phone while it runs.

---

Prerequisites

You need the following installed on your computer before setting up the project:

Tool	Purpose
Python 3.10+	Runs the bot
ADB	Communicates with your Android device
Tesseract OCR	Reads quest song counts from screen text
Git	Clones the repository

---

Installation

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/Automatic-Soundmap.git
cd Automatic-Soundmap

All template images in the assets/ folder are included in the repository — you do not need to take any screenshots yourself.

---

2. Install Python

Linux

Ubuntu / Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

Arch / Manjaro:

sudo pacman -S python python-pip

Fedora:

sudo dnf install python3 python3-pip

Verify: python3 --version (must be 3.10 or higher)

macOS

Install Homebrew if you don't have it, then:

brew install python

Verify: python3 --version

Windows

1. Download the installer from python.org
2. Run it and check "Add Python to PATH" before clicking Install
3. Open Command Prompt or PowerShell and verify:

python --version

---

3. Install ADB

ADB must be installed and available in your terminal PATH.

Linux

Ubuntu / Debian:

sudo apt install adb

Arch / Manjaro:

sudo pacman -S android-tools

Fedora:

sudo dnf install android-tools

Verify: adb version

macOS

brew install android-platform-tools

Verify: adb version

Windows

Option A — winget (recommended):

winget install Google.PlatformTools

Option B — manual:

1. Download SDK Platform Tools from Google
2. Extract the zip to a folder (e.g. C:\platform-tools)
3. Add that folder to your system PATH:
   • Open Start → search "Environment Variables" → Edit the system environment variables
   • Under "System variables", find Path, click Edit, then New, and paste the folder path
4. Restart your terminal

Verify: adb version

---

4. Install Tesseract OCR

Tesseract is used to read the number of songs required by each quest.

Linux

Ubuntu / Debian:

sudo apt install tesseract-ocr tesseract-ocr-eng

Arch / Manjaro:

sudo pacman -S tesseract tesseract-data-eng

Fedora:

sudo dnf install tesseract tesseract-langpack-eng

Verify: tesseract --version

macOS

brew install tesseract

Verify: tesseract --version

Windows

1. Download the installer from the UB-Mannheim Tesseract releases
2. Run the installer — during setup, make sure to select English language data
3. Note the install path (default: C:\Program Files\Tesseract-OCR)
4. Add it to your PATH the same way as ADB above, or set the environment variable:

   setx TESSDATA_PREFIX "C:\Program Files\Tesseract-OCR\tessdata"

5. Restart your terminal

Verify: tesseract --version

---

5. Set up a Python virtual environment and install dependencies

Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Windows (Command Prompt)

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Windows (PowerShell)

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

If you get a script execution error, run: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

---

6. Set up your Android device

1. On your phone, go to Settings → About phone and tap Build number 7 times to enable Developer Options
2. Go to Settings → Developer options and enable USB debugging
3. Connect your phone to your computer via USB
4. On the phone, accept the "Allow USB debugging?" prompt and check "Always allow from this computer"
5. Verify the connection:

adb devices

You should see your device listed with status device (not unauthorized).

Wireless connection (optional): If you prefer not to use a cable after the initial setup:

adb tcpip 5555
adb connect YOUR_PHONE_IP:5555

Find your phone's IP at Settings → Wi-Fi → tap your network → IP address.

---

Usage

Make sure your virtual environment is active before running the bot.

Drop mode (default)

python main.py

Quest mode

python main.py --quest-mode

Epic hunting mode

python main.py --quest-mode --epic-mode

If you run python main.py without flags, the bot will prompt you to choose a mode interactively.

---

Options

General options

Flag	Default	Description
--adb-path	adb	Path to the ADB executable
--match-threshold	0.8	Template match confidence threshold (0–1)
--scale	1.0	Scale factor applied to screenshots before matching
--roi-x, --roi-y	0	Top-left corner of the region of interest
--roi-w, --roi-h	0	ROI dimensions (0 = full screen)

Drop mode options

Flag	Default	Description
--template	assets/not_enough_coins.png	Out-of-coins popup template
--open-template	assets/open_drop_button.png	Open button template
--collect-template	assets/collect_button.png	Collect button template
--open-delay	4.0	Seconds to wait after tapping Open
--collect-delay	1.5	Seconds to wait after tapping Collect
--max-loops	0	Stop after N loops (0 = unlimited)
--max-misses	10	Stop after N consecutive Open button misses
--retry-delay	2.0	Seconds to wait before retrying when Open is not found
--coin-cost	85	Coins spent per loop (used for logging only)

Quest mode options

Flag	Default	Description
--quest-tap-delay	0.5	Seconds to wait after each tap in quest mode
--quest-reroll-delay	2.0	Seconds to wait after tapping Reroll
--quest-confirm-delay	2.0	Seconds to wait after tapping Confirm
--quest-lets-go-delay	1.0	Seconds to wait after tapping Let's Go
--quest-max-rerolls	500	Stop after N rerolls (0 = unlimited)
--quest-scroll-amount	500	Pixels to scroll when searching for more quests
--quest-scroll-attempts	2	Max scroll attempts before treating quest list as exhausted
--quest-max-errors	5	Stop after N consecutive cycle errors (0 = unlimited)
--max-quest-songs	15	Reroll quests that require more than N songs (0 = disabled)

Epic hunting mode options

Flag	Default	Description
--epic-mode	off	Enable epic hunting (quicksell non-epics, stop on epic/lyrics)
--sell-delay	2.0	Seconds to wait after confirming a sell
--epic-tag-template	assets/epic_tag.png	Epic rarity badge template
--rare-tag-template	assets/rare_tag.png	Rare rarity badge template
--sell-button-template	assets/sell_button.png	Sell button template
--sell-confirm-template	assets/sell_confirm_button.png	Sell confirm button template

---

Project structure

soundmap/
├── assets/            # Template images for UI element detection (included in repo)
├── bot/
│   ├── adb.py         # ADB client (tap, swipe, screenshot)
│   ├── config.py      # BotConfig, ParsedArgs, CLI argument parsing
│   ├── vision.py      # Template matching, screenshots, OCR
│   ├── drops.py       # Drop farming loop
│   └── quests.py      # Quest cycle logic and quest loop
├── main.py            # Entry point
└── requirements.txt

---

Troubleshooting

adb devices shows nothing or unauthorized

• Make sure USB debugging is enabled and you accepted the prompt on the phone
• Try a different USB cable or port
• Run adb kill-server && adb start-server and reconnect

tesseract not found on Windows

• Make sure the Tesseract install folder is in your PATH
• Restart your terminal after editing environment variables

Template not matching / bot taps wrong area

• Try lowering --match-threshold to 0.7
• Your device resolution may differ — re-capture the relevant asset at your phone's actual resolution using adb exec-out screencap -p > screen.png

pip install fails on Linux

• Make sure your venv is active (source .venv/bin/activate) before running pip