add readme
All checks were successful
Create and publish a Docker image 🚀 / build-and-push-image (push) Successful in 1m8s
All checks were successful
Create and publish a Docker image 🚀 / build-and-push-image (push) Successful in 1m8s
This commit is contained in:
Smile Rex
168
readme.md
Normal file
168
readme.md
Normal file
@@ -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.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user