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.

---