Basketball Lineup Generator

A React application that generates optimal basketball rotation schedules based on player positions, playing time priorities, and various constraints.

Features

• Smart Rotation Algorithm: Automatically generates balanced rotation schedules for 8 periods (two 20-minute halves with substitutions every 5 minutes)
• Position Balance: Ensures proper balance of guards and forwards on court
• Flexible Constraints: Optional starters, closers, bonus (prioritized), and rookie (inexperienced) player tags
• Mobile-Friendly UI: Responsive card-based player configuration and compact schedule view
• Multiple Export Options: Share image, download image, or copy as CSV
• Preset Teams: Load predefined rosters via query string (e.g., ?team=3b1)
• Real-time Validation: Detailed validation summary (optional) with retry mechanism

Getting Started

1. Install dependencies:

npm install

2. Start the development server:

npm start

3. Open http://localhost:3847 to view it in your browser.

Usage

Adding Players

• Start with an empty state or load a preset team using ?team=3b1 or ?team=4b5
• Click "Add Player" to add new players
• Configure each player's name, position (Guard or Forward), and optional tags

Player Tags

• Start: Player begins the game in the starting lineup
• Finish: Player closes out the game
• Bonus: When choosing between equally-rested players, bonus players get preference for additional playing time (only applies when time is not an even split)
• Rookie: Less experienced players. Algorithm prevents all rookies from being on court simultaneously

Generating Rotations

1. Configure your players and their tags
2. Click "🏀 Generate" to create a rotation
3. Click multiple times to see different valid rotations (randomized each time)
4. Use share/download buttons to export the lineup
5. Copy as CSV for importing into spreadsheets

How It Works

The app uses a constraint satisfaction solver (logic-solver) that:

• Balances playing time evenly across all players (within 5 minutes)
• Ensures balanced half-time distribution (no player plays all their minutes in one half)
• Enforces exactly 5 players on court each period
• Balances guards and forwards - aims for 2-3 of each position when roster allows (falls back to 1+ minimum for imbalanced rosters)
• Maximizes roster rotation - ensures no player sits on bench for 2+ consecutive periods (forces frequent substitutions, typically 95-100% of theoretical maximum)
• Prioritizes "Bonus" tagged players when opportunities for extra time arise
• Ensures at least one experienced player is always on court when rookies are tagged
• Handles edge cases like 5-player teams (everyone plays all periods)
• Randomizes solutions by shuffling player order before solving, giving different valid rotations each time

Testing

Run the comprehensive unit test suite:

npm test
# or specifically for the solver:
npm run test:solver

The test suite validates:

• Basic constraints (starters, closers, playing time balance)
• Rookie/inexperienced player constraints
• Bonus/prioritize player logic
• Positional balance (2-3 of each position when possible)
• Maximum bench time / rotation (no long bench stretches)
• Edge cases (5 players, impossible constraints)

26 tests covering all constraint scenarios

Advanced Features

• Validation Details: Add ?validation=true to the URL to see detailed validation summary
• Preset Teams: Use ?team=3b1 or ?team=4b5 to load predefined rosters
• Mobile Optimized: Compact table view with rotated headers and sticky player column

Building for Production

npm run build

This creates an optimized production build in the build folder.

License

MIT License - see LICENSE file for details