# Gridiron Sim — Roster Pack & Draft Class Schema (v1)

Two community-shareable JSON formats. Both are **lenient**: only a handful of fields per entry are required, and missing pieces (contracts, ratings, peak ages, combine numbers, etc.) get filled in by the game's existing generators.

The game ships generic; real-life rosters and draft classes are produced by the community. Drop a `.json` file into the import button on the team-select screen (rosters) or the Scout screen during the offseason (draft classes).

---

## Roster Pack

```json
{
  "formatVersion": 1,
  "kind": "roster",
  "name": "Real NFL — Pre 2027 Offseason",
  "source": "@your_handle, 2026-12-01",
  "teams": [
    /* exactly 32 entries — see slot table below */
  ]
}
```

### Required per team

```json
{
  "city": "Buffalo",
  "name": "Bills",
  "abbr": "BUF",
  "primary": "#00338D",
  "secondary": "#C60C30",
  "players": [
    { "name": "Star QB", "position": "QB", "overall": 92 }
  ]
}
```

That's the minimum. Colors accept either hex strings (`"#00338D"`) or numeric literals (`0x00338D`).

### Optional per team

- `autoFillRoster: false` — preserve the exact roster size from your pack. Default `true`, which fills the rest with generated bench bodies up to the game's standard ~44-man roster.

### Optional per player

| Field | Range | Default |
|---|---|---|
| `age` | 18–50 | generator |
| `potential` | overall–99 | overall + dev gap |
| `devTrait` | `'normal'` / `'star'` / `'superstar'` / `'xfactor'` | computed from overall+potential |
| `ratings` | partial map of attribute keys → 1-99 | per-position template |
| `contractYears` | 1–7 | generator |
| `contractSalary` | dollars/year | generator |
| `experience` | 0–25 | from age |
| `morale` / `ego` / `workEthic` | 1–99 each | randomized in normal range |

Out-of-range numbers get clamped (e.g. `overall: 250` → `99`); invalid positions fall back to `WR`. The import won't reject a pack over a single typo.

### Team slot order

Slot order is fixed — the game maps each pack entry to a fixed franchise position (used by the divisional schedule generator). Same as `presets.ts`:

| Slot | Default | Slot | Default | Slot | Default | Slot | Default |
|---|---|---|---|---|---|---|---|
| 0 | BUF | 8 | HOU | 16 | DAL | 24 | ATL |
| 1 | MIA | 9 | IND | 17 | NYG | 25 | CAR |
| 2 | NE | 10 | JAX | 18 | PHI | 26 | NO |
| 3 | NYJ | 11 | TEN | 19 | WAS | 27 | TB |
| 4 | BAL | 12 | DEN | 20 | CHI | 28 | ARI |
| 5 | CIN | 13 | KC | 21 | DET | 29 | LAR |
| 6 | CLE | 14 | LV | 22 | GB | 30 | SF |
| 7 | PIT | 15 | LAC | 23 | MIN | 31 | SEA |

You can override the city/name/abbr per slot if you want a fictional league with the same divisional structure. Whatever you put in slot 0 will play in the AFC East regardless.

---

## Draft Class Pack

```json
{
  "formatVersion": 1,
  "kind": "draftClass",
  "name": "Real 2027 Draft Class",
  "source": "@your_handle",
  "classYear": 2027,
  "prospects": [
    /* 64-250 entries */
  ]
}
```

Minimum 64 prospects (anything less isn't a real class). Recommended ~250.

### Required per prospect

```json
{ "name": "Top QB", "position": "QB", "overall": 90 }
```

### Optional per prospect

| Field | Range | Default |
|---|---|---|
| `age` | 18–26 | generator |
| `college` | string | generator |
| `potential` | overall–99 | generator |
| `collegeStats` | summary string | generator |
| `fortyYard` | 4.20–5.60 seconds | generator |
| `benchPress` | 0–50 reps | generator |
| `vertical` | 20–50 inches | generator |
| `shuttle` | 3.80–5.00 seconds | generator |
| `bustProbability` | 0.0–1.0 | generator |
| `consensusRank` | 1–250 (mock-draft slot) | generator |
| `morale`, `ego`, `workEthic` | 1–99 each | generator |

Prospects always import unscouted — your scouting points start fresh on the imported class.

---

## Tips for pack authors

- **Export first**: start a fresh franchise, hit "Export current league" on the team-select screen, and use that JSON as a template. Edit names/overalls in your favorite spreadsheet, paste back in.
- **Skip what you don't know**: every optional field falls back to a sane generator default. Filling in only `name`/`position`/`overall` for 53 players per team is a perfectly valid pack.
- **Validate locally**: open the file in any JSON linter before importing. The game will report the first error it hits, but JSON syntax errors are easier to fix in your editor.
- **Share via gist or Discord**: packs are pure data — no code, no install. Drop one in a community channel and anyone can use it.

---

## Versioning

Current version: **1**. Future schema changes will bump `formatVersion` and the game will refuse to load packs from a different version with a clear error message. Don't hand-edit `formatVersion`.