Custom rosters

You do not have to start a league from the built-in teams. You can start from a roster file. A roster file sets your own teams, divisions, colors and players, so you can run a specific group of players, rebuild a past season, or build a fictional universe of your own. This page shows how to load a file someone made, and how to build your own.

Load a roster file

If someone has shared a roster file with you, you are about 30 seconds from tip-off.

1. Open My leagues. Select Start a league, or + New league if you already have one.
2. Give your league a name in League name.
3. Paste the public https:// link to the JSON file into Community roster URL (optional).
4. Click anywhere outside the box. The game checks the file at once. A green message shows the team count and the name of the file, for example "30 teams · My Universe 2026". A red list shows what is wrong.
5. Pick your pace under Who moves the league, then select Create league.

Things to know:

• The file is locked at creation. You cannot swap the roster file after the league exists. Check that you have the right one first.
• A ftba-rosters-v1 file carries no skill numbers. The game builds every player's ratings from who the player is, so the league plays on the same scale as a normal one. A ftba-rosters-v2 file can carry a ratings block for each player, and the game uses those numbers exactly as written.
• The Community roster URL (optional) box is on the create screen of every league.
• A ftba-rosters-v2 file can also carry a salary cap and contracts. Its league opens on the file's cap, tax line and minimum, with each player's salary and years left from the file. A file built on the 2026-27 NBA numbers uses a $164,961,000 cap, a $200,428,000 tax line and a $2,474,000 minimum. A player's salary stops at his own max for his years of service. Players with no listed salary are priced by the game, up to the mid-level exception (9% of the cap). Payrolls are not trimmed, so some clubs open over the tax line and owe tax from the first season.
• A file with its own cap cannot be combined with the hard cap. The game refuses to create that league.

Build your own file

A roster file is plain JSON. The game accepts two formats, ftba-rosters-v1 and ftba-rosters-v2. The examples below use v1, and the v2 differences have their own section after them. There is no spreadsheet uploader. You, or a script, write the JSON and host it at a public link. A full league has 30 teams, so most people use a script.

Each team sets its own name, abbreviation, conference, division and colors. The basic shape is below.

{
  "format": "ftba-rosters-v1",
  "season_label": "My Universe 2026",
  "teams": [
    {
      "name": "Harbor Gulls",
      "abbrev": "HBG",
      "conference": "East",
      "division": "Atlantic",
      "colors": { "primary": "#1c3f94", "secondary": "#c8102e" },
      "active":  [ /* exactly 15 players */ ],
      "two_way": [ /* exactly 3 players */ ]
    }
    /* ...one block per team, all 30... */
  ],
  "free_agents": [ /* optional list of players */ ]
}

The rules the checker enforces

• format must be exactly "ftba-rosters-v1" or "ftba-rosters-v2".
• The file needs exactly 30 teams.
• The conference and division labels must form exactly 2 conferences, each with 3 divisions, and each division must hold exactly 5 teams. The conference labels are "East" and "West". The East divisions are Atlantic, Central and Southeast. The West divisions are Northwest, Pacific and Southwest. The schedule and the standings need this shape.
• Every team needs a unique abbrev of 4 characters or fewer, and a name of 64 characters or fewer.
• Every team needs exactly 15 active players and exactly 3 two_way players.
• Each active roster needs at least 1 center (C) and at least 1 point guard (PG). This is a hard rule, because the game engine cannot run a rotation without them.
• colors is optional: { "primary": "#rrggbb", "secondary": "#rrggbb" }. Use 6-digit hex. The secondary color is optional. If you skip colors, the game makes a color from the team name.
• free_agents is optional and holds at most 200 players. If you skip it, free agency starts thin.

Team names are yours. Pick whatever fits your universe.

Define a player

There are two ways to put a player on a roster.

Point to a player in the game's history. Give the player's NBA player id, and optionally an age. The game reads the player's real career to set his ratings.

{ "bbref_id": "2544", "age": 41 }

The key is bbref_id, but the value is the NBA player id: the number at the end of the player's nba.com/stats link. LeBron James is at nba.com/stats/player/2544, so his id is "2544". A Basketball-Reference slug such as jamesle01 matches nobody. If you leave off age, the game uses his real age.

The game takes the position of a referenced player from its own data. A position key in your file is ignored. If a referenced player shows up at the wrong position, report it with Send feedback. To force a position, define the player inline.

Or define the player inline. Use this for rookies, prospects and players you invent.

{
  "name": "Marcus Delaney",
  "position": "PG",
  "birth_year": 2001,
  "debut_year": 2024
}

An inline player needs name, position, birth_year and debut_year. position is one of PG, SG, SF, PF or C. age is optional in v1. If you leave it off, the game uses the season year minus birth_year. In v2, age is required.

How player ability works

A v1 file holds no skill numbers. For a referenced player, the game derives ratings from his real career. For an inline player, the game draws ratings from the templates it uses for its own fictional draft class. You shape a player by who he is: position, age and career. A v2 file can carry the numbers instead.

What two-way means in a file

The two_way list holds 3 players per team. When the league is created, the game signs each of those players to a two-way deal with the club the file lists him under. This holds on every new league, because new leagues use two-way contracts. The 15 active players are the roster. The 3 two-way players fill that club's two-way slots.

Format v2

Use ftba-rosters-v2 when you want to set exact ratings. Everything above still holds, with these changes:

• The key is player_id instead of bbref_id. The value is the same NBA player id. A file that still says bbref_id is refused.
• age is required on every player.
• ratings is optional. When a player has it, the game seeds him with exactly those numbers, and he is the same player in every league. A player without it is rated as in v1. The checker names the player and the field if a number is missing or out of range.
• draft is optional, for example { "year": 2026, "round": 1, "pick": 2 }.
• The same player_id cannot appear twice in one file.

A minimal v2 player:

{ "player_id": "2544", "age": 41 }

Host and test your file

• The file must sit at a public https:// link. Plain HTTP is refused. The link needs no login.
• Keep the file under 5 MB. The host must answer within 10 seconds.
• Redirects are refused, so point the link straight at the file. A raw GitHub Gist link, or any static JSON host, works.
• The checker reports all your errors at once. Paste your draft link, read the red errors, fix the file, host it again, and click out of the box again until the green message shows.

If you want help with a file, the Community roster URL (optional) box has an Ask on r/ftgsports link.