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

# Using the PerPlayerKit Java API in Your Paper Plugin

> Step-by-step guide to integrating the PerPlayerKit Java API into a Paper plugin — fetch public kits and load them for players with a full working example.

This page walks through a complete, working example of integrating the PerPlayerKit API into your own Paper plugin. You will see how to obtain the API singleton, fetch the list of configured public kits, and apply a kit to a player — all within a standard Bukkit event listener.

## Full Working Example

The example below loads the first configured public kit for every player the moment they join the server. It covers event registration, API access, and safe list handling in one self-contained class.

```java ExamplePlugin.java theme={null}
import dev.noah.perplayerkit.API;
import dev.noah.perplayerkit.PublicKit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.player.PlayerJoinEvent;
import org.bukkit.plugin.java.JavaPlugin;
import java.util.List;

public class ExamplePlugin extends JavaPlugin {

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

    @EventHandler
    public void onPlayerJoin(PlayerJoinEvent e) {
        // Get the API instance
        API api = API.getInstance();

        // Get a list of all available public kits
        List<PublicKit> publicKits = api.getPublicKits();

        if (!publicKits.isEmpty()) {
            // Load the first public kit for the joining player
            api.loadPublicKit(e.getPlayer(), publicKits.get(0));
        }
    }
}
```

## Step-by-Step Explanation

<Steps>
  <Step title="Obtain the API singleton">
    Call `API.getInstance()` to retrieve the shared API object. PerPlayerKit creates and holds this singleton during its own `onEnable()`, so as long as you have declared `PerPlayerKit` as a `depend` in your `plugin.yml`, the instance is always available by the time your code runs.
  </Step>

  <Step title="Fetch the list of public kits">
    Call `api.getPublicKits()` to get all public kits currently configured in PerPlayerKit. The method returns a **copy** of the internal list, so iterating or modifying the returned list will not affect PerPlayerKit's own data.
  </Step>

  <Step title="Load a kit for a player">
    Pass an online `Player` and a `PublicKit` object to `api.loadPublicKit(player, kit)`. PerPlayerKit applies the kit to the player's inventory silently — no message is sent to the player or broadcast to the server.
  </Step>
</Steps>

## The `PublicKit` Object

`PublicKit` is a simple data class with three public fields:

| Field  | Type                  | Description                                                     |
| ------ | --------------------- | --------------------------------------------------------------- |
| `id`   | `String`              | Unique identifier for the kit, used internally by PerPlayerKit. |
| `name` | `String`              | Human-readable display name of the kit.                         |
| `icon` | `org.bukkit.Material` | The material used to represent the kit in GUIs.                 |

You can use these fields to display kit choices in your own inventory menus, command outputs, or scoreboards before calling `loadPublicKit`.

## plugin.yml Setup

Declare `PerPlayerKit` as a hard dependency so Paper guarantees it loads before your plugin:

```yaml plugin.yml theme={null}
name: ExamplePlugin
version: 1.0
main: com.example.ExamplePlugin
depend:
  - PerPlayerKit
```

<Tip>
  If PerPlayerKit is optional for your plugin — for example, you only use it when it happens to be installed — list it under `softdepend` instead of `depend`. Your plugin will then load regardless of whether PerPlayerKit is present. Remember to null-check `API.getInstance()` and guard your PerPlayerKit code paths accordingly.
</Tip>

<Warning>
  Always check `publicKits.isEmpty()` before accessing the list by index. If no public kits have been configured in PerPlayerKit, `getPublicKits()` returns an empty list and calling `publicKits.get(0)` will throw an `IndexOutOfBoundsException`.
</Warning>