spacetris/cooperate_mode_plan.md

Spacetris — COOPERATE Mode (Two-Player Co-Op)

VS Code Copilot AI Agent Prompt

Implement a new COOPERATE play mode for Spacetris.
This is a two-player cooperative mode with a shared board and synchronized line clears.

---

1. Mode Overview

Mode Name

• COOPERATE

Core Concept

• Two players play together, not versus.
• One shared game board with double width.
• Each player is responsible for their own half of the board.
• A line clears only when BOTH halves of the same row are full.

---

2. Grid Layout

• Grid width: 20 columns
• Grid height: standard height (same as Endless/Challenge)
• Column ownership:
  • Player 1 → columns 0–9 (left half)
  • Player 2 → columns 10–19 (right half)

Visual Requirements

• Draw a vertical divider line between columns 9 and 10.
• Divider should be subtle but always visible.

---

3. Line Clear Rule (Critical)

A row clears only if:

• Player 1 half of the row is completely filled
• AND Player 2 half of the row is completely filled

If only one side is filled:

• The row does NOT clear
• Provide visual feedback:
  • Glow or pulse on the completed half
  • Optional hint on the incomplete half

---

4. Player Mechanics

Piece Streams

• Each player has their own active piece
• Each player has their own NEXT queue
• Both queues use the same RNG seed for fairness

Controls

• Player 1 controls only the left half
• Player 2 controls only the right half
• Players cannot move or rotate pieces into the other player’s half

---

5. Gravity & Timing

• Gravity applies globally (same speed for both)
• Lock delay is handled per player
• One player locking does NOT block the other player

---

6. Failure Conditions

Recommended:

• Game over occurs only when both players top out

Alternative (optional):

• If either player tops out → shared loss

---

7. Scoring System

• Score is shared
• Line clears grant:
  • Base score
  • Cooperative bonus if both halves complete simultaneously
  • Combo bonus for consecutive cooperative clears

No competitive scoring between players.

---

8. UI / HUD Requirements

• Two NEXT panels (one per player)
• Shared score display
• Shared level display
• Visual feedback for:
  • Half-filled rows
  • Successful cooperative clears

Optional:

• SYNC meter for advanced cooperative mechanics (future)

---

9. Data Model Suggestions

enum class PlayerSide {
    Left,
    Right
};

struct PlayerState {
    PlayerSide side;
    ActivePiece piece;
    bool isAlive;
};

struct Cell {
    bool occupied;
    PlayerSide owner;
};

---

10. Line Clear Algorithm (Guidance)

When checking for full rows:

1. For each row:

   • Check columns 0–9 for full (Player 1)
   • Check columns 10–19 for full (Player 2)

2. Only if both are full, mark row for clearing

3. Clear row normally and apply gravity to both halves

4. Update shared score and combos

---

11. Constraints

• COOPERATE is a separate play mode
• Do NOT reuse versus or garbage mechanics
• Focus on clarity, fairness, and readability
• Keep implementation modular (easy to expand later)

---

12. Acceptance Criteria

• Two players can play simultaneously on one board
• Each player fills only their half
• Lines clear only when both halves are filled
• Visual feedback clearly shows cooperative dependency
• Mode integrates cleanly into the main menu

---

13. Optional Future Hooks (Do Not Implement Now)

• Assist blocks
• Shared power-ups
• Cross-half interactions
• Online co-op

---

Short Summary for the Agent

Implement a two-player COOPERATE mode with a 20-column board split into two halves. Each player fills their half independently. A line clears only when both halves of the same row are full. Score, level, and progress are shared. Add clear visual feedback and a divider between player halves.