> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cakestudio.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# CakeAuction API

> Полное руководство для разработчиков по созданию аддонов и интеграций.

CakeAuction предоставляет мощный и изолированный программный интерфейс для взаимодействия с экосистемой аукциона. API уже встроено в основной плагин, поэтому вам не нужно устанавливать его отдельно.
Более подробную инструкцию по использованию API вы можете найти [**здесь**](https://github.com/CakesStudio/CakeAuctionAPI/blob/main/DOCUMENTATION.md).

<CardGroup cols={2}>
  <Card title="GitHub Репозиторий" icon="github" href="https://github.com/CakesStudio/CakeAuctionAPI">
    Исходный код и последние релизы API.
  </Card>

  <Card title="JitPack" icon="box" href="https://jitpack.io/#CakesStudio/CakeAuctionAPI">
    Подключение зависимости в ваш проект.
  </Card>
</CardGroup>

## 🚀 Подключение

Используйте `compileOnly` (Gradle) или `provided` (Maven), чтобы API не попадало в ваш итоговый JAR-файл.

### Gradle (Groovy)

```gradle theme={null}
repositories {
    maven { url 'https://jitpack.io' }
}

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

### Maven

```xml theme={null}
<dependencies>
    <dependency>
        <groupId>com.github.CakesStudio</groupId>
        <artifactId>CakeAuctionAPI</artifactId>
        <version>VERSION</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

*(Замените `VERSION` на актуальную версию, например `1.5.0`)*

<Warning>
  **Важно:** Основное ядро CakeAuction выполняет релокацию библиотек `net.kyori` (Adventure) и `com.tcoded` (FoliaLib).
  Чтобы избежать ошибки **NoSuchMethodError**, ваш аддон **ОБЯЗАН** выполнить релокацию этих библиотек в тот же пакет:

  ```gradle theme={null}
  tasks.shadowJar {
      relocate 'net.kyori', 'dev.cakestudio.cakeauction.libs.kyori'
      relocate 'com.tcoded.folialib', 'dev.cakestudio.cakeauction.libs.folialib'
  }
  ```
</Warning>

***

## 🧩 Система Аддонов

CakeAuction включает управляемую систему аддонов, которая берет на себя жизненный цикл вашего кода.

### 1. Метаданные (addon.yml)

Создайте файл `addon.yml` в папке `resources`:

```yaml theme={null}
name: MyAwesomeAddon
main: com.example.myaddon.MyAddon
version: 1.0.0
api-version: '1.5.0'
folia-supported: true
authors: [ "Developer" ]
```

### 2. Реализация (AbstractAddon)

Наследуйте ваш главный класс от `AbstractAddon`. Это обеспечит **автоматическую очистку** ресурсов (слушателей, команд, задач) при выключении.

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

***

## ⚡ Потоки и Folia (Concurrency)

Для корректной работы на **Folia**, Paper и Spigot используйте встроенные методы планировщика. Это гарантирует безопасность региональных потоков и автоматическую отмену задач при выгрузке аддона.

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

// Задача с задержкой (регионально-безопасно)
runTaskLaterAsync(() -> { ... }, 20L);
```

***

## 🛠️ Основные Менеджеры API

Доступ к API осуществляется через `CakeAuctionAPI.getApi()`.

### ⚖️ Аукцион (IAuctionManager)

Управление лотами, поиск, налоги, а также динамическая регистрация категорий и сортировок:

```java theme={null}
IAuctionManager auction = api.getAuctionManager();

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

// Создание лота
api.createAuction(player, itemStack, 500.0, 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())
);
```

### 🆔 Идентификаторы (IUUIDManager)

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

```java theme={null}
IUUIDManager uuid = api.getUUIDManager();
UUID random = uuid.random();
String shortId = uuid.toShortId(random); // напр. "7x2K9mPq1z"
```

### 📦 Предметы (IItemManager)

Сериализация в Base64 и создание уникальных цифровых подписей для защиты от дюпов.

```java theme={null}
IItemManager itemManager = api.getItemManager();
String base64 = itemManager.serialize(itemStack);
String signature = itemManager.getSignature(itemStack);
```

### 👤 Данные игроков (IUserManager)

Статистика, лимиты, история и активные абонементы (Passes).

```java theme={null}
IUserManager userManager = api.getUserManager();
if (userManager.isLimitReached(player)) {
    player.sendMessage("Лимит слотов достигнут!");
}
```

### 🔌 Интеграция предметов (IHookManager)

Регистрация кастомных провайдеров предметов (например, для Oraxen, ItemsAdder или самописных систем) для динамического разрешения идентификаторов предметов:

```java theme={null}
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)

Регистрация собственных тегов действий, которые можно использовать в любых конфигах.

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

***

## 📅 Система Событий (Events)

| Событие                       | Описание                      | Отменяемое |
| :---------------------------- | :---------------------------- | :--------: |
| `AuctionItemBuyProcessEvent`  | Перед покупкой лота           |      ✅     |
| `AuctionItemSellProcessEvent` | Перед выставлением на продажу |      ✅     |
| `AuctionItemTakeProcessEvent` | Перед снятием лота продавцом  |      ✅     |
| `AuctionItemBuyEvent`         | После успешной покупки        |      ❌     |
| `AuctionItemSellEvent`        | После создания лота           |      ❌     |
| `AuctionItemAutoBuyEvent`     | При выкупе сервером           |      ❌     |

***

## 💰 Экономика и провайдеры

Вы можете зарегистрировать собственный провайдер валюты:

```java theme={null}
api.getEconomyManager().registerProvider(new IEconomyProvider() {
    @Override public String getName() { return "gems"; }
    @Override public double getBalance(OfflinePlayer p) { ... }
    // ... остальные методы
});
```