pymordial 0.1.0

A Python library designed to control BlueStacks through ADB commands, enabling seamless automation and management of Android applications on a PC.

Pymordial 💊

Automate BlueStacks like a pro. Or a robot.

Pymordial is a Python library designed to control BlueStacks through ADB commands and image recognition, enabling seamless automation of Android applications on PC.

📑 Table of Contents

• Why Pymordial?
• Installation
• Quick Start
• Common Recipes
• Key Concepts
• Documentation
• Examples
• Requirements
• Troubleshooting
• Contributing
• License

🚀 Why Pymordial?

• Smart Automation: Uses OCR and Image Recognition to find buttons, not just blind coordinates.
• State Aware: Knows if your app is Loading, Open, or Closed. No more clicking on black screens.
• Clean API: Intuitive methods like controller.go_home() and controller.capture_screen().
• Extensible: Easy to add new apps, screens, and elements.
• Pythonic: Clean, typed, and modern Python 3.13+ codebase.
• Well Tested: 155 passing tests including integration tests with real BlueStacks.

🛠️ Installation

Pymordial uses uv for dependency management.

# Clone the repository
git clone https://github.com/IAmNo1Special/Pymordial.git
cd Pymordial

# Install with uv
uv pip install .

# Or install in development mode
uv pip install -e .

⚡ Quick Start

from pymordial import WorldLink
from pymordial.core.world import World
from pymordial.core.elements.button_element import ButtonElement
from pathlib import Path

# 1. Initialize Controller (connection is automatic!)
controller = WorldLink()

# 2. Define your App
my_game = World(
    app_name="MyGame",
    package_name="com.example.mygame"
)

# 3. Register App
controller.add_app(my_game)

# 4. Open App
my_game.open()  # Opens the app and waits for it to load

# 5. Navigate using clean API
controller.go_home()  # ← Much cleaner than controller.adb.go_home()

# 6. Define and click a button
start_button = ButtonElement(
    name="start",
    asset_path=Path("assets/start_btn.png"),
    element_text="Start",
    is_static=True
)

# Click with automatic retry
if controller.bluestacks.click_element(start_button, timeout=10):
    print("Button clicked successfully!")

# 7. Read text from screen with OCR
screenshot = controller.capture_screen()  # ← Clean API!
text_lines = controller.image.read_text(screenshot)
print(f"Found text: {text_lines}")

🧩 Common Recipes

Check if an element is visible

from pymordial.core.elements.image_element import ImageElement

logo = ImageElement(
    name="game_logo",
    asset_path=Path("assets/logo.png"),
    is_static=True
)

if my_game.is_element_visible(logo):
    print("On the main menu!")

Navigate and interact

# Go to home screen
controller.go_home()

# Press back button
controller.go_back()

# Tap at specific coordinates
controller.tap(x=500, y=300)

# Swipe gesture
controller.swipe(start_x=500, start_y=800, end_x=500, end_y=200, duration=300)

Search for specific text

screenshot = controller.capture_screen()

if controller.image.check_text(screenshot, "Victory!", case_sensitive=False):
    print("Battle won!")

Handle app lifecycle

# Check if app is running
if controller.adb.is_app_running(my_game, timeout=5, wait_time=1):
    print("App is active")

# Close app
my_game.close()

🔑 Key Concepts

• Controller: The brain. Manages ADB, BlueStacks, and Image recognition.
  • Convenience Methods: go_home(), go_back(), tap(), swipe(), capture_screen()
  • Delegates to sub-controllers internally for clean API
• App: Represents an Android package. Has a lifecycle (OPEN, CLOSED, LOADING).
• Screen: A collection of elements representing a UI screen (e.g., "Main Menu").
• Element: A UI component - button, image, text, or pixel that can be detected and interacted with.
• State Machine: Manages app and BlueStacks states with automatic transition handlers.

📚 Documentation

We have documentation for everyone:

• Explain Like I'm a Potato: For non-technical folks.
• Junior Dev Survival Guide: For developers getting started.
• God Mode Architecture Review: For architects and experts.

Detailed Guides

• Quickstart Guide: Step-by-step tutorial for beginners
• API Reference: Complete API documentation
• State Management: Understanding the state machine
• Testing Guide: Running and writing tests
• Config Guide: Configuration options
• OCR Engines: Choosing and configuring OCR
• Pluggability Guide: Extending Pymordial

💡 Examples

Check out the examples/ directory for practical, runnable examples:

• 01_basic_connection.py - Connect to BlueStacks (automatic connection!)
• 02_app_control.py - Open and close apps (uses config values)
• 03_element_clicking.py - Find and click UI elements
• 04_ocr_reading.py - Extract text with OCR
• 05_custom_app_screens.py - Structure complex apps

Run any example:

uv run python examples/01_basic_connection.py

⚠️ Requirements

• Windows 10/11 (Required for window management)
• BlueStacks 5+ (Tested on 5, might work on others)
• Python 3.13+
• ADB (Included with BlueStacks or install Android SDK)

Optional Dependencies

• Tesseract OCR: For text extraction (install separately)
• EasyOCR: Alternative OCR engine (slower but no external dependencies)

🔧 Troubleshooting

"No ADB device connected"

Cause: BlueStacks not running or ADB not enabled

Solution:

1. Start BlueStacks
2. Enable ADB in BlueStacks Settings → Advanced → Android Debug Bridge
3. Restart Pymordial controller

"Element not found" errors

Cause: Element image doesn't match or wrong screen

Solution:

1. Verify element is visible on current screen
2. Recapture element image at your resolution
3. Increase timeout: click_element(element, timeout=20)
4. Check image confidence threshold

"BlueStacks is closed" warnings

Cause: BlueStacks state not initialized

Solution:

controller = WorldLink()
# State is automatically set to READY when controller is created

OCR not detecting text

Cause: Poor image quality or wrong OCR engine

Solution:

1. Use high-contrast text
2. Crop screenshot to text area
3. Try different extraction strategies
4. Switch between Tesseract and EasyOCR

Import errors

Cause: Missing dependencies

Solution:

# Reinstall with all dependencies
uv pip install -e ".[dev]"

🤝 Contributing

Contributions welcome! Please:

1. Read the Junior Dev Guide
2. Check existing issues
3. Follow the Google Python Style Guide
4. Write tests for new features
5. Run the test suite: uv run pytest tests/ -v

📄 License

MIT License. See LICENSE for details.

---

Made with 💊 by IAmNo1Special

Automate responsibly. Don't break any ToS.