HyperSpaceOut/jackboxpartypack-gamepicker
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update README.md with new features and changes, version bump.

Browse Source
This commit is contained in:
cottongin
2026-03-23 12:04:03 -04:00
parent 0833cf6167
commit 850fed5a87
2 changed files with 191 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
README.md
View File

@@ -1,6 +1,6 @@
# Jackbox Party Pack Game Picker
A full-stack web application that helps groups pick games to play from various Jackbox Party Packs. Features include random game selection with filters, session tracking, game management, and popularity scoring through chat log imports.
A full-stack web application that helps groups pick games to play from various Jackbox Party Packs. Features include random game selection with weighted filters, session tracking, game management, popularity scoring through chat log imports and live voting, and Jackbox lobby integration.
## Features
@@ -13,26 +13,37 @@ A full-stack web application that helps groups pick games to play from various J
### Admin Features
- **Game Picker**: Randomly select games with intelligent filters
- Filter by player count, drawing games, game length, and family-friendly status
- Weighted random selection using game and pack favor bias
- Automatic repeat avoidance (prevents same game or alternating pattern)
- Manual game selection option
- Real-time session tracking
- **Game Manager**: Complete CRUD operations for games and packs
- Enable/disable individual games or entire packs
- Set favor bias on games and packs to influence pick weighting
- Import/export games via CSV
- View statistics (play counts, popularity scores)
- View statistics (play counts, upvotes, downvotes, popularity scores)
- Add, edit, and delete games
- **Session Management**: Track gaming sessions over time
- Create and close sessions
- View session history
- Import chat logs to calculate game popularity
- Track which games were played when
- View session history with pagination and filters
- Archive/unarchive sessions
- Add, edit, and delete session notes (hidden from unauthenticated users)
- Export session data
- Bulk session creation
- Per-session game management (add, remove, reorder, set status)
- **Room Code & Player Count**: Live Jackbox lobby integration
- Set room codes on session games
- Automatic player count fetching via Jackbox ecast shard API
- Start/stop player count monitoring
- Live status updates via WebSocket
- **Chat Log Import**: Process chat messages to assess game popularity
- Supports "thisgame++" and "thisgame--" voting
- Automatically matches votes to games based on timestamps
- Updates popularity scores across sessions
- Updates upvote/downvote counts across sessions
- **Live Voting API**: Real-time vote processing from external bots
- Accept live votes via REST API
@@ -50,16 +61,18 @@ A full-stack web application that helps groups pick games to play from various J
### Public Features
- View active session and games currently being played
- Browse session history
- Browse session history (with archived sessions hidden by default)
- Detailed session view with game list and vote breakdowns
- See game statistics and popularity
## Tech Stack
- **Frontend**: React 18 with Vite, Tailwind CSS, React Router
- **Backend**: Node.js with Express
- **Frontend**: React 18 with Vite, Tailwind CSS, React Router 6
- **Backend**: Node.js with Express 4
- **Database**: SQLite with better-sqlite3
- **Real-time**: WebSocket server (`ws`) for presence, subscriptions, and live events
- **Authentication**: JWT-based admin authentication
- **Deployment**: Docker with docker-compose
- **Deployment**: Docker with docker-compose (Node 22 Alpine + nginx Alpine)
## Prerequisites
@@ -78,13 +91,12 @@ A full-stack web application that helps groups pick games to play from various J
Create a `.env` file in the root directory:
```env
PORT=5000
NODE_ENV=production
DB_PATH=/app/data/jackbox.db
JWT_SECRET=your-secret-jwt-key-change-this
ADMIN_KEY=your-admin-key-here
```
`JWT_SECRET` is required. Provide either `ADMIN_KEY` (single admin) or configure named admins (see [Named Admins](#named-admins) below).
3. **Build and start the containers**
```bash
docker-compose up -d
@@ -96,7 +108,7 @@ A full-stack web application that helps groups pick games to play from various J
5. **Login as admin**
- Navigate to the login page
- Enter your `ADMIN_KEY` from the `.env` file
- Enter your `ADMIN_KEY` (or a named admin key) from your configuration
The database will be automatically initialized and populated with games from `games-list.csv` on first run.
@@ -148,10 +160,32 @@ The backend will run on http://localhost:5000
npm run dev
```
The frontend will run on http://localhost:3000 and proxy API requests to the backend.
The frontend will run on http://localhost:3000. Note: the Vite dev proxy is configured to forward `/api` requests to `http://backend:5000` (the Docker Compose service name). For bare-metal local development without Docker, you may need to update the proxy target in `vite.config.js` to `http://localhost:5000`.
## Configuration
### Named Admins
The app supports multiple named admin accounts. Create `backend/config/admins.json` (see `admins.example.json` for the format):
```json
[
{ "name": "Alice", "key": "change-me-alice-key" },
{ "name": "Bob", "key": "change-me-bob-key" }
]
```
Each admin logs in with their unique key. Their name is embedded in the JWT and displayed in the presence bar.
If `admins.json` is not found, the app falls back to the `ADMIN_KEY` environment variable as a single admin named "Admin".
To use a custom path for the admins file, set `ADMIN_CONFIG_PATH` in your environment.
For Docker, uncomment the volume mount in `docker-compose.yml`:
```yaml
- ./backend/config/admins.json:/app/config/admins.json:ro
```
### Branding and Metadata
All app branding, metadata, and PWA configuration is centralized in `frontend/src/config/branding.js`. Edit this file to customize:
@@ -176,41 +210,91 @@ cd frontend
npm run generate-manifest
```
The manifest is automatically generated during the build process, so you don't need to edit it directly.
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JWT_SECRET` | Yes | — | Secret key for signing JWT tokens |
| `ADMIN_KEY` | No | — | Single admin authentication key (fallback when `admins.json` is absent) |
| `ADMIN_CONFIG_PATH` | No | `backend/config/admins.json` | Path to named admins JSON file |
| `PORT` | No | `5000` | Backend server port |
| `NODE_ENV` | No | `development` | Environment (production/development) |
| `DB_PATH` | No | `./data/jackbox.db` | Path to SQLite database file |
| `DEBUG` | No | `false` | Enable debug logging |
## Testing
The project uses Jest for API and integration tests. Tests live in the `tests/` directory at the repository root.
```bash
# Install backend dependencies first
cd backend && npm install && cd ..
# Run tests
npx jest
# Run tests in watch mode
npx jest --watch
```
## Project Structure
```
/
├── backend/
│ ├── routes/ # API route handlers
│ │ ├── auth.js # Authentication endpoints
│ │ ├── games.js # Game CRUD and management
│ │ ├── sessions.js # Session management
│ │ ├── picker.js # Game picker algorithm
│ │ ├── stats.js # Statistics endpoints
│ │ ├── votes.js # Live voting endpoint
│ │ └── webhooks.js # Webhook management
│ ├── middleware/ # Express middleware
│ │ └── auth.js # JWT authentication
│ ├── utils/ # Utility functions
│ │ └── webhooks.js # Webhook trigger and signature
│ ├── database.js # SQLite database setup
│ ├── bootstrap.js # Database initialization
│ ├── server.js # Express app entry point
│ ├── routes/ # API route handlers
│ │ ├── auth.js # Authentication endpoints
│ │ ├── games.js # Game CRUD, packs, favor bias
│ │ ├── sessions.js # Sessions, archives, notes, room codes, export
│ │ ├── picker.js # Game picker algorithm
│ │ ├── stats.js # Statistics endpoints
│ │ ├── votes.js # Live voting endpoint
│ │ └── webhooks.js # Webhook management
│ ├── middleware/ # Express middleware
│ │ ├── auth.js # JWT authentication (required)
│ │ └── optional-auth.js # JWT authentication (optional, for public routes)
│ ├── config/ # Configuration files
│ │ ├── admins.example.json # Example named admins config
│ │ ├── admins.json # Named admins (gitignored)
│ │ └── load-admins.js # Admin config loader
│ ├── utils/ # Utility modules
│ │ ├── websocket-manager.js # WebSocket server (presence, events)
│ │ ├── ecast-shard-client.js # Jackbox ecast shard integration
│ │ ├── jackbox-api.js # Jackbox API helpers
│ │ ├── notes-preview.js # Session notes preview generation
│ │ └── webhooks.js # Webhook trigger and HMAC signatures
│ ├── database.js # SQLite database setup and migrations
│ ├── bootstrap.js # Database initialization from CSV
│ ├── server.js # Express + WebSocket entry point
│ ├── package.json
│ └── Dockerfile
├── frontend/
│ ├── src/
│ │ ├── pages/ # React page components
│ │ ├── pages/ # React page components
│ │ │ ├── Home.jsx
│ │ │ ├── Login.jsx
│ │ │ ├── Picker.jsx
│ │ │ ├── Manager.jsx
│ │ │ └── History.jsx
│ │ ├── context/ # React context providers
│ │ │ └── AuthContext.jsx
│ │ ├── api/ # API client
│ │ │ ├── History.jsx
│ │ │ └── SessionDetail.jsx
│ │ ├── components/ # Reusable UI components
│ │ │ ├── PresenceBar.jsx
│ │ │ ├── Toast.jsx
│ │ │ ├── ThemeToggle.jsx
│ │ │ ├── Logo.jsx
│ │ │ ├── RoomCodeModal.jsx
│ │ │ ├── GamePoolModal.jsx
│ │ │ ├── PopularityBadge.jsx
│ │ │ ├── InstallPrompt.jsx
│ │ │ └── SafariInstallPrompt.jsx
│ │ ├── context/ # React context providers
│ │ │ ├── AuthContext.jsx
│ │ │ └── ThemeContext.jsx
│ │ ├── hooks/ # Custom React hooks
│ │ │ └── usePresence.js
│ │ ├── config/ # Frontend configuration
│ │ │ └── branding.js
│ │ ├── api/ # API client
│ │ │ └── axios.js
│ │ ├── App.jsx
│ │ ├── main.jsx
@@ -219,44 +303,74 @@ The manifest is automatically generated during the build process, so you don't n
│ ├── vite.config.js
│ ├── tailwind.config.js
│ ├── package.json
│ ├── nginx.conf # Nginx config for Docker
│ ├── nginx.conf # Nginx config for Docker (proxy + SPA)
│ └── Dockerfile
├── tests/ # Jest API and integration tests
│ ├── api/ # Route-level tests
│ ├── helpers/ # Test utilities
│ └── jest.setup.js
├── scripts/ # Jackbox lobby inspection utilities
├── docs/ # API documentation, design specs, plans
│ ├── api/ # OpenAPI spec, endpoint docs, guides
│ ├── plans/ # Implementation plans
│ └── archive/ # Archived docs
├── docker-compose.yml
├── games-list.csv # Initial game data
├── jest.config.js
├── games-list.csv # Initial game seed data
└── README.md
```
## API Endpoints
### Health
- `GET /health` - Health check (returns `{ status: "ok" }`)
### Authentication
- `POST /api/auth/login` - Login with admin key
- `POST /api/auth/login` - Login with admin key (returns JWT with admin name)
- `POST /api/auth/verify` - Verify JWT token
### Games
- `GET /api/games` - List all games (with filters)
- `GET /api/games/packs` - List unique pack names
- `GET /api/games/meta/packs` - Get pack list with stats and favor bias
- `GET /api/games/:id` - Get single game
- `POST /api/games` - Create game (admin)
- `PUT /api/games/:id` - Update game (admin)
- `DELETE /api/games/:id` - Delete game (admin)
- `PATCH /api/games/:id/toggle` - Toggle game enabled status (admin)
- `GET /api/games/meta/packs` - Get pack list with stats
- `PATCH /api/games/:id/favor` - Set game favor bias (admin)
- `PATCH /api/games/packs/:name/toggle` - Toggle entire pack (admin)
- `PATCH /api/games/packs/:name/favor` - Set pack favor bias (admin)
- `GET /api/games/export/csv` - Export games to CSV (admin)
- `POST /api/games/import/csv` - Import games from CSV (admin)
### Sessions
- `GET /api/sessions` - List all sessions
- `GET /api/sessions` - List sessions (paginated, filterable, `X-Total-Count` header)
- `GET /api/sessions/active` - Get active session
- `GET /api/sessions/:id` - Get single session
- `GET /api/sessions/:id` - Get single session (notes hidden from unauthenticated users)
- `POST /api/sessions` - Create new session (admin)
- `POST /api/sessions/bulk` - Bulk create sessions (admin)
- `POST /api/sessions/:id/close` - Close session (admin)
- `DELETE /api/sessions/:id` - Delete session (admin)
- `PUT /api/sessions/:id/notes` - Update session notes (admin)
- `DELETE /api/sessions/:id/notes` - Delete session notes (admin)
- `POST /api/sessions/:id/archive` - Archive session (admin)
- `POST /api/sessions/:id/unarchive` - Unarchive session (admin)
- `GET /api/sessions/:id/games` - Get games in session
- `GET /api/sessions/:id/votes` - Get per-game vote breakdown for a session
- `POST /api/sessions/:id/games` - Add game to session (admin)
- `PATCH /api/sessions/:sessionId/games/:gameId/status` - Update game status (admin)
- `DELETE /api/sessions/:sessionId/games/:gameId` - Remove game from session (admin)
- `PATCH /api/sessions/:sessionId/games/:gameId/room-code` - Set room code (admin)
- `PATCH /api/sessions/:sessionId/games/:gameId/player-count` - Update player count (admin)
- `GET /api/sessions/:sessionId/games/:gameId/status-live` - Get live ecast status
- `POST /api/sessions/:sessionId/games/:gameId/start-player-check` - Start player count monitoring (admin)
- `POST /api/sessions/:sessionId/games/:gameId/stop-player-check` - Stop player count monitoring (admin)
- `GET /api/sessions/:id/votes` - Get per-game vote breakdown for a session
- `POST /api/sessions/:id/chat-import` - Import chat log (admin)
- `GET /api/sessions/:id/export` - Export session data (admin)
### Game Picker
- `POST /api/pick` - Pick random game with filters
- `POST /api/pick` - Pick random game with filters and favor bias weighting
### Statistics
- `GET /api/stats` - Get overall statistics
@@ -274,6 +388,9 @@ The manifest is automatically generated during the build process, so you don't n
- `POST /api/webhooks/test/:id` - Test webhook (admin)
- `GET /api/webhooks/:id/logs` - Get webhook logs (admin)
### WebSocket
- `ws://host/api/sessions/live` - Real-time connection for presence, session subscriptions, and live events
## Usage Guide
### Starting a Game Session
@@ -294,9 +411,10 @@ The manifest is automatically generated during the build process, so you don't n
2. Navigate to the Manager page
3. View statistics and pack information
4. Toggle individual games or entire packs on/off
5. Add new games with the "+ Add Game" button
6. Edit or delete existing games
7. Import/Export games via CSV
5. Adjust favor bias to weight certain games or packs in the picker
6. Add new games with the "+ Add Game" button
7. Edit or delete existing games
8. Import/Export games via CSV
### Closing a Session and Importing Chat Logs
@@ -322,6 +440,10 @@ The manifest is automatically generated during the build process, so you don't n
6. Click "Close Session" to finalize
7. Add optional notes about the session
### Archiving Sessions
Closed sessions can be archived to keep the history page clean. Archived sessions are hidden by default but can be viewed by toggling the archive filter. Archiving and unarchiving are available from the session detail page or via bulk actions in the history list.
## Chat Log Format
The chat import feature expects a JSON array where each message has:
@@ -332,12 +454,12 @@ The chat import feature expects a JSON array where each message has:
The system will:
1. Parse each message for vote patterns
2. Match the timestamp to the game being played at that time
3. Update the game's popularity score (+1 for ++, -1 for --)
3. Update the game's upvote/downvote counts (+1 for ++, -1 for --)
4. Store the chat log in the database
## Bot Integration
For integrating external bots (e.g., for live voting and game notifications), see **[BOT_INTEGRATION.md](docs/BOT_INTEGRATION.md)** for detailed documentation including:
For integrating external bots (e.g., for live voting and game notifications), see **[BOT_INTEGRATION.md](docs/archive/BOT_INTEGRATION.md)** for detailed documentation including:
- Live voting API usage
- **WebSocket integration (recommended)** for real-time game notifications
@@ -374,10 +496,10 @@ go run get-player-count.go JYET
- Extracts actual player count from lobby state
These tools retrieve:
- ✅ Actual player count (not just max capacity)
- ✅ List of current players and their roles (host/player)
- ✅ Game state and lobby status
- ✅ Audience count
- Actual player count (not just max capacity)
- List of current players and their roles (host/player)
- Game state and lobby status
- Audience count
**Note:** Direct WebSocket connection is not possible without authentication, so the tools join through jackbox.tv to capture the data.
@@ -386,13 +508,17 @@ These tools retrieve:
### games
- id, pack_name, title, min_players, max_players, length_minutes
- has_audience, family_friendly, game_type, secondary_type
- play_count, popularity_score, upvotes, downvotes, enabled, created_at
- play_count, popularity_score, upvotes, downvotes, favor_bias, enabled, created_at
### packs
- id, name (unique), favor_bias, created_at
### sessions
- id, created_at, closed_at, is_active, notes
- id, created_at, closed_at, is_active, notes, archived
### session_games
- id, session_id, game_id, played_at, manually_added, status
- room_code, player_count, player_count_check_status
### chat_logs
- id, session_id, chatter_name, message, timestamp, parsed_vote, message_hash
@@ -422,8 +548,10 @@ The picker uses the following logic:
- Exclude those games from selection pool
- This prevents immediate repeats and alternating patterns
3. **Random selection**:
- Pick a random game from remaining eligible games
3. **Weighted random selection**:
- Games and packs can have a `favor_bias` (+/- integer)
- Positive bias increases pick probability; negative bias decreases it
- Pick a random game from remaining eligible games, weighted by bias
- Return game details and pool size
## Docker Deployment
@@ -446,36 +574,28 @@ docker-compose down
docker-compose up -d --build
```
### Environment Variables
Set these in your `.env` file or docker-compose environment:
- `PORT` - Backend server port (default: 5000)
- `NODE_ENV` - Environment (production/development)
- `DB_PATH` - Path to SQLite database file
- `JWT_SECRET` - Secret key for JWT tokens
- `ADMIN_KEY` - Admin authentication key
### Data Persistence
The SQLite database is stored in `backend/data/` and is persisted via Docker volumes. To backup your data, copy the `backend/data/` directory.
The SQLite database is stored in a named Docker volume (`jackbox-data`) mapped to `/app/data` in the backend container. To backup your data, use `docker cp` or bind-mount a host directory.
## Troubleshooting
### Database not initializing
- Ensure `games-list.csv` is in the root directory
- Check backend logs: `docker-compose logs backend`
- Manually delete `backend/data/jackbox.db` to force re-initialization
- Manually delete the database to force re-initialization
### Can't login as admin
- Verify your `ADMIN_KEY` environment variable is set
- Verify your `ADMIN_KEY` or `admins.json` is configured correctly
- Check that the `.env` file is loaded correctly
- If using named admins, ensure `admins.json` has valid JSON with unique names and keys
- Try restarting the backend service
### Frontend can't reach backend
- Verify both containers are running: `docker-compose ps`
- Check network connectivity: `docker-compose logs frontend`
- Ensure nginx.conf proxy settings are correct
- For local dev, confirm the Vite proxy target matches your backend URL
### Games not showing up
- Check if games are enabled in the Manager
@@ -489,4 +609,3 @@ MIT
## Contributing
Feel free to submit issues and pull requests!

2
frontend/src/config/branding.js
View File

@@ -2,7 +2,7 @@ export const branding = {
app: {
name: 'HSO Jackbox Game Picker',
shortName: 'Jackbox Game Picker',
version: '0.6.3 - Fish Tank Edition',
version: '0.6.4 - Fish Tank Edition',
description: 'Spicing up Hyper Spaceout game nights!',
},
meta: {