From c0a7cadf7ecc564836d793b8590236443963239c Mon Sep 17 00:00:00 2001
From: Jona Walpert <jona.walpert@stud.unibas.ch>
Date: Tue, 21 Apr 2026 20:40:52 +0200
Subject: [PATCH] docs: add highscore protocol commands (Issue #110)

---
 .../networking/commands/protocol-document.md  | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/documents/docs/networking/commands/protocol-document.md b/documents/docs/networking/commands/protocol-document.md
index e909057..f267047 100644
--- a/documents/docs/networking/commands/protocol-document.md
+++ b/documents/docs/networking/commands/protocol-document.md
@@ -70,6 +70,18 @@ This document describes the protocol for client-server communication in our appl
     - [Success Response](#success-response)
     - [Example Request](#example-request)
     - [Example Response](#example-response)
+  - [GET_HIGHSCORES command](#get_highscores-command)
+    - [Required pre-execution checks](#required-pre-execution-checks)
+    - [Request Parameters](#request-parameters)
+    - [Success Response](#success-response)
+    - [Example Request](#example-request)
+    - [Example Response](#example-response)
+  - [CLEAR_HIGHSCORES command](#clear_highscores-command)
+    - [Required pre-execution checks](#required-pre-execution-checks)
+    - [Request Parameters](#request-parameters)
+    - [Success Response](#success-response)
+    - [Example Request](#example-request)
+    - [Example Response](#example-response)
   - [RAISE command](#raise-command)
   - [CALL command](#call-command)
   - [FOLD command](#fold-command)
@@ -1338,3 +1350,71 @@ END
   MESSAGE=Maximum number of 8 lobbies reached
 END
 ```
+
+## GET_HIGHSCORES command
+
+The `GET_HIGHSCORES` command returns the stored highscore list. The server sends a `HIGHSCORES` block containing repeated `HIGHSCORE` fields. Each entry is already formatted as `timestamp | winner name`.
+
+### Required pre-execution checks
+
+None.
+
+### Request Parameters
+
+No parameters.
+
+### Success Response
+
+| Field        | Type                    | Description                              |
+| :----------- | :---------------------- | :--------------------------------------- |
+| `HIGHSCORES` | `Collection<Highscore>` | Collection of formatted highscore lines. |
+
+| Fields of `Highscore` | Type     | Description                                         |
+| :-------------------- | :------- | :-------------------------------------------------- |
+| `HIGHSCORE`           | `String` | One formatted entry in `yyyy-MM-dd HH:mm:ss | name` |
+
+### Example Request
+
+```
+GET_HIGHSCORES
+```
+
+### Example Response
+
+```
++OK
+  HIGHSCORES
+    HIGHSCORE='2026-04-21 15:19:23 | Jona'
+    HIGHSCORE='2026-04-21 16:02:11 | Lars'
+  END
+END
+```
+
+## CLEAR_HIGHSCORES command
+
+The `CLEAR_HIGHSCORES` command deletes all stored highscore entries on the server.
+
+### Required pre-execution checks
+
+None.
+
+### Request Parameters
+
+No parameters.
+
+### Success Response
+
+No response fields.
+
+### Example Request
+
+```
+CLEAR_HIGHSCORES
+```
+
+### Example Response
+
+```
++OK
+END
+```
-- 
2.52.0