# spawning bots

Bots are spawned from loaded templates with `BotSpawnRequest`.

## Basic spawn

```java
Location spawn = player.getLocation();

BotSpawnRequest request = BotSpawnRequest.builder("arena_cpvp", spawn)
        .targetEntityUuid(player.getUniqueId())
        .build();

PracticeBotHandle bot = api.spawnBot(request);
```

## Request fields

| Field              |            Required | Description                                                        |
| ------------------ | ------------------: | ------------------------------------------------------------------ |
| `templateKey`      |                 Yes | Template key/name to spawn.                                        |
| `spawnLocation`    |                 Yes | Bukkit location with a non-null world. The request stores a clone. |
| `targetEntityUuid` | Depends on template | Live player target UUID for target-bound templates.                |

## Target compatibility

The API validates target compatibility against template `target-binding`.

| Template mode | Target UUID required? |     Target UUID accepted? |
| ------------- | --------------------: | ------------------------: |
| `REQUIRED`    |                   Yes |                       Yes |
| `NONE`        |                    No |                        No |
| `BOT`         |                    No | No explicit player target |

If a target is provided, it must be an online player.

## Despawn by API

```java
boolean removed = api.despawnBot(bot.getNpcUuid());
```

or:

```java
bot.despawn();
```

## Apply a template

```java
PracticeBotHandle updated = api.applyTemplate(
        bot.getNpcUuid(),
        "arena_normal",
        player.getUniqueId()
);
```

Use `applyTemplate` instead of mutating internal state.

## Example command handler

```java
public boolean spawnArenaBot(Player player, String templateKey) {
    try {
        BotSpawnRequest request = BotSpawnRequest.builder(templateKey, player.getLocation())
                .targetEntityUuid(player.getUniqueId())
                .build();

        PracticeBotHandle bot = api.spawnBot(request);
        player.sendMessage("Spawned bot " + bot.getStateSnapshot().name());
        return true;
    } catch (IllegalArgumentException | IllegalStateException ex) {
        player.sendMessage("Could not spawn PracticeBot: " + ex.getMessage());
        return true;
    }
}
```


---

# 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/spawning-bots.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.