paper-dynasty-card-creation/custom_cards/README.md

# Custom Card Creation System

Create fictional player cards for Paper Dynasty using baseball archetypes - no real statistics required!

## Quick Start

```bash
cd /mnt/NV2/Development/paper-dynasty/card-creation
source venv/bin/activate
python -m custom_cards.interactive_creator
```

Or via Claude Code:
```
"Create custom cards"
"I want to make fictional player cards"
```

## What This Does

This system automates the tedious manual process of creating custom fictional players by:

1. **Archetype Selection**: Choose from 16 predefined player types
   - 8 Batter archetypes (Power Slugger, Speedster, Contact Hitter, etc.)
   - 8 Pitcher archetypes (Ace, Closer, Groundball Specialist, etc.)

2. **Automatic Calculation**: Converts traditional baseball stats into D20 game mechanics
   - Takes archetype's AVG/OBP/SLG and calculates all 108 chances
   - Distributes hits, walks, strikeouts, outs across D20 probabilities
   - Generates baserunning ratings from speed metrics
   - Applies the Paper Dynasty OPS formula for rarity/cost

3. **Review & Iterate**: Preview calculated ratings before committing
   - See full stat breakdown (vs L, vs R)
   - Total OPS calculation
   - Option to tweak and refine

4. **Database Creation**: Automatically creates all required records
   - Player record
   - Batting/Pitching card
   - Card ratings (vs L and vs R)
   - Position assignments

## Architecture

### Files

- **`archetype_definitions.py`**: Baseball player profiles
  - BatterArchetype and PitcherArchetype dataclasses
  - 16 predefined archetypes with traditional stats
  - Functions to list and describe archetypes

- **`archetype_calculator.py`**: Stat conversion engine
  - BatterRatingCalculator: Converts batter stats to D20
  - PitcherRatingCalculator: Converts pitcher stats to D20
  - Handles distribution logic (hits, outs, spray charts)
  - Calculates total_OPS using PD formula

- **`interactive_creator.py`**: Main workflow script
  - CustomCardCreator class with interactive prompts
  - Cardset setup and selection
  - Player information collection
  - Review and tweak loop
  - Database record creation

- **`__init__.py`**: Package exports

### Key Concepts

**Archetypes** define traditional baseball statistics:
```python
BatterArchetype(
    name="Power Slugger",
    avg_vs_r=0.240, obp_vs_r=0.320, slg_vs_r=0.480,
    bb_pct_vs_r=0.10, k_pct_vs_r=0.28,
    # ... plus batted ball profile, spray chart, power, speed, defense
)
```

**Calculators** convert these to D20 mechanics:
```python
calc = BatterRatingCalculator(archetype)
ratings = calc.calculate_ratings(battingcard_id=123)
# Returns list of dicts with all 108 chances distributed:
# homerun, triple, double_pull, single_center, walk, strikeout, etc.
```

**Total OPS Formula** determines rarity and cost:
- Batters: `(OPS_vR + OPS_vL + min(OPS_vL, OPS_vR)) / 3`
- Pitchers: `(OPS_vR + OPS_vL + max(OPS_vL, OPS_vR)) / 3`

## Available Archetypes

### Batters

1. **Power Slugger** - High HR, lower average, high K
2. **Contact Hitter** - High average, low K, gap power
3. **Speedster** - Elite speed, slap hitter, excellent defense
4. **Balanced Star** - Well-rounded five-tool player
5. **Patient Walker** - Elite plate discipline, high OBP
6. **Slap Hitter** - Opposite field, puts ball in play
7. **Three True Outcomes** - Extreme power/walks, very high K
8. **Defensive Specialist** - Elite defense, weak bat

### Pitchers

1. **Ace** - Elite starter, dominates both sides
2. **Power Pitcher** - High velocity, high K, some walks
3. **Finesse Pitcher** - Command specialist, weak contact
4. **Groundball Specialist** - Induces grounders, low HR
5. **Dominant Closer** - Elite short relief
6. **Setup Man** - Solid late-inning reliever
7. **Swingman** - Can start or relieve
8. **Lefty Specialist** - LOOGY type, dominates lefties

## Example Workflow

```
1. Choose cardset (or create new one)
   → "Custom Heroes 2025"

2. Select player type
   → Batter

3. Choose archetype
   → Power Slugger

4. Enter player details
   → Name: Zeus Thunder
   → Hand: Right
   → Team: Yankees
   → Positions: RF DH

5. Review calculated ratings
   VS RHP: .240/.320/.480 (OPS: .800)
   VS LHP: .250/.330/.500 (OPS: .830)
   Total OPS: 0.810
   HR: 5.0 | BB: 11.7 | K: 27.2

6. Accept or tweak
   → Accept

7. System creates all database records
   ✓ MLBPlayer, Player, BattingCard, Ratings, Positions

8. Continue or exit
   → Create another player
```

## Custom Player IDs

Custom players use synthetic identifiers:
- `bbref_id`: `custom_lastnamefirstinitial01`
  - Example: "John Smith" → `custom_smithj01`
- `fangraphs_id`: 0
- `mlbam_id`: 0
- `retrosheet_id`: ""
- `is_custom`: True

## Integration with Paper Dynasty Skill

The workflow is integrated into the Paper Dynasty skill:

**Triggers**:
- "Create custom cards"
- "I want to make fictional player cards"
- "Generate custom players using archetypes"

**Skill updates**:
- Added to workflow list in SKILL.md
- Documented in `workflows/custom-card-creation.md`
- Included in workflow selection table

## Comparison to Manual Process

### Before (Manual Spreadsheet)
1. Manually type all ratings in spreadsheet
2. Formula calculates OPSvL, OPSvR
3. Manual formula: `OPSvL + OPSvR + min(OPSvL, OPSvR)` (batters)
4. Manually create battingcard/pitchingcard record
5. Manually create Player record
6. Manually create cardpositions records
7. No iterative refinement - commit or start over
8. Time-consuming and error-prone

### After (Archetype System)
1. Choose archetype that matches desired profile
2. Enter player name, team, positions
3. System calculates ALL ratings automatically
4. Review with full stat breakdown
5. Iterate and tweak if needed
6. Accept → system creates ALL database records
7. Repeatable and consistent
8. ~5 minutes per player vs ~20-30 minutes

## Future Enhancements

Possible improvements:
- [ ] Implement percentage tweaking (adjust power, contact, speed)
- [ ] Manual D20 rating adjustments with live validation
- [ ] Defensive rating calculator per position
- [ ] Import/export player profiles as JSON
- [ ] Batch creation from CSV
- [ ] Visual card preview during review
- [ ] Save custom archetypes
- [ ] Archetype mixing (50% Power Slugger + 50% Speedster)

## Testing

Run the calculator demo:
```bash
source venv/bin/activate
python -m custom_cards.archetype_calculator
```

View archetype descriptions:
```bash
python -c "from custom_cards import describe_archetypes; print(describe_archetypes('batter'))"
```

## Technical Details

### Dependencies
- pandas
- pydantic
- aiohttp
- pybaseball (indirect via creation_helpers)

### D20 System
Paper Dynasty uses a 20-sided die system with 5.4x multiplier = 108 total chances per plate appearance/batter faced.

Example batter card vs RHP:
```
Homerun: 5.0    (4.6% chance)
Triple: 0.3     (0.3%)
Doubles: 7.8    (7.2%)
Singles: 18.0   (16.7%)
Walk: 11.7      (10.8%)
HBP: 1.3        (1.2%)
Strikeout: 27.2 (25.2%)
Other outs: 36.7 (34.0%)
-----------------------
Total: 108.0    (100%)
```

### Rarity Calculation
After ratings are created, the system:
1. Fetches ratings from battingcardratings/pitchingcardratings
2. Calculates total_OPS using the formula
3. Maps to rarity thresholds (in rarity_thresholds.py)
4. Updates player record with rarity and cost

## Troubleshooting

**"ModuleNotFoundError: creation_helpers"**
- Run from card-creation directory
- Activate virtual environment first

**"Cardset not found"**
- Create new cardset when prompted
- Verify exact cardset name spelling

**"Total chances != 108"**
- Minor rounding acceptable (<0.1)
- Report if difference > 0.5

**Ratings don't match archetype**
- Check offense_mod parameter (default 1.2)
- Verify archetype definition stats
- Check for calculation bugs in archetype_calculator.py

## Support

For issues or questions:
1. Check `workflows/custom-card-creation.md` in Paper Dynasty skill
2. Review CLAUDE.md in card-creation directory
3. Check existing custom_card_creation.py script for reference

---

**Created**: 2025-11-11
**Author**: Cal Corum with Claude Code
**Version**: 1.0