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:

```bash
npm run build:parsers
```

Or specifically for TGN:

```bash
npm run build:parser:tgn
```

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

## Usage

Import the parser functions from the game module:

```typescript
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:

```tgn
[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](https://github.com/zaach/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](../../docs/tgn-format-spec.md)
- [Parser Development Guide](../../docs/README.tgn.md)