mirror of
https://github.com/elyby/docs.git
synced 2024-12-23 05:29:57 +05:30
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
GitHub
parent
ebbe82351a
commit
e7f157d0fd
@ -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>`_.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user