Flight API

Модификация Flight API предоставляет универсальную систему управления полётом для Minecraft, созданную для устранения конфликтов между различными модами, которые взаимодействуют с механикой полёта игрока.

Что решает эта библиотека

Проблема возникает, когда несколько модов одновременно пытаются управлять состоянием полёта игрока, обращаясь напрямую к настройкам player.getAbilities().flying и player.getAbilities().allowFlying. Это приводит к нестабильному поведению — игрок может внезапно падать на землю или полностью терять возможность летать из-за постоянного переключения параметров разными модами.

Flight API внедряет систему управления полётом на основе очереди запросов, которая обеспечивает предсказуемую работу полёта даже при использовании множества модификаций.

Основные возможности

• Система управления полётом через очередь: Разработана для корректного распределения контроля между модами, перехватывая изменения состояний allowFlying и flying.
• Простая диагностика проблем: Включено логирование, которое помогает игрокам определять конфликты между модами и автоматически решать проблемы совместимости. Особенно полезно при отладке больших сборок модов, где сложно выявить конкретный источник проблем с полётом.

Инструкция для игроков

Просто поместите файл .jar в папку mods — библиотека сразу готова к работе. Если вы столкнётесь с проблемами полёта, файл debug.log из папки logs поможет разработчикам выявить причину неисправности, так как Flight API фиксирует информацию о проблемных модах.

Руководство для разработчиков

Принцип работы

В стандартном Minecraft и большинстве модов логика полёта выглядит примерно так:

player.getAbilities().flying = true;
player.getAbilities().allowFlying = true;

Когда несколько модов используют такой подход одновременно, состояние полёта игрока начинает хаотично меняться.

Flight API предотвращает это через следующие механизмы:

• Единоличный контроль: Только один мод может управлять полётом игрока в определённый момент. Все остальные запросы помещаются в очередь.
• Перехват изменений: Прямые попытки изменить состояния flying или allowFlying блокируются, если они не авторизованы.
• Рекомендуемый API: Разработчикам следует использовать методы FlightAPI.requestFlight() и FlightAPI.releaseFlight() вместо прямого доступа к параметрам полёта.

Настройка зависимостей (Fabric/NeoForge)

В файле build.gradle добавьте репозиторий и зависимость:

repositories {
    maven {
        name = 'BehindTheScenery Team Maven'
        url = 'https://maven.behindthescenery.online/repository/maven-public/'
    }
}

dependencies {
    modImplementation "dev.denismasterherobrine:flightapi-${project.mod_loader}:${project.flightapi_version}"
}

Параметр ${project.mod_loader} определяет используемый загрузчик модов (например, "fabric" или "neoforge"), а ${project.flightapi_version} — версию Flight API.

Также вы можете включить API непосредственно в свой мод для упрощения установки.

Использование API

Запрос управления полётом

Когда ваш мод должен активировать полёт (например, при включении реактивного ранца или применении заклинания левитации), вызывайте:

boolean gotControl = FlightAPI.requestFlight(modId, player);
if (gotControl) {
    // Вы получили контроль над полётом
    // FlightAPI автоматически устанавливает allowFlying/flying = true
} else {
    // Другой мод уже управляет полётом
    // Ваш запрос добавлен в очередь
}

Освобождение управления полётом

Когда ваш мод завершает управление полётом:

FlightAPI.releaseFlight("MyAwesomeMod", player);

Если в очереди есть другие моды, следующий из них сразу получает контроль.

Проверка текущего владельца

Optional<String> currentOwner = FlightAPI.getCurrentOwner(player);
if (currentOwner.isPresent()) {
    System.out.println("Полётом управляет: " + currentOwner.get());
} else {
    System.out.println("В настоящее время полёт неактивен");
}

Примеры применения

Совместная работа модов "Реактивный ранец" и "Заклинание левитации"

Без Flight API оба мода постоянно переключали бы состояние полёта, вызывая рывки игрока в воздухе. С использованием API мод "Реактивный ранец" получает контроль первым, а мод "Заклинание левитации" ожидает в очереди. Когда ранец заканчивает работу, управление автоматически передаётся заклинанию.

Обнаружение проблемных модов

Если какой-то мод постоянно пытается отключить полёт без авторизации, Flight API блокирует эти попытки и регистрирует их в логах, помогая определить источник проблемы.

Логика приоритетов

По умолчанию используется принцип FIFO (первым пришёл — первым обслужен).

Лицензия

Flight API распространяется под лицензией CC0-1.0.