# events

PracticeBot exposes Bukkit events for public lifecycle integrations.

All PracticeBot public events extend:

```java
PracticeBotEvent
```

and expose:

```java
PracticeBotHandle getBot()
```

## Event list

| Event                           | When it fires                           | Important getters                                         |
| ------------------------------- | --------------------------------------- | --------------------------------------------------------- |
| `PracticeBotSpawnEvent`         | A runtime PracticeBot spawns.           | `getBot()`                                                |
| `PracticeBotDespawnEvent`       | A runtime PracticeBot despawns.         | `getBot()`, `getReason()`                                 |
| `PracticeBotDeathEvent`         | A PracticeBot dies.                     | `getBot()`, `getKillerEntityUuid()`                       |
| `PracticeBotKillEvent`          | A PracticeBot kills an entity/player.   | `getBot()`, `getVictimEntityUuid()`                       |
| `PracticeBotTargetChangeEvent`  | A bot target changes.                   | `getPreviousTarget()`, `getNewTarget()`, `getCause()`     |
| `PracticeBotCombatStartEvent`   | A bot enters combat.                    | `getTarget()`                                             |
| `PracticeBotCombatStopEvent`    | A bot leaves combat.                    | `getPreviousTarget()`                                     |
| `PracticeBotTemplateApplyEvent` | A template is applied to a runtime bot. | `getPreviousTemplate()`, `getNewTemplate()`, `getCause()` |

## Removal reasons

`PracticeBotRemovalReason` values:

* `MANUAL`
* `BOT_DEATH`
* `OWNER_QUIT`
* `OWNER_DEATH`
* `TARGET_QUIT`
* `TARGET_DEATH`
* `TARGET_INVALID`
* `TARGET_KILLED`
* `TEMPLATE_DESPAWN`
* `WORLD_UNLOAD`
* `SHUTDOWN`
* `CITIZENS_CLEANUP`
* `REPLACED`
* `UNKNOWN`

## Target change causes

`PracticeBotTargetChangeCause` values:

* `API`
* `AUTO_ACQUIRE`
* `AUTO_CLEAR`
* `DAMAGED_BY_TARGET`
* `TEMPLATE_BIND`
* `TEMPLATE_CLEAR`
* `UNKNOWN`

## Template apply causes

`PracticeBotTemplateApplyCause` values:

* `SPAWN`
* `API`

## Example listener

```java
public final class PracticeBotListener implements Listener {

    @EventHandler
    public void onPracticeBotSpawn(PracticeBotSpawnEvent event) {
        PracticeBotHandle bot = event.getBot();
        PracticeBotStateSnapshot state = bot.getStateSnapshot();

        Bukkit.getLogger().info("Spawned PracticeBot " + state.name()
                + " type=" + state.botType()
                + " npcUuid=" + state.npcUuid());
    }

    @EventHandler
    public void onPracticeBotDespawn(PracticeBotDespawnEvent event) {
        Bukkit.getLogger().info("PracticeBot despawned: " + event.getReason());
    }
}
```

## Event safety

Events are synchronous Bukkit events. Keep handlers lightweight. For database, web, or analytics work, copy the data you need, run the external work asynchronously, and return to the main thread before calling PracticeBot API again.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://edelweiss-network.gitbook.io/practicebot/developer-guide/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.