# 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.

---