ElyBy-Mirror
/
docs
mirror of https://github.com/elyby/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update skins system docs (#1) 

* Draft rewrite of skins system docs

* Second draft of skins system docs rewrite

* Final version of the article

* Apply suggestions from code review

Co-Authored-By: erickskrauch <erickskrauch@ely.by>

* Update source/ru/skins-system.rst

Co-Authored-By: erickskrauch <erickskrauch@ely.by>
This commit is contained in:
ErickSkrauch 2019-05-02 16:39:54 +03:00 committed by GitHub
parent ebbe82351a
commit e7f157d0fd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 115 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
source/ru/skins-system.rst
View File

@ -1,163 +1,165 @@
Система скинов
--------------
На этой странице вы найдёте информацию о самостоятельной реализации системы скинов на базе сервиса Ely.by.
На этой странице вы найдёте информацию о доступных запросах к сервису системы скинов Ely.by. Вы можете использовать
любой из них как дополнительный или основной источник скинов для своего проекта.
Система скинов Ely.by, в отличие от других, не заменяет, а дополняет официальную, тем самым игроки с лицензией не теряют
свои скины, а игроки без лицензии смогут установить себе скин и видеть скины других игроков.
Сервис системы скинов Ely.by обеспечивает `проксирование текстур владельцев лицензии Minecraft <#skins-proxy>`_,
что означает, что при использовании этого сервиса игроки будут видеть как скины премиум пользователей Minecraft,
так и скины пользователей сервиса Ely.by.
Кроме того, в основных принципах сервиса лежит соответствие официальной системе скинов: нет плащей, нет ушек, нет HD-скинов.
Это означает, что на вашем сервере не будут бегать разноцветные пугала с вырвиглазными скинами.
Мы стремимся соответствовать официальной системе скинов и не поддерживаем ушки и HD-скины. Система поддерживает плащи,
но не позволяет игрокам самостоятельно их надевать.
Если у вас есть предложения по развитию существующего функционала, пожалуйста,
`создайте новый Issue <https://github.com/elyby/chrly/issues/new>`_ в
`репозитории проекта Chrly <https://github.com/elyby/chrly>`_.
URL-адреса запросов
===================
Система скинов располагается по URL **http://skinsystem.ely.by**. На сервере доступно 3 основных обработчика:
.. note:: Вы можете найти более подробную информацию о реализации сервера системы скинов в
`репозитории проекта Chrly <https://github.com/elyby/chrly>`_.
Система скинов размещена на домене :samp:`http://skinsystem.ely.by`. Параметр :samp:`nickname` не
чувствителен к регистру.
Для получения информации о текстурах используются следующие обработчики:
.. _skin-request:
.. function:: /skins/{nickname}.png
Этот URL отвечает за загрузку скинов. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
Этот URL отвечает за загрузку скинов. В качестве параметра **nickname** необходимо передать ник игрока.
Расширение :samp:`.png` можно опустить.
Если текстуры не будут найдены, сервер вернёт ответ с :samp:`404` статусом.
.. _cape-request:
.. function:: /cloaks/{nickname}.png
Этот URL отвечает за загрузку плащей. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
Этот URL отвечает за загрузку плащей. В качестве параметра **nickname** необходимо передать ник игрока.
Расширение :samp:`.png` можно опустить.
Хотя Ely.by не поддерживает пользовательскую загрузку плащей, мы оставляем за собой право устанавливать дополнительные,
относительно официальной системы скинов, плащи. В любом случае, мы будет пользоваться теми же принципами, что и Mojang -
плащи только за великие заслуги.
Если текстуры не будут найдены, сервер вернёт ответ с :samp:`404` статусом.
.. function:: /textures/{nickname}
По этому URL вы можете получить текстуры для указанного в запросе **nickname**. Результатом является JSON строка, с
meta-информацией о скине следующего формата:
По этому URL вы можете получить текстуры для указанного в запросе **nickname**. Результатом является документ JSON
следующего формата:
.. code-block:: javascript
{
'SKIN': {
'url': 'http://example.com/skin.png',
'hash': 'uniquehashofskin',
'metadata': {
'model': 'default' /* default или slim, в зависимости от формата скина */
}
},
'CAPE': {
'url': '',
'hash': ''
"SKIN": {
"url": "http://example.com/skin.png",
"metadata": {
"model": "slim"
}
},
"CAPE": {
"url": "http://example.com/cape.png"
}
}
*В абсолютном большинстве случаев, содержание CAPE будет именно таким, как показано выше.*
В зависимости от доступных игроку текстур могут отсутствовать поля :samp:`SKIN` или :samp:`CAPE`.
Если модель скина не является :samp:`slim`, то поле :samp:`metadata` также будет отсутствовать.
.. note:: Ник не чувствителен к регистру и внутри обработчика в любом случае приводится к нижнему регистру.
Если текстуры не будут найдены, сервер вернёт пустой ответ с :samp:`204` статусом.
Кроме того, для всех запросов необходимо в GET параметрах передать следующие значения:
.. function:: /textures/signed/{nickname}
:version: Версия протокола, по которому идёт запрос на скины. На данный момент таковым является 2 протокол, т.е. вам
нужно всегда указывать version=2.
Этот запрос используется в нашем `плагине серверной системы скинов <http://ely.by/server-skins-system>`_ для загрузки
текстур с оригинальной подписью Mojang. Полученные в ответе текстуры могут быть без изменений переданы в
немодифицированный игровой клиент. В ответе также будет присутсвовать дополнительное property с :samp:`name`
равным **ely**.
:minecraft_version: Версия Minecraft, с которой идёт запрос. Этот параметр можно не передавать в том случае, если вы
передаёте параметр authlib_version.
.. code-block:: javascript
:authlib_version: Версия authlib, с которой выполняется запрос. Этот параметр актуален для версий Minecraft 1.7.6+, когда
для загрузки скинов стала использоваться отдельная библиотека, а не реализация внутри игры.
{
"id": "ffc8fdc95824509e8a57c99b940fb996",
"name": "ErickSkrauch",
"properties": [
{
"name": "textures",
"signature": "QH+1rlQJYk8tW+8WlSJnzxZZUL5RIkeOO33dq84cgNoxwCkzL95Zy5pbPMFhoiMXXablqXeqyNRZDQa+OewgDBSZxm0BmkNmwdTLzCPHgnlNYhwbO4sirg3hKjCZ82ORZ2q7VP2NQIwNvc3befiCakhDlMWUuhjxe7p/HKNtmKA7a/JjzmzwW7BWMv8b88ZaQaMaAc7puFQcu2E54G2Zk2kyv3T1Bm7bV4m7ymbL8McOmQc6Ph7C95/EyqIK1a5gRBUHPEFIEj0I06YKTHsCRFU1U/hJpk98xXHzHuULJobpajqYXuVJ8QEVgF8k8dn9VkS8BMbXcjzfbb6JJ36v7YIV6Rlt75wwTk2wr3C3P0ij55y0iXth1HjwcEKsg54n83d9w8yQbkUCiTpMbOqxTEOOS7G2O0ZDBJDXAKQ4n5qCiCXKZ4febv4+dWVQtgfZHnpGJUD3KdduDKslMePnECOXMjGSAOQou//yze2EkL2rBpJtAAiOtvBlm/aWnDZpij5cQk+pWmeHWZIf0LSSlsYRUWRDk/VKBvUTEAO9fqOxWqmSgQRUY2Ea56u0ZsBb4vEa1UY6mlJj3+PNZaWu5aP2E9Unh0DIawV96eW8eFQgenlNXHMmXd4aOra4sz2eeOnY53JnJP+eVE4cB1hlq8RA2mnwTtcy3lahzZonOWc=",
"value": "eyJ0aW1lc3RhbXAiOjE0ODYzMzcyNTQ4NzIsInByb2ZpbGVJZCI6ImM0ZjFlNTZmNjFkMTQwYTc4YzMyOGQ5MTY2ZWVmOWU3IiwicHJvZmlsZU5hbWUiOiJXaHlZb3VSZWFkVGhpcyIsInRleHR1cmVzIjp7IlNLSU4iOnsidXJsIjoiaHR0cDovL3RleHR1cmVzLm1pbmVjcmFmdC5uZXQvdGV4dHVyZS83Mzk1NmE4ZTY0ZWU2ZDhlYzY1NmFkYmI0NDA0ZjhlYmZmMzQxMWIwY2I5MGIzMWNiNDc2ZWNiOTk2ZDNiOCJ9fX0="
},
{
"name": "ely",
"value": "but why are you asking?"
}
]
}
Параметр может быть передан вместо параметра **minecraft_version**.
По умолчанию для этого запроса не применяется проксирование текстур. Чтобы его включить, добавьте дополнительный
GET параметр :samp:`?proxy=true`.
Если в запросе не будет параметра **version** и **minecraft_version** или **authlib_version**, сервер ответит 400
ошибкой и скин не будет загружен.
Если текстуры не будут найдены, сервер вернёт пустой ответ с :samp:`204` статусом.
Примеры запросов
~~~~~~~~~~~~~~~~
------------------------------------------------------------------------------------------------------------------------
При совершении любого из вышеописанных запросов вы также можете передать ряд дополнительных GET параметров. Они будут
использованы для анализа использования сервиса разными версиями игры.
:version: Версия протокола, по которому идёт запрос на скины. На данный момент это версия :samp:`2` ,
т.е. вам необходимо указать :samp:`version=2`.
:minecraft_version: Версия Minecraft, с которой идёт запрос.
:authlib_version: Версия используемой Authlib. Этот параметр актуален для версий Minecraft 1.7.6+, где
для загрузки скинов стала использоваться отдельная библиотека, а не внутриигровой код.
Пример запроса текстур с передачей вышеописанных параметров:
.. code-block:: text
http://skinsystem.ely.by/skins/erickskrauch.png?version=2&minecraft_version=1.7.2
http://skinsystem.ely.by/textures/erickskrauch?version=2&minecraft_version=1.14.0&authlib_version=1.5.25
Получает скин игрока **erickskrauch** с версии Minecraft 1.7.2.
Вспомогательные URL
===================
Также запрос скина и плаща можно выполнить, передавая ник через GET параметр. Эта возможность используется для
передачи аналитических параметров в версиях игры до 1.5.2, когда ник просто добавлялся в конец строки. Для этого вся
строка выстраивается таким образом, чтобы последним параметром шёл :samp:`name`, после добавления ника к которому
получался полный запрос на текстуру.
.. function:: /skins?name={nickname}.png
Смотрите `запрос на получение скина <#skin-request>`_.
.. function:: /cloaks?name={nickname}.png
Смотрите `запрос на получение плаща <#cape-request>`_.
Пример запросов на текстуры с передачей параметров выше:
.. code-block:: text
http://skinsystem.ely.by/cloaks/notch?version=2&minecraft_version=1.6.4
http://skinsystem.ely.by/skins?version=2&minecraft_version=1.5.2&name=erickskrauch.png
http://skinsystem.ely.by/cloaks?version=2&minecraft_version=1.4.7&name=notch
Получает плащ игрока **notch** с версии Minecraft 1.6.4. Обратите внимание, что расширение ".png" не передано.
.. _skins-proxy:
.. code-block:: text
Проксирование скинов
====================
http://skinsystem.ely.by/textures/EnoTiK?version=2&authlib_version=1.5.17
Сервис системы скинов Ely.by получает текстуры из официальной системы скинов в случае, если в базе данных не было
найдено информации о текстурах для запрошенного имени пользователя. Также запрос будет проксирован, если запись о скине
будет найдена, но он будет стандартным.
Получает текстуры игрока **EnoTiK** с версии authlib 1.5.17 (версия Minecraft 1.8).
Для улучшения пропускной способности проксирующего алгоритма, информация о текстурах кешируется в 2 стадии:
Вспомогательные адреса запросов
===============================
* Соответствие ника и UUID хранится в
`течение 30 дней <https://help.mojang.com/customer/portal/articles/928638#targetText=How%20often%20can%20I%20change%20my%20username%3F>`_.
Кроме того, во 2 версии протокола системы скинов определены несколько специальных URL, которые проксируют трафик внутрь
основных запросов, перечисленных выше.
* Информация о текстурах обновляется не чаще
`раза в минуту <https://wiki.vg/Mojang_API#UUID_-.3E_Profile_.2B_Skin.2FCape>`_.
Ник как GET параметр
~~~~~~~~~~~~~~~~~~~~
Если вы владеете лицензионным аккаунтом Minecraft, но ваш ник занят, пожалуйста, обратитесь в
`службу поддержки <http://ely.by/site/contact>`_ и после небольшой проверки мы передадим ник в ваше пользование.
Эти URL, в отличие от основных запросов, позволяют передать ник игрока в качестве одного из GET параметров. Такие запросы
полезены для версии Minecraft 1.5.2 и ниже, когда внутри кода игры не использовалась подстановка %s для ника, а производилась
простая конкатенация строк. Таким образом можно передать все необходимые GET параметры, указав ник последним.
Готовые реализации
==================
.. function:: /skins/?name={nickname}.png
Тот же запрос на скин. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
.. function:: /cloaks/?name={nickname}.png
Тот же запрос на плащ. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.
Примеры запросов:
"""""""""""""""""
.. code-block:: text
http://skinsystem.ely.by/skins/?version=2&minecraft_version=1.5.2&name=erickskrauch.png
Получает скин игрока **erickskrauch** с версии Minecraft 1.5.2.
.. code-block:: text
http://skinsystem.ely.by/cloaks/?version=2&minecraft_version=1.4.7&name=notch
Получает плащ игрока **notch** с версии Minecraft 1.4.7. Обратите внимание, что расширение ".png" не передано.
Старый формат запроса
~~~~~~~~~~~~~~~~~~~~~
В 1 версии протокола системы скинов применялся другой способ загрузки скинов. Все запросы шли по URL
**http://ely.by/minecraft.php** и все данные передавались через GET параметры.
На данный момент любой запрос, выполненный на вышеуказанный URL приведёт к 301 редиректу на
**http://skinsystem.ely.by/minecraft.php**, где запрос будет проксирован на основные запросы.
Этот запрос является fallback роутом, применяемым для обратной совместимости с 1 версией и не рекомендуется для
использования в новых проектах. Тем не менее, он должен быть описан, так как применятся и будет достаточно долго применяться
в связи с долгосрочным переходом на 2 версию протокола системы скинов.
1 версия системы скинов (deprecated)
====================================
.. warning:: Информация в этом разделе является устаревшей и приведена здесь только ради создания иллюзии крутого развития
проекта. В любом случае вы **не должны** использовать этот протокол, т.к. в один момент он окончательно перестанет
работать.
На старте проекта применялся URL для загрузки скинов **http://ely.by/minecraft.php**, в который через GET параметры
передавались данные. Сейчас этот URL является устаревшим и планомерно выводится из обращения в пользу 2 версии протокола.
.. function:: /minecraft.php
Параметры, передаваемые в этот запрос:
:name: Имя игрока без учёта регистра и без расширения **.png**.
:type: Тип запрашиваемых данных. Возможные значения: skin и cloack. Изначально была допущена ошибка, из-за которой
запрос на плащи шёл с значением cloack, вместо cloak. Увы, это так и останется в истории проекта.
:mine_ver: Версия Minecraft. Точки в версии должны были быть заменены на прочерки, т.е. 1.7.2 должно было быть передано
как 1_7_2. Хотя могло работать и с точками :)
:ver: Версия протокола. Обычно передавалось значение 1_0_0, которое, в принципе, ни на что не влияло, но тем не менее
передавалось. Сейчас применяется для идентификации запроса, проксируемого с 1 версии во 2.
Готовые реализации патчей и инструкции по их установке могут быть найдены в
`разделе загрузок на главном сайте Ely.by <http://ely.by/load>`_.