EasyTPA

EasyTPA

The EasyTPA for your mc server

English Description

💡 Commercial Use: This plugin is free for individuals. If you are a business or generate revenue with this plugin, you must contact me to obtain authorization.

✨ Features

• Player teleportation — /tpa, /tpahere, /tpaccept, /tpdeny, /tpcancel, /tptoggle
• Homes — /home, /sethome, /delhome with per-player limit and permission tiers
• Warps — /warp, /setwarp, /delwarp, /warps with per-player ownership and clickable list
• Spawn — /spawn, /setspawn
• Back — /back (previous position or configurable death location)
• Random teleport — /rtp (alias /wild) with async chunk loading
• Reload — /tpreload
• Global cooldown configurable between two teleportations (bypassable via permission)
• Anti-movement delay — teleportation is cancelled if the player moves
• Configurable TPA timeout — requests expire automatically
• Optional permission system — can be disabled for servers without a permissions plugin
• 100% customizable messages — MiniMessage format, colors, hover, click
• Clickable warps in chat with /warps

📦 Installation

1. Download easytpa-1.0.0.jar from the Releases
2. Place the file in your server's plugins/ folder
3. Start (or restart) the server
4. Edit plugins/EasyTPA/config.yml and messages.yml to your needs
5. Reload with /tpreload (no restart needed)

Required: Paper 1.21.4+ — Java 21+

⚙️ Configuration — config.yml

# false → everyone can use player commands without permission
# true  → checks permissions (compatible with LuckPerms and any Bukkit plugin)
permissions: false

# Delay before teleportation (seconds). 0 to disable.
# The player must not move, otherwise the teleportation is cancelled.
teleport-delay: 3

# Duration (seconds) before a TPA request expires
tpa-timeout: 60

# Global cooldown between two teleportations (seconds). 0 to disable.
# Bypass with: teleport.cooldown.bypass
teleport-cooldown: 30

# /back can bring back to death location if true
back-on-death: true

# Maximum number of homes per player
# If permissions: true, extendable via teleport.home.multiple.<number>
max-homes: 1

# Maximum number of warps per player
max-warps: 5

# Maximum radius (blocks) for /rtp
rtp-radius: 5000

# Minimum radius (blocks) for /rtp (avoids spawn)
rtp-min-radius: 100

# Maximum attempts to find a safe position for /rtp
rtp-max-attempts: 20

# Message prefix (MiniMessage format)
messages-prefix: "<dark_gray>[<aqua>EasyTPA<dark_gray>]<reset> "

📋 Commands

If permissions: false in config.yml, all player commands are accessible without permission. Admin commands always require OP or teleport.admin.

🔒 Permissions

💬 Messages — messages.yml

All messages use Adventure's MiniMessage format. You can use colors, effects, clickable links, and more.

Available placeholders:

MiniMessage customization examples:

# Colors
teleport-success: "<green>Teleportation successful!"

# Gradient color
tpa-sent: "<gradient:#55ff55:#00aa00>Request sent to <player></gradient>"

# Bold text with emoji
teleport-pending: "<gold><bold>⏳ Teleporting in <delay>s... Don't move!</bold>"

# Clickable link (already used for TPA buttons)
tpa-received-buttons: "<green><click:run_command:/tpaccept>[Accept]</click>"

🏗️ Building from source

Requirements: Java 21, Maven 3.8+

git clone https://github.com/crafteria-dev/EasyTPA.git
cd EasyTPA
mvn package

The compiled JAR is located at target/easytpa-1.0.0.jar.

📁 Project structure

src/main/java/fr/easytpa/
├── EasyTPA.java                    # Main class, initialization
├── commands/                       # One file per command (17 commands)
│   ├── TpaCommand.java
│   ├── TpaHereCommand.java
│   ├── TpAcceptCommand.java
│   ├── TpDenyCommand.java
│   ├── TpCancelCommand.java
│   ├── TpToggleCommand.java
│   ├── HomeCommand.java
│   ├── SetHomeCommand.java
│   ├── DelHomeCommand.java
│   ├── WarpCommand.java
│   ├── SetWarpCommand.java
│   ├── DelWarpCommand.java
│   ├── WarpsCommand.java
│   ├── SpawnCommand.java
│   ├── SetSpawnCommand.java
│   ├── BackCommand.java
│   ├── RtpCommand.java
│   └── TpReloadCommand.java
├── managers/                       # Business logic and persistence
│   ├── ConfigManager.java          # config.yml reader
│   ├── MessageManager.java         # MiniMessage + prefix
│   ├── TpaManager.java             # TPA requests, timeout, toggle
│   ├── TeleportDelayManager.java   # Delay, anti-movement, cooldown
│   ├── CooldownManager.java        # Global per-player cooldown
│   ├── HomeManager.java            # Homes (homes.yml)
│   ├── WarpManager.java            # Warps (warps.yml)
│   ├── SpawnManager.java           # Spawn (spawn.yml)
│   └── BackManager.java            # Previous position (in-memory)
├── listeners/
│   └── TeleportListener.java       # PlayerMove, PlayerDeath, PlayerQuit
└── utils/
    ├── LocationUtils.java          # YAML serialization, safety checks
    └── PermissionUtils.java        # Player/admin permission checks

src/main/resources/
├── plugin.yml                      # Command and permission declarations
├── config.yml                      # Main configuration
└── messages.yml                    # Customizable messages

🔧 Internal workings

Teleportation flow

1. The command (e.g. /home spawn) calls TeleportDelayManager.scheduleTeleport()
2. The cooldown is checked — if active, a message is sent and the request is dropped
3. The anti-movement delay starts (teleport-delay seconds)
4. If the player moves → cancellation (PlayerMoveEvent)
5. Otherwise → executeTeleport(): saves the position for /back, calls player.teleportAsync() asynchronously
6. On success → the cooldown is updated, the callback sends the success message

Warp system

• Each warp stores the creator's UUID (warps.yml)
• A player can only delete or overwrite their own warps
• Admins (teleport.admin or OP) can manage all warps
• The max-warps limit is per player (not global)

Random teleportation (/rtp)

• Generates coordinates within a ring between rtp-min-radius and rtp-radius
• Uses world.getChunkAtAsync() to load chunks without blocking the server
• Checks position safety (2 air blocks, solid ground, no magma/campfire)
• Retries up to rtp-max-attempts times if the position is not safe

📜 License

This project is licensed under the Fair Core License (FCL).

• ✅ Free for personal use and non-commercial servers
• ✅ Modification and redistribution of source code with attribution
• ❌ Commercial use (revenue generation) without authorization is prohibited

For any commercial inquiry, contact ZO3N on GitHub.

French Description

💡 Usage Commercial : Ce plugin est gratuit pour les particuliers. Si vous êtes une entreprise ou que vous générez des revenus avec ce plugin, vous devez me contacter pour obtenir une autorisation.

✨ Fonctionnalités

• Téléportation entre joueurs — /tpa, /tpahere, /tpaccept, /tpdeny, /tpcancel, /tptoggle
• Homes — /home, /sethome, /delhome avec limite par joueur et tiers de permissions
• Warps — /warp, /setwarp, /delwarp, /warps avec propriété par joueur et liste cliquable
• Spawn — /spawn, /setspawn
• Retour — /back (position précédente ou lieu de mort configurable)
• Téléportation aléatoire — /rtp (alias /wild) avec chargement async des chunks
• Rechargement — /tpreload
• Cooldown global configurable entre deux téléportations (bypass par permission)
• Délai anti-mouvement — la téléportation est annulée si le joueur bouge
• Timeout TPA configurable — les demandes expirent automatiquement
• Système de permissions optionnel — désactivable pour les serveurs sans plugin de perms
• Messages 100 % personnalisables — format MiniMessage, couleurs, hover, click
• Warps cliquables dans le chat avec /warps

📦 Installation

1. Télécharger easytpa-1.0.0.jar depuis les Releases
2. Placer le fichier dans le dossier plugins/ de votre serveur Paper
3. Démarrer (ou redémarrer) le serveur
4. Modifier plugins/EasyTPA/config.yml et messages.yml selon vos besoins
5. Recharger avec /tpreload (inutile de redémarrer)

Requis : Paper 26.1.2+ — Java 25+

⚙️ Configuration — config.yml

# false → tout le monde peut utiliser les commandes joueur sans permission
# true  → vérifie les permissions (compatible LuckPerms et tout plugin Bukkit)
permissions: false

# Délai avant téléportation (secondes). 0 pour désactiver.
# Le joueur ne doit pas bouger, sinon la téléportation est annulée.
teleport-delay: 3

# Durée (secondes) avant expiration d'une demande TPA
tpa-timeout: 60

# Cooldown global entre deux téléportations (secondes). 0 pour désactiver.
# Contourne avec : teleport.cooldown.bypass
teleport-cooldown: 30

# /back peut ramener au lieu de mort si true
back-on-death: true

# Nombre maximum de homes par joueur
# Si permissions: true, extensible via teleport.home.multiple.<nombre>
max-homes: 1

# Nombre maximum de warps par joueur
max-warps: 5

# Rayon maximum (blocs) pour /rtp
rtp-radius: 5000

# Rayon minimum (blocs) pour /rtp (évite le spawn)
rtp-min-radius: 100

# Tentatives maximum pour trouver une position sûre pour /rtp
rtp-max-attempts: 20

# Préfixe des messages (format MiniMessage)
messages-prefix: "<dark_gray>[<aqua>EasyTPA<dark_gray>]<reset> "

📋 Commandes

Si permissions: false dans config.yml, toutes les commandes joueur sont accessibles sans permission. Les commandes admin nécessitent toujours OP ou teleport.admin.

🔒 Permissions

💬 Messages — messages.yml

Tous les messages utilisent le format MiniMessage d'Adventure. Vous pouvez utiliser des couleurs, effets, liens cliquables, etc.

Placeholders disponibles :

Exemples de personnalisation MiniMessage :

# Couleurs
teleport-success: "<green>Téléportation effectuée !"

# Couleur dégradée
tpa-sent: "<gradient:#55ff55:#00aa00>Demande envoyée à <player></gradient>"

# Texte en gras avec emoji
teleport-pending: "<gold><bold>⏳ Téléportation dans <delay>s... Ne bougez pas !</bold>"

# Lien cliquable (déjà utilisé pour les boutons TPA)
tpa-received-buttons: "<green><click:run_command:/tpaccept>[Accepter]</click>"

🏗️ Compilation depuis les sources

Prérequis : Java 25, Maven 3.8+

git clone https://github.com/crafteria-dev/EasyTPA.git
cd EasyTPA
mvn package

Le JAR compilé se trouve dans target/easytpa-1.0.0.jar.

📁 Structure du projet

src/main/java/fr/easytpa/
├── EasyTPA.java                    # Classe principale, initialisation
├── commands/                       # Un fichier par commande (17 commandes)
│   ├── TpaCommand.java
│   ├── TpaHereCommand.java
│   ├── TpAcceptCommand.java
│   ├── TpDenyCommand.java
│   ├── TpCancelCommand.java
│   ├── TpToggleCommand.java
│   ├── HomeCommand.java
│   ├── SetHomeCommand.java
│   ├── DelHomeCommand.java
│   ├── WarpCommand.java
│   ├── SetWarpCommand.java
│   ├── DelWarpCommand.java
│   ├── WarpsCommand.java
│   ├── SpawnCommand.java
│   ├── SetSpawnCommand.java
│   ├── BackCommand.java
│   ├── RtpCommand.java
│   └── TpReloadCommand.java
├── managers/                       # Logique métier et persistance
│   ├── ConfigManager.java          # Lecture de config.yml
│   ├── MessageManager.java         # MiniMessage + préfixe
│   ├── TpaManager.java             # Demandes TPA, timeout, toggle
│   ├── TeleportDelayManager.java   # Délai, anti-mouvement, cooldown
│   ├── CooldownManager.java        # Cooldown global par joueur
│   ├── HomeManager.java            # Homes (homes.yml)
│   ├── WarpManager.java            # Warps (warps.yml)
│   ├── SpawnManager.java           # Spawn (spawn.yml)
│   └── BackManager.java            # Position précédente (mémoire)
├── listeners/
│   └── TeleportListener.java       # PlayerMove, PlayerDeath, PlayerQuit
└── utils/
    ├── LocationUtils.java          # Sérialisation YAML, vérification sécurité
    └── PermissionUtils.java        # Vérification permissions joueur/admin

src/main/resources/
├── plugin.yml                      # Déclaration commandes et permissions
├── config.yml                      # Configuration principale
└── messages.yml                    # Messages personnalisables

🔧 Fonctionnement interne

Flux d'une téléportation

1. La commande (ex: /home spawn) appelle TeleportDelayManager.scheduleTeleport()
2. Le cooldown est vérifié — si actif, message et abandon
3. Le délai anti-mouvement démarre (teleport-delay secondes)
4. Si le joueur bouge → annulation (PlayerMoveEvent)
5. Sinon → executeTeleport() : sauvegarde la position pour /back, appel async player.teleportAsync()
6. En cas de succès → le cooldown est mis à jour, le callback envoie le message de succès

Système de warps

• Chaque warp enregistre l'UUID du créateur (warps.yml)
• Un joueur ne peut supprimer ou écraser que ses propres warps
• Les admins (teleport.admin ou OP) peuvent gérer tous les warps
• La limite max-warps est par joueur (pas globale)

Téléportation aléatoire (/rtp)

• Génère des coordonnées dans un anneau entre rtp-min-radius et rtp-radius
• Utilise world.getChunkAtAsync() pour charger les chunks sans bloquer le serveur
• Vérifie la sécurité de la position (2 blocs d'air, sol solide, pas de magma/feu de camp)
• Réessaie jusqu'à rtp-max-attempts fois si la position n'est pas sûre

📜 Licence

Ce projet est sous licence Fair Core License (FCL).

• ✅ Utilisation gratuite pour usage personnel et serveurs non commerciaux
• ✅ Modification et redistribution du code source avec attribution
• ❌ Utilisation commerciale (génération de revenus) sans autorisation interdite

Pour toute demande commerciale, contactez ZO3N sur GitHub.