ProxLib

ProxLib

ProxLib — это библиотека, которая обеспечивает связь между игроками в Minecraft на основе близости. Она позволяет находящимся рядом игрокам напрямую обмениваться данными друг с другом через сервер, при этом серверу не нужно устанавливать какие-либо моды или плагины для передачи этих данных.

Обзор

ProxLib лежит в основе [ProxChat] и может использоваться другими модами для реализации функций связи на основе близости. Она предоставляет простой API для отправки и получения пакетов данных между игроками, находящимися в пределах примерно 26 блоков друг от друга.

Библиотека работает, хитроумно кодируя данные в существующую систему пакетов Minecraft через пакеты действия разрушения блока (только отмены), которые передаются всем находящимся рядом игрокам без проверки сервером (да, работает и по воздуху!).

Как это работает

• Способ связи: Использует PlayerActionC2SPacket с действием ABORT_DESTROY_BLOCK
• Кодирование данных: Данные кодируются в относительные позиции блоков вокруг игрока
• Радиус: Примерно 26 блоков (технически ограничен 32-блочной передачей пакетов действий в Minecraft)

• Ёмкость данных: 9 бит на пакет Minecraft

  • Перед отправляемыми данными добавляются 2 пакета Minecraft в качестве магии (чтобы распознать его как Prox Packet), 2 байта для Vendor и Packet Id, а также 3 байта для длины пакета.
  • Так, если вы отправите пакет с 4 байтами данных, это превратится в 2 + (2 + 2 + 3 + 4) * (8 / 9) » 11.77 » 12 пакетов Minecraft

• Надёжность: Работает практически на всех серверах, включая серверы с анти-читом

  • Учтите, что анти-читы могут расценить это как спам пакетами или какую-то странную попытку нюка. Это может привести к тому, что игрока пометят как читера.
  • Мои тесты в основном проводились на 2b2t. Анти-чит не блокировал ни один из пакетов, не кикал меня, но недавнее обновление вызывает лагбэк при отправке данных и движении (данные всё равно отправляются нормально).
  • Перестаёт работать, когда вы находитесь ближе ~6 блоков к нижнему и верхнему вертикальному пределу строительства (и, возможно, рядом с границей мира)
  • Работает даже когда отправляющий игрок в креативном режиме!

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

Установка

Для пользователей модов

ProxLib — это библиотечный мод, и его следует устанавливать вместе с модами, которые от него зависят.

Моды могут включать эту библиотеку в себя, так что вы можете даже не знать о её наличии, если не заглянете в раздел Libraries в игровом меню модов.

Для разработчиков модов

Добавьте ProxLib как зависимость в ваш build.gradle:

exclusiveContent {
    forRepository {
        maven {
            name = "Modrinth"
            url = "https://api.modrinth.com/maven"
        }
    }
    filter {
        includeGroup "maven.modrinth"
    }
}

dependencies {
    // Например, для версии MC 1.21.4 (убедитесь, что проверяете, какая версия самая свежая).
    // Уберите "include", если не хотите встраивать этот мод напрямую в свой (сейчас <30 КиБ).
    include modApi("maven.modrinth:proxlib:0.2.4+1.21")
}

В `fabric.mod.json` добавь:

```json
"depends": {
    "proxlib": ">=0.2.0"
}

Сборка

Если хочешь собрать этот мод, учти:

• Проект использует Stonecutter для одновременной сборки нескольких версий
• Не запускай задачу build, вместо неё используй chiseledBuild (в категории project)
• Подробности смотри в их документации

Версионирование

В целом я стараюсь придерживаться SemVer (MAJOR.MINOR.PATCH).

Библиотека пока не достигла 1.0.0, так что идеальной стабильности ждать не стоит. Впрочем, она может так и не дойти до 1.0.0, а текущие версии при этом вполне стабильны.

Особенно для класса ProxLib я постараюсь никогда не ломать совместимость существующих публичных методов. Если всё же придётся — подниму MINOR-версию. Впрочем, MINOR-версию я могу поднять и просто из-за большого количества новых фич, так что это не обязательно означает ломающие изменения.

Список изменений смотри в релизах на GitHub или в changelog на Modrinth.

Совместимость протокола

Протокол я зафиксировал ещё в первом релизе ProxChat в январе 2024 года и с тех пор не менял.

Моя цель — никогда не ломать совместимость. То же самое стараюсь делать и со своими пакетами.

Единственное изменение на данный момент:

• ID (u16) был разделён на 10-битный Vendor ID и 6-битный Packet ID. Это не ломающее изменение, но меняет то, как следует интерпретировать ID.

Использование разработчиками

ID пакетов

Пакеты идентифицируются 2-байтовым id, который делится на:

• 10 бит: Vendor ID (от 0 до 1023)
• 6 бит: Packet ID (от 0 до 63)

Так что если хочешь сделать свои пакеты, следует:

• Выбрать собственный Vendor ID. Лучше сгенерировать его генератором случайных чисел — этот ID будет использовать твой мод.
• Затем просто начать нумеровать пакеты

Пример:

final int VENDOR_ID = 932; // Сгенерировано генератором случайных чисел
final ProxPacketIdentifier AWESOME_PACKET_ID = ProxPacketIdentifier.of(VENDOR_ID, 0);
final ProxPacketIdentifier ANOTHER_PACKET_ID = ProxPacketIdentifier.of(VENDOR_ID, 1);

Отправка и приём пакетов

Все нужные методы легко вызываются из класса ProxLib.

Пример отправки

public void sendAwesomePacket(String message) throws IOException {
  // Создаём данные для пакета (byte[])
  ByteArrayOutputStream bytesOut = new ByteArrayOutputStream();
  DataOutputStream dataOut = new DataOutputStream(bytesOut);
  dataOut.writeByte(1); // Тип
  dataOut.writeUTF(message);

  // Отправляем пакет
  int packets = ProxLib.sendPacket(MinecraftClient.getInstance(), AWESOME_PACKET_ID, bytesOut.toByteArray());
  LOGGER.info("Отправил свой крутой пакет, использовав {} пакетов!", packets);
}

Пример приёма

public class MyAwesomeMod implements ClientModInitializer {

  @Override
  public void onInitializeClient() {
    ProxLib.addHandlerFor(AWESOME_PACKET_ID, (sender, identifier, data) -> {
      try {
        DataInputStream dataIn = new DataInputStream(new ByteArrayInputStream(data));
        int type = dataIn.readUnsignedByte(1);
        if(type == 1) {
            String message = dataIn.readUTF();
            // Делаем что-то с message...
        }else {
            LOGGER.warn("Получен неподдерживаемый тип в моём крутом пакете: {}", type);
        }
      } catch (IOException ex) {
        LOGGER.error("Не удалось обработать мой крутой пакет!", ex);
      }
    });
    ProxLib.addHandlerFor(ANOTHER_PACKET_ID, (sender, identifier, data) -> {
      // ...
    });
  }

}

### Известные ID пакетов:

| Мод         | Vendor ID | Packet ID |  Название        | Описание                                                                          | Ссылка           |
|-------------|-----------|-----------|------------------|-----------------------------------------------------------------------------------|------------------|
| [ProxChat]  | 0         | 1         | Chat             | Простое сообщение в чате (набери `% <msg>` с модом).                              | [PC-Chat]        |
| [ProxChat]  | 0         | 2         | PatPat-PatEntity | Поглаживание кого-то (устаревшее)                                                 | [PC-Pat]         |
| [ProxChat]  | 0         | 3         | EmoteCraft       | Воспроизвести / повторить / остановить свои эмоции                                | [PC-Emote]       |
| [ProxChat]  | 0         | 4         | TextDisplay      | Показать другим один или несколько настраиваемых текстовых блоков (набери `%% <msg>` с модом). | [PC-TextDisplay] |
| [PatPat]    | 2         | 0         | Pat              | Поглаживание кого-то                                                              | [PP-Pat]         |


Примечание: у ProxChat Vendor ID равен 0, потому что на тот момент ID ещё не разделялся на Vendor/Packet ID (и эта библиотека была частью ProxChat). Так что использовались номера начиная с 1, что фактически соответствует Vendor ID 0, и это сохранено для обратной совместимости со старыми версиями ProxChat.


## Интеграция с другими языками

[ItzN00bPvP](https://github.com/ItzN00bPvP) разработал базовую библиотеку для **Rust**, совместимую с этой (crates.io: [proxchat](https://crates.io/crates/proxchat), репозиторий: [proxchat-rs](https://github.com/ItzN00bPvP/proxchat-rs)). Так что это удобно, если ты хочешь, чтобы твой, например, [azalea](https://github.com/azalea-rs/azalea)-бот отправлял сообщения ProxChat.


## Благодарности

Разработано EnderKill98, основа была случайно найдена вместе с [ItzN00bPvP](https://github.com/ItzN00bPvP) при изучении логов его собственных N00bBots. Без него этого бы не существовало!