# 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)
```bash
pip install simple-botmaker
```
### From Source
```bash
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
```python
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:
```python
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:
```bash
# 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:
```python
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
```python
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
```python
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](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](https://github.com/yourusername/simple-botmaker/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
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/simple-botmaker",
"name": "simple-botmaker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "automation, bot, screen-capture, ocr, image-recognition, windows",
"author": "Jayden Clarke",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4c/3b/18c79903f452b31ff64c6e4cf5f4227f06e288fa2c854952bb765798a9ae/simple_botmaker-0.0.2.tar.gz",
"platform": "win32",
"description": "# Simple Botmaker\r\n\r\nA 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.**\r\n\r\n## Features\r\n\r\n- **Screen Capture**: Take screenshots of specific regions or entire screens\r\n- **Image Recognition**: Find images on screen with template matching and scaling\r\n- **OCR (Optical Character Recognition)**: Extract text and numbers from screen regions\r\n- **Color Detection**: Detect specific colors in screen regions\r\n- **Automated Input**: Click, move mouse, and interact with applications\r\n- **Window Management**: Work with specific windows or full screen\r\n- **Custom Interpreter**: Secure script execution environment\r\n- **Bar/Gauge Reading**: Extract percentage values from health bars, progress bars, etc.\r\n\r\n## Installation\r\n\r\n### From PyPI (Recommended)\r\n\r\n```bash\r\npip install simple-botmaker\r\n```\r\n\r\n### From Source\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/simple-botmaker.git\r\ncd simple-botmaker\r\npip install -e .\r\n```\r\n\r\n## Requirements\r\n\r\n- **Operating System**: Windows (uses Windows-specific libraries)\r\n- **Python**: 3.7 or higher\r\n- **Dependencies**: All dependencies are automatically installed via pip\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport simple_botmaker as sb\r\n\r\n# Initialize settings for a specific window (optional)\r\nsb.SETTINGS.window_name = \"My Game Window\" # Leave None for full screen\r\nsb.SETTINGS.monitor = 0 # Monitor index\r\nsb.SETTINGS.debug = True # Enable debug mode\r\n\r\n# Take a screenshot of a region\r\nscreenshot = sb.TakeRegionScreenshot(100, 100, 200, 150)\r\n\r\n# Find an image on screen\r\nresult = sb.FindImageInRegion(0, 0, 1920, 1080, \"template.png\", threshold=0.8)\r\nif result:\r\n print(f\"Found image at: {result['x']}, {result['y']}\")\r\n sb.Click(result['x'], result['y'])\r\n\r\n# Read text from a screen region\r\ntext = sb.GetText(100, 100, 300, 150)\r\nprint(f\"Extracted text: {text}\")\r\n\r\n# Get health bar percentage\r\nhealth_percent = sb.GetBar(50, 50, 200, 70, threshold=128)\r\nprint(f\"Health: {health_percent}%\")\r\n\r\n# Get color-based bar (e.g., red health bar)\r\nhealth_percent = sb.GetBarByColour(50, 50, 200, 70, 'red', tolerance=30)\r\nprint(f\"Red bar: {health_percent}%\")\r\n```\r\n\r\n## Main Functions\r\n\r\n### Screen Capture\r\n- `TakeRegionScreenshot(x, y, width, height, grayscale=False, monitor=0)` - Capture screen region\r\n- `GetPixelColour(x, y)` - Get color of a specific pixel\r\n\r\n### Image Recognition\r\n- `FindImageInRegion(x, y, width, height, template_path, threshold=0.8, ...)` - Find template image\r\n- `LoadFrameFromPath(path, grayscale=False)` - Load image from file\r\n\r\n### OCR (Text Recognition)\r\n- `GetText(x1, y1, x2, y2, one_word=False, threshold=128, ...)` - Extract text\r\n- `GetValue(x1, y1, x2, y2, threshold=128, ...)` - Extract numeric values\r\n- `Capture2Text(frame, numeric_only=False, ...)` - OCR on image frame\r\n\r\n### Bar/Gauge Reading\r\n- `GetBar(x1, y1, x2, y2, threshold=128, ...)` - Get percentage from binary threshold\r\n- `GetBarByColour(x1, y1, x2, y2, color, tolerance=30, ...)` - Get percentage by color\r\n\r\n### Automation\r\n- `Click(x, y, delay=100)` - Click at coordinates\r\n- `MouseMove(x, y, delay=100)` - Move mouse\r\n- `FocusedClick(x, y, focusDelay=100, delay=100)` - Move then click\r\n\r\n### Utility\r\n- `SaveObject(fileName, obj)` - Save object to file\r\n- `LoadObject(fileName)` - Load object from file\r\n- `SetRegions()` - Interactive region selection tool\r\n\r\n### Window Management\r\n- `GetWindowByName(window_name)` - Get window object\r\n- `GetScreenResolution(monitor=0)` - Get screen dimensions\r\n- `GetScreenCoordinatesFromWindowCoordinates(window_name, x, y)` - Convert coordinates\r\n\r\n## Interactive Region Selection\r\n\r\nUse the `SetRegions()` function to interactively select regions on your screen:\r\n\r\n```python\r\nimport simple_botmaker as sb\r\n\r\n# Launch interactive region selector\r\nsb.SetRegions()\r\n```\r\n\r\nThis will:\r\n1. Show you a list of available windows\r\n2. Let you select regions, pixels, or screenshots\r\n3. Save the coordinates and images to a timestamped folder\r\n4. Generate a text file with all coordinates for easy copying\r\n\r\n## Custom Interpreter\r\n\r\nThe package includes a secure interpreter for running scripts with restricted access:\r\n\r\n```bash\r\n# Run a script with the custom interpreter\r\nsimple-botmaker-interpreter your_script.py\r\n\r\n# Check script for issues without running\r\nsimple-botmaker-interpreter --check your_script.py\r\n```\r\n\r\n## Configuration\r\n\r\nConfigure global settings:\r\n\r\n```python\r\nimport simple_botmaker as sb\r\n\r\n# Configure for a specific window\r\nsb.SETTINGS.window_name = \"Game Window\"\r\nsb.SETTINGS.monitor = 0 # Primary monitor\r\nsb.SETTINGS.debug = True # Enable debug output\r\n\r\n# Or work with full screen (default)\r\nsb.SETTINGS.window_name = None\r\n```\r\n\r\n## Examples\r\n\r\n### Health Monitoring Bot\r\n```python\r\nimport simple_botmaker as sb\r\nimport time\r\n\r\nsb.SETTINGS.window_name = \"My Game\"\r\n\r\nwhile True:\r\n # Check health bar (red color)\r\n health = sb.GetBarByColour(100, 50, 200, 70, 'red')\r\n \r\n if health < 30: # Health below 30%\r\n # Click health potion\r\n sb.Click(500, 600)\r\n print(\"Used health potion!\")\r\n time.sleep(2)\r\n \r\n time.sleep(0.5) # Check every 500ms\r\n```\r\n\r\n### Text Recognition Bot\r\n```python\r\nimport simple_botmaker as sb\r\n\r\n# Read game score\r\nscore_text = sb.GetValue(800, 50, 900, 80)\r\nprint(f\"Current Score: {score_text}\")\r\n\r\n# Check if specific text appears\r\nstatus_text = sb.GetText(400, 200, 600, 230, one_word=True)\r\nif status_text == \"READY\":\r\n sb.Click(500, 300) # Click start button\r\n```\r\n\r\n## Platform Support\r\n\r\n- **Windows**: Full support (primary platform)\r\n- **macOS/Linux**: Not supported (uses Windows-specific libraries)\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## Disclaimer\r\n\r\nThis 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.\r\n\r\n## Support\r\n\r\n- **Issues**: [GitHub Issues](https://github.com/yourusername/simple-botmaker/issues)\r\n- **Documentation**: This README and inline code documentation\r\n- **Examples**: See the examples in the repository\r\n\r\n## Changelog\r\n\r\n### Version 1.0.0\r\n- Initial release\r\n- Core screen capture functionality\r\n- Image recognition with template matching\r\n- OCR support with Capture2Text integration\r\n- Bar/gauge reading capabilities\r\n- Interactive region selection tool\r\n- Custom secure interpreter\r\n- Full Windows automation support\r\n",
"bugtrack_url": null,
"license": "Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)",
"summary": "A package that simplifies the creation of bots that react to the screen in real time",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/BARKEM-JC/simple-botmaker"
},
"split_keywords": [
"automation",
" bot",
" screen-capture",
" ocr",
" image-recognition",
" windows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fdcedb50b2ccc65754ca3f7b0b84e902486670a047e44cd4bfde025ac1319f96",
"md5": "e3a5fb870c434c78498a4e9a4ae45b04",
"sha256": "cfeb33aadaec700ba8e0e0e4a517d8ccf65f5bf873031d67f81ecce603a4c039"
},
"downloads": -1,
"filename": "simple_botmaker-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3a5fb870c434c78498a4e9a4ae45b04",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15113,
"upload_time": "2025-08-12T22:07:05",
"upload_time_iso_8601": "2025-08-12T22:07:05.298343Z",
"url": "https://files.pythonhosted.org/packages/fd/ce/db50b2ccc65754ca3f7b0b84e902486670a047e44cd4bfde025ac1319f96/simple_botmaker-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c3b18c79903f452b31ff64c6e4cf5f4227f06e288fa2c854952bb765798a9ae",
"md5": "572059e3c8808ac31dff13806f214b70",
"sha256": "89dfdeab5aa2bbb4358f26f7dadc5f7cd6b6459beb4767d507da3c7c6ea69174"
},
"downloads": -1,
"filename": "simple_botmaker-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "572059e3c8808ac31dff13806f214b70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17124,
"upload_time": "2025-08-12T22:07:12",
"upload_time_iso_8601": "2025-08-12T22:07:12.672846Z",
"url": "https://files.pythonhosted.org/packages/4c/3b/18c79903f452b31ff64c6e4cf5f4227f06e288fa2c854952bb765798a9ae/simple_botmaker-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 22:07:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "simple-botmaker",
"github_not_found": true,
"lcname": "simple-botmaker"
}
JSON
