trigo-web/README.md

# Trigo - 3D Go Board Game

A modern web implementation of Go played on a three-dimensional board, built with Vue 3, TypeScript, Node.js, and Three.js.

## Features

- **3D Board**: Play Go on a 5x5x5 three-dimensional board
- **Multiplayer**: Real-time online gameplay via WebSocket
- **Single Player**: Play against AI opponents
- **Game Replay**: Review and analyze completed games
- **Modern Tech Stack**: Vue 3, TypeScript, Three.js for WebGL rendering

## Project Structure

```
trigo-web/
├── app/                # Frontend application (Vue 3)
│   ├── src/
│   │   ├── components/ # Vue components
│   │   ├── views/      # Page views
│   │   ├── game/       # Game logic and 3D rendering
│   │   ├── store/      # Pinia state management
│   │   └── services/   # API and WebSocket services
│   └── package.json
├── backend/            # Backend server (Node.js)
│   ├── src/
│   │   ├── controllers/
│   │   ├── services/   # Game logic and room management
│   │   ├── sockets/    # Socket.io handlers
│   │   └── server.ts   # Main server entry
│   └── package.json
├── inc/                # Shared code between frontend and backend
│   ├── trigo/          # Core game logic and types
│   │   ├── types.ts    # TypeScript interfaces
│   │   ├── gameUtils.ts # Game utility functions (capture, Ko, territory)
│   │   ├── game.ts     # TrigoGame class - main game state management
│   │   └── ab0yz.ts    # TGN coordinate encoding
├── tests/              # Test files
│   └── game/           # Game logic tests (TrigoGame)
├── vitest.config.ts    # Vitest test configuration
├── tsconfig.json       # TypeScript configuration
└── package.json        # Root package.json with dev scripts
```

## Getting Started

### Prerequisites

- Node.js (v18+ recommended)
- npm or yarn

### Installation

1. Clone the repository:

```bash
git clone [repository-url]
cd trigo-web
```

2. Install all dependencies:

```bash
npm run install:all
```

This will install dependencies for the root, frontend, and backend.

### Development

Run both frontend and backend in development mode:

```bash
npm run dev
```

Or run them separately:

```bash
# Frontend only (runs on http://localhost:5173)
npm run dev:app

# Backend only (runs on http://localhost:3000)
npm run dev:backend
```

### Building for Production

Build both frontend and backend:

```bash
npm run build
```

### Testing

The project includes comprehensive unit tests for the game logic (TrigoGame class).

**Run all tests once:**

```bash
npm run test:run
```

**Run tests in watch mode (auto-rerun on file changes):**

```bash
npm test
```

**Run tests with UI dashboard:**

```bash
npm run test:ui
```

**Run specific test file:**

```bash
npm exec vitest -- run tests/game/trigoGame.core.test.ts
```

**Test Coverage:**

- **109/109 tests passing (100%)**
- Core functionality (35 tests) - Drop, pass, surrender, reset
- History management (21 tests) - Undo, redo, jump to step
- Game rules (18 tests) - Capture, Ko rule, suicide, territory calculation
- State management (32 tests) - Serialization, callbacks, session storage

**Test Files Location:** `tests/game/`

- `trigoGame.core.test.ts` - Basic game operations
- `trigoGame.history.test.ts` - History and navigation
- `trigoGame.rules.test.ts` - Go game rules implementation
- `trigoGame.state.test.ts` - State persistence and callbacks

### Code Formatting

Format all code with Prettier:

```bash
npm run format
```

Check formatting without making changes:

```bash
npm run format:check
```

## Technology Stack

### Frontend

- **Vue 3** - Progressive JavaScript framework
- **TypeScript** - Type-safe JavaScript
- **Three.js** - 3D graphics library for WebGL
- **Pinia** - State management
- **Vue Router** - Client-side routing
- **Socket.io Client** - WebSocket communication
- **Vite** - Fast build tool
- **SASS** - CSS preprocessor

### Backend

- **Node.js** - JavaScript runtime
- **Express** - Web framework
- **Socket.io** - Real-time bidirectional communication
- **TypeScript** - Type-safe JavaScript
- **UUID** - Unique ID generation

## Game Rules

Trigo extends the traditional Go game into three dimensions:

1. The game is played on a 5x5x5 cubic board
2. Players take turns placing stones (black and white)
3. Stones are captured when completely surrounded in 3D space
4. The goal is to control more territory than your opponent

## API Endpoints

### REST API

- `GET /health` - Health check
- `GET /api/rooms` - List active game rooms
- `GET /api/rooms/:roomId` - Get specific room details

### WebSocket Events

#### Client → Server

- `joinRoom` - Join or create a game room
- `leaveRoom` - Leave current room
- `makeMove` - Make a game move
- `pass` - Pass turn
- `resign` - Resign from game
- `chatMessage` - Send chat message

#### Server → Client

- `roomJoined` - Successfully joined room
- `gameUpdate` - Game state update
- `playerJoined` - Another player joined
- `playerLeft` - Player left room
- `chatMessage` - Incoming chat message
- `gameEnded` - Game finished

## Development Guidelines

### Code Style

- Uses Prettier for consistent formatting
- Tab indentation (following prototype style)
- Double quotes for strings
- No trailing commas
- Semicolons always

### Git Workflow

1. Create feature branch from `main`
2. Make changes and test locally
3. Format code with `npm run format`
4. Commit with descriptive messages
5. Create pull request

## Based On

This project is a modern reimplementation of the original Trigo prototype found in `third_party/klstrigo/`, updating the technology stack while preserving the core game mechanics and 3D gameplay experience.

## License

MIT License - See LICENSE file for details

## Contributing

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.

## Support

For issues, questions, or suggestions, please open an issue on GitHub.