UltimateTPA+++

** 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

 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

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

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

 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 🎮✨**