trigo-web/inc/tgn/README.md

TGN (Trigo Game Notation) Parser

This directory contains the TGN parser implementation for reading and writing Trigo game notation files.

Files

• tgn.jison - Grammar definition for TGN format (similar to PGN for chess)
• tgnParser.ts - TypeScript wrapper providing type-safe API for the parser
• tgn.jison.cjs - Generated parser (auto-generated, gitignored)

Building the Parser

The parser is generated from the jison grammar file. To rebuild:

npm run build:parsers

Or specifically for TGN:

npm run build:parser:tgn

This will generate tgn.jison.cjs from tgn.jison.

Usage

Import the parser functions from the game module:

import { TrigoGame, validateTGN, TGNParseError } from "@inc/trigo/game";

// Parse TGN and create game instance
const tgn = `
[Event "Test Game"]
[Board 5x5x5]

1. 000 y00
2. 0y0 Pass
`;

try {
    const game = TrigoGame.fromTGN(tgn);
    console.log("Game loaded successfully!");
} catch (error) {
    if (error instanceof TGNParseError) {
        console.error("Parse error at line", error.line);
    }
}

// Validate TGN without parsing
const result = validateTGN(tgn);
if (result.valid) {
    console.log("Valid TGN");
} else {
    console.error("Invalid TGN:", result.error);
}

TGN Format

TGN format consists of:

1. Metadata tags - Key-value pairs in square brackets
2. Move sequence - Numbered rounds with moves in ab0yz coordinate notation

Example:

[Event "World Championship"]
[Site "Tokyo"]
[Date "2025.10.31"]
[Black "Alice"]
[White "Bob"]
[Board 5x5x5]
[Rules "Chinese"]

1. 000 y00
2. 0y0 yy0
3. aaa Pass

Coordinate Notation (ab0yz)

• 0 = center position
• a, b, c, ... = positions from one edge toward center
• z, y, x, ... = positions from opposite edge toward center

Examples for 5×5×5 board:

• 000 = center (2,2,2)
• aaa = corner (0,0,0)
• zzz = opposite corner (4,4,4)
• y00 = (4,2,2)

For 2D boards (e.g., 19×19×1), only two coordinates are used:

• 00 = center
• aa = corner

Development

The parser is built using Jison, a JavaScript parser generator similar to Bison/Yacc.

Note: Generated files (*.jison.cjs, *.jison.js) are gitignored and must be built locally or in CI/CD.

Related Documentation

• TGN Format Specification
• Parser Development Guide