# 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.