spacetris/docs/ai/cooperate_network.md

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)

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.