272 lines
5.2 KiB
Markdown
272 lines
5.2 KiB
Markdown
# Spacetris — COOPERATE Mode
|
||
## Network Multiplayer (2 PLAYER – NETWORK)
|
||
### VS Code Copilot AI Agent Prompt
|
||
|
||
You are integrating **online cooperative multiplayer** into an existing **C++ / SDL3 game** called **Spacetris**.
|
||
|
||
This feature extends the existing **COOPERATE mode** to support:
|
||
- Local 2 players
|
||
- Human + AI
|
||
- **Human + Human over network (NEW)**
|
||
|
||
The networking solution must be **deterministic, lightweight, and stable**.
|
||
|
||
---
|
||
|
||
## 1. High-Level Goal
|
||
|
||
Add **COOPERATE 2 PLAYER (NETWORK)** mode where:
|
||
- Two players play together over the internet
|
||
- Each player controls one half of the shared grid
|
||
- A line clears only when both halves are filled
|
||
- Gameplay remains identical to local COOPERATE mode
|
||
|
||
---
|
||
|
||
## 2. Technology Constraints
|
||
|
||
- Language: **C++**
|
||
- Engine: **SDL3**
|
||
- Networking: **ENet (UDP with reliability)**
|
||
- No engine rewrite
|
||
- No authoritative server logic required (co-op only)
|
||
|
||
SDL3 is used ONLY for:
|
||
- Rendering
|
||
- Input
|
||
- Timing
|
||
|
||
Networking is a **separate layer**.
|
||
|
||
---
|
||
|
||
## 3. Network Model (MANDATORY)
|
||
|
||
### Use **Input Lockstep Networking**
|
||
|
||
#### Core idea:
|
||
- Both clients run the same deterministic simulation
|
||
- Only **player inputs** are sent over the network
|
||
- No board state is transmitted
|
||
- Both simulations must remain identical
|
||
|
||
This model is ideal for Tetris-like games.
|
||
|
||
---
|
||
|
||
## 4. Determinism Requirements (CRITICAL)
|
||
|
||
To ensure lockstep works:
|
||
|
||
- Fixed simulation tick (e.g. 60 Hz)
|
||
- Identical RNG seed for both clients
|
||
- Deterministic piece generation (bag system)
|
||
- No floating-point math in core gameplay
|
||
- Same gravity, rotation, lock-delay logic
|
||
- Identical line clear and scoring rules
|
||
|
||
Before networking:
|
||
- Input recording + replay must produce identical results
|
||
|
||
---
|
||
|
||
## 5. Network Topology
|
||
|
||
### Host / Client Model (Initial Implementation)
|
||
|
||
- One player hosts the game
|
||
- One player joins
|
||
- Host is authoritative for:
|
||
- RNG seed
|
||
- start tick
|
||
- game settings
|
||
|
||
This is sufficient and fair for cooperative gameplay.
|
||
|
||
---
|
||
|
||
## 6. Network Library
|
||
|
||
Use **ENet** for:
|
||
- Reliable, ordered UDP packets
|
||
- Low latency
|
||
- Simple integration with C++
|
||
|
||
Do NOT use:
|
||
- SDL_net
|
||
- TCP-only networking
|
||
- High-level matchmaking SDKs
|
||
|
||
---
|
||
|
||
## 7. Network Packet Design
|
||
|
||
### Input Packet (Minimal)
|
||
|
||
```cpp
|
||
struct InputPacket {
|
||
uint32_t tick;
|
||
uint8_t buttons; // bitmask
|
||
};
|
||
````
|
||
|
||
Button bitmask example:
|
||
|
||
* bit 0 → move left
|
||
* bit 1 → move right
|
||
* bit 2 → rotate
|
||
* bit 3 → soft drop
|
||
* bit 4 → hard drop
|
||
* bit 5 → hold
|
||
|
||
Packets must be:
|
||
|
||
* Reliable
|
||
* Ordered
|
||
* Small
|
||
|
||
---
|
||
|
||
## 8. Tick & Latency Handling
|
||
|
||
### Input Delay Buffer (RECOMMENDED)
|
||
|
||
* Add fixed delay: **4–6 ticks**
|
||
* Simulate tick `T` using inputs for `T + delay`
|
||
* Prevents stalls due to latency spikes
|
||
|
||
Strict lockstep without buffering is NOT recommended.
|
||
|
||
---
|
||
|
||
## 9. Desync Detection (IMPORTANT)
|
||
|
||
Every N ticks (e.g. once per second):
|
||
|
||
* Compute a hash of:
|
||
|
||
* Both grid halves
|
||
* Active pieces
|
||
* RNG index
|
||
* Score / lines / level
|
||
* Exchange hashes
|
||
* If mismatch:
|
||
|
||
* Log desync
|
||
* Stop game or mark session invalid
|
||
|
||
This is required for debugging and stability.
|
||
|
||
---
|
||
|
||
## 10. Network Session Architecture
|
||
|
||
Create a dedicated networking module:
|
||
|
||
```
|
||
/network
|
||
NetSession.h
|
||
NetSession.cpp
|
||
```
|
||
|
||
Responsibilities:
|
||
|
||
* ENet host/client setup
|
||
* Input packet send/receive
|
||
* Tick synchronization
|
||
* Latency buffering
|
||
* Disconnect handling
|
||
|
||
SDL main loop must NOT block on networking.
|
||
|
||
---
|
||
|
||
## 11. Integration with Existing COOPERATE Logic
|
||
|
||
* COOPERATE grid logic stays unchanged
|
||
* SyncLineRenderer remains unchanged
|
||
* Scoring logic remains unchanged
|
||
* Network layer only injects **remote inputs**
|
||
|
||
Game logic should not know whether partner is:
|
||
|
||
* Local human
|
||
* AI
|
||
* Network player
|
||
|
||
---
|
||
|
||
## 12. UI Integration (Menu Changes)
|
||
|
||
In COOPERATE selection screen, add a new button:
|
||
|
||
```
|
||
[ LOCAL CO-OP ] [ AI PARTNER ] [ 2 PLAYER (NETWORK) ]
|
||
```
|
||
|
||
### On selecting 2 PLAYER (NETWORK):
|
||
|
||
* Show:
|
||
|
||
* Host Game
|
||
* Join Game
|
||
* Display join code or IP
|
||
* Confirm connection before starting
|
||
|
||
---
|
||
|
||
## 13. Start Game Flow (Network)
|
||
|
||
1. Host creates session
|
||
2. Client connects
|
||
3. Host sends:
|
||
|
||
* RNG seed
|
||
* start tick
|
||
* game settings
|
||
4. Both wait until agreed start tick
|
||
5. Simulation begins simultaneously
|
||
|
||
---
|
||
|
||
## 14. Disconnect & Error Handling
|
||
|
||
* If connection drops:
|
||
|
||
* Pause game
|
||
* Show “Reconnecting…”
|
||
* After timeout:
|
||
|
||
* End match or switch to AI (optional)
|
||
* Never crash
|
||
* Never corrupt game state
|
||
|
||
---
|
||
|
||
## 15. What NOT to Implement
|
||
|
||
* ❌ Full state synchronization
|
||
* ❌ Prediction / rollback
|
||
* ❌ Server-authoritative gameplay
|
||
* ❌ Complex matchmaking
|
||
* ❌ Versus mechanics
|
||
|
||
This is cooperative, not competitive.
|
||
|
||
---
|
||
|
||
## 16. Acceptance Criteria
|
||
|
||
* Two players can complete COOPERATE mode over network
|
||
* Gameplay matches local COOPERATE exactly
|
||
* No noticeable input lag under normal latency
|
||
* Desync detection works
|
||
* Offline / disconnect handled gracefully
|
||
* SDL3 render loop remains smooth
|
||
|
||
---
|
||
|
||
## 17. Summary for Copilot
|
||
|
||
Integrate networked cooperative multiplayer into Spacetris using SDL3 + C++ with ENet. Implement input lockstep networking with deterministic simulation, fixed tick rate, input buffering, and desync detection. Add a new COOPERATE menu option “2 PLAYER (NETWORK)” that allows host/join flow. Networking must be modular, non-blocking, and transparent to existing gameplay logic.
|