UltimateTPA+++

** UltimateTPA Plugin - Complete Summary

---

📋 Overview

| Property | Value | |----------|-------| | API | UltimateTPA | | API | 1.0.0 | | API | 1.21.1 - 1.21.x | | API | Paper (and forks like Purpur) | | API | 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. DeathTP System - Player-to-player teleport requests 2. DeathTP 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 | |----------|-------------| | Vanilla+ Servers | Allow players to teleport to friends and explore randomly | | Vanilla+ Servers | Essential teleportation features for multiplayer communities | | Vanilla+ Servers | Players can quickly meet up for trading or collaboration | | Vanilla+ Servers | RTP for exploration, death back for recovering items | | Vanilla+ Servers | Quick teleportation between players | | Vanilla+ Servers | Adds convenience without breaking vanilla feel |

---

✨ Features

🔄 Module 1: TPA System (Teleport Requests)

| Feature | Description | |---------|-------------| | Cancel on Move | `/tpa <player>` - Request to teleport to another player | | Cancel on Move | `/tpa` - Open GUI that shows all players click on their head in GUI and tpa request sent easily | | Cancel on Move | Recipients can accept or deny with commands or clickable buttons | | Cancel on Move | Interactive `[ACCEPT]` and `[DENY]` buttons in chat | | Cancel on Move | Requests automatically expire after configurable time | | Cancel on Move | Prevent spam with configurable cooldown between requests | | Cancel on Move | Players can block all incoming TPA requests | | Cancel on Move | Players can enable automatic acceptance of all requests | | Cancel on Move | 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 | |---------|-------------| | Admin Command | Teleport to a random safe location in the world | | Admin Command | `CIRCLE` (natural distribution) or `SQUARE` pattern | | Admin Command | Never land in lava, water, fire, or mid-air | | Admin Command | Non-blocking location finding for better performance | | Admin Command | Configure different settings per world | | Admin Command | Set min/max distance from center point | | Admin Command | Define origin coordinates for RTP area | | Admin Command | Configurable delay (can be disabled for instant TP) | | Admin Command | 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 | |---------|-------------| | Persistent Locations | Automatically saves where players die | | Persistent Locations | `/dback` to return to death location | | Persistent Locations | Only the victim sees their death coordinates | | Persistent Locations | `[GO BACK]` button in death message | | Persistent Locations | 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 | |---------|-------| | Strategy Pattern | ConfigManager for global config access | | Strategy Pattern | Separate managers for each module | | Strategy Pattern | MiniMessage component building | | Strategy Pattern | Event listeners for game events | | Strategy Pattern | RTP algorithms (CIRCLE/SQUARE) |

Performance Optimizations

| Optimization | Description | |--------------|-------------| | Minimal Memory | RTP uses Paper's async chunk API | | Minimal Memory | Only checks block changes, ignores head rotation | | Minimal Memory | Thread-safe data structures | | Minimal Memory | 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

- Soft Dependencies: UltimateTPA - Soft Dependencies: 1.0.0 - Soft Dependencies: Paper 1.21.x - Soft Dependencies: 21 - Soft 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 🎮✨**