jackboxpartypack-gamepicker/scripts

Jackbox Player Count Fetcher

Tools to retrieve the actual player count from a Jackbox game room in real-time.

Available Implementations

1. Go + chromedp (Recommended) 🚀

The most reliable method - automates joining through jackbox.tv to capture WebSocket data.

2. Browser HTML Interface 🌐

Quick visual tool for manual testing - no installation required.

3. Node.js Script (Limited)

Attempts direct WebSocket connection - may not work due to authentication requirements.

Features

• 🔍 Automatically joins jackbox.tv to capture WebSocket data
• 📊 Returns actual player count (not just max capacity)
• 👥 Lists all current players and their roles (host/player)
• 🎮 Shows game state, lobby state, and audience count
• 🎨 Pretty-printed output with colors

Installation

Go Version (Recommended)

cd scripts
go mod download

Prerequisites: Go 1.21+ and Chrome/Chromium browser installed

Browser Version (No Installation Required!)

Just open get-player-count.html in any web browser - no installation needed!

Node.js Version

cd scripts
npm install

Note: The Node.js version may not work reliably due to Jackbox WebSocket authentication requirements.

Usage

Go Version (Best) 🚀

# Navigate to scripts directory
cd scripts

# Run the script
go run get-player-count.go JYET

# Or build and run
go build -o get-player-count get-player-count.go
./get-player-count JYET

How it works:

1. Opens jackbox.tv in headless Chrome
2. Automatically enters room code and joins as "Observer"
3. Captures WebSocket messages from the browser
4. Extracts player count from client/welcome message
5. Enriches with data from REST API

Browser Version 🌐

# Just open in browser
open get-player-count.html

1. Open get-player-count.html in your web browser
2. Enter a room code (e.g., "JYET")
3. Click "Get Player Count"
4. View results instantly

This version runs entirely in the browser and doesn't require any backend!

Node.js Version (Limited)

node get-jackbox-player-count.js JYET

Warning: May fail due to WebSocket authentication requirements. Use the Go version for reliable results.

JSON Output (for scripting)

JSON_OUTPUT=true node get-jackbox-player-count.js JYET

As a Module

const { getRoomInfo, getPlayerCount } = require('./get-jackbox-player-count');

async function example() {
  const roomCode = 'JYET';
  
  // Get room info
  const roomInfo = await getRoomInfo(roomCode);
  console.log('Game:', roomInfo.appTag);
  
  // Get player count
  const result = await getPlayerCount(roomCode, roomInfo);
  console.log('Players:', result.playerCount);
  console.log('Player list:', result.players);
}

example();

Output Example

Jackbox Player Count Fetcher
Room Code: JYET

Fetching room information...
✓ Room found: triviadeath
  Max Players: 8

Connecting to WebSocket...
URL: wss://i-007fc4f534bce7898.play.jackboxgames.com/api/v2/rooms/JYET

✓ WebSocket connected

═══════════════════════════════════════════
  Jackbox Room Status
═══════════════════════════════════════════

Room Code:      JYET
Game:           triviadeath
Game State:     Lobby
Lobby State:    CanStart
Locked:         No
Full:           No

Players:        3 / 8
Audience:       0

Current Players:
  1. Host (host)
  2. E (player)
  3. F (player)

═══════════════════════════════════════════

How It Works

1. REST API Call: First queries https://ecast.jackboxgames.com/api/v2/rooms/{ROOM_CODE} to get room metadata
2. WebSocket Connection: Establishes a WebSocket connection to the game server
3. Join as Observer: Sends a client/connect message to join as an audience member
4. Parse Response: Listens for the client/welcome message containing the full lobby state
5. Extract Player Count: Counts the players in the here object

API Response Structure

The script returns an object with the following structure:

{
  roomCode: "JYET",
  appTag: "triviadeath",
  playerCount: 3,              // Actual player count
  audienceCount: 0,            // Number of audience members
  maxPlayers: 8,               // Maximum capacity
  gameState: "Lobby",          // Current game state
  lobbyState: "CanStart",      // Whether game can start
  locked: false,               // Whether lobby is locked
  full: false,                 // Whether lobby is full
  players: [                   // List of all players
    { id: "1", role: "host", name: "Host" },
    { id: "2", role: "player", name: "E" },
    { id: "3", role: "player", name: "F" }
  ]
}

Integration with Your App

You can integrate this into your Jackbox game picker application:

// In your backend API
const { getRoomInfo, getPlayerCount } = require('./scripts/get-jackbox-player-count');

app.get('/api/room-status/:roomCode', async (req, res) => {
  try {
    const roomCode = req.params.roomCode.toUpperCase();
    const roomInfo = await getRoomInfo(roomCode);
    const playerData = await getPlayerCount(roomCode, roomInfo);
    res.json(playerData);
  } catch (error) {
    res.status(404).json({ error: 'Room not found' });
  }
});

Troubleshooting

"Room not found or invalid"

• Double-check the room code is correct
• Make sure the game is currently running (room codes expire after games end)

"Connection timeout"

• The game server might be unavailable
• Check your internet connection
• The room might have closed

WebSocket connection fails

• Ensure you have the ws package installed: npm install
• Some networks/firewalls might block WebSocket connections

Dependencies

• ws (^8.14.0) - WebSocket client for Node.js

License

MIT