# ISO Bot — Isometric Game Bot Engine

## Overview
Screen-reading bot engine for isometric games. First implementation: Diablo II: Resurrected.

**Approach:** Screen capture + computer vision + human-like input simulation. No memory injection, no hooking, no client modification.

## Repository
- **Local:** `/home/openclaw/.openclaw/workspace/projects/iso-bot`
- **Remote:** `git@git.cloonar.com:openclawd/iso-bot.git` (pending repo creation)

## Architecture

```
engine/           # Reusable core — game-agnostic
├── screen/       # Screenshot capture (mss), OCR, template matching
├── input/        # Mouse (bezier curves), keyboard, humanization
├── vision/       # Object detection, color analysis, UI element finding
├── state/        # State machine, event bus
├── navigation/   # Pathfinding (A*), click-to-move
└── safety/       # Session timing, break scheduling, pattern randomization

games/d2r/        # Diablo II: Resurrected implementation
├── config.py     # Screen regions, colors, timings (1920x1080)
├── game.py       # Main bot loop & orchestration
├── screens/      # State detection (menu, in-game, inventory)
├── routines/     # Farming routines (Mephisto, Pindle, Countess)
└── templates/    # UI template images for matching

ui/               # Web dashboard (FastAPI) — planned
config/           # YAML configuration
```

## Key Design Decisions
1. **Screen reading only** — captures screenshots, analyzes pixels/templates, never touches game memory
2. **Human-like input** — Bezier mouse curves, randomized delays, micro/long breaks, fatigue simulation
3. **Reusable engine** — adding a new game = new `games/<name>/` directory implementing game-specific detection
4. **Anti-detection** — session timing, route randomization, behavioral variation, configurable break schedules
5. **Configuration-driven** — YAML configs for all tunable parameters

## Tech Stack
- Python 3.11+
- OpenCV (template matching, color detection)
- pytesseract (OCR)
- mss (fast screenshot capture)
- pyautogui/pynput (input simulation)
- FastAPI (dashboard — planned)

## Development Conventions
- Type hints on all functions
- Docstrings on all modules, classes, public methods
- `black` formatting
- Tests in `tests/`
- Feature branches → main

## Git Workflow
```bash
cd /home/openclaw/.openclaw/workspace/projects/iso-bot
git checkout -b feature/<name>
# ... work ...
git add -A && git commit -m "descriptive message"
git checkout main && git merge feature/<name>
git push origin main
```

## Current Status
- ✅ Project structure created
- ✅ Core engine modules with meaningful stubs
- ✅ D2R config (screen regions, colors, timings)
- ✅ D2R farming routines (Mephisto, Pindle, Countess) — stub phase
- ⏳ Remote git repo (needs write-access token)
- ⏳ Implement actual screen detection logic
- ⏳ Implement input simulation
- ⏳ Template image collection
- ⏳ Web dashboard
- ⏳ Testing

## Next Steps (Priority Order)
1. Get remote repo set up and push
2. Implement `engine/screen/capture.py` — verified working on target machine
3. Implement `engine/input/mouse.py` — Bezier curve mouse movement
4. Implement `engine/input/keyboard.py` — human-like key presses
5. D2R menu detection (character select, create game)
6. D2R basic Mephisto run (teleport → kill → loot → exit)
7. Loot detection and filtering
8. Web dashboard for monitoring

## Notes
- Bot runs on a separate machine or VM from the game client
- Target resolution: 1920x1080
- Primary farming character: Sorceress with Teleport
- The user plays D2R (Necro "Baltasar", Summoner build) — knows the game well