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

```bash
# 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 "X*Y*Z" 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

```tgn
[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`