UltimateTPA Plugin - Complete Summary

---

📋 Overview

| Property | Value |
|----------|-------|
| **Plugin Name** | UltimateTPA |
| **Version** | 1.0.0 |
| **Minecraft Versions** | 1.21.1 - 1.21.x |
| **Server Software** | Paper (and forks like Purpur) |
| **Java Version** | Java 21 |
| **API** | Paper API with Kyori Adventure |

---

📝 Description

**UltimateTPA** is an all-in-one teleportation plugin designed for modern Paper Minecraft servers. It combines three essential teleportation systems into a single, lightweight JAR file:

1. **TPA System** - Player-to-player teleport requests
2. **RTP System** - Random/Wild teleportation
3. **DeathTP System** - Return to death location

The plugin features a modern codebase using Java 21, full MiniMessage support for colorful and clickable chat components, and highly configurable settings including optional warmup timers that can be completely disabled for instant teleportation.

---

🎯 Primary Uses

| Use Case | Description |
|----------|-------------|
| **Survival Servers** | Allow players to teleport to friends and explore randomly |
| **SMP Servers** | Essential teleportation features for multiplayer communities |
| **Towny/Nations** | Players can quickly meet up for trading or collaboration |
| **Adventure Servers** | RTP for exploration, death back for recovering items |
| **Mini-game Lobbies** | Quick teleportation between players |
| **Vanilla+ Servers** | Adds convenience without breaking vanilla feel |

---

✨ Features

🔄 Module 1: TPA System (Teleport Requests)

| Feature | Description |
|---------|-------------|
| **Send Requests** | `/tpa <player>` - Request to teleport to another player |
| **Open GUI (for TPA only)** | `/tpa` - Open GUI that shows all players click on their head in GUI and tpa request sent easily |
| **Accept/Deny** | Recipients can accept or deny with commands or clickable buttons |
| **Clickable Chat** | Interactive `[ACCEPT]` and `[DENY]` buttons in chat |
| **Request Expiry** | Requests automatically expire after configurable time |
| **Cooldowns** | Prevent spam with configurable cooldown between requests |
| **Toggle System** | Players can block all incoming TPA requests |
| **Auto-Accept** | Players can enable automatic acceptance of all requests |
| **Optional Warmup** | Configurable delay before teleporting (can be disabled) |
| **Cancel on Move** | Warmup cancels if player moves (configurable) |

**Commands:**
```
/tpa - Open tpa GUI (only works for tpa)
/tpa <player> - Send teleport request
/tpaccept - Accept latest request
/tpdeny - Deny latest request
/tpacancel - Cancel your sent request
/tpatoggle - Toggle incoming requests on/off
/tpaauto - Toggle auto-accept mode
/tpreload - Reload configuration
```

---

🌍 Module 2: RTP System (Random Teleport / Wild)

| Feature | Description |
|---------|-------------|
| **Random Location** | Teleport to a random safe location in the world |
| **Two Algorithms** | `CIRCLE` (natural distribution) or `SQUARE` pattern |
| **Safety Checks** | Never land in lava, water, fire, or mid-air |
| **Async Chunk Loading** | Non-blocking location finding for better performance |
| **Multi-World** | Configure different settings per world |
| **Configurable Radius** | Set min/max distance from center point |
| **Custom Center** | Define origin coordinates for RTP area |
| **Optional Warmup** | Configurable delay (can be disabled for instant TP) |
| **Cooldowns** | Prevent spam with configurable cooldown |
| **Admin Command** | Force RTP players with custom parameters |

**Commands:**
```
/wild - Teleport to random location
/rtp - Alias for /wild
/randomtp - Alias for /wild
/wildrtp - Alias for /wild
/wild info - Show RTP settings for current world
/wild reload - Reload configuration
/wild help - Show help message
/customrtp <player> <world> <minR> <maxR> <x> <z> - Admin RTP
```

**Safety Checks - Avoids:**
- Lava and fire
- Deep water
- Mid-air spawns
- Magma blocks
- Cacti and berry bushes
- Powder snow
- Campfires

---

☠️ Module 3: DeathTP System

| Feature | Description |
|---------|-------------|
| **Death Location Saved** | Automatically saves where players die |
| **Teleport Back** | `/dback` to return to death location |
| **Private Death Message** | Only the victim sees their death coordinates |
| **Clickable Return** | `[GO BACK]` button in death message |
| **Hide Global Death** | Option to cancel public death messages |
| **Persistent Locations** | Death location saved even after relog |

**Commands:**
```
/dback - Teleport to death location
/deathback - Alias for /dback
/back - Alias for /dback
/deathtp - Alias for /dback
```

---

⚙️ Configuration Highlights

Instant vs Delayed Teleportation

```yaml
INSTANT TELEPORTATION (No warmup)
tpa:
warmup:
enabled: false

rtp:
warmup:
enabled: false

DELAYED TELEPORTATION (With warmup)
tpa:
warmup:
enabled: true
seconds: 3
cancel-on-move: true

rtp:
warmup:
enabled: true
seconds: 5
```

Multi-World RTP Configuration

```yaml
rtp:
worlds:
world:
enabled: true
min-radius: 100
max-radius: 5000
center-x: 0
center-z: 0
algorithm: CIRCLE

world_nether:
enabled: true
min-radius: 50
max-radius: 1000
algorithm: CIRCLE

world_the_end:
enabled: false
```

MiniMessage Formatting

```yaml
messages:
prefix: "<gray>[<gradient:00ff88:00aaff>UltimateTPA</gradient>]</gray> "
tpa:
sent: "<green>TPA request sent to <white>{player}</white>."
received: "<green>{player}</green> <yellow>wants to teleport to you!"
click:
accept: "<green><bold>[ACCEPT]</bold></green>"
deny: "<red><bold>[DENY]</bold></red>"
```

---

🔐 Permissions

Player Permissions (Default: true)

| Permission | Description |
|------------|-------------|
| `ultimatetpa.tpa` | Send TPA requests |
| `ultimatetpa.tpa.accept` | Accept TPA requests |
| `ultimatetpa.tpa.deny` | Deny TPA requests |
| `ultimatetpa.tpa.cancel` | Cancel sent requests |
| `ultimatetpa.tpa.toggle` | Toggle incoming requests |
| `ultimatetpa.tpa.auto` | Toggle auto-accept |
| `ultimatetpa.rtp` | Use random teleport |
| `ultimatetpa.rtp.info` | View RTP information |
| `ultimatetpa.deathtp` | Use death teleport |

Admin Permissions (Default: op)

| Permission | Description |
|------------|-------------|
| `ultimatetpa.reload` | Reload configuration |
| `ultimatetpa.rtp.custom` | Use /customrtp command |
| `ultimatetpa.tpa.bypass.cooldown` | Bypass TPA cooldown |
| `ultimatetpa.rtp.bypass.cooldown` | Bypass RTP cooldown |

Wildcard Permissions

| Permission | Description |
|------------|-------------|
| `ultimatetpa.*` | All permissions |
| `ultimatetpa.tpa.*` | All TPA permissions |
| `ultimatetpa.rtp.*` | All RTP permissions |

---

🎵 Sound Effects

| Event | Default Sound |
|-------|---------------|
| Teleport | `ENTITY_ENDERMAN_TELEPORT` |
| Request Received | `ENTITY_EXPERIENCE_ORB_PICKUP` |
| Warmup Tick | `BLOCK_NOTE_BLOCK_HAT` |
| Warmup Cancel | `ENTITY_VILLAGER_NO` |
| Success | `ENTITY_PLAYER_LEVELUP` |
| Error | `ENTITY_VILLAGER_NO` |

All sounds are fully configurable with custom volume and pitch.

```

Design Patterns Used

| Pattern | Usage |
|---------|-------|
| **Singleton** | ConfigManager for global config access |
| **Manager Pattern** | Separate managers for each module |
| **Builder Pattern** | MiniMessage component building |
| **Observer Pattern** | Event listeners for game events |
| **Strategy Pattern** | RTP algorithms (CIRCLE/SQUARE) |

Performance Optimizations

| Optimization | Description |
|--------------|-------------|
| **Async Chunk Loading** | RTP uses Paper's async chunk API |
| **Efficient Move Check** | Only checks block changes, ignores head rotation |
| **ConcurrentHashMap** | Thread-safe data structures |
| **Lazy Cleanup** | Expired requests cleaned periodically |
| **Minimal Memory** | In-memory storage with automatic cleanup |

---

🚀 Quick Start Guide

Installation

1. Download or build `UltimateTPA-1.0.0.jar`
2. Place in server's `plugins/` folder
3. Start/restart the server
4. Edit `plugins/UltimateTPA/config.yml` as needed
5. Run `/tpreload` or `/wild reload` to apply changes

Recommended First Configuration

```yaml
For most servers, start with these settings:

tpa:
warmup:
enabled: true Prevent TP abuse
seconds: 3
cancel-on-move: true
request-expiry: 60
cooldown: 30

rtp:
warmup:
enabled: true
seconds: 5
cooldown: 120 2 minutes to prevent lag
max-attempts: 15

deathtp:
cancel-death-message: false Keep vanilla death messages
private-message: true Add coordinates privately
```

For Instant Teleportation

```yaml
If you want no delays at all:

tpa:
warmup:
enabled: false
cooldown: 10

rtp:
warmup:
enabled: false
cooldown: 60
```

---

🔄 Comparison with Similar Plugins

| Feature | UltimateTPA | EssentialsX | Other TPA Plugins |
|---------|-------------|-------------|-------------------|
| TPA System | ✅ | ✅ | ✅ |
| RTP System | ✅ | ❌ (separate) | ❌ |
| Death Back | ✅ | ✅ | ❌ |
| Clickable Chat | ✅ | ❌ | Some |
| MiniMessage | ✅ | ❌ | Rare |
| Optional Warmup | ✅ | ✅ | Some |
| Async RTP | ✅ | N/A | Some |
| Multi-World RTP | ✅ | N/A | Some |
| Single JAR | ✅ | ❌ (large) | ✅ |
| Paper 1.21 Native | ✅ | ✅ | Varies |
| Lightweight | ✅ | ❌ | Varies |

---

📄 License & Credits

- **Plugin:** UltimateTPA
- **Version:** 1.0.0
- **Target:** Paper 1.21.x
- **Java:** 21
- **Dependencies:** None (standalone)
- **Soft Dependencies:** Vault, LuckPerms (optional)

---

📞 Support Checklist

Before reporting issues, verify:

- [ ] Server is running Paper 1.21.x
- [ ] Java 21 is installed
- [ ] Plugin JAR is in `/plugins/` folder
- [ ] No errors in server console on startup
- [ ] Players have correct permissions
- [ ] Config syntax is valid YAML
- [ ] Ran `/tpreload` after config changes

---

**UltimateTPA - The Ultimate Teleportation Solution for Modern Minecraft Servers** 🎮✨

Need a server to run UltimateTPA?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting