TeleHop

Cross-server teleportation for Paper + Velocity networks.

TeleHop is a full-featured teleportation suite designed for multi-server Minecraft networks. Every feature works seamlessly across servers, keeping your players connected no matter where they are. All data is centralised through MySQL, meaning warps, homes, and player locations are shared instantly across your entire network.

---

Features

Teleportation

• /spawn — Send players to the hub server from anywhere on the network
• /tpa — Request to teleport to another player, works across servers
• /tpahere — Pull another player to your location, cross-server
• /tpatoggle — Session-only toggle to block incoming TPA requests, network-aware
• /back — Return to your last teleport or death location, even across servers
• /rtp — Random teleport with a GUI region and dimension picker, safe landing guaranteed

Warps

• Admin Warps — /warp, /setwarp, /delwarp, /warps shared across all servers via MySQL
• Player Warps — /pwarp with per-rank limits and a public/private toggle, cross-server

Homes

• /home and /sethome — Permission-based slots (1 to 5), configurable GUI with bed colours, blocked server support, and full cross-server teleportation

Admin Tools

• /tp and /tphere — Cross-server admin teleportation
• /telehop reload/version/perms/help — Plugin management
• /listwarps, /forcedelwarp, /forcedelhome — Network-wide admin oversight

---

Highlights

• Fully cross-server — Every feature, including TPA, homes, warps, /back, and /spawn, works across your entire Velocity network
• MySQL backed — All data is stored and shared centrally with no per-server duplication; MariaDB 10.5+ is also supported
• Modular config — Enable or disable any feature per server without touching commands or removing the plugin
• Teleport effects — Configurable particles and sounds for every teleport type: spawn, TPA, RTP, warp, home, and back
• Multi-language — 6 built-in languages with automatic fallback: English, Dutch, German, Spanish, Chinese, and Polish
• LuckPerms support — Full permission-based slot and feature control out of the box
• Tab completion — Player and warp names autocomplete across the entire network
• Auto config migration — Automatically splits legacy config.yml into the new modular layout on first boot

---

Multi-Server Support

TeleHop is built from the ground up for Velocity proxy networks. It is not a single-server plugin. The Velocity-side plugin handles cross-server routing and player tracking, whilst each Paper backend handles local commands and teleportation. Communication between servers uses plugin messaging channels, with MySQL as the shared data layer.

This means:

• A player on survival can /tpa to a player on skyblock and be transferred automatically
• Homes and warps set on one server are accessible from any other server on the network
• /back tracks your last location even if it was on a different server
• TPA toggle state is propagated across servers for the duration of the session

TeleHop requires both the Velocity plugin and the Paper plugin to function. It will not work on a standalone Paper server.

---

Installation

Requirements

Software	Version
Paper	1.21+
Velocity	3.3+
Java	21+
MySQL	8.0+ (MariaDB 10.5+ also works)
LuckPerms	5.4+ (optional, recommended)

Setup Steps

1. Create a MySQL database and user for TeleHop to use
2. Place telehop-velocity-1.0.0.jar in your Velocity proxy's plugins/ folder
3. Place telehop-paper-1.0.0.jar in the plugins/ folder on each Paper backend server
4. Start Velocity once to generate the config, then stop it
5. Edit plugins/TeleHop/config/database.yml on each server with your MySQL credentials
6. Edit plugins/TeleHop/config/general.yml on each Paper server and set server-name to match the server's name in your Velocity velocity.toml
7. Restart Velocity first, then start all Paper backend servers

The database tables are created automatically on first startup. No manual SQL setup is required.

Configuration Layout

plugins/TeleHop/
  config/
    general.yml     # server-name, hub-server, language, messaging, audit
    database.yml    # MySQL connection details and pool size
    features.yml    # per-server feature toggles
    teleport.yml    # countdown, particles and sounds per teleport type
    tpa.yml         # timeout, cooldown, delay, cancel-on-move
    rtp.yml         # cooldown, delay, radius, regions, dimensions, GUI
    home.yml        # slots, GUI, beds, blocked servers, world/server colours
  storage.yml       # runtime-mutable spawn location
  languages/        # en.yml, nl.yml, de.yml, es.yml, zh.yml, pl.yml

---

Compatibility

Software	Notes
Paper 1.21+	Required for all backend servers
Velocity 3.3+	Required on the proxy
MariaDB 10.5+	Fully supported as a MySQL alternative
LuckPerms 5.4+	Optional but recommended for permission-based home slots and feature control
Geyser / Floodgate	Not officially tested
BungeeCord	Not supported; Velocity only

Hybrid server software such as Mohist or Magma is not supported and may cause unexpected behaviour.

---

Database Tables

All tables are created automatically on first startup.

Table	Purpose
players	Tracks which server each player is currently on
warps	Admin warps including name, location, and server
player_warps	Player warps with owner, name, location, and visibility
tpa_requests	Active TPA requests with timestamps
homes	Player homes including UUID, slot, server, world, and coordinates

---

Permissions

All permission nodes can be viewed in-game with /telehop perms.

Default Permissions (all players)

Node	Description
telehop.spawn	Use /spawn
telehop.rtp	Use /rtp
telehop.warp	Use /warp and /warps
telehop.pwarp	Use /pwarp
telehop.tpa	Use /tpa
telehop.tpahere	Use /tpahere
telehop.tpa.accept	Use /tpaaccept
telehop.tpa.deny	Use /tpadeny
telehop.tpa.cancel	Use /tpacancel
telehop.tpa.toggle	Use /tpatoggle
telehop.homes	Use /home and /sethome
telehop.homes.1	1 home slot (default)

Home Slots

The plugin uses the highest matching telehop.homes.<n> node. Locked slots display as blue beds in the GUI.

Node	Effect
telehop.homes.1	1 home slot
telehop.homes.2	2 home slots
telehop.homes.3	3 home slots
telehop.homes.4	4 home slots
telehop.homes.5	5 home slots

Player Warp Limits

The plugin uses the highest matching telehop.warps.<n> node. If a player has both telehop.warps.3 and telehop.warps.10, they get 10.

Node	Effect
telehop.warps.1	1 player warp
telehop.warps.3	3 player warps
telehop.warps.10	10 player warps
telehop.warps.100	100 player warps
telehop.warps.unlimited	No limit
(no permission)	Cannot create warps; can still use admin warps

Per-Warp Access

Node	Description
telehop.warp.<name>	Access a specific admin warp (e.g. telehop.warp.shop)

Admin Permissions

Node	Description
telehop.admin	/setwarp, /delwarp, /listwarps, /forcedelwarp, /forcedelhome, /telehop reload, /telehop perms, /pwarp admin del
telehop.back	Use /back
telehop.back.death	Use /back death
telehop.tp	Cross-server admin teleport /tp
telehop.tphere	Cross-server admin pull /tphere
telehop.rtp.bypasscooldown	Skip the RTP cooldown
telehop.rtp.bypassdelay	Skip the RTP warmup delay
telehop.tpa.bypasscooldown	Skip the TPA cooldown
telehop.warps.unlimited	Unlimited player warps

LuckPerms Quick Setup

# Default rank: 3 player warps, 1 home slot (already default)
lp group default permission set telehop.warps.3

# VIP rank: 10 player warps, 3 home slots
lp group vip permission set telehop.warps.10
lp group vip permission set telehop.homes.3

# MVP rank: unlimited warps, 5 home slots
lp group mvp permission set telehop.warps.unlimited
lp group mvp permission set telehop.homes.5

# Staff: all admin commands + back
lp group staff permission set telehop.admin
lp group staff permission set telehop.tp
lp group staff permission set telehop.tphere
lp group staff permission set telehop.back
lp group staff permission set telehop.back.death
lp group staff permission set telehop.warps.unlimited
lp group staff permission set telehop.homes.5

---

Developed by Epildev — MIT Licence — free to use, modify, and distribute