# 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. Engine runs on host, game runs in VM for detection isolation.

## Repository
- **Local:** `/home/openclaw/.openclaw/workspace/projects/iso-bot`
- **Remote:** `ssh://forgejo@git.cloonar.com/openclawd/iso-bot.git`

## Tech Stack
- **Engine:** Go 1.23+
- **Vision:** GoCV (OpenCV bindings for Go)
- **Screen capture:** Platform-native (Win32 API / X11)
- **Input simulation:** Platform-native (SendInput / uinput)
- **API:** net/http + gorilla/websocket (REST + WS)
- **Dashboard:** React + TypeScript (planned)
- **Config:** YAML
- **Loot filter:** Declarative YAML rule engine

## Architecture

```
cmd/iso-bot/          Single binary entry point
pkg/
├── engine/
│   ├── capture/      Screen capture (window, VM, full screen)
│   ├── vision/       Template matching, color detection (GoCV)
│   ├── input/        Mouse (Bézier curves), keyboard, humanization
│   ├── state/        Game state machine with event callbacks
│   ├── safety/       Session timing, breaks, pattern randomization
│   ├── navigation/   A* pathfinding, click-to-move
│   └── loot/         Declarative rule-based loot filter
├── plugin/           Game plugin interface
├── api/              REST + WebSocket API
└── auth/             License/account validation
plugins/d2r/          D2R game plugin
web/                  React dashboard (planned)
```

## Plugin System
All game logic is behind interfaces in `pkg/plugin/plugin.go`:
- `Plugin` — main entry point, returns detector/reader/routines
- `GameDetector` — detect state from screenshots
- `ScreenReader` — extract items, enemies, text
- `Routine` — automated farming sequences (context-aware, cancellable)
- `LootFilter` — item pickup rules
- `EngineServices` — engine capabilities provided to plugins

## Development Conventions
- Go standard project layout
- Type hints / godoc on all exported types
- `gofmt` formatting
- Tests in `*_test.go` files alongside code
- Feature branches → main
- Always commit and push after changes

## Git Workflow
```bash
cd /home/openclaw/.openclaw/workspace/projects/iso-bot
git add -A && git commit -m "descriptive message"
GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no" git push origin main
```

## Current Status
- ✅ Go project structure
- ✅ Plugin interface system (`pkg/plugin`)
- ✅ Engine: capture, vision, input/humanize, state, safety, loot filter
- ✅ API server skeleton (REST endpoints)
- ✅ D2R plugin: config, detector, reader, Mephisto routine
- ✅ Declarative loot filter with YAML rules
- ⏳ Platform-specific capture backends (Win32, X11)
- ⏳ GoCV integration for actual vision processing
- ⏳ Platform-specific input backends
- ⏳ Remaining D2R routines (Pindle, Countess)
- ⏳ Web dashboard (React)
- ⏳ Account/license system
- ⏳ Multi-instance support
- ⏳ Tests

## Next Steps (Priority Order)
1. GoCV integration — make vision pipeline actually work
2. Platform capture backends — Windows (BitBlt/DXGI) and Linux (X11)
3. Platform input backends — Windows (SendInput) and Linux (uinput)
4. D2R detector implementation — health orb reading, menu detection
5. D2R Mephisto routine — complete implementation
6. WebSocket real-time status streaming
7. React dashboard
8. Pindle + Countess routines
9. Account system + licensing

## Key Design Decisions
1. **Go over Python** — performance for real-time capture+vision at 30+ FPS
2. **Plugin system** — engine is game-agnostic, new game = new plugin
3. **VM isolation** — engine on host, game in VM, zero detection surface
4. **Declarative loot** — YAML rules, user-customizable via web UI
5. **Single binary** — engine + API in one Go binary, easy distribution
6. **Human-like input** — Bézier curves, fatigue, breaks, route randomization

## D2R Notes
- Target resolution: 1920x1080
- Primary farming character: Sorceress with Teleport
- Key routines: Mephisto (moat trick), Pindle (fastest), Countess (runes)
- Screen regions and HSV colors defined in `plugins/d2r/config.go`
- The user plays D2R actively and knows the game well