CakeAuction API

CakeAuction предоставляет API для разработки аддонов, интеграции со сторонними плагинами и регистрации кастомных провайдеров валют. API входит в ядро плагина; зависимость можно подключить через Maven или Gradle. Подробная документация также доступна в репозитории CakeAuctionAPI.

GitHub

Исходный код CakeAuctionAPI.

JitPack

Зависимости для сборщиков проектов.

Подключение

Подключайте доступную версию зависимости как compileOnly (Gradle) или provided (Maven). Версия API 2.1.0 подготовлена в исходниках; её выпуск ещё не опубликован.

Gradle

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.CakesStudio:CakeAuctionAPI:VERSION'
}

Maven

<dependencies>
    <dependency>
        <groupId>com.github.CakesStudio</groupId>
        <artifactId>CakeAuctionAPI</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Ядро CakeAuction релоцирует библиотеки net.kyori (Adventure) и com.tcoded (FoliaLib). При сборке аддона релоцируйте их в те же пакеты для предотвращения NoSuchMethodError:

tasks.shadowJar {
    relocate 'net.kyori', 'dev.cakestudio.cakeauction.libs.kyori'
    relocate 'com.tcoded.folialib', 'dev.cakestudio.cakeauction.libs.folialib'
}

Система аддонов

CakeAuction поддерживает модульную загрузку аддонов из директории plugins/CakeAuction/addons/.

Метаданные

Создайте addon.yml в src/main/resources:

name: MyAddon
main: com.example.myaddon.MyAddon
version: 1.0.0
api-version: '2.1.0'
folia-supported: true
authors: [ "Developer" ]

Главный класс

Класс аддона наследует AbstractAddon. Зарегистрированные через него слушатели, команды и задачи автоматически очищаются при выгрузке:

public class MyAddon extends AbstractAddon {
    @Override
    protected void onEnable() {
        saveDefaultConfig();
        registerListener(new MyListener());
        registerCommand(new MyCommand());
    }
}

Автообновление конфигов аддона

import dev.cakestudio.cakeauctionapi.config.ConfigUpdateOptions;

@Override
protected ConfigUpdateOptions getConfigUpdateOptions() {
    return ConfigUpdateOptions.builder()
            .relocate(2, "messages.loaded", "messages.ready")
            .build();
}

В ресурсе config.yml храните актуальные настройки и версию:

messages:
  ready: "Готово"

config-version: 2

Файл создаётся или обновляется до onEnable() и при reloadConfig(). getConfig() по-прежнему возвращает Bukkit FileConfiguration. Без переименований верните ConfigUpdateOptions.DEFAULT; вызывать saveDefaultConfig() для такого аддона необязательно. Не используйте в методе правил поля, которые заполняются только в onEnable(). При изменении шаблона увеличивайте config-version на 1, оставляйте его последним ключом с пустой строкой перед ним. Для переименований указывайте версию перехода через .relocate(...) и сохраняйте прежние правила, чтобы поддерживать обновление через несколько выпусков. Обновление сохраняет пользовательские значения, комментарии и дополнительные ключи. При переносе разделов добавляются только отсутствующие поля: существующие новые значения имеют приоритет, а конфликтующие старые значения остаются на месте. Перед заменой файл копируется в backups/ рядом с ним. Повторная загрузка актуального файла не переписывает его; более новые версии не понижаются. Старые файлы без корректной версии считаются версией 1. Если YAML повреждён или обновление не удалось, файл не сбрасывается: загрузка аддона останавливается до исправления. Без переопределения getConfigUpdateOptions() прежнее поведение аддона не меняется. Для отдельных файлов из onLoad() или onEnable() используйте:

updateConfig("messages.yml", ConfigUpdateOptions.builder()
        .relocate(3, "errors.old", "errors.new")
        .build());

Ресурс и файл используют одинаковый относительный путь внутри каталога аддона. Ресурс тоже должен иметь config-version. Метод возвращает ConfigUpdateResult с версиями и путём резервной копии; кеш основного конфига он не перечитывает. Для config.yml используйте reloadConfig(). Обычный saveConfig() сохраняет текущий Bukkit-конфиг и может переформатировать комментарии.

Потоки и Folia

Для совместимости со Spigot, Paper и Folia используйте методы планировщика AbstractAddon:

// Асинхронная задача
runTaskAsync(() -> {
    // логика
});

// Асинхронная задача с задержкой
runTaskLaterAsync(() -> {
    // логика
}, 20L);

Менеджеры API

Точка входа API: CakeAuctionAPI.getApi().

IEconomyManager

Управление мультивалютной экономикой и регистрация кастомных валют:

IEconomyManager economy = api.getEconomyManager();

// Режим аукциона: "MULTI_CURRENCY" или "SINGLE_CURRENCY"
String mode = economy.getAuctionMode();

// Идентификатор валюты по умолчанию (например, "vault")
String defaultCurrency = economy.getDefaultCurrencyId();

// Список всех зарегистрированных валют
Collection<String> currencies = economy.getSupportedCurrencies();

if (economy.supportsMultiCurrency()) {
    double points = economy.getBalance(player, "playerpoints");
    
    boolean withdrawn = economy.withdraw(player, "playerpoints", 150.0);
    
    String formatted = economy.format("playerpoints", 150.0);
}

// MyEconomyProvider реализует IEconomyProvider
// и обращается к системе валюты вашего плагина.
economy.registerProvider(new MyEconomyProvider());

IAuctionManager

Создание лотов, поиск, регистрация категорий и сортировок:

IAuctionManager auction = api.getAuctionManager();

// Поиск: запрос, категория, валюта, тип сортировки
Collection<IAuctionItem> results = auction.search("Diamond", "Resources", "vault", "price_asc");

// Создание лота
api.createAuction(player, itemStack, 500.0, "vault", 3600L, false);

// Регистрация категории с предикатом-фильтром
ItemStack icon = new ItemStack(Material.GOLDEN_APPLE);
auction.registerCategory(
    "mythic_gear",
    "<gradient:#ffd700:#ff4500>Mythic Gear</gradient>",
    icon,
    itemStack -> {
        if (itemStack == null || !itemStack.hasItemMeta()) return false;
        return itemStack.getItemMeta().getDisplayName().contains("Mythic");
    }
);

// Регистрация кастомной сортировки
auction.registerSortingType(
    "seller_name_length",
    "<aqua>Seller Name Length</aqua>",
    Comparator.comparingInt(item -> item.getSellerName().length())
);

ITaxManager

Расчет налогов с учетом валют и групп:

ITaxManager taxManager = api.getTaxManager();

// Общая ставка налога игрока для валюты
double rate = taxManager.getTaxRate(player, "vault");

// Раздельные ставки продавца и покупателя
double sellerRate = taxManager.getSellerTaxRate(player, "vault");
double buyerRate = taxManager.getBuyerTaxRate(player, "vault");

IUserManager

Проверка лимитов и параметров игрока:

IUserManager userManager = api.getUserManager();

if (userManager.isLimitReached(player, "playerpoints")) {
    player.sendMessage("Лимит лотов для этой валюты исчерпан.");
}

int totalMaxSlots = userManager.getMaxSlots(player);
int pointsMaxSlots = userManager.getMaxSlots(player, "playerpoints");
long duration = userManager.getSellDuration(player, "playerpoints");

IUUIDManager

Генерация упорядоченных по времени UUID v7 и компактных Base62 short ID:

IUUIDManager uuid = api.getUUIDManager();
UUID random = uuid.random();
String shortId = uuid.toShortId(random);

IItemManager

Сериализация предметов в Base64 и получение контрольных сумм:

IItemManager itemManager = api.getItemManager();
String base64 = itemManager.serialize(itemStack);
String signature = itemManager.getSignature(itemStack);

IHookManager

Регистрация кастомных провайдеров предметов:

IHookManager hooks = api.getHookManager();

hooks.registerProvider(new IItemHookProvider() {
    @Override
    public @Nullable ItemStack getItem(@NonNull String id) {
        if (id.equalsIgnoreCase("ruby_gem")) {
            return new ItemStack(Material.EMERALD);
        }
        return null;
    }

    @Override
    public @Nullable String getItemId(@NonNull ItemStack item) {
        if (item.getType() == Material.EMERALD) {
            return "ruby_gem";
        }
        return null;
    }

    @Override
    public @NonNull String getPrefix() {
        return "myprovider"; // префикс myprovider:ruby_gem
    }
});

IActionManager

Регистрация действий кликов в GUI:

// Регистрация тега действия [GIVE_REWARD]
api.getActionManager().registerAction("GIVE_REWARD", (player, loc, text) -> {
    player.sendMessage("Награда: " + text);
});

IAIManager

Асинхронные методы работы с ИИ-моделями:

IAIManager ai = api.getAiManager();

if (ai.isEnabled()) {
    // Оценка цены предмета
    ai.getPriceAdvice(diamondSword).thenAccept(advice -> {
        if (advice != null) {
            double fair = advice.getFairPrice();
            double fast = advice.getFastPrice();
            int confidence = advice.getConfidence();
            String reason = advice.getAdvice();
        }
    });

    // Семантический поиск
    ai.search("сет брони для пвп").thenAccept(result -> {
        if (result != null) {
            String keyword = result.getKeyword();
            String category = result.getSuggestedCategory();
        }
    });

    // Генерация рыночной сводки
    ai.generateMarketDigest().thenAccept(digest -> {
        // обработка текста сводки
    });
}

IDatabaseManager

Диагностика подключения к базе данных:

IDatabaseManager db = api.getDatabaseManager();

// Проверка гибридного режима (Redis + SQL)
boolean isHybrid = db.isHybridStorage();

// Текущий режим ("HYBRID" или "SQL")
String storageMode = db.getStorageMode();

INetworkManager

Состояние межсерверного сетевого слоя:

INetworkManager network = api.getNetworkManager();

// Проверка активности Direct TCP
boolean isDirectTcp = network.isDirectTcpEnabled();

// Тип синхронизации: "DIRECT_TCP", "REDIS", "BUNGEE", "NONE"
String netType = network.getNetworkType();

IMonitorManager

Диагностика производительности и управление стресс-тестом:

IMonitorManager monitor = api.getMonitorManager();

// Открыть статусное меню игроку
monitor.openStatusMenu(player);

// Отправить текстовый отчет
monitor.sendStatusReport(commandSender);

// Проверить и остановить стресс-тест
if (monitor.isStressTestRunning()) {
    monitor.stopStressTest();
}

IBonusLimitManager

Постоянные бонусные слоты и статус аренды:

IBonusLimitManager bonusLimits = api.getBonusLimitManager();

int bonus = bonusLimits.getBonus(player.getUniqueId());
bonusLimits.addBonus(player.getUniqueId(), 5);
bonusLimits.setBonus(player.getUniqueId(), 10);
bonusLimits.resetBonus(player.getUniqueId());

// Запрос арендованных слотов и времени окончания
int rentSlots = bonusLimits.getRentSlots(player.getUniqueId());
long rentExpiry = bonusLimits.getRentExpiry(player.getUniqueId());

IRentManager

Временная аренда слотов (/ah rent):

IRentManager rentManager = api.getRentManager();

if (rentManager != null && rentManager.isEnabled()) {
    int activeSlots = rentManager.getActiveRentSlots(player.getUniqueId());
    long expiry = rentManager.getRentExpiry(player.getUniqueId());

    // Тарифы из settings/economy/limits.yml
    Collection<? extends IRentTier> tiers = rentManager.getTiers();

    // Проведение аренды
    boolean success = rentManager.rent(player, "tier_1", "vault");
}

IPassManager

Создание предметов-абонементов и проверка скидок на комиссию:

IPassManager passManager = api.getPassManager();

// Создание ItemStack абонемента по ключу из passes.yml
if (passManager.hasPass("vip_pass")) {
    ItemStack passItem = passManager.createPass("vip_pass");
    player.getInventory().addItem(passItem);
}

// Проверка активности абонемента
if (passManager.hasActivePass(player)) {
    double discount = passManager.getDiscount(player);
    long remainingMs = passManager.getRemainingTime(player);
}

События

Событие	Описание	Отменяемое
`AuctionItemBuyProcessEvent`	Перед покупкой лота игроком	Да
`AuctionItemSellProcessEvent`	Перед выставлением лота на продажу	Да
`AuctionItemTakeProcessEvent`	Перед снятием лота продавцом	Да
`AuctionItemBuyEvent`	После успешного завершения покупки	Нет
`AuctionItemSellEvent`	После успешного создания лота	Нет
`AuctionItemAutoBuyEvent`	При автовыкупе сервером	Нет
`AuctionPassUseEvent`	При активации торгового абонемента игроком	Нет

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

Настройка

Основные разделы

Аддоны

Разработчикам

GitHub

JitPack

Подключение

Gradle

Maven

Система аддонов

Метаданные

Главный класс

Автообновление конфигов аддона

Потоки и Folia

Менеджеры API

IEconomyManager

IAuctionManager

ITaxManager

IUserManager

IUUIDManager

IItemManager

IHookManager

IActionManager

IAIManager

IDatabaseManager

INetworkManager

IMonitorManager

IBonusLimitManager

IRentManager

IPassManager

События

GitHub

JitPack

​Подключение

​Gradle

​Maven

​Система аддонов

​Метаданные

​Главный класс

​Автообновление конфигов аддона

​Потоки и Folia

​Менеджеры API

​IEconomyManager

​IAuctionManager

​ITaxManager

​IUserManager

​IUUIDManager

​IItemManager

​IHookManager

​IActionManager

​IAIManager

​IDatabaseManager

​INetworkManager

​IMonitorManager

​IBonusLimitManager

​IRentManager

​IPassManager

​События

Подключение

Gradle

Maven

Система аддонов

Метаданные

Главный класс

Автообновление конфигов аддона

Потоки и Folia

Менеджеры API

IEconomyManager

IAuctionManager

ITaxManager

IUserManager

IUUIDManager

IItemManager

IHookManager

IActionManager

IAIManager

IDatabaseManager

INetworkManager

IMonitorManager

IBonusLimitManager

IRentManager

IPassManager

События