trigo-web/tools/README.md

Trigo Tools

Development tools for the Trigo project.

Random Game Generator

Generate random Trigo games in TGN (Trigo Game Notation) format for testing, development, and analysis.

Usage

# Generate 10 games with default settings (play until territory settled)
npm run generate:games

# Generate 100 games with custom move range
npm run generate:games -- --count 100 --moves 20-80

# Generate games with exactly 30 moves each
npm run generate:games -- --moves 30 --count 50

# Generate games on 3x3x3 board (plays until settled)
npm run generate:games -- --board "3*3*3" --count 50

# Generate 2D games (9x9x1 board)
npm run generate:games -- --board "9*9*1" --count 20

# Higher pass probability
npm run generate:games -- --pass-chance 0.3

# Custom output directory
npm run generate:games -- --output "my_games" --count 50

Options

Option	Short	Default	Description
--count	-c	10	Number of games to generate
--moves	-m	(settled)	Moves per game as "MIN-MAX" or single number. Default: play until neutral territory = 0
--pass-chance		0	Probability of passing (0.0-1.0)
--board	-b	"random"	Board size as "XYZ" or "random"
--output	-o	"output"	Output directory (relative to tools/)
--help	-h	-	Show help message

How It Works

Default Mode (no --moves specified):

1. Creates a new Trigo game with the specified board shape
2. Plays random valid moves until the board reaches 90% coverage
3. After 90% coverage, checks territory after each move
4. Stops when neutral territory reaches 0 (game is fully settled)
5. Results in complete, finished games with all territory claimed

Custom Move Mode (--moves specified):

1. Creates a new Trigo game with the specified board shape
2. Randomly selects valid moves for the specified number of moves
3. Respects Go rules: Ko, suicide prevention, capture
4. Games may end early on double-pass
5. Exports each game to TGN format with metadata

Output Format

Generated files are named using SHA-256 hash of the TGN content: game_<HASH>.tgn

This ensures:

• Content-based naming: Same game content = same filename
• Duplicate detection: Identical games won't overwrite each other
• Deterministic: Reproducible filenames independent of generation time

Example output:

tools/output/
├── game_a3f5c8d912e4b6f1.tgn
├── game_7b2d9e1a4c8f3605.tgn
└── game_9e4b6f1a3f5c8d91.tgn

TGN Format Example

[Event "Random Generated Game"]
[Site "Batch Generator"]
[Date "2025.11.03"]
[Black "Random Black"]
[White "Random White"]
[Board "5x5x5"]
[Rules "Chinese"]
[Application "Trigo Random Generator v1.0 (5×5×5)"]

1. 000 y00
2. 0y0 yy0
3. aaa zzz
4. Pass 0az
5. z0z Pass

Performance

• Small boards (3×3×3): ~250 games/second
• Standard boards (5×5×5): ~75 games/second
• Large boards (9×9×1): ~33 games/second

Generating 1000 games on a 5×5×5 board takes approximately 13 seconds.

Use Cases

1. Testing TGN parser - Create diverse test files for import functionality
2. Performance testing - Generate large datasets for board rendering tests
3. AI training - Create training data for future AI opponent
4. Game analysis - Study patterns in random gameplay
5. Format validation - Verify TGN export works correctly across scenarios

Board Sizes

3D Boards:

• 3*3*3 - Tiny cube (27 positions)
• 5*5*5 - Standard cube (125 positions)
• 7*7*7 - Large cube (343 positions)
• 9*9*2 - Wide board (162 positions)

2D Boards (Traditional Go):

• 9*9*1 - Small board (81 positions)
• 13*13*1 - Medium board (169 positions)
• 19*19*1 - Standard board (361 positions)

Implementation Details

File: tools/generateRandomGames.ts

Key Functions:

• generateRandomGame() - Simulates a complete random game
• getValidMoves() - Finds all legal moves for current player
• selectRandomMove() - Randomly picks from valid moves
• generateBatch() - Generates multiple games in parallel

Safety Features:

• Validates all moves using game rules (Ko, suicide, occupation)
• Handles cases where no valid moves exist (must pass)
• Respects double-pass game end condition
• Progress indicator for large batches
• Error handling and validation

Dependencies

• tsx - TypeScript execution
• yargs - Advanced command-line argument parsing with validation
• TrigoGame - Core game logic from inc/trigo/game.ts
• Node.js fs/path - File system operations

---

For more information about TGN format, see /tests/game/trigoGame.tgn.test.ts