# Developer Guide

Welcome to the PixelRTPPool developer documentation. If you intend to fork, contribute, or write an addon for this plugin, this guide covers the core expectations.

## Building with Maven

The project relies entirely on Maven for dependency management and lifecycle builds.

**Command:**
```bash
mvn clean package
```
*Note: We utilize the `maven-shade-plugin` to shade bStats into the final jar. The compiled output will be `PixelRTPPool-1.0.0.jar` in the `target/` directory.*

## Project Structure

```
me.pixel.rtppool
├── combat       # Combat tagger hooks and providers
├── commands     # Command executors
├── config       # YAML parsing and data modeling
├── hooks        # Soft-depend external hooks (e.g., PlaceholderAPI)
├── listeners    # Bukkit event listeners
├── manager      # Central logic controllers (RTP, Cooldown, Countdown)
├── model        # Immutable data classes (e.g., RTPRegion)
├── region       # WorldGuard SessionHandlers
├── tasks        # BukkitRunnables
├── teleport     # Execution providers (PLAYER vs CONSOLE)
└── util         # Static utilities (Colors, Particles, Sounds)
```

## Coding Standards
- **Java 21 Required:** The project is compiled targeting JDK 21. Ensure your IDE is properly configured.
- **Paper API Only:** We use the `paper-api` dependency. Do not use Spigot-exclusive API methods. Use Adventure API (MiniMessage) exclusively for text formatting; legacy `ChatColor` is strictly prohibited.
- **SRP (Single Responsibility Principle):** Managers manage. Listeners listen. Do not write monolithic classes.
- **UUIDs Over Players:** Never store `org.bukkit.entity.Player` in HashMaps or Lists.

## Adding Providers

### Adding a new TeleportProvider
If you wish to add a native integration for an external plugin (e.g., BetterRTP API instead of executing commands):
1. Create a class implementing `TeleportProvider`.
2. Implement the `teleport(Player player, String commandTemplate)` method.
3. Hook it inside `TeleportManager#setupProvider()`.

### Adding a new CombatProvider
If you wish to integrate a combat tagger (e.g., CombatLogX):
1. Create a class implementing `CombatProvider`.
2. Implement `boolean isInCombat(Player player)`.
3. Hook it inside `CombatManager` during plugin initialization.

## Versioning
This project strictly adheres to [Semantic Versioning](https://semver.org/).
- `MAJOR` version for incompatible API/Config changes.
- `MINOR` version for adding functionality in a backwards compatible manner.
- `PATCH` version for backwards compatible bug fixes.

---
[🏡 Home](Home.md) | [📖 Read Next: FAQ](FAQ.md)