From e7f157d0fd01063330a4fdf71b984548517aa8e5 Mon Sep 17 00:00:00 2001 From: ErickSkrauch Date: Thu, 2 May 2019 16:39:54 +0300 Subject: [PATCH] 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 * Update source/ru/skins-system.rst Co-Authored-By: erickskrauch --- source/ru/skins-system.rst | 228 +++++++++++++++++++------------------ 1 file changed, 115 insertions(+), 113 deletions(-) diff --git a/source/ru/skins-system.rst b/source/ru/skins-system.rst index 34eebe5..4f12971 100644 --- a/source/ru/skins-system.rst +++ b/source/ru/skins-system.rst @@ -1,163 +1,165 @@ Система скинов -------------- -На этой странице вы найдёте информацию о самостоятельной реализации системы скинов на базе сервиса Ely.by. +На этой странице вы найдёте информацию о доступных запросах к сервису системы скинов Ely.by. Вы можете использовать +любой из них как дополнительный или основной источник скинов для своего проекта. -Система скинов Ely.by, в отличие от других, не заменяет, а дополняет официальную, тем самым игроки с лицензией не теряют -свои скины, а игроки без лицензии смогут установить себе скин и видеть скины других игроков. +Сервис системы скинов Ely.by обеспечивает `проксирование текстур владельцев лицензии Minecraft <#skins-proxy>`_, +что означает, что при использовании этого сервиса игроки будут видеть как скины премиум пользователей Minecraft, +так и скины пользователей сервиса Ely.by. -Кроме того, в основных принципах сервиса лежит соответствие официальной системе скинов: нет плащей, нет ушек, нет HD-скинов. -Это означает, что на вашем сервере не будут бегать разноцветные пугала с вырвиглазными скинами. +Мы стремимся соответствовать официальной системе скинов и не поддерживаем ушки и HD-скины. Система поддерживает плащи, +но не позволяет игрокам самостоятельно их надевать. + +Если у вас есть предложения по развитию существующего функционала, пожалуйста, +`создайте новый Issue `_ в +`репозитории проекта Chrly `_. URL-адреса запросов =================== -Система скинов располагается по URL **http://skinsystem.ely.by**. На сервере доступно 3 основных обработчика: +.. note:: Вы можете найти более подробную информацию о реализации сервера системы скинов в + `репозитории проекта 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. + Этот запрос используется в нашем `плагине серверной системы скинов `_ для загрузки + текстур с оригинальной подписью 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 дней `_. -Кроме того, во 2 версии протокола системы скинов определены несколько специальных URL, которые проксируют трафик внутрь -основных запросов, перечисленных выше. +* Информация о текстурах обновляется не чаще + `раза в минуту `_. -Ник как GET параметр -~~~~~~~~~~~~~~~~~~~~ +Если вы владеете лицензионным аккаунтом Minecraft, но ваш ник занят, пожалуйста, обратитесь в +`службу поддержки `_ и после небольшой проверки мы передадим ник в ваше пользование. -Эти 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 `_.