Encodings

Chess squares

Chess squares as bytes, with a choice of board numbering
IDsquare19 / 20chess · 16 characters
Encoding / Chess

Chess squares

One byte per square. e4 is 28 or 36, depending on who's counting.

Overhead
text only
Padding
none
Standard
FIDE Laws of Chess, Appendix C (algebraic notation)
Used by
Chess engines, PGN and FEN tools, chess puzzles
family 2 / 20

Sample

Out
b7 f6 a7
Back
"1-0"

Options

layoutstring
default a1
a1 = 0 rank by rank, a8 = 0 as FEN reads the board, or file by file
pairsboolean
default false
Squares as (file, rank) pairs counted from 0, such as (4, 3) for e4
bitboardboolean
default false
The squares as one bitboard: 8 bytes big-endian, bit i for square i

Access

Importimport { square } from "@agntn/encodings/chess"
CLIencodings encode square 1-0
Tryplayground with the sample above
Kinfen

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.