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

# PerPlayerKit Java API — Overview for Plugin Developers

> PerPlayerKit exposes a Java API for other plugins to interact with kit data. Add PerPlayerKit as a dependency and access public kits programmatically.

PerPlayerKit provides a simple Java API that other Paper plugins can use to interact with kit data — load public kits for players, query available kits, and react to kit events. You access all functionality through a singleton `API` instance that PerPlayerKit registers at startup. The surface area is intentionally small: retrieve a list of configured public kits, then apply one to any online player with a single method call.

<Warning>
  The PerPlayerKit API is **not yet stable**. Method signatures, class names, and behaviour may change in future versions without notice. Pin your integration to a specific version of the jar and test against new releases before upgrading.
</Warning>

## Adding the Dependency

PerPlayerKit is not published to a public Maven repository, so you need to add the plugin jar to your project manually.

1. Place `PerPlayerKit-1.1.jar` inside a `lib/` folder at the root of your project.
2. Declare it as a `system`-scoped dependency in your `pom.xml`:

```xml pom.xml theme={null}
<dependency>
    <groupId>com.local</groupId>
    <artifactId>PerPlayerKit</artifactId>
    <version>local</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/PerPlayerKit-1.1.jar</systemPath>
</dependency>
```

<Note>
  Add `PerPlayerKit` to the `depend` (or `softdepend`) list in your `plugin.yml` so Paper loads PerPlayerKit before your plugin. Without this, `API.getInstance()` may be called before PerPlayerKit has initialised, returning an uninitialised instance.
</Note>

## Obtaining the API Instance

Import `dev.noah.perplayerkit.API` and call the static `getInstance()` method. You can call this anywhere after your plugin has loaded — typically inside an event handler or command executor, after PerPlayerKit is guaranteed to be enabled:

```java theme={null}
import dev.noah.perplayerkit.API;

API api = API.getInstance();
```

## Available Methods

The following methods make up the current public API surface:

| Method                                 | Return Type       | Description                                                                             |
| -------------------------------------- | ----------------- | --------------------------------------------------------------------------------------- |
| `API.getInstance()`                    | `API`             | Returns the singleton API instance, creating it if it does not yet exist.               |
| `api.getPublicKits()`                  | `List<PublicKit>` | Returns a **copy** of the list of all public kits configured in PerPlayerKit.           |
| `api.loadPublicKit(Player, PublicKit)` | `void`            | Loads the given public kit for the specified online player, silently (no chat message). |

Each `PublicKit` object exposes an `id` (String), a `name` (String), and an `icon` (`org.bukkit.Material`) that you can use to identify or display kits in your own UI.

For a complete, runnable integration example, see the [Usage](/api/usage) page.