chess960

Chess960 (Fischer Random Chess) start position generator for JavaScript and TypeScript, built by ZappChess.

• All 960 starting positions, by their standard position number (0–959, 518 is the normal chess start).
• Random start positions, with an optional seeded random source.
• FEN for every position, in X-FEN (KQkq) and Shredder-FEN (rook file letters) form.
• Reverse lookup: back rank letters → position number, plus validation.
• A chess960 command for the terminal: npx chess960.
• Zero dependencies, ES modules, TypeScript types included, Node 18+.

Install

npm install chess960

Or run the generator once without installing anything:

npx chess960

Quick start

import { randomPosition, positionFromId, idFromBackRank, allPositions } from "chess960";

const position = randomPosition();
position.id;          // 0–959
position.backRank;    // "BBQNNRKR"
position.fen;         // "bbqnnrkr/pppppppp/8/8/8/8/PPPPPPPP/BBQNNRKR w KQkq - 0 1"
position.shredderFen; // "bbqnnrkr/pppppppp/8/8/8/8/PPPPPPPP/BBQNNRKR w HFhf - 0 1"

positionFromId(518).backRank; // "RNBQKBNR" (the standard chess start)
idFromBackRank("RNBQKBNR");   // 518
allPositions().length;        // 960

Every Position is a frozen object with four fields: id, backRank, fen, shredderFen.

Command line

npx chess960              random Chess960 start position
npx chess960 518          position by number (0–959)
npx chess960 BBQNNRKR     position by back rank letters
npx chess960 --json       JSON output
npx chess960 --all        all 960 positions, one per line (id, back rank, FEN)
npx chess960 --all --json all 960 positions as a JSON array

Example:

$ npx chess960 518
Chess960 position 518 (RNBQKBNR)
FEN:          rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
Shredder-FEN: rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w HAha - 0 1

  r n b q k b n r
  p p p p p p p p
  . . . . . . . .
  . . . . . . . .
  . . . . . . . .
  . . . . . . . .
  P P P P P P P P
  R N B Q K B N R

API

| Export | Returns | Notes | | --- | --- | --- | | positionFromId(id) | Position | id must be an integer 0–959, otherwise a RangeError. | | randomPosition(random?) | Position | random is a function returning a number in [0, 1); defaults to Math.random. Pass a seeded generator for reproducible positions. | | allPositions() | readonly Position[] | All 960 positions in id order. Built once and cached. | | idFromBackRank(backRank) | number | Accepts "RNBQKBNR", "rnbqkbnr" or ["R","N","B","Q","K","B","N","R"]. Throws a RangeError for anything that is not a legal Chess960 back rank. | | isValidBackRank(backRank) | boolean | Same input as above, never throws. | | fenFromBackRank(backRank) | string | X-FEN with KQkq castling rights. | | shredderFenFromBackRank(backRank) | string | Shredder-FEN with the rook files as castling rights, for example HAha. | | POSITION_COUNT | 960 | | | STANDARD_POSITION_ID | 518 | |

Types: Position, BackRankInput, Piece.

Chess960 position numbers

The package uses the standard Chess960 numbering (Reinhard Scharnagl's scheme), the same numbers that Lichess, Chess.com and Wikipedia use. Position 518 is the classical start RNBQKBNR; position 0 is BBQNNRKR; position 959 is RKRNNQBB.

Each number encodes one back rank:

1. id % 4 places the light-squared bishop (b, d, f or h).
2. The next % 4 places the dark-squared bishop (a, c, e or g).
3. The next % 6 places the queen on one of the six free files.
4. The remaining value (0–9) picks one of ten knight patterns over the last five files.
5. The three files that are left get rook, king, rook, from left to right.

The rules of Chess960 follow from this: the king always stands between the two rooks, and the bishops always stand on opposite colours. Black mirrors White.

FEN for Chess960

Standard FEN writes castling rights as KQkq, which assumes rooks on the a- and h-files. In Chess960 a rook can start on any file, so two conventions exist:

• X-FEN keeps KQkq and lets the reader work out the outermost rooks. Chess GUIs and Lichess accept it. position.fen uses this form.
• Shredder-FEN writes the files of the castling rooks instead, for example HAha for the standard start or HFhf for position 0. UCI engines such as Stockfish (with UCI_Chess960 set) accept it. position.shredderFen uses this form.

Castling itself works like in normal chess: after castling the king and rook stand on the same squares they would in a standard game (king on g1 or c1, rook on f1 or d1), whatever files they started on. The normal castling rules about check and moved pieces still apply.

Looking at a position

Paste position.fen into the free analysis board on ZappChess to set the position up and try moves. If you are new to the pieces and the standard chess board setup, start there: position 518 in this package is exactly that setup. Chess960 exists to skip memorised chess openings; if you would rather learn them, that page walks through the main ones.

License

MIT