miku-discord/readmes/UNO_QUICK_REF.md

# 🎮 Miku UNO Bot - Quick Reference

## Setup (One-Time)
```bash
# 1. Install Playwright browsers
cd /home/koko210Serve/docker/miku-discord/bot
bash setup_uno_playwright.sh

# 2. Start UNO servers (2 terminals)
# Terminal 1 - Backend
cd /home/koko210Serve/docker/uno-online
node server.js

# Terminal 2 - Frontend
cd /home/koko210Serve/docker/uno-online/client
npm start

# 3. Start Miku bot
cd /home/koko210Serve/docker/miku-discord/bot
python bot.py
```

## Discord Commands

| Command | Description | Example |
|---------|-------------|---------|
| `!uno create` | Create & join new game | `!uno create` |
| `!uno join CODE` | Join existing game | `!uno join ABC123` |
| `!uno list` | Show active games | `!uno list` |
| `!uno quit CODE` | Leave a game | `!uno quit ABC123` |
| `!uno help` | Show help | `!uno help` |

## Quick Start Test

1. **In Discord**: Type `!uno create`
2. **Bot responds** with room code (e.g., ABC123)
3. **In browser**: Open http://192.168.1.2:3002
4. **Join room** with the code
5. **Game starts** automatically with 2 players
6. **Watch Miku play** and trash talk! 🎵

## File Locations

```
/home/koko210Serve/docker/miku-discord/
├── UNO_BOT_SETUP.md          # Full setup guide
├── UNO_BOT_TESTING.md        # Testing checklist
├── bot/
│   ├── commands/uno.py       # Discord command handler
│   ├── utils/uno_game.py     # Game automation
│   ├── bot.py                # Updated with !uno routing
│   └── setup_uno_playwright.sh  # Setup script

/home/koko210Serve/docker/uno-online/
├── server.js                 # Game backend (port 5000)
├── client/                   # Game frontend (port 3002)
├── test-bot-action.js        # Manual testing tool
├── BOT_ACTION_SPEC.md        # JSON action format
└── BOT_INTEGRATION_COMPLETE.md  # Integration details
```

## Architecture Flow

```
Discord User
    │
    ├─> !uno create
    │       │
    │       v
    │   Miku Bot (bot.py)
    │       │
    │       ├─> commands/uno.py (route command)
    │       │       │
    │       │       v
    │       │   utils/uno_game.py (MikuUnoPlayer)
    │       │       │
    │       │       ├─> Playwright (join game via browser)
    │       │       │       │
    │       │       │       v
    │       │       │   http://192.168.1.2:3002 (Frontend)
    │       │       │
    │       │       ├─> HTTP API (get state, send actions)
    │       │       │       │
    │       │       │       v
    │       │       │   http://localhost:5000/api/... (Backend)
    │       │       │
    │       │       └─> LLM (query_llama for strategy)
    │       │               │
    │       │               v
    │       │           Llama 3.1 Model
    │       │               │
    │       │               v
    │       │           JSON Action {"action":"play","card":"R5"}
    │       │
    │       └─> Discord Message (trash talk) 💙✨
    │
    v
Game proceeds...
```

## Key Components

### MikuUnoPlayer Class
- **Location**: `bot/utils/uno_game.py`
- **Methods**:
  - `create_and_join_game()` - Creates new room
  - `join_game()` - Joins existing room
  - `play_game()` - Main game loop (polls every 2s)
  - `get_miku_decision()` - LLM strategy
  - `send_trash_talk()` - Personality messages

### JSON Action Format
```json
{
  "action": "play",      // or "draw" or "uno"
  "card": "R5",         // card code (if playing)
  "color": "R",         // color choice (if Wild)
  "callUno": false      // true if calling UNO
}
```

### Card Codes
- **Colors**: R (Red), G (Green), B (Blue), Y (Yellow)
- **Numbers**: 0-9
- **Actions**: S (Skip), R (Reverse), D (Draw 2)
- **Wilds**: W (Wild), WD4 (Wild Draw 4)
- **Examples**: R5, GS, BD, W, WD4

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "Executable doesn't exist" | Run: `python -m playwright install chromium` |
| Bot not responding | Check bot.py is running, check logs |
| Game not starting | Check both UNO servers running (ports 5000, 3002) |
| Invalid moves | Check LLM logs, verify JSON format |
| Browser issues | Check Playwright installation |

## Logs to Watch

```bash
# Bot main logs
tail -f /home/koko210Serve/docker/miku-discord/bot/bot.log | grep UNO

# Look for:
[UNO] Creating new game room...
[MikuUnoPlayer] Browser launched
[MikuUnoPlayer] It's my turn!
[MikuUnoPlayer] Action executed successfully!
```

## Personality Traits

Miku's trash talk reflects her cheerful idol personality:
- 💙 Supportive and encouraging
- ✨ Uses sparkle emojis
- 🎵 Musical references
- ~ Playful tone with tildes
- 🎶 Upbeat and positive

## Next Steps

1. **Testing**: Use `UNO_BOT_TESTING.md` checklist
2. **Monitor**: Watch logs during first few games
3. **Adjust**: Tune polling interval or prompts if needed
4. **Enjoy**: Play UNO with Miku! 🎮

## Quick Debugging

```bash
# Check if Playwright is installed
python -c "from playwright.async_api import async_playwright; print('OK')"

# Check if UNO servers are up
curl http://localhost:5000/health
curl http://192.168.1.2:3002

# Test bot action API manually
node /home/koko210Serve/docker/uno-online/test-bot-action.js ABC123 '{"action":"draw"}'
```

## Documentation Index

- **UNO_BOT_SETUP.md** - Full setup guide with details
- **UNO_BOT_TESTING.md** - Comprehensive testing checklist  
- **BOT_ACTION_SPEC.md** - JSON action format specification
- **BOT_INTEGRATION_COMPLETE.md** - Technical integration details
- **QUICK_START_BOT.md** - Manual testing quick start

---

**Ready to test?** Type `!uno create` in Discord! 🎮✨