# public api reference

## Package boundary

Supported public package:

```
com.sheldera.practicebot.api.*
```

Unsupported packages:

```
com.sheldera.practicebot.internal.*
com.sheldera.practicebot.cpvp.*
com.sheldera.practicebot.bot.*
com.sheldera.practicebot.template.*
com.sheldera.practicebot.gui.*
```

## `PracticeBotApi`

| Method                                                                                           | Description                                          |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `String getApiVersion()`                                                                         | Returns public API version.                          |
| `Optional<PracticeBotHandle> getBotByNpcUuid(UUID npcUuid)`                                      | Looks up an active runtime bot by Citizens NPC UUID. |
| `Optional<PracticeBotHandle> getBotByEntityUuid(UUID entityUuid)`                                | Looks up an active runtime bot by live entity UUID.  |
| `List<PracticeBotHandle> getActiveBots()`                                                        | Lists active runtime bots.                           |
| `Optional<BotTemplateView> getTemplate(String templateKeyOrName)`                                | Looks up a template by key/name/display name.        |
| `List<BotTemplateView> getTemplates()`                                                           | Lists loaded templates.                              |
| `PracticeBotHandle spawnBot(BotSpawnRequest request)`                                            | Spawns a bot from a validated request.               |
| `boolean despawnBot(UUID npcUuid)`                                                               | Despawns a bot.                                      |
| `PracticeBotHandle applyTemplate(UUID npcUuid, String templateKeyOrName, UUID targetEntityUuid)` | Applies a template to a runtime bot.                 |
| `PracticeBotHandle updateCpvpSettings(UUID npcUuid, CpvpSettingsUpdateRequest request)`          | Applies selected CPvP runtime changes.               |

## `PracticeBotType`

```java
NORMAL
CPVP
DUMMY
```

## `BotSpawnRequest`

```java
BotSpawnRequest request = BotSpawnRequest.builder("arena_cpvp", location)
        .targetEntityUuid(player.getUniqueId())
        .build();
```

## `PracticeBotMetadataType`

```java
STRING
BOOLEAN
INTEGER
LONG
DOUBLE
UUID
```

## Public events

* `PracticeBotSpawnEvent`
* `PracticeBotDespawnEvent`
* `PracticeBotDeathEvent`
* `PracticeBotKillEvent`
* `PracticeBotTargetChangeEvent`
* `PracticeBotCombatStartEvent`
* `PracticeBotCombatStopEvent`
* `PracticeBotTemplateApplyEvent`

## Main-thread rule

Unless documented otherwise, use the API on the server main thread. Metadata read methods are the documented exception.


---

# 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/reference/public-api-reference.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.