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

# API

LootRoll provides a comprehensive event API for plugin developers to integrate with the roll system.

### Events

All events are located in the `me.newtale.lootroll.api.event` package.

#### RollSessionStartEvent

Fired when a new roll session starts (item drops).

```java
@EventHandler
public void onRollStart(RollSessionStartEvent event) {
    RollSession session = event.getSession();
    ItemStack item = session.getItem();
    List<Player> participants = session.getParticipants();
    
    // Your code here
}
```

**Event Properties**:

* `RollSession getSession()` - The roll session that started

#### RollSessionFinishEvent

Fired when a roll session finishes (winner determined).

```java
@EventHandler
public void onRollFinish(RollSessionFinishEvent event) {
    RollSession session = event.getSession();
    Player winner = event.getWinner();
    Map<Player, Integer> rolls = event.getEffectiveRolls();
    
    // Your code here
}
```

**Event Properties**:

* `RollSession getSession()` - The roll session that finished
* `Player getWinner()` - The player who won the roll
* `Map<Player, Integer> getEffectiveRolls()` - All rolls that were considered

#### RollNeedEvent

Fired when a player makes a Need roll.

```java
@EventHandler
public void onNeedRoll(RollNeedEvent event) {
    RollSession session = event.getSession();
    Player player = event.getPlayer();
    int roll = event.getRoll();
    
    // Cancel to prevent the roll
    event.setCancelled(true);
}
```

**Event Properties**:

* `RollSession getSession()` - The roll session
* `Player getPlayer()` - The player who rolled
* `int getRoll()` - The roll value
* `void setRoll(int roll)` - Change the roll value
* `boolean isCancelled()` - Check if cancelled
* `void setCancelled(boolean cancel)` - Cancel the roll

#### RollGreedEvent

Fired when a player makes a Greed roll.

```java
@EventHandler
public void onGreedRoll(RollGreedEvent event) {
    RollSession session = event.getSession();
    Player player = event.getPlayer();
    int roll = event.getRoll();
    
    // Cancel to prevent the roll
    event.setCancelled(true);
}
```

**Event Properties**: Same as `RollNeedEvent`

#### RollPassEvent

Fired when a player passes on an item.

```java
@EventHandler
public void onPass(RollPassEvent event) {
    RollSession session = event.getSession();
    Player player = event.getPlayer();
    
    // Cancel to prevent passing
    event.setCancelled(true);
}
```

**Event Properties**:

* `RollSession getSession()` - The roll session
* `Player getPlayer()` - The player who passed
* `boolean isCancelled()` - Check if cancelled
* `void setCancelled(boolean cancel)` - Cancel the pass

### RollSession

The `RollSession` class provides access to roll session data.

#### Getting Session Data

```java
RollSession session = // from event

ItemStack item = session.getItem();
List<Player> participants = session.getParticipants();
Location location = session.getLocation();
long startTime = session.getStartTime();
Player winner = session.getWinner();
```

#### Roll Data

```java
// Get all Need rolls
Map<Player, Integer> needRolls = session.getRolls();

// Get all Greed rolls
Map<Player, Integer> getGreedRolls = session.getGreedRolls();

// Get effective rolls (Need rolls if any, otherwise Greed rolls)
Map<Player, Integer> effectiveRolls = session.getEffectiveRolls();

// Check if player rolled
boolean hasRolled = session.hasPlayerRolled(player);
boolean hasGreedRolled = session.hasPlayerGreedRolled(player);
```

### Example: Custom Roll Modifier

```java
@EventHandler
public void onNeedRoll(RollNeedEvent event) {
    Player player = event.getPlayer();
    
    // Give bonus roll based on player level
    int playerLevel = player.getLevel();
    int bonus = playerLevel / 10; // +1 per 10 levels
    
    int currentRoll = event.getRoll();
    event.setRoll(currentRoll + bonus);
}
```

### Example: Track Roll Statistics

```java
private final Map<UUID, Integer> rollCounts = new HashMap<>();

@EventHandler
public void onRollFinish(RollSessionFinishEvent event) {
    Player winner = event.getWinner();
    UUID uuid = winner.getUniqueId();
    
    rollCounts.put(uuid, rollCounts.getOrDefault(uuid, 0) + 1);
    
    Bukkit.broadcastMessage(winner.getName() + " has won " + 
        rollCounts.get(uuid) + " rolls!");
}
```