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 # 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 ## Features
@@ -13,26 +13,37 @@ A full-stack web application that helps groups pick games to play from various J
### Admin Features ### Admin Features
- **Game Picker**: Randomly select games with intelligent filters - **Game Picker**: Randomly select games with intelligent filters
- Filter by player count, drawing games, game length, and family-friendly status - 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) - Automatic repeat avoidance (prevents same game or alternating pattern)
- Manual game selection option - Manual game selection option
- Real-time session tracking - Real-time session tracking
- **Game Manager**: Complete CRUD operations for games and packs - **Game Manager**: Complete CRUD operations for games and packs
- Enable/disable individual games or entire packs - Enable/disable individual games or entire packs
- Set favor bias on games and packs to influence pick weighting
- Import/export games via CSV - Import/export games via CSV
- View statistics (play counts, popularity scores) - View statistics (play counts, upvotes, downvotes, popularity scores)
- Add, edit, and delete games - Add, edit, and delete games
- **Session Management**: Track gaming sessions over time - **Session Management**: Track gaming sessions over time
- Create and close sessions - Create and close sessions
- View session history - View session history with pagination and filters
- Import chat logs to calculate game popularity - Archive/unarchive sessions
- Track which games were played when - 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 - **Chat Log Import**: Process chat messages to assess game popularity
- Supports "thisgame++" and "thisgame--" voting - Supports "thisgame++" and "thisgame--" voting
- Automatically matches votes to games based on timestamps - 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 - **Live Voting API**: Real-time vote processing from external bots
- Accept live votes via REST API - 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 ### Public Features
- View active session and games currently being played - 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 - See game statistics and popularity
## Tech Stack ## Tech Stack
- **Frontend**: React 18 with Vite, Tailwind CSS, React Router - **Frontend**: React 18 with Vite, Tailwind CSS, React Router 6
- **Backend**: Node.js with Express - **Backend**: Node.js with Express 4
- **Database**: SQLite with better-sqlite3 - **Database**: SQLite with better-sqlite3
- **Real-time**: WebSocket server (`ws`) for presence, subscriptions, and live events
- **Authentication**: JWT-based admin authentication - **Authentication**: JWT-based admin authentication
- **Deployment**: Docker with docker-compose - **Deployment**: Docker with docker-compose (Node 22 Alpine + nginx Alpine)
## Prerequisites ## 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: Create a `.env` file in the root directory:
```env ```env
PORT=5000
NODE_ENV=production
DB_PATH=/app/data/jackbox.db
JWT_SECRET=your-secret-jwt-key-change-this JWT_SECRET=your-secret-jwt-key-change-this
ADMIN_KEY=your-admin-key-here 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** 3. **Build and start the containers**
```bash ```bash
docker-compose up -d 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** 5. **Login as admin**
- Navigate to the login page - 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. 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 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 ## 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 ### Branding and Metadata
All app branding, metadata, and PWA configuration is centralized in `frontend/src/config/branding.js`. Edit this file to customize: 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 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 ## Project Structure
``` ```
/ /
├── backend/ ├── backend/
│ ├── routes/ # API route handlers │ ├── routes/ # API route handlers
│ │ ├── auth.js # Authentication endpoints │ │ ├── auth.js # Authentication endpoints
│ │ ├── games.js # Game CRUD and management │ │ ├── games.js # Game CRUD, packs, favor bias
│ │ ├── sessions.js # Session management │ │ ├── sessions.js # Sessions, archives, notes, room codes, export
│ │ ├── picker.js # Game picker algorithm │ │ ├── picker.js # Game picker algorithm
│ │ ├── stats.js # Statistics endpoints │ │ ├── stats.js # Statistics endpoints
│ │ ├── votes.js # Live voting endpoint │ │ ├── votes.js # Live voting endpoint
│ │ └── webhooks.js # Webhook management │ │ └── webhooks.js # Webhook management
│ ├── middleware/ # Express middleware │ ├── middleware/ # Express middleware
│ │ └── auth.js # JWT authentication │ │ ├── auth.js # JWT authentication (required)
│ ├── utils/ # Utility functions │ │ └── optional-auth.js # JWT authentication (optional, for public routes)
│ │ └── webhooks.js # Webhook trigger and signature │ ├── config/ # Configuration files
│ ├── database.js # SQLite database setup │ │ ├── admins.example.json # Example named admins config
│ ├── bootstrap.js # Database initialization │ │ ├── admins.json # Named admins (gitignored)
│ ├── server.js # Express app entry point │ │ └── 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 │ ├── package.json
│ └── Dockerfile │ └── Dockerfile
├── frontend/ ├── frontend/
│ ├── src/ │ ├── src/
│ │ ├── pages/ # React page components │ │ ├── pages/ # React page components
│ │ │ ├── Home.jsx │ │ │ ├── Home.jsx
│ │ │ ├── Login.jsx │ │ │ ├── Login.jsx
│ │ │ ├── Picker.jsx │ │ │ ├── Picker.jsx
│ │ │ ├── Manager.jsx │ │ │ ├── Manager.jsx
│ │ │ └── History.jsx │ │ │ ├── History.jsx
│ │ ├── context/ # React context providers │ │ │ └── SessionDetail.jsx
│ │ │ └── AuthContext.jsx │ │ ├── components/ # Reusable UI components
│ │ ├── api/ # API client │ │ │ ├── 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 │ │ │ └── axios.js
│ │ ├── App.jsx │ │ ├── App.jsx
│ │ ├── main.jsx │ │ ├── main.jsx
@@ -219,44 +303,74 @@ The manifest is automatically generated during the build process, so you don't n
│ ├── vite.config.js │ ├── vite.config.js
│ ├── tailwind.config.js │ ├── tailwind.config.js
│ ├── package.json │ ├── package.json
│ ├── nginx.conf # Nginx config for Docker │ ├── nginx.conf # Nginx config for Docker (proxy + SPA)
│ └── Dockerfile │ └── 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 ├── docker-compose.yml
├── games-list.csv # Initial game data ├── jest.config.js
├── games-list.csv # Initial game seed data
└── README.md └── README.md
``` ```
## API Endpoints ## API Endpoints
### Health
- `GET /health` - Health check (returns `{ status: "ok" }`)
### Authentication ### 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 - `POST /api/auth/verify` - Verify JWT token
### Games ### Games
- `GET /api/games` - List all games (with filters) - `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 - `GET /api/games/:id` - Get single game
- `POST /api/games` - Create game (admin) - `POST /api/games` - Create game (admin)
- `PUT /api/games/:id` - Update game (admin) - `PUT /api/games/:id` - Update game (admin)
- `DELETE /api/games/:id` - Delete game (admin) - `DELETE /api/games/:id` - Delete game (admin)
- `PATCH /api/games/:id/toggle` - Toggle game enabled status (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/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) - `GET /api/games/export/csv` - Export games to CSV (admin)
- `POST /api/games/import/csv` - Import games from CSV (admin) - `POST /api/games/import/csv` - Import games from CSV (admin)
### Sessions ### 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/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` - Create new session (admin)
- `POST /api/sessions/bulk` - Bulk create sessions (admin)
- `POST /api/sessions/:id/close` - Close session (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/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) - `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) - `POST /api/sessions/:id/chat-import` - Import chat log (admin)
- `GET /api/sessions/:id/export` - Export session data (admin)
### Game Picker ### Game Picker
- `POST /api/pick` - Pick random game with filters - `POST /api/pick` - Pick random game with filters and favor bias weighting
### Statistics ### Statistics
- `GET /api/stats` - Get overall 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) - `POST /api/webhooks/test/:id` - Test webhook (admin)
- `GET /api/webhooks/:id/logs` - Get webhook logs (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 ## Usage Guide
### Starting a Game Session ### 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 2. Navigate to the Manager page
3. View statistics and pack information 3. View statistics and pack information
4. Toggle individual games or entire packs on/off 4. Toggle individual games or entire packs on/off
5. Add new games with the "+ Add Game" button 5. Adjust favor bias to weight certain games or packs in the picker
6. Edit or delete existing games 6. Add new games with the "+ Add Game" button
7. Import/Export games via CSV 7. Edit or delete existing games
8. Import/Export games via CSV
### Closing a Session and Importing Chat Logs ### 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 6. Click "Close Session" to finalize
7. Add optional notes about the session 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 ## Chat Log Format
The chat import feature expects a JSON array where each message has: 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: The system will:
1. Parse each message for vote patterns 1. Parse each message for vote patterns
2. Match the timestamp to the game being played at that time 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 4. Store the chat log in the database
## Bot Integration ## 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 - Live voting API usage
- **WebSocket integration (recommended)** for real-time game notifications - **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 - Extracts actual player count from lobby state
These tools retrieve: These tools retrieve:
- ✅ Actual player count (not just max capacity) - Actual player count (not just max capacity)
- ✅ List of current players and their roles (host/player) - List of current players and their roles (host/player)
- ✅ Game state and lobby status - Game state and lobby status
- ✅ Audience count - Audience count
**Note:** Direct WebSocket connection is not possible without authentication, so the tools join through jackbox.tv to capture the data. **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 ### games
- id, pack_name, title, min_players, max_players, length_minutes - id, pack_name, title, min_players, max_players, length_minutes
- has_audience, family_friendly, game_type, secondary_type - 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 ### sessions
- id, created_at, closed_at, is_active, notes - id, created_at, closed_at, is_active, notes, archived
### session_games ### session_games
- id, session_id, game_id, played_at, manually_added, status - id, session_id, game_id, played_at, manually_added, status
- room_code, player_count, player_count_check_status
### chat_logs ### chat_logs
- id, session_id, chatter_name, message, timestamp, parsed_vote, message_hash - 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 - Exclude those games from selection pool
- This prevents immediate repeats and alternating patterns - This prevents immediate repeats and alternating patterns
3. **Random selection**: 3. **Weighted random selection**:
- Pick a random game from remaining eligible games - 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 - Return game details and pool size
## Docker Deployment ## Docker Deployment
@@ -446,36 +574,28 @@ docker-compose down
docker-compose up -d --build 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 ### 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 ## Troubleshooting
### Database not initializing ### Database not initializing
- Ensure `games-list.csv` is in the root directory - Ensure `games-list.csv` is in the root directory
- Check backend logs: `docker-compose logs backend` - 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 ### 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 - 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 - Try restarting the backend service
### Frontend can't reach backend ### Frontend can't reach backend
- Verify both containers are running: `docker-compose ps` - Verify both containers are running: `docker-compose ps`
- Check network connectivity: `docker-compose logs frontend` - Check network connectivity: `docker-compose logs frontend`
- Ensure nginx.conf proxy settings are correct - Ensure nginx.conf proxy settings are correct
- For local dev, confirm the Vite proxy target matches your backend URL
### Games not showing up ### Games not showing up
- Check if games are enabled in the Manager - Check if games are enabled in the Manager
@@ -489,4 +609,3 @@ MIT
## Contributing ## Contributing
Feel free to submit issues and pull requests! Feel free to submit issues and pull requests!

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

@@ -2,7 +2,7 @@ export const branding = {
app: { app: {
name: 'HSO Jackbox Game Picker', name: 'HSO Jackbox Game Picker',
shortName: '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!', description: 'Spicing up Hyper Spaceout game nights!',
}, },
meta: { meta: {