# template reference

This reference summarizes `bot_templates.yml`.

## Template root

```yaml
templates:
  arena_normal:
    name: "Arena Normal"
    display-name: "ArenaBot"
    bot-type: NORMAL
```

Each child under `templates:` is a template key.

## General fields

| Field                   | Type    | Values                                   |
| ----------------------- | ------- | ---------------------------------------- |
| `name`                  | string  | Any readable name.                       |
| `display-name`          | string  | NPC name.                                |
| `skin-name`             | string  | Player skin name or empty.               |
| `bot-type`              | enum    | `NORMAL`, `CPVP`, `DUMMY`                |
| `allow-gui`             | boolean | Usually false for template runtime bots. |
| `target-binding`        | enum    | `REQUIRED`, `NONE`, `BOT`                |
| `death-mode`            | enum    | `REMOVE`, `RESPAWN`                      |
| `kill-mode`             | enum    | `DESPAWN`, `RESPAWN`, `NONE`             |
| `respawn-delay-seconds` | integer | Delay before respawn.                    |
| `warm-up-seconds`       | integer | Delay before fighting.                   |

## `settings`

Used by `NORMAL` and `DUMMY` templates.

| Field                 | Type                 |
| --------------------- | -------------------- |
| `look-at-target`      | boolean              |
| `follow-target`       | boolean              |
| `random-walk`         | boolean              |
| `hold-shield`         | boolean              |
| `use-shield`          | boolean              |
| `resistance`          | boolean              |
| `frozen`              | boolean              |
| `shield-in-main-hand` | boolean              |
| `pvp-enabled`         | boolean; Normal only |

## `combat`

Used by `NORMAL` templates.

| Field            | Type    | Values                                    |
| ---------------- | ------- | ----------------------------------------- |
| `strafe`         | boolean | true/false                                |
| `wtap`           | boolean | true/false                                |
| `stap`           | boolean | true/false                                |
| `crits`          | boolean | true/false                                |
| `shield-breaker` | boolean | true/false                                |
| `retreat`        | boolean | true/false                                |
| `reach-mode`     | enum    | `SHORT`, `NORMAL`, `EXTENDED`, `ADVANCED` |
| `aggression`     | enum    | `LOW`, `MEDIUM`, `HIGH`                   |
| `crit-chance`    | integer | 25, 50, 75, 100                           |
| `crit-speed`     | enum    | `SLOW`, `NORMAL`, `FAST`                  |

## `inventory`

Used by all template types.

| Field                    | Description                                  |
| ------------------------ | -------------------------------------------- |
| `helmet-material`        | Armor material string.                       |
| `chestplate-material`    | Armor material string.                       |
| `leggings-material`      | Armor material string.                       |
| `boots-material`         | Armor material string.                       |
| `helmet-enchant`         | `protection`, `blast_protection`, or `none`. |
| `chestplate-enchant`     | `protection`, `blast_protection`, or `none`. |
| `leggings-enchant`       | `protection`, `blast_protection`, or `none`. |
| `boots-enchant`          | `protection`, `blast_protection`, or `none`. |
| `offhand-type`           | `totem`, `shield`, or `none`.                |
| `totem-count`            | Totem amount.                                |
| `main-hand.material`     | Bukkit material name.                        |
| `main-hand.amount`       | Item amount.                                 |
| `main-hand.unbreakable`  | Boolean.                                     |
| `main-hand.enchantments` | Enchantment keys and levels.                 |
| `trims.<piece>.pattern`  | Armor trim pattern or empty.                 |
| `trims.<piece>.material` | Armor trim material or empty.                |

## Armor material values

Common supported values:

* `leather`
* `copper`
* `gold`
* `chain`
* `iron`
* `diamond`
* `netherite`

## `cpvp`

Used by `CPVP` templates.

| Field                                       | Type        |
| ------------------------------------------- | ----------- |
| `enabled`                                   | boolean     |
| `skill-level`                               | preset name |
| `aggression-weight`                         | number      |
| `use-pearls`                                | boolean     |
| `use-mace`                                  | boolean     |
| `use-golden-apples`                         | boolean     |
| `place-obsidian`                            | boolean     |
| `break-blocks`                              | boolean     |
| `strafing-enabled`                          | boolean     |
| `anchoring-mode`                            | boolean     |
| `heal-threshold`                            | number      |
| `low-hp-crystal-lethal-reserve`             | number      |
| `pearl-cooldown-ms`                         | integer     |
| `fov-degrees`                               | number      |
| `place-delay-min-ms`                        | integer     |
| `place-delay-max-ms`                        | integer     |
| `break-delay-min-ms`                        | integer     |
| `break-delay-max-ms`                        | integer     |
| `sword-delay-ms`                            | integer     |
| `reaction-hesitation-chance-percent`        | integer     |
| `reaction-hesitation-min-ms`                | integer     |
| `reaction-hesitation-max-ms`                | integer     |
| `crystal-miss-chance-percent`               | integer     |
| `crystal-miss-min-ms`                       | integer     |
| `crystal-miss-max-ms`                       | integer     |
| `non-urgent-pearl-restraint-chance-percent` | integer     |

## Minimal Normal template

```yaml
templates:
  arena_normal:
    name: "Arena Normal"
    display-name: "ArenaBot"
    bot-type: NORMAL
    allow-gui: false
    target-binding: REQUIRED
    death-mode: RESPAWN
    kill-mode: DESPAWN
    respawn-delay-seconds: 3
    warm-up-seconds: 0
    skin-name: ""
    settings:
      look-at-target: true
      follow-target: false
      random-walk: false
      hold-shield: false
      use-shield: true
      resistance: false
      frozen: false
      shield-in-main-hand: false
      pvp-enabled: true
    combat:
      strafe: true
      wtap: false
      stap: false
      crits: true
      shield-breaker: true
      retreat: false
      reach-mode: NORMAL
      aggression: MEDIUM
      crit-chance: 75
      crit-speed: NORMAL
```


---

# 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/template-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.