Skip to content

Commit 0971cab

Browse files
th33kth33k
committed
Checkpoint from VS Code for coding agent session
1 parent ca9f76c commit 0971cab

37 files changed

Lines changed: 2863 additions & 558 deletions

‎.github/workflows/copilot-instructions.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
2+
---
3+
4+
## 🧠 `copilot-instructions.md`
5+
6+
### 🎯 Project Goal
7+
8+
Develop a **web-based multiplayer game backend** using **Core Java 21 network programming concepts**.
9+
The server will handle **real-time communication** between multiple players over the network using **TCP, UDP, and NIO**, while the currently implemented frontend.
10+
The focus is entirely on the **server-side networking, concurrency, and data handling** using **pure Java** — no frameworks.
11+
12+
---
13+
14+
### 🕹️ Game Context
15+
16+
The Currently implemented multiplayer game:
17+
18+
* Real-time position updates and actions from multiple players.
19+
* Fast and reliable message delivery (TCP for reliability, UDP for speed).
20+
* Concurrent player connections and synchronization.
21+
* A server that manages player sessions, game state, and broadcasts updates.
22+
23+
---
24+
25+
### 🧩 Java Network Programming Concepts to Demonstrate
26+
27+
| Concept | Purpose in Game | Java Classes/Packages |
28+
| -------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
29+
| **TCP (ServerSocket, Socket)** | Reliable data transfer (e.g., login, game setup, chat). | `java.net.ServerSocket`, `java.net.Socket` |
30+
| **UDP (DatagramSocket, DatagramPacket)** | Fast real-time game updates (e.g., player movement, actions). | `java.net.DatagramSocket`, `java.net.DatagramPacket` |
31+
| **NIO (Channels, Buffers, Selectors)** | Non-blocking I/O for scalability with many clients. | `java.nio.channels.*`, `java.nio.ByteBuffer` |
32+
| **Multithreading (Thread, ExecutorService)** | Handle multiple player connections concurrently. | `java.util.concurrent.*`, `Thread` |
33+
| **Serialization (Object Streams)** | Transfer game state objects (e.g., player info, bullets, map updates). | `ObjectInputStream`, `ObjectOutputStream` |
34+
| **Networking Utilities (InetAddress, HttpServer)** | IP handling and optional HTTP communication (e.g., leaderboard). | `java.net.InetAddress`, `com.sun.net.httpserver.HttpServer` |
35+
| **Game Loop Timing (ScheduledExecutorService)** | Maintain consistent tick rate (e.g., 60 updates/sec). | `ScheduledExecutorService`, `Runnable` |
36+
37+
> ✅ Use **Core Java 21 only** — no Spring Boot, Netty, or external libraries.
38+
39+
---
40+
41+
### 📁 Folder Structure
42+
43+
```
44+
java-multiplayer-game/
45+
│
46+
├── server/src/
47+
│ ├── main/
48+
│ │ ├── java/
49+
│ │ │ ├── com/example/game/
50+
│ │ │ │ ├── server/
51+
│ │ │ │ │ ├── GameServer.java # Main entry for server
52+
│ │ │ │ │ ├── TcpServer.java # Handles reliable data
53+
│ │ │ │ │ ├── UdpServer.java # Handles fast real-time updates
54+
│ │ │ │ │ ├── NioServer.java # Non-blocking I/O demo
55+
│ │ │ │ │ ├── ClientHandler.java # One thread per client
56+
│ │ │ │ │ ├── GameLoop.java # Game tick controller
57+
│ │ │ │ │ ├── GameStateManager.java # Tracks all players
58+
│ │ │ │ │ └── BroadcastService.java # Sends updates to all clients
59+
│ │ │ │ │
60+
│ │ │ │ ├── client/
61+
│ │ │ │ │ ├── TcpClient.java
62+
│ │ │ │ │ ├── UdpClient.java
63+
│ │ │ │ │ ├── NioClient.java
64+
│ │ │ │ │ └── ClientInputHandler.java
65+
│ │ │ │ │
66+
│ │ │ │ ├── model/
67+
│ │ │ │ │ ├── Player.java
68+
│ │ │ │ │ ├── GameObject.java
69+
│ │ │ │ │ ├── GameAction.java
70+
│ │ │ │ │ └── Message.java
71+
│ │ │ │ │
72+
│ │ │ │ ├── util/
73+
│ │ │ │ │ ├── LoggerUtil.java
74+
│ │ │ │ │ └── NetworkUtils.java
75+
│ │ │ │ │
76+
│ │ │ │ └── Main.java
77+
│ │ │
78+
│ │ └── resources/
79+
│ │ └── config.properties
80+
│ │
81+
│ └── test/
82+
│ └── GameServerTest.java
83+
│
84+
├── client/
85+
│ ├── index.html
86+
│ ├── css/style.css
87+
│ └── js/app.js
88+
│
89+
├── README.md
90+
└── .github/
91+
└── copilot-instructions.md
92+
93+
```
94+
95+
---
96+
97+
### ⚙️ Implementation Guidelines for Copilot
98+
99+
#### 1. Programming Rules
100+
101+
* Only **Core Java 21** standard APIs.
102+
* No external dependencies or frameworks.
103+
* Use modular code and packages as shown above.
104+
105+
#### 2. Networking Requirements
106+
107+
* Implement both **TCP** (for login, chat, lobby setup) and **UDP** (for in-game position updates).
108+
* Use **multithreading** to manage each client connection.
109+
* Use **ExecutorService** or **ThreadPoolExecutor** for efficiency.
110+
* Implement **broadcasting** to send updates to all connected players.
111+
* Add **basic serialization** for transferring object data.
112+
113+
#### 3. Game Loop
114+
115+
* Create a **GameLoop.java** that runs at a fixed tick rate (e.g., 60 FPS).
116+
* Periodically updates positions, handles collisions, and sends state updates.
117+
118+
#### 4. Synchronization
119+
120+
* Use synchronized blocks or concurrent collections for shared data (e.g., `ConcurrentHashMap` for player sessions).
121+
* Prevent race conditions when multiple threads modify the game state.
122+
123+
#### 5. NIO Integration
124+
125+
* Implement a simple **NioServer.java** version that uses non-blocking channels and selectors.
126+
* Compare it with the blocking I/O TCP version.
127+
128+
#### 6. Optional HTTP Features
129+
130+
* Create a small `HttpServerExample.java` using `com.sun.net.httpserver.HttpServer` to display online players or leaderboard data in a browser.
131+
132+
#### 7. Logging and Error Handling
133+
134+
* Use `LoggerUtil.java` for standardized logs (connections, disconnections, errors).
135+
* Handle `IOException` and `SocketTimeoutException` gracefully.
136+
* Print player events and server info to console.
137+
138+
---
139+
140+
### 🧠 Concept Integration in Game Flow
141+
142+
1. **Player joins** via TCP connection → Server authenticates player.
143+
2. **UDP socket** established for real-time gameplay updates.
144+
3. **Multithreaded handlers** manage client sessions and game logic concurrently.
145+
4. **Game loop** updates positions and broadcasts state changes.
146+
5. **NIO server** demo shows how to scale non-blocking player communication.
147+
6. **Serialization** used for compact game state updates.
148+
7. **Optional HTTP server** provides game stats (leaderboard, player count).
149+
150+
---
151+
152+
### ✅ Deliverables
153+
154+
* Full Java source under `server/src/main/java/com/example/game/`
155+
* production level frontend under `/client/`
156+
* Configuration file (`config.properties`) for ports and tick rates.
157+
* This `copilot-instructions.md` and `README.md` with explanations.
158+
* updated GitHub repository with all code and instructions.
159+
---
160+
161+
### 💡 Best Practices for Copilot
162+
163+
* Use meaningful class and method names.
164+
* Write small, single-responsibility methods.
165+
* Use clear comments and JavaDoc explaining network logic.
166+
* Print server startup info (port, protocol, player connections).
167+
* Keep data formats (JSON/String/Object) consistent for client-server sync.
168+
169+
---
170+
171+
### 🔍 Example Scenarios
172+
173+
| Scenario | Java Concept | Description |
174+
| ---------------- | ----------------- | ------------------------------------------------ |
175+
| Player connects | TCP | ServerSocket accepts client connection. |
176+
| Player moves | UDP | Fast broadcast of position update. |
177+
| Game tick | Multithreading | ScheduledExecutorService updates all entities. |
178+
| Multiple clients | Thread per client | Each client runs independently. |
179+
| Leaderboard | HTTP Server | Displays game info via simple GET endpoint. |
180+
| Scaling | NIO | Non-blocking selector handles multiple channels. |
181+
182+
---

0 commit comments

Comments
 (0)