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

# Developer API

For plugin developers: hook into ClickEm with the ClickEmAPI service and about 43 events.

{% hint style="info" %}
This section is for **plugin developers** who want to read or change ClickEm from their own plugin. Server owners do not need it.
{% endhint %}

ClickEm exposes:

* **`ClickEmAPI`**: a service for balances, stats, Profile Level, Rebirth, zones, pets and mobs.
* **Events** in `com.lethiumstore.clickem.api.event`: about 43 events. Most are **cancellable** and many let you **change a value** (a reward, a price, damage).
* **Stat contributors**: give players stats from your own plugin.

Everything is in one package that is **not obfuscated**, so your IDE shows real names and autocompletes.

### Add ClickEm to your plugin

1. Get the API jar, `clickem-core-<version>-api.jar`. It contains only the API package and the small set of types it exposes (`StatBlock`, `StatType`, `StatContributor`, `Zone`, pet and ability types, and the event classes), so you can compile against it alone.
2. Add it as a compile-only dependency.

{% tabs %}
{% tab title="Gradle (Kotlin)" %}

```kotlin
dependencies {
    compileOnly(files("libs/clickem-core-1.0.0-api.jar"))
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
}
```

{% endtab %}

{% tab title="Maven" %}

```xml
<dependency>
  <groupId>com.lethiumstore</groupId>
  <artifactId>clickem-core</artifactId>
  <version>1.0.0</version>
  <classifier>api</classifier>
  <scope>system</scope>
  <systemPath>${project.basedir}/libs/clickem-core-1.0.0-api.jar</systemPath>
</dependency>
```

{% endtab %}
{% endtabs %}

3. Declare the dependency in your `plugin.yml` so ClickEm loads first:

```yaml
depend: [ClickEmCore]      # or softdepend: [ClickEmCore] if it is optional
```

The plugin name is **`ClickEmCore`**.

### Get the API

```java
import com.lethiumstore.clickem.api.ClickEmAPI;

ClickEmAPI api = ClickEmAPI.get();          // throws IllegalStateException if ClickEm is not enabled
int version = ClickEmAPI.VERSION;           // the API version (currently 2)
```

`ClickEmAPI.get()` reads the service from Bukkit's `ServicesManager`. It is registered at the **end** of ClickEm's startup, so call it in your own `onEnable` (after ClickEm has enabled), not in a static initialiser. If ClickEm is optional, check the plugin is present first.

```java
Bukkit.getPluginManager().isPluginEnabled("ClickEmCore");
```

### A first example

```java
public final class MyPlugin extends JavaPlugin implements Listener {

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onReward(CurrencyRewardEvent event) {
        if (!event.currency().equals("coins")) return;
        // Double coin rewards for players with a permission
        if (event.player().hasPermission("myplugin.double")) {
            event.setAmount(event.amount() * 2);
        }
    }
}
```

### Rules to know

| Rule                                                                        | Why                                                                                                                  |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Main thread only** for anything that changes player state                 | The plugin is not thread-safe. Schedule with Bukkit's scheduler if you are async.                                    |
| `CurrencyChangeEvent` fires from the economy service on the **main thread** | Do not block in it.                                                                                                  |
| Setters clamp bad values                                                    | For example `setAmount(NaN)` becomes `0`.                                                                            |
| Events with no `Cancellable` are **notify-only**                            | You cannot stop them.                                                                                                |
| Do not call API methods from a `StatCalculateEvent` handler                 | It fires while stats are being computed. Use the event's own `stats()`.                                              |
| Methods return empty or zero when the owning module is **disabled**         | For example `api.level(player)` returns `0` if `profile-level` is off. Check `api.isModuleEnabled("profile-level")`. |

### What's next

| Page                                                       |                                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [The ClickEmAPI service](/lethium-docs/dev-api/service.md) | Every method.                                                                      |
| [Stats and contributors](/lethium-docs/dev-api/stats.md)   | Give players stats from your plugin.                                               |
| [Events](/lethium-docs/dev-api/events.md)                  | The full event catalog.                                                            |
| [Examples](/lethium-docs/dev-api/examples.md)              | Practical recipes: custom currency reward, zone gate, stat bonus, mob spawn tweak. |

### Versioning

`ClickEmAPI.VERSION` is an integer that goes up when the API changes. Version 2 added `language(Player)`. Additions are backward compatible. Check `ClickEmAPI.VERSION` if you rely on a newer method.

{% hint style="warning" %}
The API was written recently and has been compiled but **not yet tested live against a large number of third-party plugins**. Report problems to the plugin author.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://lethium.gitbook.io/lethium-docs/dev-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.