> For the complete documentation index, see [llms.txt](https://docs.mantic.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mantic.dev/mantichoes/developer-api.md).

# Developer API

This page documents the ManticHoes developer API.

`me.fullpage.mantichoes.api.ManticHoesAPI` is the static entry point for third-party plugins. It wraps player data, harvester hoes, crops, enchants, harvest statistics, tokens, and economy operations. Bukkit events and the `EconomyProvider` interface are also part of the API.

## Add the API to your build

The API is published to our Maven repository, so there is nothing to install locally.

```xml
<repositories>
  <repository>
    <id>mantic</id>
    <url>https://repo.mantic.dev/public</url>
  </repository>
</repositories>

<dependency>
  <groupId>me.fullpage</groupId>
  <artifactId>mantichoes-api</artifactId>
  <version>2.1</version>
  <scope>provided</scope>
</dependency>
```

Gradle:

```kotlin
repositories {
    maven("https://repo.mantic.dev/public") {
        content { includeGroup("me.fullpage") }
    }
}

dependencies {
    compileOnly("me.fullpage:mantichoes-api:2.1")
}
```

The JAR retains class and member signatures but stubs method bodies, so it is only for compiling integrations. Do not put it on a server or bundle it in another plugin; the installed ManticHoes plugin supplies the runtime classes. Published versions are browsable at <https://repo.mantic.dev/\\_browse/public>.

Keep your Bukkit/Spigot API and ManticLib compile dependencies provided as well; some public wrapper and event signatures use their types. In `plugin.yml`, load ManticHoes before your integration:

```yaml
depend: [ManticHoes]
```

## Players, hoes, and configuration

The facade exposes `getPlugin`, `getPlayer`, and `getPlayers`; `getPlayers` returns an empty, read-only collection until player data loads. Hoe access is available through `getHoe(Player)`, `getHoe(ItemStack, Player)`, `getHoe(ItemStack, MPlayer)`, and `getVirtualHoe(Player)`. Configuration lookups are `getHoeSetting`, `getEnchant`, and `getEnchants`. Crop lookups are `getCrop`, `getCropFromBlock`, and `getCropFromDrop`.

```java
import me.fullpage.mantichoes.api.ManticHoesAPI;
import me.fullpage.mantichoes.api.types.Crop;
import me.fullpage.mantichoes.data.HarvesterHoes;
import me.fullpage.mantichoes.wrappers.HarvesterHoe;
import me.fullpage.mantichoes.wrappers.HoeEnchant;
import me.fullpage.mantichoes.wrappers.MPlayer;
import org.bukkit.Material;
import org.bukkit.entity.Player;

class Example {
    void example(Player player) {
        MPlayer data = ManticHoesAPI.getPlayer(player);
        if (data != null) {
            double tokens = ManticHoesAPI.getTokens(player);
            long wheat = ManticHoesAPI.getHarvested(player, Crop.WHEAT);
        }

        HarvesterHoe hoe = ManticHoesAPI.getHoe(player);
        if (hoe.isValid()) {
            HoeEnchant fortune = ManticHoesAPI.getEnchant("fortune");
            if (fortune != null) {
                int level = hoe.getLevel(fortune);
            }
        }

        Crop crop = ManticHoesAPI.getCropFromBlock(Material.WHEAT);
        HarvesterHoes.HoeSetting setting = ManticHoesAPI.getHoeSetting("default");
    }
}
```

`getPlayer` accepts a Bukkit player, offline player, UUID, name, or existing `MPlayer`; it returns `null` when it cannot resolve the identifier. Token and harvest-stat methods require valid player data and throw `IllegalArgumentException` if it cannot be found. Hoe helpers return a wrapper for any item, so call `isValid()` before using hoe-specific methods. `getVirtualHoe` creates a virtual default hoe; `getEnchants` returns the configured enchants. Crop helpers include `getCrop`, `getCropFromBlock`, and `getCropFromDrop`.

Harvest-stat methods are `getHarvested`, `getTotalHarvested`, and `addHarvested`.

## Tokens and economy

The facade offers `getTokens`, `setTokens`, `addTokens`, `takeTokens`, `hasEnoughTokens`, and `payTokens`. These use the active token economy provider when one is configured. `getTokenEconomyProvider` returns that provider; use `registerTokenEconomyProvider` and `unregisterTokenEconomyProvider` to manage an external provider.

Money operations use the configured money provider: `getMoney`, `giveMoney`, `takeMoney`, `setMoney`, and `hasEnoughMoney`. Provider lookups can return `null` when no provider is available; the boolean money operations return `false` when the operation cannot be performed. `getSellPrice` returns the configured price for a material and durability, optionally using player-specific pricing.

## Events

Register these with Bukkit's `PluginManager`:

* `HoePreUseEvent` fires before a hoe action and can be cancelled.
* `HoeUseEvent` exposes the broken blocks, loot, token and XP rewards, and money amounts. Its mutable outcome fields can be adjusted by listeners.
* `PreDisenchantEvent` and `DisenchantEvent` expose the disenchant flow; the pre-event can be cancelled.
* `FastBreakAlertEvent` reports a fast-break alert and supports cancellation.

All event classes are under `me.fullpage.mantichoes.api.events`. Implement `me.fullpage.mantichoes.api.providers.economy.EconomyProvider` to integrate an economy with token operations.
