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:

git clone [repository-url]
cd trigo-web

2. Install all dependencies:

npm run install:all

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

Development

Run both frontend and backend in development mode:

npm run dev

Or run them separately:

# 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:

npm run build

Testing

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

Run all tests once:

npm run test:run

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

npm test

Run tests with UI dashboard:

npm run test:ui

Run specific test file:

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:

npm run format

Check formatting without making changes:

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.