UltimateAdvancementAPI

UltimateAdvancementAPI - это плагин для серверов Minecraft (Paper/Spigot), который даёт разработчикам возможность создавать свои собственные достижения (advancements). В ванильной игре достижения - это просто набор заданий, но на серверах часто хочется добавить уникальные ачивки: за прохождение данжа, за сбор редких ресурсов, за PvP-рекорды. Этот API решает именно эту задачу - позволяет гибко настраивать любые условия и визуал.

Ключевые особенности

• Простота - API спроектирован так, чтобы добавление своих достижений не вызывало головной боли.
• Асинхронность - все операции работают через пакеты, поэтому сервер не лагает даже при массовой выдаче ачивок.
• Гибкая система видимости - можно легко настроить, какие достижения видны игрокам, а какие скрыты.
• Поддержка команд - прогресс синхронизируется между участниками одной команды.
• Офлайн-игроки - полная поддержка изменения прогресса у игроков, которые не в сети.
• Кастомные тосты - можно отправлять свои уведомления (toast) игрокам.
• Базы данных - сохранение прогресса в SQLite, MySQL или в памяти (In-Memory).
• Отключение ванильных достижений - можно полностью убрать стандартные ачивки без редактирования jar-файла сервера.

Для кого этот плагин?

UltimateAdvancementAPI - инструмент для разработчиков плагинов. Если какой-то плагин на вашем сервере требует его, просто скачайте нужную версию и положите в папку plugins. Если вы сами пишете плагины - добавьте зависимость через Maven и начинайте кодить.

Подключение через Maven

<repositories>
    <repository>
        <id>fren_gor</id>
        <url>https://nexus.frengor.com/repository/public/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.frengor</groupId>
    <artifactId>ultimateadvancementapi</artifactId>
    <version>2.8.0</version>
    <scope>provided</scope>
</dependency>

Также есть shadeable-версия - подробнее в документации.

Пример использования

Вот как выглядит создание простого достижения:

public class MainClass extends JavaPlugin implements Listener {

    private AdvancementTab advancementTab;
    private UltimateAdvancementAPI api;

@Override
public void onEnable() {
    api = UltimateAdvancementAPI.getInstance(this);
    advancementTab = api.createAdvancementTab("your_tab_name");

    AdvancementDisplay rootDisplay = new AdvancementDisplay(Material.GRASS_BLOCK, "Example", AdvancementFrameType.TASK, true, true, 0, 0, "A random", "description.");
    RootAdvancement root = new RootAdvancement(advancementTab, "root", rootDisplay, "textures/block/stone.png");
    advancementTab.registerAdvancements(root);

    Bukkit.getPluginManager().registerEvents(this, this);
}

@EventHandler
public void onJoin(PlayerLoadingCompletedEvent e) {
    Player p = e.getPlayer();
    advancementTab.showTab(p);
}

}

## Команды и права

<details>
  <summary>Список команд и разрешений</summary>

`/ultimateadvancementapi <progression|grant|revoke> ...`
**Permission:** `ultimateadvancementapi.command`

`/ultimateadvancementapi grant <all|tab|one> ...`
**Permission:** `ultimateadvancementapi.grant`

`/ultimateadvancementapi grant all <player> [giveRewards]`
**Permission:** `ultimateadvancementapi.grant.all`

`/ultimateadvancementapi grant tab <advancementTab> [player] [giveRewards]`
**Permission:** `ultimateadvancementapi.grant.tab`

`/ultimateadvancementapi grant one <advancement> [player] [giveRewards]`
**Permission:** `ultimateadvancementapi.grant.one`

`/ultimateadvancementapi revoke <all|tab|one> ...`
**Permission:** `ultimateadvancementapi.revoke`

`/ultimateadvancementapi revoke all <player> [hideTab]`
**Permission:** `ultimateadvancementapi.revoke.all`

`/ultimateadvancementapi revoke tab <advancementTab> [player] [hideTab]`
**Permission:** `ultimateadvancementapi.revoke.tab`

`/ultimateadvancementapi revoke one <advancement> [player]`
**Permission:** `ultimateadvancementapi.revoke.one`

`/ultimateadvancementapi progression <get|set> ...`
**Permission:** `ultimateadvancementapi.progression`

`/ultimateadvancementapi progression get <advancement> [player]`
**Permission:** `ultimateadvancementapi.progression.get`

`/ultimateadvancementapi progression set <advancement> <progression> [player] [giveRewards]`
**Permission:** `ultimateadvancementapi.progression.set`

</details>

## Итог

Если вы разрабатываете плагины для Minecraft и хотите добавить на сервер кастомные достижения - UltimateAdvancementAPI сэкономит кучу времени. Он уже проверен многими проектами, стабилен и хорошо документирован. Скачайте плагин UltimateAdvancementAPI и начните создавать свои ачивки прямо сейчас.