A tracker is a little scorekeeper. While Chessalyzer works through your PGN file, each tracker watches the games go by and tallies up the one thing it cares about — results, captures, square activity, anything. You decide what gets measured by choosing which trackers to attach, and tracking only what you need is what keeps analyses fast.

Factory, instance, state

You'll meet three words over and over:

A factory is a function like tileTracker() that creates a tracker. Built-in factories ship with Chessalyzer; you can also write your own.
An instance is what the factory hands back — the handle you pass to analyzePGN.
The state is where the instance accumulates its numbers. After the analysis finishes, you read instance.state.

import { analyzePGN } from 'chessalyzer';
import { tileTracker, gameTracker } from 'chessalyzer/trackers';

const tiles = tileTracker(); // factory call → instance
const games = gameTracker();

await analyzePGN('games.pgn', { trackers: [tiles, games] });

tiles.state.movesTotal; // 19 — tile stats
games.state.gameCount; // 3  — game stats

Every factory call creates a fresh instance with its own state, so calling tileTracker() twice gives you two independent counters — handy for comparing groups of games.

Wait for the finish line

Don't read instance.state while an analysis is still in flight. Chessalyzer works in parallel by default, and the partial results from all worker threads are only merged into your instance right before analyzePGN resolves — so mid-run reads see incomplete numbers. Await the call, then read state. Curious why? Multithreading has the details.

Two kinds of trackers

Kind	Created with	Sees	Built-in examples
Move tracker	`defineMoveTracker`	Every half-move, with board context	`tileTracker`, `pieceTracker`
Game tracker	`defineGameTracker`	One summary per game (headers, result)	`gameTracker`

Pick by the question you're asking. "Where do knights get captured?" needs to watch every move → move tracker. "Which openings are most common?" only needs each game's headers → game tracker.

Replay is taken care of

Move trackers need Chessalyzer to replay each game on an internal board; game trackers usually don't. You never have to configure this — analyzePGN looks at your trackers and chooses the cheapest sufficient mode automatically. The replay option exists for rare overrides; How Chessalyzer works explains the machinery.

Next steps

Built-in trackers — the three ready-made scorekeepers and what their state contains
Custom trackers — teach Chessalyzer a statistic of your own

Trackers

Factory, instance, state

Two kinds of trackers

Next steps

On this page