Does this handle every possible chess move?

It handles standard algebraic notation for normal moves and captures (with disambiguation and promotion) and castling ('O-O'/'O-O-O'). It does not implement en passant captures or check/checkmate legality validation: a move it can't resolve simply stops the animation there rather than guessing.

What happens if my PGN has comments or variations?

Comments in {curly braces}, numeric annotation glyphs like $1, and parenthesized side-variations are stripped out before parsing, so only the main line's move tokens are used.

Where does the board rendering come from?

It reuses this codebase's existing chess board model (createStandardChessStartingBoard and the ChessPiece/ChessBoard types from random/lib/chess-board.ts, already used by this app's random chess position/game generators), though that module only ever offered text rendering: the actual pixel drawing (squares, piece discs, letter glyphs) is new, built specifically for this GIF renderer.

Why does the animation stop partway through my game?

The first move that can't be parsed or resolved (most commonly an en passant capture, which isn't supported) stops the game there; every position rendered up to that point is still included in the output GIF.

PGN to GIF Converter - Animate a Chess Game

Overview

Introduction

This tool turns a PGN chess game transcript into a simple animated GIF, playing through the game one move at a time so you can watch the position develop without a full chess GUI.

It's built on this codebase's existing chess board model, adding a real (if honestly simplified) move-applying engine and a purpose-built pixel renderer.

What Is PGN to GIF Converter?

PGN (Portable Game Notation) is the standard plain-text format for recording chess games: a sequence of numbered move pairs in algebraic notation, like '1. e4 e5 2. Nf3 Nc6'.

This tool parses that move list, applies each move to a chess board, and renders the resulting position as one frame of an animated GIF, one frame per ply (half-move).

How PGN to GIF Converter Works

PGN text is tokenized by stripping comments, NAGs, parenthesized variations, move numbers, and result markers, leaving a flat list of SAN (Standard Algebraic Notation) move tokens.

Starting from the standard opening position (from this codebase's shared chess-board.ts model), each token is resolved to a source and destination square using each piece type's real movement rules (including sliding-piece path blocking) and applied to the board; the position after every successfully-applied move is rendered as one RGBA frame and the whole sequence is encoded as a GIF via this category's shared codec.

When To Use PGN to GIF Converter

Use it to get a quick, shareable visual of how a chess game unfolded from its PGN transcript, without needing a chess GUI or website.

Don't use it as a rules-accurate chess engine: it doesn't validate check, checkmate, stalemate, or that a move doesn't leave your own king in check.

Often used alongside SGF to GIF Converter, PDN to GIF Converter and GIF to ZIP Archive Converter.

Features

Advantages

Implements a real move-applying engine, not just a static diagram: captures, disambiguation, promotion, and castling are all genuinely handled.
Reuses this codebase's existing, already-tested chess board model rather than inventing a new one.
Fails gracefully: an unresolvable move stops the animation at that point instead of erroring out the whole conversion.

Limitations

En passant pawn captures are not supported; a PGN containing one will stop the rendered animation at that move.
There is no check, checkmate, or stalemate validation, and no verification that a move doesn't leave the mover's own king in check: moves are applied by piece-movement geometry alone.
When multiple pieces of the same type could reach a destination and the PGN's disambiguation is incomplete or ambiguous, the first matching candidate (in board-scan order) is used rather than fully resolving which piece a human PGN writer intended.
Nested PGN variations (parenthesized side-lines) are stripped entirely rather than rendered as branches; only the main line is animated.

Examples

Animating the opening of a Ruy Lopez game

Input

1. e4 e5 2. Nf3 Nc6 3. Bb5 a6 4. Ba4 Nf6 5. O-O Be7 6. Re1 b5 7. Bb3 d6 8. c3 O-O

Output

An animated GIF with 17 frames (starting position + 16 plies), each showing the board after one move, both sides' O-O castling correctly reflected

Every move parses as valid SAN and resolves against the board's real piece positions, including both castling moves.

Best Practices & Notes

Best Practices

Strip result markers and heavy annotation from very long PGNs if you only care about a specific opening sequence, to keep the frame count manageable.
If the animation stops earlier than expected, check the move right after the last rendered frame: it's very likely an en passant capture or a typo in the SAN notation.
Keep games under this category's 256-frame GIF limit; extremely long games (128+ full moves) may need trimming first.

Developer Notes

convertPgnToGif tokenizes PGN text with a series of regex passes (comments, NAGs, parenthesized variations, move numbers, results), then applies each SAN token to a ChessBoard from random/lib/chess-board.ts via applySanMove: pawns get dedicated forward/capture logic (including the two-square-from-start-rank case), and N/B/R/Q/K moves are resolved by scanning the board for a same-color, same-type piece that can geometrically reach the destination (with sliding-piece path-blocking via canReach), optionally narrowed by SAN disambiguation. Every successfully-reached position is rendered via a purpose-built rasterizer (fillRect/fillCircle/drawGlyph over a PixelBuffer) and encoded with the shared encodeGif().

PGN to GIF Converter Use Cases

Sharing a quick visual walkthrough of a chess opening or tactical sequence from its PGN
Turning a PGN game archive into a GIF preview for a blog post or forum
Visually spot-checking a PGN file's move list for obvious notation errors

Common Mistakes

Assuming every legal PGN will fully animate: en passant captures specifically will stop the sequence early.
Expecting check/checkmate symbols ('+'/'#') to affect rendering; they're stripped and ignored, since this tool only applies piece geometry, not check detection.

Tips

If a game won't fully render, try removing the specific move causing trouble (often an en passant capture) to see the rest of the game animate.
Pair with gif-to-zip-archive-converter to export the animation's individual frames as separate PNGs for a slideshow-style presentation instead.

PGN to GIF Converter