# installation

## Requirements

| Requirement    | Status   | Notes                                                                                       |
| -------------- | -------- | ------------------------------------------------------------------------------------------- |
| Paper          | Required | PracticeBot is built for Paper. Use a modern 1.21.x server matching your distributed build. |
| Java 21        | Required | The plugin is compiled for Java 21.                                                         |
| Citizens       | Required | PracticeBot depends on Citizens for NPC runtime.                                            |
| PlaceholderAPI | Optional | Required only if you want `%practicebot_*%` placeholders.                                   |

{% hint style="info" %}
Standard Paper is the supported deployment target. Do not assume Folia compatibility unless your purchased build explicitly says it supports Folia.
{% endhint %}

## Install steps

1. Stop the server.
2. Install Citizens in the `plugins` folder.
3. Install PracticeBot in the same `plugins` folder.
4. Optional: install PlaceholderAPI if you want placeholders.
5. Start the server once so PracticeBot can generate files.
6. Stop the server.
7. Review the generated files.
8. Start the server again.
9. Activate the license with `/pbadmin license set <key>`.
10. Run the first functional test from [First Setup Checklist](broken://pages/4cb7276ef2d094358e0f7934dac64633dfd88331).

## Generated files

PracticeBot creates these files and folders:

| File/folder         | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| `config.yml`        | Main runtime configuration.                           |
| `messages.yml`      | Command, error, status, license, and editor messages. |
| `default_inv.yml`   | Default player bot inventory and armor state.         |
| `bot_templates.yml` | Saved template bot profiles.                          |
| `gui/`              | YAML GUI layouts for menus and editors.               |

## Startup checklist

A clean startup should show these phases without errors:

* Citizens loads before PracticeBot.
* PracticeBot loads configuration files.
* GUI configuration loads.
* Template system loads.
* Commands and listeners register.
* PlaceholderAPI expansion registers if PlaceholderAPI is installed.
* Public API service registers after license validation.

## Common install mistakes

| Symptom                      | Likely cause                        | Fix                                                                         |
| ---------------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| PracticeBot does not enable  | Citizens missing or failed to load  | Install a compatible Citizens build and restart.                            |
| Commands show license lock   | License not configured or not valid | Use `/pbadmin license set <key>`.                                           |
| Placeholders do not work     | PlaceholderAPI is not installed     | Install PlaceholderAPI and restart.                                         |
| Bots do not spawn in a world | World is disabled in config         | Check `default.disabled-worlds`.                                            |
| Players cannot spawn bots    | Missing permissions                 | See [Permissions](broken://pages/2d841856415b4647053ac55fbffb7860ffab73f8). |

> **Media placeholder:** Add a screenshot of a clean console startup with private paths and license code hidden.


---

# 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/server-owner-guide/installation.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.