paper-dynasty-card-creation/custom_cards

Custom Card Creation System

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

Quick Start

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:

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:

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:

source venv/bin/activate
python -m custom_cards.archetype_calculator

View archetype descriptions:

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