NexaTeleport Documentation

What is NexaTeleport?#

A modular teleport layer for player requests, random teleportation, queue-based launches, zones and admin support workflows.

Who is it for?#

SMP, Survival, Lifesteal and network owners who need configurable teleport safety, economy costs, history and polished GUIs.

Supported server types#

Paper and Spigot-style servers. Folia runtime scheduling is detected, but only claim Folia support after testing your complete setup.

Main features#

• TPA and TPAHere request flow
• No-target player selector GUI
• Random teleport worlds
• RTPQueue solo, duel, team, coop and battle modes
• Zone-triggered RTP
• History, limits, cooldowns and costs
• Public API, events and PlaceholderAPI values

Dependencies#

• Java 21
• Paper-compatible 1.21 server API
• LicenseGate key
• PlaceholderAPI optional
• Vault, CoinsEngine or PlayerPoints optional
• WorldGuard, GriefPrevention, Lands and other protection hooks optional

Setup checklist#

1. Set license-key
2. Choose modules under modules
3. Choose storage.type
4. Configure RTP worlds and radius rules
5. Configure queue mode sizes and countdowns
6. Review menus and messages
7. Assign permissions
8. Test TPA, RTP, queue and admin status

Production notes#

• Use LuckPerms or another permission manager for rank-specific limits.
• Keep SQLite files and SQL exports in regular backups.
• Test cross-server messaging on staging before using it on a live network.
• Do not disable protection checks unless your spawn, claims and regions are already protected elsewhere.

How to edit messages#

Edit plugins/NexaTeleport/messages.yml, preserve placeholder names such as <player>, then run /nexatp reload or restart.

Formatting#

<red>Error message</red>
<yellow><player></yellow>
&cLegacy color message

tpa-player-select.yml#

Player selector shown when /tpa or /tpahere is used without a target.

• Title: &8Select Player
• Size: 54
• Actions: TPA_SELECT, PAGE_PREVIOUS, PAGE_NEXT, CLOSE

tpa-confirm.yml#

Confirmation screen before sending selected TPA or TPAHere request.

• Use for request review
• Supports target placeholders

tpa-incoming.yml#

Incoming request GUI with accept and deny controls.

• Use for GUI-first request handling
• Works with request timeout

tpa-history.yml#

Paginated history menu for recent TPA activity.

• Backed by storage
• Supports page navigation

rtp-main.yml#

RTP world selector.

• Title: &8Random Teleport
• Size: 54
• Actions: RTP_WORLD, OPEN_MENU:RTP_QUEUE, ZONE_TOGGLE

rtp-confirm.yml#

Optional RTP confirmation menu before consuming cost or starting warmup.

• Use when confirmation is enabled
• Works with pending timeout

rtpqueue-main.yml#

Main queue selector for solo, duel, team, coop and battle modes.

• Title: &8RTP Queue
• Size: 36
• Actions: QUEUE_JOIN, QUEUE_STATUS, QUEUE_LEAVE

rtpqueue-status.yml#

Queue state menu for current mode, remaining time, penalties and match data.

• Use for player queue status
• Supports queue placeholders

admin-panel.yml#

Staff panel for status, requests, queue list, cache, failed logs, reload and metrics.

• Title: &8NexaTeleport Admin
• Size: 45
• Actions: COMMAND, OPEN_MENU:RTP, CLOSE

TPA values#

• %nexateleport_tpa_toggle%
• %nexateleport_tpahere_toggle%
• %nexateleport_tpa_auto%
• %nexateleport_pending_requests%

RTP and queue values#

• %nexateleport_rtp_cooldown%
• %nexateleport_rtp_last_location%
• %nexateleport_rtp_total%
• %nexateleport_queue_mode%
• %nexateleport_queue_stats%
• %nexateleport_rtp_zone%

Storage recommendation#

SQLite is suitable for one server. MySQL or MariaDB is recommended when you need centralized data, SQL backups or cross-server reporting.

Saved data#

• Player TPA preferences
• Trusted and ignored players
• Cooldowns and daily usage
• TPA history
• RTP history and last location
• Queue stats and failed teleport logs

Service access#

NexaTeleportApi api = Bukkit.getServicesManager()
    .load(NexaTeleportApi.class);

Events#

• TpaRequestCreateEvent
• TpaRequestResolveEvent
• RtpTeleportCompleteEvent
• RtpQueueUpdateEvent

Request flow#

1. Send /tpa or /tpahere.
2. Accept/deny and verify timeout.
3. Move during warmup and confirm cancellation policy.
4. Test ignore and trusted lists after a player rename.

Trust flow#

1. Add a trusted player with /tpatrust.
2. Verify auto-accept only when configured.
3. Remove trust and confirm normal request behavior.

Go-live#

• Set per-world permissions and cooldowns.
• Keep unsafe-location retry limits finite.
• Test proxy transfer and player quit during warmup.
• Monitor failed destination warnings.

Baseline#

tpa: warmup-seconds: 3 timeout-seconds: 60 cancel-on-move: true rtp: max-attempts: 20 deny-unsafe: true queue: minimum-players: 2

TPA workflow#

1. Send /tpa Steve or /tpahere Steve.
2. The target uses /tpaccept or /tpdeny; the sender can use /tpacancel.
3. Configure /tpatoggle, /tpaheretoggle, /tpauto and /tpadnd for personal receive policy.
4. Use /tpatrust only for trusted repeated requests; review ignore/trusted lists after a rename or staff action.

RTP workflow#

1. Enable the target world and set min/max radius plus biome policy.
2. Run /rtp <world> or /rtp <min> <max> and confirm the warmup.
3. If the location is unsafe, cancel and inspect blacklist, zones, protection and attempt limits.
4. For queues, use /rtp queue join, status and leave; test timeout and minimum player count.

World baseline#

queue:
  enabled: true
  timeout-seconds: 600
worlds:
  world:
    enabled: true
    min-radius: 500
    max-radius: 10000
    biome-mode: BLACKLIST

Network checklist#

Give every server a unique id, configure Redis/proxy only after local TPA/RTP works, then test heartbeat, cross-server request timeout, disconnect and duplicate request handling.

Survival SMP#

• Enable TPA and RTP
• Keep protection checks on
• Use RTP cooldown and warmup
• Set per-world RTP permissions

Lifesteal / PvP#

• Enable combat blocking
• Use movement and damage cancel
• Restrict queue team modes by permission
• Keep post-teleport protection short

Network#

• Set unique server IDs
• Configure Redis channels
• Test heartbeats and proxy transfer
• Use SQL storage for reporting

Before asking for support#

• Test on the latest available plugin version.
• Check Java and server version.
• Temporarily remove unrelated plugins when debugging conflicts.
• Attach changed YAML files when config is involved.