Encodings

FEN

Chess positions in FEN as 64 bytes of piece letters or twelve piece bitboards. Castling and clocks in details and a board diagram too
IDfen20 / 20chess · 34 characters
Encoding / Chess

FEN

A whole position on one line. Bytes for the pieces, details for whose move it is.

Overhead
text only
Padding
none
Standard
PGN Standard §16.1 (Forsyth-Edwards Notation)
Used by
Chess engines, PGN headers, Lichess and puzzle passwords
family 2 / 20

Sample

Out
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
Back
"RNBQKBNRPPPPPPPP................................pppppppprnbqkbnr" · turn w, castling KQkq, enPassant -, halfmove 0, fullmove 1

Options

layoutstring
default a1
Which square is byte 0: a1 rank by rank, a8 as FEN reads, or file by file
diagramboolean
default false
The board as eight lines of pieces and dots, rank 8 first, no fields
bitboardsboolean
default false
The board as twelve 8-byte bitboards, one per piece in PNBRQKpnbrqk order
turnstring
optional
Side to move, w or b (default w)
castlingstring
optional
Castling rights, such as KQkq, or - for none (default -)
enPassantstring
optional
En passant target square on rank 3 or 6, or - (default -)
halfmovenumber
optional
Halfmoves since the last capture or pawn move (default 0)
fullmovenumber
optional
Move number, from 1 (default 1)

Access

Importimport { fen } from "@agntn/encodings/chess"
CLIencodings encode fen RNBQKBNRPPPPPPPP................................pppppppprnbqkbnr --castling KQkq
Tryplayground with the sample above
Kinsquare

FEN strings turn up in chess puzzles, sometimes inside a password. Parse one by hand and a typo puts a bishop on the wrong colour. fen reads the notation strictly and says where it broke.

ts
const start = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
decode("fen", start).bytes   // 64 bytes: "RNBQKBNRPPPPPPPP................................pppppppprnbqkbnr"
decode("fen", start).details // { turn: "w", castling: "KQkq", enPassant: "-", halfmove: 0, fullmove: 1 }

The board becomes 64 bytes. Everything else lands in details, where it can't get in the way.

Where is each piece?

Each byte is a piece letter in ASCII, or . for an empty square. White writes P N B R Q K, Black p n b r q k. Print the bytes as text and the position reads itself.

ts
const afterE4 = "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1";
const position = decode("fen", afterE4);
position.bytes[28] // 80, "P" on e4
position.bytes[12] // 46, "." on e2
position.details   // { turn: "b", castling: "KQkq", enPassant: "e3", halfmove: 0, fullmove: 1 }

The default layout: "a1" starts at a1 and counts along each rank. It goes from a1 to h1, then a2, up to h8. Byte 0 is R, byte 4 is K, and byte 60 is k.

Want FEN's own reading order instead? Use layout: "a8" to start at a8. Use layout: "file" to count a1 through a8, then b1.

ts
decode("fen", start, { layout: "a8" }).bytes // 64 bytes: "rnbqkbnrpppppppp................................PPPPPPPPRNBQKBNR"

Byte 0 is r here. These layouts match the square codec, so their indices agree.

How do you get the FEN back?

Pass the decoded fields back as options. The board bytes don't remember whose turn it is or who can castle.

ts
const { bytes, details } = decode("fen", start);
encode("fen", bytes)                       // "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w - - 0 1"
encode("fen", bytes, { castling: "KQkq" }) // "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
encode("fen", bytes, details)              // "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
encode("fen", bytes, { turn: "b", castling: "Kq", enPassant: "e3", halfmove: 7, fullmove: 40 }) // "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR b Kq e3 7 40"

Without options, turn defaults to w and castling to -. enPassant defaults to -, halfmove to 0, and fullmove to 1. Castling rights don't survive unless you pass them back.

A short FEN keeps only the fields it contains. Extra spaces and line breaks between fields are fine.

ts
decode("fen", "4k3/8/8/8/8/8/4P3/4K3 b").details // { turn: "b" }
decode("fen", "8/8/8/8/8/8/8/8").details         // {}

A missing field stays missing in details. No guessing that it's White to move.

Can it draw the board?

Set diagram: true to print the board with rank 8 on top. White sits at the bottom, just as with python-chess's print(board).

ts
const board = decode("fen", afterE4).bytes;
encode("fen", board, { diagram: true })

The result is:

text
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

A diagram shows the board alone. Decode it with diagram: true, with or without spaces between squares. Its details is {}. Encode won't accept fields beside the diagram option.

ts
encode("fen", board, { diagram: true, castling: "KQkq" }) // throws: Invalid option castling=KQkq: a diagram shows the board alone

No castling rights fit in that picture.

Can the pieces hide bits of their own?

The board can be the message. Twelve boards for one position sounds like a lot. But a puzzle that hides one bit per piece needs exactly that, and bitboards: true hands it over.

ts
const bytes = decode("fen", afterE4, { bitboards: true }).bytes // 96 bytes
bytes.subarray(0, 8)                                             // white pawns, in hex 000000001000ef00
encode("square", bytes.subarray(0, 8), { bitboard: true })       // "a2 b2 c2 d2 f2 g2 h2 e4"

Each piece type gets its own 8-byte big-endian board. White moves first here too: P N B R Q K p n b r q k. The FEN fields stay in details as usual.

Bit i marks square i in the chosen layout. The default is a1: bit 0 is a1, bit 63 is h8. Same layouts and same bitboards as square, so any slice plugs straight into it. That's the nice part.

At the start, the boards look like this:

ts
decode("fen", start, { bitboards: true }).bytes // 96 bytes, in hex 000000000000ff00 0000000000000042 0000000000000024 0000000000000081 0000000000000008 0000000000000010 00ff000000000000 4200000000000000 2400000000000000 8100000000000000 0800000000000000 1000000000000000

The first board is white pawns. The bitboards match python-chess.

And they encode back into a FEN. As with the 64-byte board, options supply the fields after it.

ts
encode("fen", bytes, { bitboards: true, turn: "b", castling: "KQkq", enPassant: "e3" }) // "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1"

diagram: true works both ways too. Decode a diagram to bitboards, or encode bitboards to a diagram.

Bitboards going in must be 96 bytes. Two pieces on one square get refused too.

ts
encode("fen", new Uint8Array(64), { bitboards: true }) // throws: fen: twelve bitboards are 96 bytes, not 64

A pawn and the black king both on e1 throws fen: e1 holds both P and k; one piece a square. Cosy, but no.

identify never guesses bitboards. It's the same board again, so it would turn up twice.

What does it refuse?

Bad notation gets a precise complaint. DecodeError.index points at the guilty character, not just the field.

ts
decode("fen", "rnbqkbnr/pppppppp/44/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1") // throws: fen: "4" (U+0034) at index 19 follows another count; add them up
decode("fen", "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w kqKQ - 0 1") // throws: fen: "kqKQ" at index 46 is not castling rights, "K" (U+004B) at index 48 is out of place; use K, Q, k and q, each once and in that order, or -
decode("fen", "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq e4 0 1") // throws: fen: "e4" at index 51 is not an en passant square, "4" (U+0034) at index 52 is out of place; use a square on rank 3 or 6, or -

FEN writes an empty rank as 8, not consecutive counts like 44. Castling letters follow K, Q, k, q order. An en passant square must be on rank 3 or 6. That's the square a pawn skips on its double step.

The codec also rejects ranks with the wrong number of squares and boards without exactly eight ranks. It rejects a turn other than w or b, and a move number of 0. Each error names where the problem is.

Encoding requires exactly 64 bytes, each a piece letter or ..

ts
encode("fen", "hello") // throws: fen: a board is 64 bytes, not 5

It checks notation, not chess legality. Two white kings, nine queens, or pawns on rank 8 all pass. The arbiter can take the day off.

Can identify spot a FEN?

Yes, and it hands the fields back too.

ts
identify("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1")[0] // encoding "fen", with fields in details

It never guesses layout. Every layout reads the same board, so a guess would list one position three times.

Aliases, subpath and CLI

The aliases forsyth and forsythedwards name fen. The @agntn/encodings/chess subpath exports fen and FEN_TURNS alongside square.

shell
encodings decode fen "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

The CLI prints the 64 bytes on stdout. It prints fields on stderr, one per line, such as turn: w and castling: KQkq.

The bytes are printable, so the board goes back in as plain text.

shell
encodings encode fen RNBQKBNRPPPPPPPP................................pppppppprnbqkbnr --castling KQkq --en-passant e3 --turn b

That prints rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR b KQkq e3 0 1. The flags are --layout, --diagram, --bitboards, --turn, --castling, --en-passant, --halfmove and --fullmove.