paper-dynasty-card-creation/docs/CUSTOM_CARD_TIERS.md

Custom Card Tier System

Custom cards are rewards earned by Paper Dynasty players. Players earn their initial card and subsequent upgrades through gameplay achievements.

Progression Path

Cards progress through tiers in this order:

Low Starter → Mid Starter → High Starter →
Low All-Star → Mid All-Star → High All-Star →
Low MVP → Mid MVP → High MVP →
Low HoF → Mid HoF → High HoF →
(Legendary tiers follow .x20/.x50/.x80 pattern)

Target OPS by Tier

Batters

Tier	Code	Target OPS	Notes
Low Starter	L-STR	0.820	Entry-level custom card
Mid Starter	M-STR	0.850	First upgrade
High Starter	H-STR	0.880
Low All-Star	L-AS	0.920
Mid All-Star	M-AS	0.950
High All-Star	H-AS	0.980
Low MVP	L-MVP	1.025
Mid MVP	M-MVP	1.075
High MVP	H-MVP	1.150
Low Hall of Fame	L-HOF	1.220
Mid Hall of Fame	M-HOF	1.250
High Hall of Fame	H-HOF	1.280
Legendary+	LEG-1	1.320	Further upgrades follow pattern
Legendary++	LEG-2	1.350
Legendary+++	LEG-3	1.380

Pattern for Legendary+: Each subsequent tier adds +0.030 OPS following the .x20/.x50/.x80 pattern.

Pitchers (OPS Allowed)

Pitchers use inverted logic - lower OPS allowed = better pitcher. Starting pitchers and relievers have separate progressions - relievers are held to a higher standard (lower OPS) at each tier.

Starting Pitchers

Tier	Code	Target OPS	Notes
Low Starter	L-STR	0.580	Entry-level custom card
Mid Starter	M-STR	0.560
High Starter	H-STR	0.540
Low All-Star	L-AS	0.520
Mid All-Star	M-AS	0.500
High All-Star	H-AS	0.485
Low MVP	L-MVP	0.460
Mid MVP	M-MVP	0.435
High MVP	H-MVP	0.410
Low Hall of Fame	L-HOF	0.390
Mid Hall of Fame	M-HOF	0.370
High Hall of Fame	H-HOF	0.350

Beyond H-HOF: Decrease OPS by 0.015 per upgrade (0.335 → 0.320 → 0.305...)

Relief Pitchers

Tier	Code	Target OPS	Notes
Low Starter	L-STR	0.540	Entry-level custom card
Mid Starter	M-STR	0.515
High Starter	H-STR	0.490
Low All-Star	L-AS	0.465
Mid All-Star	M-AS	0.440
High All-Star	H-AS	0.415
Low MVP	L-MVP	0.380
Mid MVP	M-MVP	0.360
High MVP	H-MVP	0.340
Low Hall of Fame	L-HOF	0.320
Mid Hall of Fame	M-HOF	0.300
High Hall of Fame	H-HOF	0.280

Beyond H-HOF: Decrease OPS by 0.020 per upgrade (0.260 → 0.240 → 0.220...)

YAML Profile Schema

Each custom card profile should include tier tracking:

name: Player Name
player_type: batter  # or pitcher
pitcher_role: starter  # starter or reliever (pitchers only)
hand: R

# Tier tracking
tier: H-STR          # Current tier code
tier_history:        # Upgrade history
  - tier: L-STR
    date: 2025-01-15
    reason: Initial card creation
  - tier: M-STR
    date: 2025-03-20
    reason: Season 5 championship reward
  - tier: H-STR
    date: 2025-06-10
    reason: MVP award

target_ops: 0.880    # Should match tier target (use SP or RP table for pitchers)
cardset_id: 29
player_id: 12345
batting_card_id: 6789  # or pitching_card_id for pitchers

# ... rest of profile

Upgrade Process

When upgrading a card:

1. Identify current tier from profile
2. Determine next tier from progression path
3. Calculate OPS delta needed (next_target - current_target)
4. Distribute delta across ratings:
   • Increase positive outcomes (hits, walks)
   • Decrease negative outcomes (strikeouts, outs)
   • Maintain player's characteristic style (spray charts, power/contact balance)
5. Update profile:
   • Set new tier code
   • Update target_ops to new tier target
   • Add entry to tier_history
   • Update ratings with new values
6. Submit to database via pd-cards custom submit

CLI Commands

# Preview current tier status
pd-cards custom preview kalin_young

# Upgrade a player to next tier
pd-cards custom upgrade kalin_young --reason "Season 6 reward"

# Upgrade to specific tier
pd-cards custom upgrade kalin_young --to-tier M-AS --reason "Special event"

# List all players by tier
pd-cards custom list --by-tier

OPS Calculation Reference

For batters, Combined OPS uses the formula:

combined_ops = (ops_vL + ops_vR + min(ops_vL, ops_vR)) / 3

For pitchers (OPS allowed):

combined_ops = (ops_vL + ops_vR + max(ops_vL, ops_vR)) / 3

This weights the weaker split more heavily for batters (penalizes platoon weaknesses) and the stronger split for pitchers (rewards same-side dominance).

Maintaining Player Identity

When upgrading, preserve the player's characteristic profile:

• Power hitters: Increase HR/XBH proportionally
• Contact hitters: Increase singles, reduce strikeouts
• Patient hitters: Increase walks
• Speedsters: Improve baserunning stats alongside OPS
• Defensive specialists: May upgrade defense alongside OPS

Avoid creating "generic good players" - each upgrade should feel like a natural evolution of the player's established style.