# ISO Bot - Isometric Game Bot Engine

A reusable bot engine designed for isometric games, starting with Diablo II: Resurrected. Built on screen-reading and human-like input simulation principles.

## Project Goals

- **Reusable Architecture**: Core engine that can be adapted to different isometric games
- **Screen-Reading Approach**: No memory injection or game modification - purely visual recognition
- **Human-like Behavior**: Realistic mouse movement, timing patterns, and randomization
- **Modular Design**: Clean separation between engine components and game-specific implementations
- **Safety First**: Built-in anti-detection measures and break scheduling

## Architecture Overview

### Core Engine (`engine/`)

The reusable engine provides fundamental bot capabilities:

- **Screen Module**: Screenshot capture, OCR text extraction, template matching
- **Input Module**: Human-like mouse movement with Bézier curves, keyboard input with realistic timing
- **Vision Module**: Computer vision utilities for object detection and color analysis  
- **State Module**: Game state management with event system
- **Navigation Module**: Pathfinding algorithms and movement control
- **Safety Module**: Anti-detection measures including timing randomization and break scheduling

### Game Implementations (`games/`)

Game-specific implementations inherit from the core engine:

- **D2R Module**: Diablo II: Resurrected implementation with screen detection, bot routines, and UI templates

### Supporting Components

- **UI Module**: Web dashboard for monitoring and control
- **Config Module**: YAML-based configuration system
- **Tests Module**: Unit tests for engine components

## Technical Approach

### Screen Reading Only

This bot uses **no memory injection or game modification**. All game state detection relies on:

- Screenshot analysis using OpenCV
- OCR text extraction with pytesseract  
- Template matching for UI elements
- Color-based object detection

### Human-like Input

All input simulation mimics human behavior:

- **Mouse Movement**: Bézier curves with natural acceleration/deceleration
- **Timing Patterns**: Randomized delays based on realistic human response times
- **Break Scheduling**: Regular breaks with varying durations
- **Behavioral Randomization**: Varied click positions, movement patterns, and reaction times

## Adding a New Game

1. Create directory under `games/your_game/`
2. Inherit from `engine.state.manager.GameStateManager`
3. Implement screen detection classes in `screens/`
4. Define bot routines in `routines/`
5. Add UI templates for visual recognition
6. Configure game-specific settings

## Diablo II: Resurrected Implementation

The D2R implementation includes:

- **Screen Detection**: Main menu, character select, in-game state, inventory management
- **Bot Routines**: Mephisto runs, Pindleskin runs, Countess runs
- **Template Matching**: UI elements, items, monsters
- **Configuration**: D2R-specific timing, coordinates, and behavior settings

## Installation & Setup

```bash
# Install dependencies
pip install -r requirements.txt

# Configure settings
cp config/default.yaml config/local.yaml
# Edit local.yaml with your settings

# Run bot
python -m games.d2r.game
```

## Development

- **Python 3.11+** required
- **Code Style**: Black formatting, type hints required
- **Testing**: pytest for unit tests
- **Git Workflow**: Feature branches, PR reviews

## Safety & Responsibility

This bot is intended for educational and research purposes. Users are responsible for:

- Compliance with game terms of service
- Ethical use of automation
- Respect for other players
- Following applicable laws and regulations

## Architecture Decisions

- **Screen-reading only**: Maintains game integrity, reduces detection risk
- **Human-like input**: Natural behavior patterns for safety
- **Modular design**: Enables reuse across different games
- **Configuration-driven**: Easy customization without code changes
- **Event-driven state management**: Responsive to changing game conditions

## Current Status

✅ Initial project structure created  
⏳ Engine implementation in progress  
⏳ D2R game implementation pending  
⏳ Web dashboard pending  
⏳ Testing framework pending  

## Contributing

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

## License

This project is for educational purposes. Please respect game terms of service and applicable laws.