miku-discord/uno-online/BOT_QUICK_REF.md

UNO Bot Integration - Quick Reference

Game State JSON Quick View

Checking Bot's Turn

gameState.game.currentTurn === "Player 2"  // Bot's turn
gameState.player2.isCurrentTurn  // Alternative check

Getting Playable Cards

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

gameState.currentCard.displayName  // "5 red"
gameState.currentCard.color  // "R"
gameState.currentCard.value  // 5

Bot Status

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

GET http://localhost:5000/api/game/ABC123/state

Play a Card

POST http://localhost:5000/api/game/ABC123/action
Content-Type: application/json

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

Play Wild Card

POST http://localhost:5000/api/game/ABC123/action
Content-Type: application/json

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

Draw a Card

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

# 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.