Connections

A Java client-server implementation of the Connections word puzzle game, inspired by the NYT Connections game.

Players are shown 16 words and must group them into 4 categories of 4 words each, where each category shares a common theme.

---

Table of Contents

• Features
• Project Structure
• Architecture
• Prerequisites
• Configuration
• How to Run
• Gameplay
• Available Commands (Client CLI)

---

Features

• User Management: Register, login, logout and update credentials.
• Multiplayer: Multiple clients can connect concurrently to the same server instance.
• Timed Matches: Each game has a configurable duration (default: 2 minutes).
• Word Grouping: Submit a proposal of 4 words; the server validates whether they belong to the same category.
• Game History: Query info and statistics for past games.
• Leaderboard: View the global leaderboard or look up your own rank.
• Player Statistics: View detailed stats for any player.
• Real-time Notifications: UDP multicast notifies all connected clients when a game time expires.
• Persistence: User data and game archives are automatically saved to JSON files.

---

Project Structure

The project is built using a Gradle Multi-Project structure, separating the client, server, and shared resources for better modularity and dependency management.

Connections/
├── build.gradle                # Global Gradle build configuration
├── settings.gradle             # Gradle multi-project settings
├── gradle.properties           # Gradle properties (hides Gradle logs from CLI)
├── gradlew / gradlew.bat       # Gradle Wrapper scripts
├── config/                     # Configuration files
│   ├── client.properties
│   └── server.properties
├── data/                       # JSON datasets and persistence files
│   ├── Connections_Data.json
│   ├── gameArchive.json
│   └── users.json
├── shared/                     # SHARED MODULE (Models and DTOs)
│   ├── build.gradle
│   └── src/main/java/shared/
│       ├── Response.java
│       ├── requests/           # Client-to-Server request models
│       └── models/             # Shared game models (Status, Player stats, etc.)
├── client/                     # CLIENT MODULE
│   ├── build.gradle
│   └── src/main/java/client/
│       ├── ClientMain.java
│       └── UdpNotificationReceiver.java
└── server/                     # SERVER MODULE
    ├── build.gradle
    └── src/main/java/server/
        ├── ServerMain.java
        ├── TerminationHandler.java
        ├── UdpNotificationService.java
        ├── Worker.java
        ├── UserGameState.java
        ├── game/               # Game logic and session management
        └── user/               # User persistence and logic

---

Architecture

The application follows a classic client-server model:

• Transport: TCP (via Java NIO SocketChannel) for reliable request/response communication.
• Notifications: UDP multicast for broadcasting game-end events to all connected clients simultaneously.
• Concurrency: The server uses a cached thread pool (ExecutorService) — each client connection is handled by a dedicated Worker thread.
• Serialization: All messages are serialized/deserialized as JSON using Google Gson.
• Persistence: User data is saved periodically (every minute) and on graceful shutdown; the game archive is updated at the end of each game.

---

Prerequisites

• Java 17 or later
• You do not need to install Gradle manually or download any .jar files. The included Gradle Wrapper (gradlew) will automatically download the correct Gradle version and all required dependencies (like Gson).

---

Configuration

config/server.properties

Property	Default	Description
hostname	localhost	Server hostname
tcpPort	12345	TCP port the server listens on
bufSize	8192	Size of the server-side read/write buffer (bytes)
maxDelay	50	Max seconds to wait for threads on shutdown
gameDurationMinutes	2	Duration of a single game round (minutes)
multicastAddress	230.0.0.1	Multicast group address for UDP notifications
multicastPort	54321	UDP multicast port

config/client.properties

Property	Default	Description
hostname	localhost	Server hostname to connect to
tcpPort	12345	Server TCP port
multicastAddress	230.0.0.1	Multicast group address to join for notifications
multicastPort	54321	UDP multicast port
bufSize	1024	Size of the client-side read/write buffer (bytes)

---

How to Run

Thanks to the Gradle Wrapper, running the project is incredibly simple from the root directory. You do not need to install Gradle manually.

Note for Linux / macOS users: If you get a "Permission denied" error when running ./gradlew, you may need to make the script executable first by running:

chmod +x gradlew

1. Start the Server

Open a terminal in the project root and run:

Linux / macOS:

./gradlew :server:run

Windows:

gradlew.bat :server:run 

2. Start the Client

Open a new terminal window in the project root and run:

Linux / macOS:

./gradlew :client:run 

Windows:

gradlew.bat :client:run 

3. Build Executable JARs (Optional)

If you want to compile the project into standalone executable .jar files, run:

./gradlew build

The compiled files will be generated in:

• server/build/libs/
• client/build/libs/

---

Gameplay

1. Register or Login with your credentials.
2. Once a game is active, select Submit Proposal and enter 4 words you believe share a common theme.
3. The server validates your proposal:
   • Correct — the group and its theme are revealed.
   • Malformed — you don't have 4 valid words from the current board (no penalty).
   • Wrong — you lose a life (maximum 4 errors per game).
4. Complete all 4 groups before the timer runs out to win.
5. When the game ends, all connected clients receive a UDP multicast notification.

---

Available Commands (Client CLI)

When not logged in

Option	Action
1	Register
2	Update Credentials
3	Login

When logged in

Option	Action
1	Logout
2	Submit Proposal
3	Request Game Info
4	Request Game Stats
5	Request Leaderboard
6	Request Player Stats

For Game Info and Game Stats, enter -1 to refer to the current active game, or a specific game ID for historical data. For Leaderboard, leave the player name empty to see the global top-N ranking (you will be prompted for the number of players to display), or enter a username to see their rank.