---
title: "FEN"
description: "Chess positions in FEN as 64 bytes of piece letters or twelve piece bitboards. Castling and clocks in details and a board diagram too"
canonical_url: "https://encodings.agntn.dev/encodings/fen"
---
# 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

<encoding-facts name="fen">



</encoding-facts>

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

```sh
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.

```sh
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`.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
