Java WebSocket Room Manager

A lightweight, reusable Java module for building real-time multiplayer and room-based applications using WebSockets.

This project demonstrates how to design a room-based architecture, manage live sessions, and build real-time features such as chat systems and multiplayer games.

This project provides reusable room and session management components for:

• multiplayer turn-based games
• chat rooms
• collaborative real-time applications
• live event systems

It is framework-agnostic at the room-management level and can be integrated into a Java WebSocket server implementation.

Related Architecture

This project is based on the ludoworld multiplayer architecture:

👉 https://github.com/mkkaliel/ludoworld-multiplayer-architecture

The architecture repository explains the system design, message flow, and server-authoritative model behind this implementation.

Features

• Room-based session management
• Real-time message broadcasting
• WebSocket endpoint integration
• Clean separation of engine vs application logic
• Embedded server for easy local testing
• Runnable browser demos

Why this project exists

Many real-time applications need a simple way to manage users inside rooms without rewriting the same room lifecycle logic.

This module separates:

• player session tracking
• room membership
• room broadcasting
• room cleanup

from the application-specific game or chat rules.

Example Use Cases

• turn-based multiplayer games
• WebSocket chat servers
• collaborative editing tools
• quiz / trivia rooms
• live classroom groups

Package Structure

• PlayerSession – represents a connected user
• Room – stores room members and room-level operations
• RoomManager – creates, joins, leaves, and removes rooms
• RoomEventListener – optional event hook interface
• MessageRouter – helper for routing room-scoped messages

Basic Usage

RoomManager roomManager = new RoomManager();

PlayerSession alice = new PlayerSession("s1", "u1", "Alice", null);
PlayerSession bob = new PlayerSession("s2", "u2", "Bob", null);

roomManager.createRoom("room-1");
roomManager.joinRoom("room-1", alice);
roomManager.joinRoom("room-1", bob);

roomManager.broadcastToRoom("room-1", "Hello room!");

Local Run

Step 1 — Open terminal in project folder

Step 2 — Start the embedded Tomcat server with one command:

mvn compile exec:java

Step 3 — Open browser

then open:

• Simple chat: http://localhost:8080/simple-chat/
• Tic-tac-toe: http://localhost:8080/tic-tac-toe/

To test the reusable room endpoint directly, open test-client.html in your browser while the embedded server is running.

The test client connects to:

ws://localhost:8080/ws/room?roomId=room1&playerId=user1&playerName=Alice

Use the form fields in test-client.html to set:

• roomId - the room to create or join
• playerId - the unique player/user ID
• playerName - the display name broadcast to the room

Open the same file in two browser tabs with different playerId and playerName values to verify room broadcasts between clients.

The examples/ directory remains as lightweight documentation/discoverability, while the runnable static assets live under src/main/webapp/ for embedded Tomcat startup.

Examples

Simple Chat

A minimal WebSocket broadcast demo.

• Browser asset: src/main/webapp/simple-chat/index.html
• URL when running locally: http://localhost:8080/simple-chat/
• WebSocket endpoint: ws://localhost:8080/chat

---

Tic Tac Toe Multiplayer

A real-time turn-based multiplayer game.

• Browser assets: src/main/webapp/tic-tac-toe/index.html and src/main/webapp/tic-tac-toe/game.js
• URL when running locally: http://localhost:8080/tic-tac-toe/
• WebSocket endpoint: ws://localhost:8080/tictactoe

Design Philosophy

This project is designed to be:

• small and understandable
• easy to extend
• framework-independent
• suitable for real-time systems

The core room manager is intentionally generic so it can be reused across:

• multiplayer games
• chat systems
• collaboration tools
• live classrooms

Future Improvements

You can extend this system with:

• authentication
• room capacity limits
• room metadata support
• private/public room visibility
• distributed room coordination adapters
• matchmaking
• persistence (database)
• distributed scaling (Redis, Kafka)
• pluggable serializers
• heartbeat / idle timeout helpers
• replay systems
• analytics and metrics

🤖 AI-Assisted Development

This repository is designed to work well with AI tools.

Developers can adapt it using prompts like:

"Add matchmaking to this room manager" "Convert this into a chat moderation system" "Add team-based multiplayer support"

Notes

This project intentionally does not include:

• game rules
• monetization logic
• persistence/database code
• authentication
• product-specific business logic

It is intended to be used as a reusable building block inside a larger real-time application.

License

MIT