Форматируйте текст сервера Minecraft с помощью PHP

Строите сервер Minecraft на PHP? Вы столкнетесь с проблемой, которую решают все администраторы: как отобразить форматированные, цветные сообщения сервера без борьбы с кодировкой текста Minecraft. PHP-Minecraft решает эту задачу, обернув систему кодов цвета и форматирования текста Minecraft в чистые PHP-классы.

Почему вашему серверу Minecraft нужна эта библиотека

Minecraft использует нестандартную систему форматирования текста. Если вы строите серверное ПО, плагины или инструменты управления на PHP, вы работаете с текстом, использующим либо устаревшие коды цвета (эти символы, выглядящие как ничего), либо компоненты JSON. Преобразование между этими форматами или ручное применение цветов - утомительно и склонно к ошибкам.

Важно: администраторы серверов хотят красивые MOTD. Игроки ожидают цветные сообщения сервера. Ваш PHP-код не должен заставлять выбирать между «просто» и «правильно».

PHP-Minecraft обрабатывает преобразование. Позволяет работать с текстом Minecraft рационально.

С чем вы работаете

Minecraft имеет три основных формата текста, с которыми вы столкнетесь:

• Устаревшие коды цвета - формат Red §4, Blue §3. Прочитать легко, но ограничено.
• Компоненты текста JSON - новый формат Minecraft. Более мощный, но громоздкий.
• Голоса Votifier - протокол голосования сервера, требующий форматирования и передачи.

Библиотека обрабатывает Java Edition и Bedrock Edition по-разному (они используют разные палитры цветов), что является деталью, которую пропускают многие библиотеки.

Возможно, вы строите плагин голосования, монитор статуса сервера, или веб-инструмент управления сервером. Вам нужно отправлять форматированный текст игрокам, парсить JSON из сервера или обрабатывать голоса. PHP-Minecraft обрабатывает все это без необходимости понимания внутренней кодировки текста Minecraft.

Начало работы

Установка проста, если вы используете Composer:

composer require spirit55555/php-minecraft

После установки можно сразу использовать:

<?php
require 'vendor/autoload.php';
use \Spirit55555\Minecraft\MinecraftColors;

$text = '§4Red §3Blue §lBold §r';
echo MinecraftColors::convertToHTML($text);?>

Библиотека поддерживает как символ § (стандартный формат Minecraft), так и символ & (используемый в конфигурациях BungeeCord), поэтому вы работаете с тем форматом, который приходит в ваши данные.

Коды цвета и сообщения сервера

Самый частый случай использования - преобразование кодов цвета Minecraft в HTML/CSS для веб-отображения. Если вы показываете страницу статуса сервера или строите веб-панель, отображающую MOTD сервера, вы хотите, чтобы цвета отображались правильно. При настройке сервера вы можете использовать бесплатный DNS для Minecraft, чтобы управлять адресом сервера, а затем отобразить красиво отформатированное MOTD на веб-панели.

Вы можете преобразовать в чистый HTML с инлайн-стилями, использовать CSS-классы для стилизации или даже заменять переносы строк на теги `
` сразу. Выберите тот формат вывода, который подходит вашему веб-стеку.

Есть также родная поддержка формата MOTD (текст в server.properties), что полезно, если вы читаете или записываете файлы конфигурации сервера программно. Хотите программно обновить MOTD сервера? Парсите его, изменяйте и записывайте обратно с помощью того же класса. А если вы работаете с конфигурациями BungeeCord вместо этого, библиотека также это обрабатывает.

Компоненты текста JSON

Современный Minecraft использует JSON для сложного форматирования. Команды отправляют JSON обратно игрокам. Плагины генерируют JSON-текст с кликабельными ссылками и текстом на наведении.

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

И версия 2.0.1 специально исправила наследование в компонентах JSON. Это такой деталь, который важен, если вы работаете с вложенными текстовыми компонентами.

Votifier и голосование на сервере

Библиотека включает поддержку votifier для протоколов v1 (публичный ключ) и v2 (токен). Если вы управляете сервисом голосования или интегрируете голоса в ваш сервер, вы можете отправлять правильно отформатированные сообщения votifier с помощью PHP.

Библиотека сначала пробует v2, затем автоматически переключается на v1, если необходимо. Значит, вам не нужно знать, какую версию поддерживает удаленный сервер.

Советы, которые спасут от головной боли

Начните с локального тестирования. Функции преобразования - чистый PHP, поэтому вы можете экспериментировать в скрипте перед интеграцией в приложение.

Помните, что не все форматирования работают везде. Minecraft удаляет цвета в определенных контекстах (например, в книгах), а Bedrock имеет меньшую палитру цветов, чем Java Edition. Тестируйте то, что действительно нужно поддерживать.

Если вы храните форматированный текст в базе данных, рассмотрите хранение исходного формата (независимо от того, это JSON или устаревшие коды). Таким образом, вы сможете сгенерировать HTML заново, если измените стили, и не будете привязаны к одному формату вывода.

Библиотека выпущена под лицензией GPLv3, поэтому убедитесь, что лицензия вашего проекта совместима, если вы строите что-то коммерческое или проприетарное.

Когда стоит поискать альтернативу

Если вы строите игровую систему или сложную логику RPG, вам, вероятно, нужен что-то более тяжелое, например, система локализации Laravel. PHP-Minecraft предназначен специально для форматирования текста и голосования, а не для логики игры.

Для клиентской отрисовки текста Minecraft используйте JavaScript-библиотеки вместо этого. И если вам нужно парсить данные Minecraft NBT или взаимодействовать с протоколом игры, вы выходите за рамки возможностей этой библиотеки.

Но для того, что она делает, она солидна. 68 звезд на GitHub, активно поддерживается, и обрабатывает краевые случаи, которые пропускают другие библиотеки.