LLM-powered AI agent framework for 4X mobile strategy games.
Build AI bots that play Rise of Kingdoms, Evony, Lords Mobile, Kingshot, and other city-building strategy games — using vision + reasoning at 99% lower cost than pure LLM approaches.
Existing game bots are either:
- Rule-based (pixel matching, hardcoded coordinates) — fragile, no reasoning
- Pure LLM (send every screenshot to GPT-4/Claude) — smart but costs $1+/hour
This framework combines both: local perception handles 98% of decisions for free, LLM vision steps in only when the bot is stuck or needs strategic planning.
| Approach | Cost/Hour | Cost/Month (24/7) |
|---|---|---|
| Pure LLM (every 3s) | ~$1.00 | ~$720 |
| 4x-game-agent | ~$0.01 | ~$7 |
LAYER 5: STRATEGIC AI ──── LLM vision review (every 30 min, ~$0.004)
LAYER 4: WORKFLOWS ─────── Scripted tap sequences with verification (FREE)
LAYER 3: WORLD MODEL ───── Persistent state + timer predictions (FREE)
LAYER 2: STATE MACHINE ─── Screen detection + popup handling (FREE)
LAYER 1: PERCEPTION ────── Pixel classify (<100ms) + OCR text reading (FREE)
| Game | Status | Contributor |
|---|---|---|
| Kingshot | Reference implementation | @sonpiaz |
| Rise of Kingdoms | Planned | Help wanted! |
| Evony: The King's Return | Planned | Help wanted! |
| Lords Mobile | Planned | Help wanted! |
| Call of Dragons | Planned | Help wanted! |
Want to add your game? See Adding a New Game.
git clone https://github.com/sonpiaz/4x-game-agent.git
cd 4x-game-agent
pip install -e ".[all]"# Start BlueStacks/LDPlayer with your game
adb devices # Should show your emulatorexport ANTHROPIC_API_KEY='sk-ant-...' # Optional: for AI fallback
cd games/kingshot
python main.py --test # Test connection + OCR
python main.py # Run the botcp -r games/_template games/my_game
# Edit config.yaml, coordinate_map.py, knowledge.py, etc.
# See docs/adding-a-game.md for the full guide4x-game-agent/
├── agent/ # Core utilities (game-agnostic)
│ ├── adb.py # ADB screenshot + tap/swipe
│ ├── ocr.py # PaddleOCR text reading
│ ├── template_match.py # OpenCV visual matching
│ ├── reflection.py # Success/failure learning
│ ├── llm.py # LLM vision API wrapper
│ └── dashboard.py # Web monitoring UI
│
├── games/
│ ├── kingshot/ # Reference implementation (fully working)
│ │ ├── main.py # Entry point
│ │ ├── config.yaml # Game settings
│ │ ├── engine.py # Bot engine
│ │ ├── coordinate_map.py # UI positions
│ │ ├── knowledge.py # Game data (TC1-30 prerequisites)
│ │ └── ... # FSM, workflows, world model, etc.
│ │
│ └── _template/ # Copy this to start a new game
│
└── docs/
├── architecture.md # How it works
├── adding-a-game.md # Step-by-step guide
└── cost-analysis.md # Cost breakdown
- Take screenshot via ADB (works with any Android emulator)
- Classify screen using pixel analysis (<100ms, no API)
- Handle popups automatically via FSM (tap close/cancel)
- Check timers in world model (predict when builders/research finish)
- Execute workflows — scripted tap sequences for upgrades, training, etc.
- OCR read game state every 60s (power, gems, resources)
- AI review every 30 min — Claude Sonnet checks if strategy is on track
- AI fallback — if a workflow fails, Claude Haiku guides step-by-step
- Multi-game framework — plug any 4X strategy game
- Self-improving — learns building positions via template capture
- Self-reflecting — logs failures and avoids repeating mistakes
- Config-driven — YAML config, no code changes for tuning
- Web dashboard — real-time monitoring at
localhost:8080 - Cost-efficient — 99% cheaper than pure LLM approaches
This framework works best with 4X mobile strategy games that share this gameplay loop:
Build city → Research → Train troops → Collect resources → Alliance help → Hero upgrades → Events → Repeat
Examples: Rise of Kingdoms, Evony, Lords Mobile, Call of Dragons, King of Avalon, Whiteout Survival, State of Survival, Viking Rise, Age of Empires Mobile, Last War, Kingshot.
We welcome contributions! The most valuable contribution is adding a new game.
See CONTRIBUTING.md for guidelines.
MIT — see LICENSE.