Blackijecky - Intro to Nets 2025 Hackathon
==========================================

Team Name: CreativeTeamName
Submitted Files:
  1. server.py       - The Game Server (Dealer)
  2. client.py       - The Standard CLI Client
  3. client_gui.py   - The Graphical Interface Client (Bonus)
  4. protocol.py     - Shared Protocol Logic (Packet Formats)
  5. back.png        - (Optional) Background image for GUI

----------------------------------------------------------------------
HOW TO RUN
----------------------------------------------------------------------

1. Start the Server (The Dealer)
   -----------------------------
   Run the server in a terminal window. It will listen for TCP connections
   and broadcast UDP offers automatically.
   
   Command:
   $ python3 server.py

   * To stop the server, press Ctrl+C.

2. Start the CLI Client (Standard Text Interface)
   ----------------------------------------------
   Run this in a separate terminal. It will listen for UDP offers,
   connect to the server, and let you play via the command line.
   
   Command:
   $ python3 client.py

3. Start the GUI Client (Graphical Interface)
   ------------------------------------------
   For a better visual experience, run the GUI version. It features
   real-time updates, thread-safe rendering, and dark mode support.
   
   Command:
   $ python3 client_gui.py

   * Note: You need Tkinter installed (standard on most Python installs).
   * Note: If 'back.png' is missing, it falls back to a dark gray theme.

----------------------------------------------------------------------
HOW IT WORKS (Architecture Description)
----------------------------------------------------------------------

A. Connection Phase (Discovery)
   - The Server broadcasts UDP 'Offer' packets (Type 0x2) every second 
     to port 13122 containing its TCP port.
   - The Client listens on UDP port 13122. When it receives an offer, 
     it extracts the server's IP and TCP port.
   - The Client establishes a TCP connection to the Server.

B. Game Logic (The Protocol)
   1. Request: The Client sends a TCP 'Request' packet (Type 0x3) 
      specifying the number of rounds.
   2. Dealing: The Server deals cards. It sends 3 'Payload' packets 
      (Type 0x4): Player Card 1, Player Card 2, Dealer Card 1.
   3. Player Turn: 
      - Client sends "Hittt" or "Stand" via Payload packets.
      - Server responds with a new card (if Hit) or proceeds to dealer turn.
      - If Player busts (>21), Server immediately sends a Result=2 (Loss) 
        packet along with the busting card.
   4. Dealer Turn: 
      - Server reveals the hidden card.
      - Dealer hits until sum >= 17.
   5. Result: Server calculates the winner and sends a final Payload 
      packet with the result code (Win=3, Loss=2, Tie=1).

C. Robustness Features
   - Threading: The Server handles multiple clients simultaneously using 
     threading. The GUI Client uses threading to keep the interface 
     responsive while waiting for network packets.
   - Fragmentation: Both Client and Server use a helper function 
     `_recv_all` to handle TCP stream fragmentation, ensuring packets 
     are never corrupted or cut off.
   - Race Conditions: The Server combines the "Card" and "Result" into 
     a single packet when a player busts to prevent synchronization errors.

----------------------------------------------------------------------
REQUIREMENTS MET
----------------------------------------------------------------------
[x] Client and Server run forever until manually stopped.
[x] Supports multi-client execution (SO_REUSEPORT).
[x] Strict adherence to binary protocol (Magic Cookie, Endianness).
[x] "Fun to read" output (ANSI colors in CLI, Dark Mode in GUI).
[x] Robust error handling for network disconnects.