From 1c60264d1d81b801340da9c2b355c1e0e13bfdf0 Mon Sep 17 00:00:00 2001
From: Smile Rex <alexander.levin@1win.pro>
Date: Thu, 15 Jan 2026 11:55:05 +0300
Subject: [PATCH] add readme

---
 readme.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..c6c7c60
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,168 @@
+# GoDot — компактная документация проекта
+
+Кратко
+- Язык реализации: Go.
+- Серверная часть через WebSocket с использованием `github.com/gorilla/websocket`.
+- Основные концепции: Hub (хаб) хранит состояние игроков, World формирует снимки мира и рассылает их всем клиентам.
+- Протокол: MSG_WELCOME, MSG_INPUT, MSG_SNAPSHOT.
+
+---
+
+## 1) Архитектура и компоненты
+
+- Client (клиент) — подключается к WebSocket по адресу /ws.
+- Hub (сервер) — управляет списком подключённых игроков, обновлениями позиций, рассылкой снимков.
+- World (сервер) — формирует снимок мира и передаёт его клиентам.
+- Connection WS Handler — принимает соединения и обрабатывает входящие сообщения.
+
+Схема взаимодействия (упрощенная)
+- Client <-> Hub <-> World
+- Hub: хранит список игроков и их состояния
+- World: собирает состояние и отправляет снимок всем клиентам
+
+Пример последовательности:
+- Клиент соединяется: ws://host:8080/ws
+- Сервер отправляет MSG_WELCOME
+- Клиент отправляет MSG_WELCOME (ID, Name)
+- Клиент периодически отправляет MSG_INPUT (X, Y)
+- Сервер раз в ~50 мс отправляет MSG_SNAPSHOT всем клиентам
+
+---
+
+## 2) Протокол и бинарная структура сообщений
+
+Общие принципы
+- Заголовок сообщения:
+  - Type: uint16
+  - Version: uint16
+  - PayloadLen: uint16
+- Payload — бинарная полезная нагрузка длинной PayloadLen.
+
+Типы сообщений
+- MSG_WELCOME = 0
+- MSG_INPUT   = 1
+- MSG_SNAPSHOT = 2
+
+Структуры полезной нагрузки
+
+- MSG_WELCOME (payload: handshake клиента)
+  - ID: uint32
+  - Name: string, кодируется как [uint16 длина][байты]
+
+- MSG_INPUT (payload: позиционные данные клиента)
+  - X: float32
+  - Y: float32
+
+- MSG_SNAPSHOT (payload: снимок мира)
+  - Count: uint16 (число игроков)
+  - Для каждого игрока:
+    - ID: uint32
+    - Type: uint8 (обычно EntityPlayer)
+    - X: float32
+    - Y: float32
+    - Z: float32
+    - Yaw: float32
+
+Примечание
+- Версия снимка в Payload зафиксирована как 1 (Version: 1).
+
+---
+
+## 3) Модели данных
+
+- Entity
+  - ID: uint32
+  - Type: EntityType (Player/NPC/Bullet)
+  - X, Y, Z, Yaw: float32
+
+- Player
+  - Включает Entity + Name и Conn (websocket.Conn)
+
+- Message
+  - Type, Version, Payload ([]byte)
+
+- Reader / Writer
+  - Быстрая бинарная сериализация/десериализация полей и строк
+
+---
+
+## 4) Основные файлы (кратко)
+
+- `GoDot/controllers/hub.go` — менеджер хаба, запуск сервера, хранение игроков.
+- `GoDot/controllers/connection.go` — чтение сообщений клиента, handshake, обработка MSG_INPUT.
+- `GoDot/controllers/world.go` — формирование и рассылка снимков (`MSG_SNAPSHOT`).
+- `GoDot/controllers/ws.go` — обработчик WebSocket-подключений.
+- `GoDot/models/message.go` — структура Message, кодирование/декодирование.
+- `GoDot/models/reader.go` и `GoDot/models/writer.go` — бинарная сериализация/десериализация.
+- `GoDot/models/player.go` — игрок, его сущность и соединение.
+- `GoDot/main.go` — точка входа, создание Hub и запуск.
+
+---
+
+## 5) Как запустить
+
+1) Установи зависимости
+   - `go mod download`
+
+2) Запусти сервер
+   - `go run main.go`
+
+3) Открой WebSocket-подключение к:
+   - ws://<адрес_хоста>:8080/ws
+
+Опционально:
+- ограничить Origin в продакшене (сейчас CheckOrigin возвращает true)
+- настроить порт через окружение (при необходимости можно добавить ENV-переменную)
+
+---
+
+## 6) Быстрая проверка простым клиентом (идея)
+
+- Подключиться к `/ws`.
+- Получить MSG_WELCOME.
+- Отправить MSG_WELCOME с Payload: [ID (uint32)][Name (uint16+bytes)].
+- Отправлять MSG_INPUT с Payload: [X (float32)][Y (float32)].
+- Ожидать MSG_SNAPSHOT от сервера каждые ~50 ms.
+
+---
+
+## 7) Mermaid-диаграмма архитектуры (в сыром виде)
+
+Mermaid диаграмма (сырой текст)
+```
+graph TD
+  Client[Client] -->|WebSocket| Hub[Hub]
+  Hub -->|Broadcast| World[World]
+  Client --> Hub
+  Hub --> Client
+```
+
+---
+
+## 8) Список файлов и их роль
+
+- `GoDot/controllers/hub.go` — менеджер хаба и запуск сервера.
+- `GoDot/controllers/connection.go` — чтение сообщений, handshake, обработка input.
+- `GoDot/controllers/world.go` — формирование и рассылка снимков.
+- `GoDot/controllers/ws.go` — обработчик WebSocket-подключений.
+- `GoDot/models/message.go` — структура Message и кодирование/декодирование.
+- `GoDot/models/reader.go` и `GoDot/models/writer.go` — бинарная сериализация/десериализация.
+- `GoDot/models/player.go` — игрок, его сущность и соединение.
+- `GoDot/models/entity.go` — базовая сущность мира.
+- `GoDot/main.go` — точка входа, создание Hub и запуск.
+
+---
+
+## 9) Примеры команд и конфигураций
+
+- Запуск сервера напрямую
+  - go run main.go
+
+- Запуск с использованием модулей
+  - go mod download
+  - go run main.go
+
+- Порт и origin
+  - В текущей конфигурации порт жестко задан как 8080, origin не фильтруется. При необходимости можно добавить ENV-переменные и ограничение origin.
+
+---