Minecraft/mc-protocol
Archived
0
Fork 0
Code Activity

первые страницы документации к протоколу

Browse Source
This commit is contained in:
DmitriyMX
2020-08-19 04:00:19 +03:00
parent 2b125fe1a0
commit 36e9d0f68f
18 changed files with 513 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
README.MD Normal file
View File

@@ -0,0 +1,16 @@
# mc-protocol
![version: 0.0](https://img.shields.io/badge/version-0.0-0a0.svg?style=flat)
![support protocol: 1.8](https://img.shields.io/badge/support_protocol-1.8-222.svg?style=flat)
## Build
```shell script
gradle build
```
### Build documentation
```shell script
gradle sphinx
```

137
src/docs/_static/server_info.schema.json vendored Normal file
View File

@@ -0,0 +1,137 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"version": {
"description": "Описание версии протокола",
"type": "object",
"properties": {
"name": {
"description": "Название версии",
"type": "string",
"examples": [
"1.8.7"
]
},
"protocol": {
"description": "Номер версии",
"type": "number",
"examples": [
47
]
}
},
"required": [
"name",
"protocol"
]
},
"players": {
"description": "Информация о слотах и игроках",
"type": "object",
"properties": {
"max": {
"description": "Максимальное количество мест",
"type": "number",
"examples": [
20
]
},
"online": {
"description": "Количество игроков на сервере",
"type": "number",
"examples": [
5
]
},
"sample": {
"description": "Список некоторых игроков, что сейчас присутствуют на сервере",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Имя игрока",
"type": "string",
"examples": [
"Notch"
]
},
"id": {
"description": "UUID игрока",
"type": "string",
"pattern": "[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}",
"examples": [
"00000000-0000-0000-0000-000000000000"
]
}
},
"required": [
"name",
"id"
]
}
}
},
"required": [
"max",
"online"
]
},
"description": {
"$id": "#/properties/description",
"description": "Описание сервера (motd)",
"type": [
"object",
"string"
],
"properties": {
"text": {
"type": "string"
},
"bold": {
"type": ["boolean", "string"],
"pattern": "true|false"
},
"italic": {
"type": ["boolean", "string"],
"pattern": "true|false"
},
"underlined": {
"type": ["boolean", "string"],
"pattern": "true|false"
},
"strikethrough": {
"type": ["boolean", "string"],
"pattern": "true|false"
},
"obfuscated": {
"type": ["boolean", "string"],
"pattern": "true|false"
},
"color": {
"type": "string",
"pattern": "(dark_)?(blue|green|aqua|red|gray)|(dark|light)_purple|black|gold|yellow|white|[klmnor]"
},
"extra": {
"type": "array",
"items": {
"$ref": "#/properties/description"
}
}
},
"required": [
"text"
]
},
"favicon": {
"description": "Иконка сервера в формате base64",
"type": "string",
"pattern": "data:image/png;base64,.+"
}
},
"required": [
"version",
"players"
]
}

30
src/docs/_static/style.css vendored Normal file
View File

@@ -0,0 +1,30 @@
/* https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs */
.wy-nav-content {
max-width: none;
}
.wy-side-nav-search {
background-color: #ECD304;
}
.wy-side-nav-search > a, .wy-side-nav-search .wy-dropdown > a {
color: #535252;
}
.wy-side-nav-search > div.version {
color: rgba(0, 0, 0, 0.3);
}
.rst-content .line-block {
margin-bottom: 0;
}
.row-odd .line-block,
.row-even .line-block {
margin-bottom: 0;
}
.row-odd th.head p,
.row-even th.head p {
margin-bottom: 0;
}

5
src/docs/_templates/layout.html vendored Normal file
View File

@@ -0,0 +1,5 @@
<!-- https://stackoverflow.com/questions/23211695/modifying-content-width-of-the-sphinx-theme-read-the-docs -->
{% extends "!layout.html" %}
{% block extrahead %}
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}

50
src/docs/conf.py
View File

@@ -1,34 +1,34 @@
# -*- coding: utf-8 -*-
import sys, os
from recommonmark.parser import CommonMarkParser
import sphinx_rtd_theme
import os
project = u'My Project'
copyright = u'YYYY, John Doe'
version = '1.0'
release = '1.0.0'
project = u'mc-protocol'
copyright = u'2020, DmitriyMX'
version = '0.0'
release = '0.1.0'
# General options
needs_sphinx = '1.0'
master_doc = 'index'
pygments_style = 'tango'
add_function_parentheses = True
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.plantuml']
extensions = [
'sphinx.ext.autodoc',
'sphinx_rtd_theme',
'sphinxcontrib.plantuml',
]
templates_path = ['_templates']
exclude_trees = ['.build']
source_suffix = ['.rst', '.md']
source_encoding = 'utf-8-sig'
source_parsers = {
'.md': CommonMarkParser
}
# HTML options
html_theme = 'sphinx_rtd_theme'
html_short_title = "my-project"
htmlhelp_basename = 'my-project-doc'
html_use_index = True
html_show_sourcelink = False
html_static_path = ['_static']
# Source options
source_encoding = 'utf-8-sig'
source_suffix = ['.rst']
# PlantUML options
plantuml = os.getenv('plantuml')
plantuml_output_format = 'svg'
# HTML options
html_theme = 'sphinx_rtd_theme'
html_use_index = True
html_show_sourcelink = False
html_static_path = ['_static']
html_theme_options = {
'collapse_navigation': False,
'sticky_navigation': True
}

61
src/docs/data_types.rst Normal file
View File

@@ -0,0 +1,61 @@
Типы данных
===========
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Тип | Размер (в байтах) | Кодирование | Коментарий |
+================+===================+=====================================================+================================================================================+
| Boolean | 1 | True или False | True = ``0x01``; False = ``0x00`` |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Byte | 1 | Число от -128 до 127 | 8-bit число со знаком |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Unsigned Byte | 1 | Число от 0 до 255 | 8-bit без знаковое число |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Short | 2 | Число от -32768 до 32767 | 16-bit число со знаком |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Unsigned Short | 2 | Число от 0 до 65535 | 16-bit без знаковое число |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Int | 4 | Число от -2147483648 и 2147483647 | 32-bit число со знаком |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Long | 8 | Число от -9223372036854775808 и 9223372036854775807 | 64-bit число со знаком |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Float | 4 | 32-bit число одинарной точности (IEEE 754-2008) | |Single-precision floating-point format| |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Double | 8 | 64-bit число одинарной точности (IEEE 754-2008) | |Double-precision floating-point format| |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| String (n) | | >= 1 | Последовательность Unicode scalar values | | В начале пишется длина строки в **VarInt**, после чего записываются символы. |
| | | <= (n * 4) + 3 | | | Каждый символ может состоять |максимум из 4 байт|. |
| | | | | Максимальная длина строки - 32767 (``3`` в колонке Размер - это как раз |
| | | | размер **VarInt** для этого числа). |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| Text | | >= 1 | JSON, закодированный как String | |wiki.vg:Chat| |
| | | <= (n * 4) + 3 | | |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| VarInt | | >= 1 | Число от -2147483648 и 2147483647 | 32-bit число с плавающей размерностью от 1 до 5 байт |
| | | <= 5 | | |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
| VarLong | | >= 1 | Число от -9223372036854775808 и 9223372036854775807 | 64-bit число с плавающей размерностью от 1 до 10 байт |
| | | <= 10 | | |
+----------------+-------------------+-----------------------------------------------------+--------------------------------------------------------------------------------+
.. |Single-precision floating-point format| raw:: html
<a href="https://en.wikipedia.org/wiki/Single-precision_floating-point_format" target="_blank">Single-precision floating-point format</a>
.. |Double-precision floating-point format| raw:: html
<a href="https://en.wikipedia.org/wiki/Double-precision_floating-point_format" target="_blank">Double-precision floating-point format</a>
.. |максимум из 4 байт| raw:: html
<a href="http://unicode.org/glossary/#unicode_scalar_value" target="_blank">максимум из 4 байт</a>
.. |wiki.vg:Chat| raw:: html
<a href="https://wiki.vg/index.php?title=Chat&oldid=8329" target="_blank">wiki.vg:Chat</a>
.. |wiki.vg:Data types| raw:: html
<a href="https://wiki.vg/index.php?title=Protocol&oldid=7368#Data_types" target="_blank">wiki.vg:Data types</a>

33
src/docs/index.rst
View File

@@ -1,27 +1,10 @@
Это заголовок
=============
Заголовок содержит главную тему и отделяется символами '='.
Их количество должно быть не меньше, чем количество символов
в заголовке.
Сетевой протокол Minecraft 1.8
==============================
Подзаголовок
------------
Подзаголовки отделяются символами '-'. Их количество должно
быть тем же, что и количество символов в подзаголовке
(так же, как и в случае с заголовками).
.. toctree::
:maxdepth: 4
Списки могут быть маркированными:
* Элемент Foo
* Элемент Bar
Или же автоматически пронумерованными:
#. Элемент 1
#. Элемент 2
Внутренняя разметка
------------––––––-
Слова можно выделять *наклонным* или **полужирным** шрифтами.
Фрагменты кода (например, примеры команд) можно заключать в обратные кавычки, например:
команда ``sudo`` дает вам привилегии суперпользователя!
data_types
packet_format
packets
protocol_schema

39
src/docs/packet_format.rst Normal file
View File

@@ -0,0 +1,39 @@
Формат пакетов
==============
+-------------+--------+----------------------------------------------------------------+
| Название | Тип | Коментарии |
+=============+========+================================================================+
| SIZE | VarInt | | Общий размер пакета в байтах. |
| | | | Вычисляется как: ``sizeOf(packet_id) + sizeOf(packet_data)`` |
+-------------+--------+----------------------------------------------------------------+
| PACKET ID | VarInt | Идентификатор пакета |
+-------------+--------+----------------------------------------------------------------+
| PACKET DATA | bytes | Данные/Полезная нагрузка |
+-------------+--------+----------------------------------------------------------------+
Пример
------
Пакет **DisconnectPacket**
.. code-block:: none
+-------------------------------------------------+
| 0 1 2 3 4 5 6 7 8 9 a b c d e f |
+--------+-------------------------------------------------+----------------+
|00000000| 2c 00 2a 22 59 6f 75 20 61 72 65 20 6e 6f 74 20 |,.*"You are not |
|00000010| 77 68 69 74 65 2d 6c 69 73 74 65 64 20 6f 6e 20 |white-listed on |
|00000020| 74 68 69 73 20 73 65 72 76 65 72 21 22 |this server!" |
+--------+-------------------------------------------------+----------------+
+-------------+-----------+--------------------------------------------------------------+
| SIZE | PACKET ID | PACKET DATA |
| | +--------------------------------------------------------------+
| | | Поле: Reason (тип **Text** в виде **String**) |
| | +----------------------------+---------------------------------+
| | | Длинна строки (**VarInt**) | Сама *"строка"* |
+-------------+-----------+----------------------------+---------------------------------+
| ``2c`` = 44 | ``00`` | ``2a`` = 42 | ``22 59 6f 75 ... 65 72 21 22`` |
+-------------+-----------+----------------------------+---------------------------------+

7
src/docs/packets.rst Normal file
View File

@@ -0,0 +1,7 @@
Список пакетов
==============
.. toctree::
packets_clientside
packets_serverside

58
src/docs/packets_clientside.rst Normal file
View File

@@ -0,0 +1,58 @@
От Клиента к Серверу
====================
HANDSHAKING
-----------
HandshakePacket
^^^^^^^^^^^^^^^
Основная задача пакета: указать серверу на какой **State** нужно переключиться.
+------------------+----------------+----------------------------------------------+
| Поле | Тип | Коментарий |
+==================+================+==============================================+
| Protocol version | VarInt | |Версия протокола| |
+------------------+----------------+----------------------------------------------+
| Server address | Stirng | Hostname или IP |
+------------------+----------------+----------------------------------------------+
| Server port | Unsigned Short | Порт сервера |
+------------------+----------------+----------------------------------------------+
| Next stage | VarInt | ID State на который необходимо переключиться |
+------------------+----------------+----------------------------------------------+
STATUS
------
StatusServerRequest
^^^^^^^^^^^^^^^^^^^
Запрос информации о сервере.
Пакет не содержит никаких данных.
PingPacket
^^^^^^^^^^
| Формат точно такой же как и у :ref:`PingPacket от Сервера к Клиенту <serverside_pingpacket>`.
| Клиент должен вернуть Серверу данный пакет "как есть", без изменений.
LOGIN
-----
LoginStartPacket
^^^^^^^^^^^^^^^^
Запуск авторизации.
+------+--------+------------------+
| Поле | Тип | Коментарий |
+======+========+==================+
| Name | String | Имя/Логин игрока |
+------+--------+------------------+
.. |Версия протокола| raw:: html
<a href="https://wiki.vg/Protocol_version_numbers" target="_blank">Версия протокола</a>

75
src/docs/packets_serverside.rst Normal file
View File

@@ -0,0 +1,75 @@
От Сервера к Клиенту
====================
STATUS
------
StatusServerResponse
^^^^^^^^^^^^^^^^^^^^
Информация о Сервере.
+-------------+--------+-------------------------------------+
| Поле | Тип | Коментарий |
+=============+========+=====================================+
| Server info | String | Информация о сервере в JSON формате |
+-------------+--------+-------------------------------------+
В поле *Server info* находится JSON объект следующего вида:
.. code-block:: json
{
"version": {
"name": "1.8.7",
"protocol": 47
},
"players": {
"max": 20,
"online": 5,
"sample": [
{
"name": "Notch",
"id": "00000000-0000-0000-0000-000000000000"
}
]
},
"description": {
"text": "Hello world"
},
"favicon": "data:image/png;base64,<data>"
}
Подробнее: :download:`JSON Schema <_static/server_info.schema.json>`
PingPacket
^^^^^^^^^^
.. _serverside_pingpacket:
Пакет для обмена "пингом".
+---------+------+-------------+
| Поле | Тип | Коментарий |
+=========+======+=============+
| Payload | Long | Любое число |
+---------+------+-------------+
.. note::
| "Ванильный" сервер в *Payload* указывает текущее время в формате unixstamp.
| Но по факту в данное поле можно указать любое число: клиент всё равно обязан вернуть данный пакет "как есть".
LOGIN
-----
DisconnectPacket
^^^^^^^^^^^^^^^^
Отключение клиента сервером с указанием причины.
+--------+------+----------------------------------+
| Поле | Тип | Коментарий |
+========+======+==================================+
| Reason | Text | Причина отключения. Опционально. |
+--------+------+----------------------------------+

29
src/docs/protocol_schema.rst Normal file
View File

@@ -0,0 +1,29 @@
Схемы работы протокола
======================
Получение информации о Сервере
------------------------------
.. uml::
CLIENT --\ SERVER: Подключение
CLIENT -> SERVER: **HandshakePacket** с указанием "Next state" = STATUS
CLIENT -> SERVER: **StatusServerRequest**
CLIENT <- SERVER: **StatusServerResponse**
CLIENT -> SERVER: **PingPacket** (ping)
CLIENT <- SERVER: **PingPacket** (pong)
CLIENT \-- SERVER: Разрыв соединения
Вход на сервер
--------------
Неудачный вход / Доступ закрыт
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. uml::
CLIENT --\ SERVER: Подключение
CLIENT -> SERVER: **HandshakePacket** с указанием "Next state" = LOGIN
CLIENT -> SERVER: **LoginStartPacket**
CLIENT <- SERVER: **DisconnectPacket**
CLIENT \-- SERVER: Разрыв соединения

4
src/main/java/mc/protocol/handshake/client/HandshakePacket.java
View File

@@ -11,7 +11,7 @@ import mc.protocol.io.NetOutputStream;
*
* <p>Данный пакет заставляет сервер переключить текущий {@link State}</p>
*
* <p>Структура пакета
* <p>Структура пакета</p>
* <pre>
* | FIELD | TYPE | NOTES |
* |------------------|----------------|----------------------------------------------|
@@ -21,7 +21,7 @@ import mc.protocol.io.NetOutputStream;
* | Next stage | VarInt | ID State на который необходимо переключиться |
*
* [1] - <a href="https://wiki.vg/Protocol_version_numbers" target="_top">Protocol version numbers</a>
* </pre></p>
* </pre>
*
* @see <a href="https://wiki.vg/index.php?title=Protocol&oldid=7368#Handshake" target="_top">Handshake</a>
* @see State

2
src/main/java/mc/protocol/io/package-info.java
View File

@@ -7,7 +7,7 @@ Data types
| Byte | 1 | Число от -128 до 127 | 8-bit число со знаком |
| Unsigned Byte | 1 | Число от 0 до 255 | 8-bit без знаковое число |
| Short | 2 | Число от -32768 до 32767 | 16-bit число со знаком |
| Unsigned Short | 2 | Число от -32768 до 32767 | 16-bit без знаковое число |
| Unsigned Short | 2 | Число от 0 до 65535 | 16-bit без знаковое число |
| Int | 4 | Число от -2147483648 и 2147483647 | 32-bit число со знаком |
| Long | 8 | Число от -9223372036854775808 и 9223372036854775807 | 64-bit число со знаком |
| Float | 4 | 32-bit число одинарной точности (IEEE 754-2008) | [1] |

4
src/main/java/mc/protocol/login/client/LoginStartPacket.java
View File

@@ -11,12 +11,12 @@ import mc.protocol.io.NetOutputStream;
*
* <p>Начало авторизации.</p>
*
* <p>Структура пакета
* <p>Структура пакета</p>
* <pre>
* | FIELD | TYPE | NOTES |
* |-------|--------|------------------|
* | Name | String | Имя/Логин игрока |
* </pre></p>
* </pre>
*
* @see <a href="https://wiki.vg/index.php?title=Protocol&oldid=7368#Login_Start" target="_top">Login start</a>
* @see State

4
src/main/java/mc/protocol/login/server/DisconnectPacket.java
View File

@@ -14,12 +14,12 @@ import mc.protocol.utils.json.JsonUtils;
*
* <p>Отключение клиента сервером с указанием причины.</p>
*
* <p>Структура пакета
* <p>Структура пакета</p>
* <pre>
* | FIELD | TYPE | NOTES |
* |--------|------|----------------------------------|
* | Reason | Text | Причина отключения. Опционально. |
* </pre></p>
* </pre>
*
* @see <a href="https://wiki.vg/index.php?title=Protocol&oldid=7368#Login_Start" target="_top">Login start</a>
* @see State

14
src/main/java/mc/protocol/status/PingPacket.java
View File

@@ -5,6 +5,20 @@ import mc.protocol.Packet;
import mc.protocol.io.NetInputStream;
import mc.protocol.io.NetOutputStream;
/**
* Пинг.
*
* <p>Пакет для обмена "пингом".</p>
*
* <p>Структура пакета</p>
* <pre>
* | FIELD | TYPE | NOTES |
* |---------|------|-------------|
* | Payload | Long | Любое число |
* </pre>
*
* @see <a href="https://wiki.vg/index.php?title=Protocol&oldid=7368#Ping" target="_top">Ping</a>
*/
@Data
public class PingPacket implements Packet {

4
src/main/java/mc/protocol/status/server/StatusServerResponse.java
View File

@@ -12,14 +12,14 @@ import mc.protocol.utils.json.JsonUtils;
*
* <p>Информация о сервере</p>
*
* <p>Структура пакета
* <p>Структура пакета</p>
* <pre>
* | FIELD | TYPE | NOTES |
* |---------------|--------|-----------------------------------------|
* | JSON Response | String | Информация о сервере в JSON формате [1] |
*
* [1] - <a href="https://wiki.vg/index.php?title=Server_List_Ping&oldid=7555#Response" target="_top">Server List Ping: Response</a>
* </pre></p>
* </pre>
*/
@Data
public class StatusServerResponse implements Packet {