simple-botmaker 0.0.2

A package that simplifies the creation of bots that react to the screen in real time

Simple Botmaker

A package that simplifies the creation of bots that react to the screen in real time, for example your health gets low in a game so it automatically drinks a potion. Only works on Windows.

Features

• Screen Capture: Take screenshots of specific regions or entire screens
• Image Recognition: Find images on screen with template matching and scaling
• OCR (Optical Character Recognition): Extract text and numbers from screen regions
• Color Detection: Detect specific colors in screen regions
• Automated Input: Click, move mouse, and interact with applications
• Window Management: Work with specific windows or full screen
• Custom Interpreter: Secure script execution environment
• Bar/Gauge Reading: Extract percentage values from health bars, progress bars, etc.

Installation

From PyPI (Recommended)

pip install simple-botmaker

From Source

git clone https://github.com/yourusername/simple-botmaker.git
cd simple-botmaker
pip install -e .

Requirements

• Operating System: Windows (uses Windows-specific libraries)
• Python: 3.7 or higher
• Dependencies: All dependencies are automatically installed via pip

Quick Start

import simple_botmaker as sb

# Initialize settings for a specific window (optional)
sb.SETTINGS.window_name = "My Game Window"  # Leave None for full screen
sb.SETTINGS.monitor = 0  # Monitor index
sb.SETTINGS.debug = True  # Enable debug mode

# Take a screenshot of a region
screenshot = sb.TakeRegionScreenshot(100, 100, 200, 150)

# Find an image on screen
result = sb.FindImageInRegion(0, 0, 1920, 1080, "template.png", threshold=0.8)
if result:
    print(f"Found image at: {result['x']}, {result['y']}")
    sb.Click(result['x'], result['y'])

# Read text from a screen region
text = sb.GetText(100, 100, 300, 150)
print(f"Extracted text: {text}")

# Get health bar percentage
health_percent = sb.GetBar(50, 50, 200, 70, threshold=128)
print(f"Health: {health_percent}%")

# Get color-based bar (e.g., red health bar)
health_percent = sb.GetBarByColour(50, 50, 200, 70, 'red', tolerance=30)
print(f"Red bar: {health_percent}%")

Main Functions

Screen Capture

• TakeRegionScreenshot(x, y, width, height, grayscale=False, monitor=0) - Capture screen region
• GetPixelColour(x, y) - Get color of a specific pixel

Image Recognition

• FindImageInRegion(x, y, width, height, template_path, threshold=0.8, ...) - Find template image
• LoadFrameFromPath(path, grayscale=False) - Load image from file

OCR (Text Recognition)

• GetText(x1, y1, x2, y2, one_word=False, threshold=128, ...) - Extract text
• GetValue(x1, y1, x2, y2, threshold=128, ...) - Extract numeric values
• Capture2Text(frame, numeric_only=False, ...) - OCR on image frame

Bar/Gauge Reading

• GetBar(x1, y1, x2, y2, threshold=128, ...) - Get percentage from binary threshold
• GetBarByColour(x1, y1, x2, y2, color, tolerance=30, ...) - Get percentage by color

Automation

• Click(x, y, delay=100) - Click at coordinates
• MouseMove(x, y, delay=100) - Move mouse
• FocusedClick(x, y, focusDelay=100, delay=100) - Move then click

Utility

• SaveObject(fileName, obj) - Save object to file
• LoadObject(fileName) - Load object from file
• SetRegions() - Interactive region selection tool

Window Management

• GetWindowByName(window_name) - Get window object
• GetScreenResolution(monitor=0) - Get screen dimensions
• GetScreenCoordinatesFromWindowCoordinates(window_name, x, y) - Convert coordinates

Interactive Region Selection

Use the SetRegions() function to interactively select regions on your screen:

import simple_botmaker as sb

# Launch interactive region selector
sb.SetRegions()

This will:

1. Show you a list of available windows
2. Let you select regions, pixels, or screenshots
3. Save the coordinates and images to a timestamped folder
4. Generate a text file with all coordinates for easy copying

Custom Interpreter

The package includes a secure interpreter for running scripts with restricted access:

# Run a script with the custom interpreter
simple-botmaker-interpreter your_script.py

# Check script for issues without running
simple-botmaker-interpreter --check your_script.py

Configuration

Configure global settings:

import simple_botmaker as sb

# Configure for a specific window
sb.SETTINGS.window_name = "Game Window"
sb.SETTINGS.monitor = 0  # Primary monitor
sb.SETTINGS.debug = True  # Enable debug output

# Or work with full screen (default)
sb.SETTINGS.window_name = None

Examples

Health Monitoring Bot

import simple_botmaker as sb
import time

sb.SETTINGS.window_name = "My Game"

while True:
    # Check health bar (red color)
    health = sb.GetBarByColour(100, 50, 200, 70, 'red')
    
    if health < 30:  # Health below 30%
        # Click health potion
        sb.Click(500, 600)
        print("Used health potion!")
        time.sleep(2)
    
    time.sleep(0.5)  # Check every 500ms

Text Recognition Bot

import simple_botmaker as sb

# Read game score
score_text = sb.GetValue(800, 50, 900, 80)
print(f"Current Score: {score_text}")

# Check if specific text appears
status_text = sb.GetText(400, 200, 600, 230, one_word=True)
if status_text == "READY":
    sb.Click(500, 300)  # Click start button

Platform Support

• Windows: Full support (primary platform)
• macOS/Linux: Not supported (uses Windows-specific libraries)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This software is intended for educational and automation purposes. Users are responsible for ensuring compliance with the terms of service of any applications they interact with. The authors are not responsible for any misuse of this software.

Support

• Issues: GitHub Issues
• Documentation: This README and inline code documentation
• Examples: See the examples in the repository

Changelog

Version 1.0.0

• Initial release
• Core screen capture functionality
• Image recognition with template matching
• OCR support with Capture2Text integration
• Bar/gauge reading capabilities
• Interactive region selection tool
• Custom secure interpreter
• Full Windows automation support