# README

PracticeBot is a premium Citizens-based PvP bot platform for Paper servers. It provides player-spawned practice bots, staff-controlled template bots, Crystal PvP training, editable GUIs, PlaceholderAPI placeholders, and a stable public API for addon developers.

{% hint style="success" %}
This documentation is written for public distribution. It explains how to install, configure, use, and integrate with PracticeBot without exposing private source-code internals, license infrastructure, obfuscation details, private endpoints, development paths, or implementation-sensitive combat logic.
{% endhint %}

## Who this documentation is for

| Audience         | Start here                                                                                                     | Purpose                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Server owners    | [Installation](/practicebot/server-owner-guide/installation.md)                                                | Install the plugin, activate the license, configure public access, and test bots safely. |
| Staff/admins     | [Commands](/practicebot/server-owner-guide/commands.md) and [Template Editor](/practicebot/template-editor.md) | Manage bots, templates, GUI layouts, and arena setups.                                   |
| Players          | [Player Usage](/practicebot/player-usage.md)                                                                   | Learn how to spawn and control personal bots.                                            |
| Addon developers | [API Overview](/practicebot/developer-guide/api-overview.md)                                                   | Build integrations using the public API only.                                            |

## Main features

* Citizens-powered NPC practice bots
* Normal melee PvP bots
* Crystal PvP bots with configurable difficulty, timing, pearls, gapples, obsidian placement, block breaking, strafing, and optional respawn-anchor mode
* Dummy bots for passive targets and controlled training scenarios
* Player spawn GUI
* Per-bot settings GUI
* Default inventory and armor-trim editor
* Live template editor with preview NPCs
* Template-controlled arena bots
* Configurable GUI files with legacy color, hex color, RGB, and gradient formatting
* PlaceholderAPI support
* Bukkit Services API for third-party addons

## Recommended reading order

For a new server setup:

1. [Installation](/practicebot/server-owner-guide/installation.md)
2. [License Activation](/practicebot/server-owner-guide/license.md)
3. [First Setup Checklist](/practicebot/server-owner-guide/first-setup.md)
4. [Commands](/practicebot/server-owner-guide/commands.md)
5. [Permissions](/practicebot/permissions.md)
6. [Configuration](/practicebot/server-owner-guide/configuration.md)
7. [Templates](/practicebot/templates-1.md)
8. [Troubleshooting](/practicebot/troubleshooting.md)

For addon development:

1. [API Overview](/practicebot/developer-guide/api-overview.md)
2. [Setup and Dependency](/practicebot/setup-and-dependency.md)
3. [Service Access](/practicebot/service-access.md)
4. [Spawning Bots](/practicebot/spawning-bots.md)
5. [Bot Handles and State](/practicebot/developer-guide/bot-handles-and-state.md)
6. [Events](/practicebot/developer-guide/events.md)
7. [Threading and Safety](/practicebot/threading-and-safety.md)

## Public boundary

PracticeBot supports public integration through `com.sheldera.practicebot.api.*`. Addons should not import internal implementation packages, Citizens traits, manager classes, combat classes, movement classes, license classes, GUI internals, or template editor internals.

The public API is intentionally limited to stable integration operations: bot lookup, bot spawning, template lookup, template application, immutable snapshots, metadata, lifecycle events, and a small set of validated CPvP runtime setting updates.

## Media placeholders

Several pages include clear media placeholders such as:

> **Media placeholder:** Add a short GIF of the `/pb spawn` GUI here.

Use [Media Guide](/practicebot/server-owner-guide/media-guide.md) as the checklist for screenshots and GIFs to add after importing the documentation into GitBook.


---

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