Initial project structure: reusable isometric bot engine with D2R implementation

README.md

@@ -0,0 +1,132 @@
+# 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.