# bot handles and state

`PracticeBotHandle` is the stable public object for interacting with an active runtime bot.

## Handle methods

| Method                        | Description                                                            |
| ----------------------------- | ---------------------------------------------------------------------- |
| `getNpcUuid()`                | Citizens NPC UUID.                                                     |
| `getEntityUuid()`             | Live entity UUID if spawned.                                           |
| `isActive()`                  | True if the bot is still an active PracticeBot runtime NPC.            |
| `getStateSnapshot()`          | Immutable state snapshot.                                              |
| `getCurrentTarget()`          | Current target snapshot if present.                                    |
| `getCurrentTemplate()`        | Current template view if template-controlled.                          |
| `despawn()`                   | Despawns the bot using manual removal semantics.                       |
| `setTarget(UUID)`             | Sets a target for non-template-controlled compatible runtime bots.     |
| `clearTarget()`               | Clears the target for non-template-controlled compatible runtime bots. |
| `updateCpvpSettings(request)` | Applies supported CPvP runtime setting changes.                        |
| `setMetadata(...)`            | Writes addon metadata.                                                 |
| `getMetadata(...)`            | Reads one metadata value.                                              |
| `getMetadataSnapshot()`       | Reads all metadata for the bot.                                        |
| `hasMetadata(...)`            | Checks if a key exists.                                                |
| `removeMetadata(...)`         | Removes metadata.                                                      |

## State snapshot fields

`PracticeBotStateSnapshot` includes:

| Field                  | Meaning                                            |
| ---------------------- | -------------------------------------------------- |
| `npcUuid`              | Citizens NPC UUID.                                 |
| `entityUuid`           | Live Bukkit entity UUID, nullable.                 |
| `name`                 | NPC name.                                          |
| `botType`              | `NORMAL`, `CPVP`, or `DUMMY`.                      |
| `spawned`              | Whether the NPC is spawned.                        |
| `alive`                | Whether the live entity is alive.                  |
| `inCombat`             | Whether the bot is currently considered in combat. |
| `pvpEnabled`           | Normal PvP enabled state.                          |
| `cpvpEnabled`          | Crystal PvP enabled state.                         |
| `anchoringMode`        | CPvP anchor mode state.                            |
| `blockBreaking`        | CPvP block-breaking state.                         |
| `frozen`               | Frozen state.                                      |
| `templateControlled`   | Whether a runtime template is applied.             |
| `autoTargetingEnabled` | Whether auto-targeting is active.                  |
| `autoTargetBotsOnly`   | Whether auto-targeting is restricted to bots.      |
| `ownerUuid`            | Owning player UUID, nullable.                      |
| `templateKey`          | Current template key, nullable.                    |
| `location`             | Immutable location snapshot, nullable.             |
| `target`               | Target snapshot, nullable.                         |

## Location snapshot

`PracticeBotLocationSnapshot` avoids exposing mutable Bukkit `Location` state:

```java
PracticeBotStateSnapshot state = bot.getStateSnapshot();
state.locationOptional().ifPresent(location -> {
    String world = location.worldName();
    double x = location.x();
    double y = location.y();
    double z = location.z();
});
```

## Target snapshot

`PracticeBotTargetSnapshot` contains:

* entity UUID
* NPC UUID when the target is a bot
* name
* kind: `HUMAN` or `BOT`

## Template-controlled target rule

Template-controlled bots reject direct public target mutation through `setTarget` and `clearTarget`. Use `applyTemplate` or spawn the template with the correct target instead.


---

# 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/bot-handles-and-state.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.