docs/source/skin-system.rst

Система скинов
--------------

На этой странице вы найдёте информацию о самостоятельной реализации системы скинов на базе сервиса Ely.by.

Система скинов Ely.by, в отличие от других, не заменяет, а дополняет официальную, тем самым игроки с лицензией не теряют
свои скины, а игроки без лицензии смогут установить себе скин и видеть скины других игроков.

Кроме того, в основных принципах сервиса лежит соответствие официальной системе скинов: нет плащей, нет ушек, нет HD-скинов.
Это означает, что на вашем сервере не будут бегать разноцветные пугала с вырвиглазными скинами.

URL-адреса запросов
===================

Система скинов располагается по URL **http://skinsystem.ely.by**. На сервере доступно 3 основных обработчика:

.. function:: /skins/{nickname}.png

   Этот URL отвечает за загрузку скинов. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.

.. function:: /cloaks/{nickname}.png

   Этот URL отвечает за загрузку плащей. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.

   Хотя Ely.by не поддерживает пользовательскую загрузку плащей, мы оставляем за собой право устанавливать дополнительные,
   относительно официальной системы скинов, плащи. В любом случае, мы будет пользоваться теми же принципами, что и Mojang -
   плащи только за великие заслуги.

.. function:: /textures/{nickname}

   По этому URL вы можете получить текстуры для указанного в запросе **nickname**. Результатом является JSON строка, с
   meta-информацией о скине следующего формата:

   .. code-block:: javascript

      {
          'SKIN': {
              'url': 'http://example.com/skin.png',
              'hash': 'uniquehashofskin',
              'metadata': {
                  'model': 'default' /* default или slim, в зависимости от формата скина */
              }
          },
          'CAPE': {
              'url': '',
              'hash': ''
          }
      }

   *В абсолютном большинстве случаев, содержание CAPE будет именно таким, как показано выше.*

.. note:: Ник не чувствителен к регистру и внутри обработчика в любом случае приводится к нижнему регистру.

Кроме того, для всех запросов необходимо в GET параметрах передать следующие значения:

:version: Версия протокола, по которому идёт запрос на скины. На данный момент таковым является 2 протокол, т.е. вам
          нужно всегда указывать version=2.

:minecraft_version: Версия Minecraft, с которой идёт запрос. Этот параметр можно не передавать в том случае, если вы
                    передаёте параметр authlib_version.

:authlib_version: Версия authlib, с которой выполняется запрос. Этот параметр актуален для версий Minecraft 1.7.6+, когда
                  для загрузки скинов стала использоваться отдельная библиотека, а не реализация внутри игры.

                  Параметр может быть передан вместо параметра **minecraft_version**.

Если в запросе не будет параметра **version** и **minecraft_version** или **authlib_version**, сервер ответит 400
ошибкой и скин не будет загружен.

Примеры запросов
~~~~~~~~~~~~~~~~

.. code-block:: http

   http://skinsystem.ely.by/skins/erickskrauch.png?version=2&minecraft_version=1.7.2

Получает скин игрока **erickskrauch** с версии Minecraft 1.7.2.

.. code-block:: http

   http://skinsystem.ely.by/cloaks/notch?version=2&minecraft_version=1.6.4

Получает плащ игрока **notch** с версии Minecraft 1.6.4. Обратите внимание, что расширение ".png" не передано.

.. code-block:: http

   http://skinsystem.ely.by/textures/EnoTiK?version=2&authlib_version=1.5.17

Получает текстуры игрока **EnoTiK** с версии authlib 1.5.17 (версия Minecraft 1.8).

Вспомогательные адреса запросов
===============================

Кроме того, во 2 версии протокола системы скинов определены несколько специальных URL, которые проксируют трафик внутрь
основных запросов, перечисленных выше.

Ник как GET параметр
~~~~~~~~~~~~~~~~~~~~

Эти URL, в отличие от основных запросов, позволяют передать ник игрока в качестве одного из GET параметров. Такие запросы
полезены для версии Minecraft 1.5.2 и ниже, когда внутри кода игры не использовалась подстановка %s для ника, а производилась
простая конкатенация строк. Таким образом можно передать все необходимые GET параметры, указав ник последним.

.. function:: /skins/?name={nickname}.png

   Тот же запрос на скин. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.

.. function:: /cloaks/?name={nickname}.png

   Тот же запрос на плащ. Вместо параметра **nickname** необходимо передать ник игрока. Расширение .png можно опустить.

Примеры запросов:
"""""""""""""""""

.. code-block:: http

   http://skinsystem.ely.by/skins/?version=2&minecraft_version=1.5.2&name=erickskrauch.png

Получает скин игрока **erickskrauch** с версии Minecraft 1.5.2.

.. code-block:: http

   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.