reorganize: consolidate all documentation into readmes/
- Moved 20 root-level markdown files to readmes/ - Includes COMMANDS.md, CONFIG_README.md, all UNO docs, all completion reports - Added new: MEMORY_EDITOR_FEATURE.md, MEMORY_EDITOR_ESCAPING_FIX.md, CONFIG_SOURCES_ANALYSIS.md, MCP_TOOL_CALLING_ANALYSIS.md, and others - Root directory is now clean of documentation clutter
This commit is contained in:
192
readmes/UNO_QUICK_REF.md
Normal file
192
readmes/UNO_QUICK_REF.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 🎮 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! 🎮✨
|
||||
Reference in New Issue
Block a user