miku-discord/readmes/UNO_QUICK_REF.md

🎮 Miku UNO Bot - Quick Reference

Setup (One-Time)

# 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

{
  "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

# 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

# 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! 🎮✨