mirror of
https://github.com/tiennm99/caro.git
synced 2026-09-20 05:11:44 +00:00
docs: comprehensive README with setup, architecture, and credits
- Full project README: quick start, game rules, project structure, server/client architecture diagrams, CLI/web options, protocol docs - Web client README: setup, scripts, tech stack - Credit to ainilili/ratel original project
This commit is contained in:
tiennm99 committed
1 parent
22bb9c1371
commit
4bad51314d
2 files changed
+173
-24
No files matched your search
@@ -1,57 +1,170 @@
|
||||
# Caro (Gomoku)
|
||||
|
||||
A command-line Gomoku (Five-in-a-Row) game with client-server architecture, built on Netty.
|
||||
A multiplayer Gomoku (Five-in-a-Row) game with client-server architecture. Play in the browser or from the command line.
|
||||
|
||||
Based on [Ratel](https://github.com/ainilili/ratel).
|
||||
Built on [Netty](https://netty.io/) (server) and [Phaser 3](https://phaser.io/) (web client).
|
||||
|
||||
## Installation
|
||||
## Features
|
||||
|
||||
Requires Maven and JRE (Java 8+):
|
||||
- **15x15 board** with standard Gomoku rules
|
||||
- **Player vs Player (PVP)** — create or join rooms, play against others online
|
||||
- **Player vs AI (PVE)** — three difficulty levels (Easy, Medium, Hard)
|
||||
- **Spectator mode** — watch ongoing games in real-time
|
||||
- **Web client** — professional 2D game UI with canvas board, stone animations, sound effects
|
||||
- **CLI client** — terminal-based client for lightweight play
|
||||
- **WebSocket + TCP** — dual protocol support
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Java 8+** and **Maven** — for the server and CLI client
|
||||
- **Node.js 18+** — for the web client (development only)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Build the server
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tiennm99/caro.git
|
||||
cd caro
|
||||
mvn install package
|
||||
mvn clean package -DskipTests
|
||||
```
|
||||
|
||||
## Running
|
||||
### 2. Start the server
|
||||
|
||||
Start the server:
|
||||
```bash
|
||||
java -jar landlords-server/target/landlords-server-1.4.0.jar -p 1024
|
||||
```
|
||||
|
||||
Start a client:
|
||||
The server starts two listeners:
|
||||
- **TCP** on port `1024` (for CLI clients)
|
||||
- **WebSocket** on port `1025` (for web clients and the built-in web UI)
|
||||
|
||||
### 3. Play in the browser (Web Client)
|
||||
|
||||
#### Option A: Built-in web UI
|
||||
|
||||
Open `http://localhost:1025/` in your browser. The server serves a basic web UI directly.
|
||||
|
||||
#### Option B: Phaser web client (recommended)
|
||||
|
||||
```bash
|
||||
cd web-client
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open `http://localhost:5173` in your browser. This is the full-featured Phaser 3 game client with:
|
||||
- Wood-textured board with gradient stones
|
||||
- Stone placement animations and hover preview
|
||||
- Move history panel and turn indicator
|
||||
- Sound effects (Web Audio API)
|
||||
- Lobby with room management
|
||||
|
||||
To play multiplayer, open two browser tabs.
|
||||
|
||||
### 4. Play from the terminal (CLI Client)
|
||||
|
||||
```bash
|
||||
java -jar landlords-client/target/landlords-client-1.4.0.jar -h 127.0.0.1 -p 1024
|
||||
```
|
||||
|
||||
Enter moves as `row,col` (e.g. `7,7` for the center of the board). Type `exit` or `e` to leave.
|
||||
|
||||
## Game Rules
|
||||
|
||||
- Two players take turns placing black and white pieces on a 15x15 board
|
||||
- Black moves first
|
||||
- First to form an unbroken line of 5 pieces (horizontal, vertical, or diagonal) wins
|
||||
- The game ends in a draw if the board is full
|
||||
- Two players take turns placing **black** and **white** pieces on a 15x15 board
|
||||
- **Black moves first**
|
||||
- The first player to form an unbroken line of **5 pieces** (horizontally, vertically, or diagonally) wins
|
||||
- The game ends in a **draw** if all 225 positions are filled
|
||||
|
||||
## Game Modes
|
||||
## Project Structure
|
||||
|
||||
- **PVP** - Player vs Player
|
||||
- **PVE** - Player vs AI (Easy / Medium / Hard)
|
||||
- **Spectator** - Watch ongoing games
|
||||
```
|
||||
caro/
|
||||
landlords-common/ Java shared library (game logic, entities, protocol)
|
||||
landlords-server/ Java Netty server (TCP + WebSocket)
|
||||
landlords-client/ Java CLI client
|
||||
web-client/ Phaser 3 web client (Vite + vanilla JS)
|
||||
```
|
||||
|
||||
## Game Commands
|
||||
### Server Architecture
|
||||
|
||||
Moves are entered as `row,col` (e.g. `7,7` for center).
|
||||
```
|
||||
Client (browser/CLI)
|
||||
|
|
||||
+-- TCP :1024 --> ProtobufTransferHandler --> ServerEventListener_*
|
||||
+-- WS :1025 --> WebsocketTransferHandler --> ServerEventListener_*
|
||||
+-- HTTP :1025 --> StaticFileHandler --> static files
|
||||
```
|
||||
|
||||
- `exit` or `e` - Leave the game
|
||||
### Web Client Architecture
|
||||
|
||||
## Protocol Support
|
||||
```
|
||||
web-client/src/
|
||||
main.js Phaser game boot
|
||||
config/
|
||||
game-config.js Phaser config (800x800, Scale.FIT)
|
||||
protocol-constants.js Server/client event code enums
|
||||
scenes/
|
||||
boot-scene.js Connect to server
|
||||
menu-scene.js DOM overlay menus
|
||||
game-scene.js Board rendering + game interaction
|
||||
services/
|
||||
event-bus.js Pub/sub event decoupling
|
||||
connection-service.js WebSocket with heartbeat + reconnect
|
||||
game-state-service.js Client-side state container
|
||||
objects/
|
||||
board.js 15x15 grid with wood texture
|
||||
stone.js Gradient stones with drop animation
|
||||
ui/
|
||||
menu-ui.js Nickname, lobby, room list, waiting room
|
||||
game-ui.js HUD, move history, game over, toasts
|
||||
```
|
||||
|
||||
- TCP (default, port 1024)
|
||||
- WebSocket (port = TCP port + 1)
|
||||
## Server Options
|
||||
|
||||
WebSocket address: `ws://host:port/ratel`
|
||||
```
|
||||
-p, -port TCP port (default: 1024, WebSocket = TCP + 1)
|
||||
```
|
||||
|
||||
## CLI Client Options
|
||||
|
||||
```
|
||||
-h, -host Server address (required)
|
||||
-p, -port Server TCP port (default: 1024)
|
||||
-ptl, -protocol Protocol: "pb" (TCP/Protobuf) or "ws" (WebSocket)
|
||||
-lang Language: "en" / "en_US"
|
||||
```
|
||||
|
||||
## Web Client Scripts
|
||||
|
||||
```bash
|
||||
cd web-client
|
||||
npm run dev # Start Vite dev server (port 5173)
|
||||
npm run build # Production build to web-client/dist/
|
||||
npm run preview # Preview production build
|
||||
```
|
||||
|
||||
## Protocol
|
||||
|
||||
Communication uses JSON messages over WebSocket or Protobuf over TCP.
|
||||
|
||||
WebSocket message format:
|
||||
```json
|
||||
{"code": "CODE_GAME_MOVE", "data": "{\"row\":7,\"col\":7}", "info": ""}
|
||||
```
|
||||
|
||||
WebSocket endpoint: `ws://host:{tcp_port + 1}/ratel`
|
||||
|
||||
## Credits
|
||||
|
||||
This project is based on [Ratel](https://github.com/ainilili/ratel) by [ainilili](https://github.com/ainilili), originally a Chinese Landlords (Dou Di Zhu) card game. It has been converted to Gomoku (Five-in-a-Row) with a new web client.
|
||||
|
||||
- **Original project**: [ainilili/ratel](https://github.com/ainilili/ratel) — Netty-based multiplayer game framework
|
||||
- **Networking**: [Netty](https://netty.io/) — asynchronous event-driven network framework
|
||||
- **Web game engine**: [Phaser 3](https://phaser.io/) — HTML5 game framework
|
||||
- **Build tool**: [Vite](https://vite.dev/) — next-generation frontend tooling
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](LICENSE) file.
|
||||
Licensed under the [Apache License 2.0](LICENSE).
|
||||
@@ -0,0 +1,36 @@
|
||||
# Gomoku Web Client
|
||||
|
||||
Phaser 3 web client for the Gomoku game server.
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open `http://localhost:5173` in your browser.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js 18+
|
||||
- Game server running on `localhost:1024` (WebSocket on port `1025`)
|
||||
|
||||
## Server Connection
|
||||
|
||||
The client connects via WebSocket to `ws://localhost:1025/ratel` by default.
|
||||
To connect to a remote server, update the URL in `src/services/connection-service.js`.
|
||||
|
||||
## Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `npm run dev` | Start development server with HMR |
|
||||
| `npm run build` | Build for production (`dist/`) |
|
||||
| `npm run preview` | Preview production build locally |
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- [Phaser 3](https://phaser.io/) — HTML5 game engine
|
||||
- [Vite](https://vite.dev/) — build tool
|
||||
- Vanilla JavaScript with JSDoc annotations
|
||||
Reference in new issue
Block a user