miku-discord/uno-online/BOT_QUICK_REF.md

# UNO Bot Integration - Quick Reference

## Game State JSON Quick View

### Checking Bot's Turn
```javascript
gameState.game.currentTurn === "Player 2"  // Bot's turn
gameState.player2.isCurrentTurn  // Alternative check
```

### Getting Playable Cards
```javascript
const playable = gameState.player2.playableCards
// Each card has: code, type, value, color, displayName, isPlayable
```

### Card Types
- `number`: 0-9 cards
- `skip`: Skip opponent (code: 404)
- `reverse`: Reverse direction (code: 0, acts as skip in 2-player)
- `draw2`: Opponent draws 2 (code: 252)
- `wild`: Change color (code: 300)
- `draw4_wild`: Change color + opponent draws 4 (code: 600)

### Current Card Info
```javascript
gameState.currentCard.displayName  // "5 red"
gameState.currentCard.color  // "R"
gameState.currentCard.value  // 5
```

### Bot Status
```javascript
gameState.botContext.canPlay    // Can play a card?
gameState.botContext.mustDraw   // Must draw a card?
gameState.botContext.hasUno     // Has 2 cards (press UNO)?
gameState.botContext.isWinning  // Has 1 card (about to win)?
```

## API Quick Reference

### Get Game State
```bash
GET http://localhost:5000/api/game/ABC123/state
```

### Play a Card
```bash
POST http://localhost:5000/api/game/ABC123/action
Content-Type: application/json

{
  "action": "play_card",
  "cardCode": "5R",
  "chosenColor": null
}
```

### Play Wild Card
```bash
POST http://localhost:5000/api/game/ABC123/action
Content-Type: application/json

{
  "action": "play_card",
  "cardCode": "W",
  "chosenColor": "R"
}
```

### Draw a Card
```bash
POST http://localhost:5000/api/game/ABC123/action
Content-Type: application/json

{
  "action": "draw_card"
}
```

## Color Codes
- `R` = Red
- `G` = Green
- `B` = Blue
- `Y` = Yellow

## Card Code Examples
- `5R` = 5 Red
- `0G` = 0 Green
- `skipB` = Skip Blue
- `_Y` = Reverse Yellow
- `D2R` = Draw 2 Red
- `W` = Wild
- `D4W` = Draw 4 Wild

## Simple Bot Logic

```python
# 1. Get game state
state = requests.get(f"{base_url}/api/game/{room}/state").json()['gameState']

# 2. Check if bot's turn
if state['game']['currentTurn'] != 'Player 2':
    return  # Not our turn

# 3. Get playable cards
playable = state['player2']['playableCards']

# 4. Choose card (simple strategy: play first playable)
if playable:
    card = playable[0]
    action = {
        'action': 'play_card',
        'cardCode': card['code'],
        'chosenColor': 'R' if 'wild' in card['type'] else None
    }
else:
    action = {'action': 'draw_card'}

# 5. Submit action
requests.post(f"{base_url}/api/game/{room}/action", json=action)
```

## LLM Prompt Template

```
You are playing UNO as Player 2.

CURRENT CARD: {currentCard.displayName}
YOUR HAND: {player2.cards with displayNames}
PLAYABLE CARDS: {player2.playableCards}
OPPONENT CARDS: {player1.cardCount}

RULES:
- Match color OR number
- Wild cards can be played anytime
- Special cards: Skip (opponent skips turn), Draw 2, Wild, Draw 4

Choose an action. Respond in JSON format:
{"action": "play_card", "cardCode": "CODE", "chosenColor": "R/G/B/Y or null"}
OR
{"action": "draw_card"}

Your decision:
```

## Console Logs to Watch

When running the game, look for these in browser console:
- `🎮 UNO GAME STATE (Simplified):` - Quick view
- `🤖 FULL GAME STATE (For Bot):` - Complete state object
- `📋 JSON for Bot API:` - Formatted JSON (copy-paste ready)

## Files Modified

### Client-side
- `/client/src/components/Game.js` - Added game state export & logging
- `/client/src/utils/cardParser.js` - NEW: Card parsing utilities
- `/client/src/utils/gameStateBuilder.js` - NEW: Game state JSON builder

### Server-side
- `/server.js` - Added HTTP API endpoints & Socket.IO event handlers

## Testing Workflow

1. Start server: `npm start` (in /uno-online)
2. Start client: `npm start` (in /uno-online/client)
3. Create game in browser, get room code
4. Join as Player 2
5. Open browser console (F12)
6. Watch for game state logs
7. Test API: `curl http://localhost:5000/api/game/ROOMCODE/state`

## Next: Miku Bot Integration

See `BOT_INTEGRATION_GUIDE.md` for full implementation details.