MU Bot - Game Automation Scripts

Automation scripts for MU Origin 2 using ADB commands, screen capture, and OCR.

Requirements

Software

• macOS (tested on Darwin 25.3.0)
• Homebrew - package manager for macOS
• Python 3.12+ - installed via Homebrew
• ImageMagick 7+ - for screenshot cropping and image processing
• ADB - Android Debug Bridge for emulator communication

Emulator

• BlueStacks - Android emulator
  • Resolution: 1920x1080
  • ADB enabled: Settings > Advanced > toggle ADB ON
  • Default ADB address: 127.0.0.1:5555

Game

• MU Origin 2 (package: com.tszz.gpen.nowgg) installed on BlueStacks

Setup

1. Install dependencies

brew install python@3.12
brew install imagemagick

2. Install Python packages

pip3 install easyocr Pillow numpy scikit-image

3. Connect ADB to BlueStacks

Start BlueStacks, then:

adb connect 127.0.0.1:5555
adb devices  # verify connection

4. Configure project path

A ready-to-use template lives at example/local_example.properties. Copy it to the project root and rename it to local.properties (the filename and location are both required — scripts look for <project_root>/local.properties):

cp example/local_example.properties local.properties

Then edit the copied file and update at minimum project.dir and emulator.id for your machine. The full set of supported properties:

# local.properties
project.dir=/path/to/your/MuBot
emulator.id=127.0.0.1:5555
game.package=com.tszz.gpen.nowgg
quick.buff=false
use.immortal.satan=true
pickup.items.boss=10
pickup.items.golden=4
autoPlay.attack.timeout=240
autoPlay.healthbar.check.interval=1
autoPlay.healthbar.times.killed=1
farm.buy.potions=true
farm.health.potions=2500
farm.mana.potions=2000
farm.boss.wires=1,2,3
farm.boss.performance.mode=false
farm.mob.wire=1
sanctuary.level=2
sanctuary.wires=1,2
sanctuary.health.potions=3000
sanctuary.mana.potions=3000

This file is gitignored — each computer needs its own. If omitted, the project path is auto-detected from the script location.

Property	Description	Default
project.dir	Absolute path to the project directory	Auto-detected
emulator.id	ADB device ID (get with adb devices)	127.0.0.1:5555
game.package	Game package name installed on the emulator	com.tszz.gpen.nowgg
use.immortal.satan	When true, uses satan_immortal.png marker. When false, uses satan.png.	true
quick.buff	When true, only one buff (attack or defense) is needed during buff check. When false, both are required.	false
pickup.items.boss	Seconds to wait picking up items after killing a boss	10
pickup.items.golden	Seconds to wait picking up items after killing a golden monster	4
autoPlay.attack.timeout	Timeout in seconds for the smartAutoPlay attack script	240
autoPlay.healthbar.check.interval	Seconds between health bar checks in smartAutoPlay. Increase to 2 if the computer is under heavy load	1
autoPlay.healthbar.times.killed	Number of consecutive "no health bar" detections before considering the target dead	1
autoPlay.performance.mode	When true, smartAutoPlay.sh skips the expired-popup precheck at startup (saves a screencap + image-compare on slow PCs)	false
farm.buy.potions	Enable potion buying during farming runs	true
farm.health.potions	Target health potions to buy during farming runs	2500
farm.mana.potions	Target mana potions to buy during farming runs	2000
farm.auto.recycle	Enable automatic recycling during travel	true
farm.boss.wires	Wire rotation for the generic boss farm template (farmBossTemplate.sh). Comma-separated wire numbers; the template cycles through them one wire per cycle	1,2,3
farm.boss.performance.mode	Used by farmBossTemplate.sh (replaces sanctuary.performance.mode in the template). When true, skips OCR-based location validation while traveling between bosses, and taps attack early (right after the "Fighting..." log) so the fight starts before smartAutoPlay.sh finishes warming up. Helps slow PCs.	false
farm.mob.wire	Wire to switch to before traveling to the mob spot in autoPlayMobTemplate.sh. 1 = no switch (post-teleport default on most maps). Set higher when the mob spot lives on a different wire (e.g. Foggy Forest uses 2).	1
sanctuary.level	Sanctuary level for boss farming (1-6)	2
sanctuary.wires	Wire sequence for sanctuary boss farming (comma-separated, e.g., 1,2,3 or 2)	1,2
sanctuary.health.potions	Target health potions to buy during sanctuary runs	3000
sanctuary.mana.potions	Target mana potions to buy during sanctuary runs	3000
sanctuary.performance.mode	When true, skips OCR-based location validation while traveling between sanctuary bosses, and taps attack early (right after the "Fighting..." log) so the fight starts before smartAutoPlay.sh finishes warming up. Helps slow PCs.	false
sanctuary.long.travel.duration	Threshold in seconds for treating a boss-to-boss travel as "long". Travels at or above this run the full validation pass (recycle + game check + location); shorter travels only run recycle. Raise this on slow computers to route more travels through the lighter branch.	15
event.devil.square.hours	Hours when Devil Square is available (comma-separated)	0,2,4,6
event.devil.square.minutes.start	Start minute of the Devil Square window	0
event.devil.square.minutes.end	End minute of the Devil Square window	14
event.blood.castle.hours	Hours when Blood Castle is available (comma-separated)	1,3,5
event.blood.castle.minutes.start	Start minute of the Blood Castle window	0
event.blood.castle.minutes.end	End minute of the Blood Castle window	14
event.devil.square.max.fails	Max failed attempts per hour before skipping Devil Square	3
event.blood.castle.max.fails	Max failed attempts per hour before skipping Blood Castle	3
plan.before.devil.square	Plan to set before Devil Square (0=no change, 1=plan 1, 2=plan 2)	1
plan.after.devil.square	Plan to set after Devil Square (0=no change, 1=plan 1, 2=plan 2)	2
plan.before.blood.castle	Plan to set before Blood Castle (0=no change, 1=plan 1, 2=plan 2)	2
plan.after.blood.castle	Plan to set after Blood Castle (0=no change, 1=plan 1, 2=plan 2)	0
event.change.gold.pickup	Toggle gold pickup before/after Blood Castle and Devil Square events	false

5. Update configuration

Edit config/variables.sh:

Project Structure

bot/
├── config/
│   └── variables.sh          # Main configuration (tap coordinates, settings)
├── python/
│   ├── boss_database/        # Per-map boss coords + travel times (single source of truth)
│   │   ├── sanctuary.py
│   │   ├── foggyForest.py
│   │   ├── abyssalFerea.py
│   │   └── nixiesLake.py
│   ├── detectGoldenHealthBar.py
│   ├── detectBossHealthBar.py
│   ├── detectBossStatus.py        # Generic boss-status scan (--map <name>)
│   ├── optimizeBossRoute.py       # Generic route optimizer (--map <name>)
│   ├── readNumbersOCR.py
│   ├── readTextOCR.py
│   └── compareImages.py
├── bash/
│   ├── actions/              # Single actions (buy potions, recycle, etc.)
│   ├── attack/               # Auto-play and smart attack scripts
│   ├── boss/                 # Boss navigation scripts
│   ├── changeMode/           # PvP mode switching
│   ├── detection/            # Boss status detection
│   ├── event/                # Devil Square, Blood Castle
│   ├── teleport/             # Map teleportation scripts
│   ├── test/                 # Test scripts for debugging
│   ├── travel/               # In-map navigation scripts
│   └── utils/
│       ├── visionUtils.sh    # Screen reading, OCR, image comparison
│       ├── farmingUtils.sh   # Buff, validation, party management
│       └── eventUtils.sh     # Event timing and handling
├── img/
│   ├── daily_goal/           # Daily Goal event icons for grid detection
│   └── ...                   # Other reference images for screen comparison
├── autoPlay*.sh              # Main farming loop scripts
├── farmSanctuaryBosses.sh    # Sanctuary boss farming script
├── farmSanctuaryBossesImproved.sh  # Improved version: re-scans after each boss fight
└── MIGRATION_STATUS.md       # Resolution migration tracking

Usage

Main scripts

# Farm golden monsters at Eversong Forest
bash autoPlayGolden510EversongForest.sh

# Farm mobs at Foggy Forest
bash autoPlayMobFoggyForest.sh

# Farm sanctuary bosses (level 1-6)
bash farmSanctuaryBosses.sh 2

# Farm sanctuary bosses with re-scan after each kill (adapts to boss respawns/kills by others)
bash farmSanctuaryBossesImproved.sh 2

Key controls during farming

Key	Action
p	Pause (5 min timeout)
s	Stop (15 min timeout)
n	Skip to next cycle
b	Force buff on next cycle
q	Force Devil Square event
r	Force Blood Castle event
Other	Abort script

Test scripts

# Check boss health bar detection
bash bash/test/checkBossHealth.sh

# Check golden monster detection
bash bash/test/checkGoldenHealth.sh

# Check current map location
bash bash/test/checkCurrentLocation.sh

Quick screenshot

Double-click screenshot.command on Desktop to capture the emulator screen.

Notes

• Each project instance uses its own .tmp/ directory for temporary files (screenshots, pause flags), avoiding collisions when running multiple instances
• All tap coordinates are calibrated for 1920x1080 resolution
• Reference images in img/ must match the current resolution
• See MIGRATION_STATUS.md for resolution migration progress