# 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:

```yaml
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

```bash
# 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.