---
title: "Chess squares"
description: "Chess squares as bytes, with a choice of board numbering"
canonical_url: "https://encodings.agntn.dev/encodings/square"
---
# Chess squares

> Chess squares as bytes, with a choice of board numbering

<encoding-facts name="square">



</encoding-facts>

Each chess square gets one byte, numbered from 0 to 63. The `square` codec turns those bytes into names and back.

```ts
encode("square", Uint8Array.of(28, 35))                        // "e4 d5"
decode("square", "e4 d5").bytes                                // Uint8Array [28, 35]
```

A square holds six bits, just like a base64 character. Not bad for a board of 64 squares.

## Which square is zero?

The default `layout: "a1"` counts along each rank. It starts with a1 = 0 and b1 = 1. Then a2 = 8, up to h8 = 63. Stockfish counts this way, and so does python-chess.

The `layout: "a8"` option starts at the other end. It counts a8 = 0, b8 = 1 and a1 = 56. That's the order FEN reads the board in.

```ts
encode("square", Uint8Array.of(0, 63))                         // "a1 h8"
encode("square", Uint8Array.of(0, 63), { layout: "a8" })       // "a8 h1"
decode("square", "e4 a1", { layout: "a8" }).bytes              // Uint8Array [36, 56]
```

The same e4 is 28 in one layout and 36 in another. Same square, two numbers. Got indices from someone else's tool? Check its numbering first.

The `layout: "file"` option counts up each file instead. It starts a1 = 0, a2 = 1 and b1 = 8.

```ts
decode("square", "a2 b1", { layout: "file" }).bytes            // Uint8Array [1, 8]
```

## Prefer coordinates?

The `pairs: true` option reads and writes `(file, rank)` pairs. Both coordinates start at 0, like python-chess `square_file` and `square_rank`. So `(4, 3)` is e4. Spaces inside the parentheses are optional.

```ts
encode("square", Uint8Array.of(28, 35), { pairs: true })       // "(4, 3) (3, 4)"
decode("square", "(4, 3) (3, 4)", { pairs: true }).bytes       // Uint8Array [28, 35]
```

Pairs name coordinates, not byte values. The `layout` option still decides the byte.

Capital files pass too, since puzzles like to shout. Separate squares with whitespace or commas.

```ts
decode("square", "E4, D5").bytes                               // Uint8Array [28, 35]
```

## Can one number hold a whole board?

Yes. A bitboard gives each of the 64 squares one bit of a 64-bit number. Nice and tight.

Turn on `bitboard` and `decode` packs the squares into exactly eight bytes, big-endian. Bit `i` marks square index `i` in the chosen layout. Want hex or bits? The `hex` and `binary` codecs already do that.

```ts
const board = decode("square", "e4 d5", { bitboard: true }).bytes; // Uint8Array [0, 0, 0, 8, 16, 0, 0, 0]
encode("hex", board)                                           // "0000000810000000"
encode("binary", board)                                        // "00000000 00000000 00000000 00001000 00010000 00000000 00000000 00000000"
encode("square", decode("hex", "000000000000ff00").bytes, { bitboard: true }) // "a2 b2 c2 d2 e2 f2 g2 h2"
```

That's 1. e4 d5, the Scandinavian, in eight bytes. And `0x000000000000ff00` is every white pawn still at home on the second rank. The bitboards agree with python-chess's `SquareSet`.

Layout still decides which square each bit is. From a8, the same opening lands on other bits.

```ts
encode("hex", decode("square", "e4 d5", { bitboard: true, layout: "a8" }).bytes) // "0000001008000000"
```

Input order doesn't matter, so `"d5 e4"` gives the same bytes as `"e4 d5"`. Encoding writes the squares lowest index first. Empty text gives eight zero bytes, and eight zero bytes give an empty string. `pairs: true` works with bitboards too.

A set has no room for a square twice. And a bitboard is eight bytes, not seven, not nine.

```ts
decode("square", "e4 d5 e4", { bitboard: true })               // throws: square: e4 at index 6 is already on the board
encode("square", Uint8Array.of(28, 35), { bitboard: true })    // throws: square: a bitboard is 8 bytes, not 2
```

Want hex straight from the CLI? `encodings decode square "e4 d5" --bitboard -o hex` prints `0000000810000000`.

## Can text become squares?

Text is encoded as bytes first, and every byte has to fit between 0 and 63. The game result `1-0` fits: its bytes are 49, 45 and 48.

```ts
encode("square", "1-0")                                        // "b7 f6 a7"
encode("square", "hi")                                         // throws: square: byte 104 at index 0 is over 63, the last square
```

White wins, and three squares appear. Lowercase letters don't fit: their bytes are over 63.

## What does it refuse?

Bad squares fail with the position of the offending character. In `e9`, that's index 1, the `9`. The wrong text form also gets a hint.

```ts
decode("square", "e9")                                         // throws: square: "9" (U+0039) is not a rank, 1 to 8
decode("square", "(4, 3)")                                     // throws: square: "(" (U+0028) is not a file, a to h; for (file, rank) pairs, set pairs
decode("square", "e4", { pairs: true })                        // throws: square: "e" (U+0065) where ( goes; for names such as e4, leave pairs off
```

## Can identify spot squares?

The `identify` function tries square names and pairs.

```ts
identify("e4 d5")[0];                                          // encoding "square"
```

It never guesses `layout`. Read from a8, a1 is byte 56, which prints as `8`, and a guess would fall for that. Nor `bitboard`: the text reads as the same squares either way, only the packing differs.

## Aliases, subpath and CLI

The aliases `squares` and `chesssquare` name `square`. The subpath `@agntn/encodings/chess` exports `square` and `CHESS_LAYOUTS`.

In the CLI, `encodings encode square 1-0` prints `b7 f6 a7`. The flags are `--layout`, `--pairs` and `--bitboard`.


## Sitemap

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