Local Multiplayer

Welcome to the Local Multiplayer! This Java-based project with a client-server communication framework, designed for local multiplayer applications. It includes a Vector3F class for 3D vector operations, a Server for handling multiple client connections, a Client for sending and receiving messages (including vectors), a NetworkOutput utility for network communication, and an App class for testing the entire system.

Overview

• Vector3F: A class representing a 3D vector with float coordinates, supporting operations like addition, subtraction, scaling, dot product, cross product, rotation, normalization, and serialization for network transmission.
• Server: A multi-threaded server that listens on port 8080, handles client connections, sends ACK responses, and broadcasts messages to all connected clients.
• Client: A client that connects to the server, sends messages and vectors, receives responses (including broadcasts), and supports automatic reconnection.
• NetworkOutput: A utility class (formerly Input) for sending UTF-8 strings and serialized Vector3F objects over a socket.
• App: A test application that demonstrates all functionalities, including edge cases and integration tests.

This project serves as a foundation for local multiplayer games or networked simulations.

Features

• Vector3F:
  • Basic operations: addition, subtraction, scaling, dot product, cross product.
  • Advanced operations: rotation around an axis, normalization with edge case handling.
  • Serialization/deserialization for network use.
• Server:
  • Multi-threaded client handling with a dedicated thread per connection.
  • Graceful shutdown with resource cleanup.
  • Broadcast functionality to send messages to all clients.
• Client:
  • Automatic reconnection with up to 3 attempts.
  • Asynchronous message reception (including ACKs and broadcasts).
  • Support for sending Vector3F objects.
• NetworkOutput:
  • Efficient sending of strings and vectors.
  • Buffered output with flush control.
• App:
  • Comprehensive tests for Vector3F (including zero vector and rotation).
  • Integration tests for client-server communication with multiple clients and vectors.

Prerequisites

• Java Development Kit (JDK): Version 8 or higher.
• Build Tool: Any Java-compatible IDE (e.g., IntelliJ IDEA, Eclipse, VSCode) or command-line tools (e.g., javac, java).

Installation

1. Clone the Repository: Ensure you have Git installed, then clone the project (or copy the files manually):

   git clone git@github.com:gabriel-aplok/local-multiplayer-java.git
   cd local-multiplayer-java

2. Compile the Code: Use the following command to compile all .java files in the mplocal package:

   javac mplocal/*.java

3. Run the Application: Execute the App class to run all tests:

   java mplocal.App

Usage

Running the Project

• Start the application by running App.java. This will:

  • Test Vector3F operations (e.g., addition, rotation).
  • Start a server on port 8080.
  • Launch three client instances, each sending a message and a Vector3F object.
  • Demonstrate broadcast messages and graceful shutdown.

• Example output will include vector calculations, client connections, and received messages (e.g., ACKs and broadcasts).

Customizing the Code

• Modify Vector3F: Add new vector operations or adjust the serialization format.
• Adjust Server Settings: Change the port (currently 8080) in Server.java by modifying the ServerSocket constructor.
• Extend Client Behavior: Add more messages or vectors in Client.main or create a loop for continuous sending.
• Enhance Tests: Update App.java to include more edge cases or stress tests.

Tutorial

Step-by-Step Guide

1. Understand the Vector3F Class:

   • Create a vector: Vector3F v1 = new Vector3F(1.0f, 2.0f, 3.0f);
   • Perform operations: Vector3F sum = v1.add(new Vector3F(4.0f, 5.0f, 6.0f));
   • Rotate it: Vector3F rotated = v1.rotate(new Vector3F(0, 1, 0).normalize(), (float) Math.toRadians(90));
   • Serialize it: Use v1.writeTo(new DataOutputStream(socket.getOutputStream()));

2. Set Up the Server:

   • Instantiate and start: Server server = new Server(); server.start();
   • Stop it manually: server.stop(); (useful for testing).
   • The server will handle clients and broadcast messages automatically.

3. Configure a Client:

   • Create and start: Client client = new Client(); client.start();
   • Send a message: client.sendMessage("Hello Server");
   • Send a vector: client.sendVector(new Vector3F(1.0f, 2.0f, 3.0f));
   • Stop it: client.stop();

4. Test with App:

   • Run App.java to see all features in action.
   • Observe the console output for vector operations, client-server communication, and broadcasts.
   • Modify testVector3F or testServerClient to add custom test cases.

Example Output

Starting application tests...
=== Starting Vector3F Tests ===
Vector v1: Vector3F(x=1.00, y=2.00, z=3.00)
Vector v2: Vector3F(x=4.00, y=5.00, z=6.00)
Addition (v1 + v2): Vector3F(x=5.00, y=7.00, z=9.00)
Subtraction (v1 - v2): Vector3F(x=-3.00, y=-3.00, z=-3.00)
Scaling (v1 * 2): Vector3F(x=2.00, y=4.00, z=6.00)
Dot product (v1.v2): 32.0
Cross product (v1 x v2): Vector3F(x=-3.00, y=6.00, z=-3.00)
Magnitude of v1: 3.74
Normalized v1: Vector3F(x=0.27, y=0.53, z=0.80)
Normalized zero vector: Vector3F(x=0.00, y=0.00, z=0.00)
Rotation of v1 around (0,1,0) by 90 degrees: Vector3F(x=3.00, y=2.00, z=-1.00)
v1 equals v3: true
v1 equals v2: false

=== Starting Server and Client Tests ===
Starting server...
Server started on port 8080, awaiting client connections...
New client connected from 127.0.0.1
Successfully connected to server at localhost:8080
Sent message to server: Message from Client #1 to server
[32mReceived message from client 127.0.0.1: Message from Client #1 to server[0m
Received from server: ACK: Message received successfully
Sent vector to server: Vector3F(x=1.00, y=2.00, z=3.00)
[32mReceived message from client 127.0.0.1: <binary Vector3F data>[0m
Received from server: ACK: Message received successfully
... (similar for Client #2 and #3, with broadcasts)
Client 127.0.0.1 disconnected
Output stream closed
Connection to server closed
Server shut down
All tests completed successfully.

Contributing

Feel free to contribute by submitting pull requests or issues. Suggested improvements include:

• Adding more vector operations (e.g., angle between vectors).
• Implementing a message protocol (e.g., JSON) for the server.
• Enhancing client with a callback interface for received messages.
• Adding stress tests in App.java.

License

This project is open-source and available under the MIT License. See the LICENSE file for details (if applicable).