GroupeZ Docs
Modules

Teleportation Module

Complete teleportation system with TPA, RTP, delays, and safety features

File: modules/teleportation/config.yml

The Teleportation module is a comprehensive teleportation system supporting direct teleports, teleport requests (TPA), random teleportation (RTP), configurable delays and sounds, safety checks, protection timers, biome blacklists, and world overrides. It includes a permission-based delay and protection system, allowing different behavior for different player groups.

Source Configuration

enable: true
teleport-safety: true
teleport-to-center: true
teleport-delay: 5
teleport-delay-permissions:
  - permission: "essentials.teleport.delay.vip"
    delay: 4
  - permission: "essentials.teleport.delay.staff"
    delay: 2
teleport-delay-bypass: false

# Sound played every second during the teleport countdown
countdown-sound:
  enabled: false
  sound: BLOCK_NOTE_BLOCK_HAT
  volume: 1.0
  pitch: 1.0

# Sound played when the teleportation is completed
complete-sound:
  enabled: false
  sound: ENTITY_ENDERMAN_TELEPORT
  volume: 1.0
  pitch: 1.0

teleport-tpa-expire: 60
open-confirm-inventory-for-tpa: false
open-confirm-inventory-for-tpa-here: false
rtp-worlds:
  - world: "world"
    center-x: 0
    center-z: 0
    radius-x: 5000
    radius-z: 5000
  - world: "survivalspawn"
    center-x: 0
    center-z: 0
    radius-x: 5000
    radius-z: 5000
max-rtp-attempts: 10
blacklist-biomes:
  - cold_ocean
  - deep_cold_ocean
  - deep_frozen_ocean
  - deep_lukewarm_ocean
  - deep_ocean
  - deep_warm_ocean
  - frozen_ocean
  - frozen_river
  - lukewarm_ocean
  - ocean
  - river
  - warm_ocean
teleport-protection: 1000
teleport-protections:
  - permission: "essentials.teleport.protection.vip"
    delay: 2000
  - permission: "essentials.teleport.protection.staff"
    delay: 3000
enable-random-teleport-search-log-message: true
enable-rtp-queue: false
rtp-queue-delay: 2000
enable-first-join-rtp: false
first-join-rtp-world: "world"
rtp-world-overrides:
  - from: "world_nether"
    to: "world"
  - from: "world_the_end"
    to: "world"

Options

General Options

OptionTypeDefaultDescription
enableBooleantrueEnable or disable the Teleportation module
teleport-safetyBooleantrueIf true, players teleporting to an unsafe location are moved to the nearest safe location on the same X/Z (only Y changes). If false, teleports to unsafe locations are cancelled with a warning
teleport-to-centerBooleantrueIf true, players are teleported to the center of the block (X.5, Z.5) for cleaner positioning

Teleport Delay

OptionTypeDefaultDescription
teleport-delayInteger5Default delay in seconds before a teleport is executed. If the player moves or takes damage during this time, the teleport is cancelled
teleport-delay-permissionsList(see above)Permission-based overrides for the teleport delay
teleport-delay-permissions[].permissionString-The permission node the player must have for this delay override to apply
teleport-delay-permissions[].delayInteger-The delay in seconds to use for players with this permission
teleport-delay-bypassBooleanfalseIf true, players with the essentials.teleport.bypass permission skip the teleport delay

If a player has several permissions from teleport-delay-permissions, the lowest delay is used. Players without any matching permission use teleport-delay.

Teleport Sounds

OptionTypeDefaultDescription
countdown-sound.enabledBooleanfalsePlay a sound every second during the teleport countdown
countdown-sound.soundStringBLOCK_NOTE_BLOCK_HATSound to play
countdown-sound.volumeDecimal1.0Sound volume
countdown-sound.pitchDecimal1.0Sound pitch
complete-sound.enabledBooleanfalsePlay a sound when the teleportation is completed
complete-sound.soundStringENTITY_ENDERMAN_TELEPORTSound to play
complete-sound.volumeDecimal1.0Sound volume
complete-sound.pitchDecimal1.0Sound pitch

Sounds are resolved through the zMenu XSound API, so they work on every supported Minecraft version. If the name is not a known vanilla sound, it is played as a custom sound (for example a resource pack sound such as myserver:teleport).

TPA (Teleport Ask) Options

OptionTypeDefaultDescription
teleport-tpa-expireInteger60Time in seconds before a pending TPA request expires automatically
open-confirm-inventory-for-tpaBooleanfalseIf true, opens a zMenu confirmation inventory for the sender before a /tpa request is sent
open-confirm-inventory-for-tpa-hereBooleanfalseIf true, opens a zMenu confirmation inventory for the sender before a /tpahere request is sent

When the confirmation inventory options are enabled, the player running /tpa or /tpahere gets a GUI prompt to confirm the request before it is sent to the target.

Random Teleportation (RTP) Options

OptionTypeDefaultDescription
rtp-worldsList(see above)Defines which worlds allow random teleportation and the search area for each world
rtp-worlds[].worldString-The name of the world where RTP is allowed
rtp-worlds[].center-xInteger0The X coordinate of the center point for the RTP search area
rtp-worlds[].center-zInteger0The Z coordinate of the center point for the RTP search area
rtp-worlds[].radius-xInteger5000The maximum distance from center-x on the X axis for random location selection
rtp-worlds[].radius-zInteger5000The maximum distance from center-z on the Z axis for random location selection
max-rtp-attemptsInteger10Maximum number of attempts to find a safe random location before giving up
enable-random-teleport-search-log-messageBooleantrueIf true, logs a message to the console each time the plugin searches for a random teleport location

Biome Blacklist

OptionTypeDefaultDescription
blacklist-biomesList of Strings(see above)A list of biome identifiers where random teleportation will not place players. If a selected location falls within a blacklisted biome, the plugin retries up to max-rtp-attempts

If too many biomes are blacklisted and the RTP area is small, the plugin may exhaust all attempts without finding a valid location. Increase max-rtp-attempts or expand the RTP radius if players frequently fail to find a location.

Teleport Protection

OptionTypeDefaultDescription
teleport-protectionInteger1000Default protection duration in milliseconds after teleportation. During this time, the player is immune to damage
teleport-protectionsList(see above)Permission-based overrides for the teleport protection duration
teleport-protections[].permissionString-The permission node the player must have for this protection override to apply
teleport-protections[].delayInteger-The protection duration in milliseconds for players with this permission

Teleport protection prevents players from taking damage immediately after teleporting. This is especially useful for RTP where players may land in hostile environments. The value is in milliseconds (e.g., 1000 = 1 second, 3000 = 3 seconds). As for the delay, if a player matches several entries, the lowest value is used.

RTP Queue

OptionTypeDefaultDescription
enable-rtp-queueBooleanfalseIf true, enables a queue system for RTP requests to prevent server lag from simultaneous random teleport searches
rtp-queue-delayInteger2000Delay in milliseconds between processing each queued RTP request

First Join RTP

OptionTypeDefaultDescription
enable-first-join-rtpBooleanfalseIf true, new players are automatically randomly teleported when they first join the server
first-join-rtp-worldString"world"The world in which the first-join random teleport takes place. Must be defined in rtp-worlds. Leave empty to use the player's spawn world

First join RTP is useful for survival servers that want to spread players out across the map from the start, rather than having everyone spawn at the same location.

World Overrides

OptionTypeDefaultDescription
rtp-world-overridesList(see above)Redirects RTP requests from one world to another. If a player uses /tpr in a listed from world, they are teleported to a random location in the to world instead
rtp-world-overrides[].fromString-The world where the player is currently located
rtp-world-overrides[].toString-The target world where the player will be randomly teleported

World overrides are useful for preventing RTP in dimensions like the Nether or The End, redirecting those requests back to the overworld instead.

How It Works

  1. Direct Teleports (/tp, /tphere, /tpall): Instantly teleport players to a target location or player.
  2. Teleport Requests (/tpa, /tpahere): Send a request to another player. The target can accept (/tpaccept) or deny (/tpdeny) within the expiration window. The requester can cancel with /tpacancel <player>, which removes the request from the target's pending requests.
  3. Random Teleport (/tpr): Selects a random location within the configured RTP bounds for the player's current world (or the override world), avoiding blacklisted biomes, and teleports the player there after safety checks.
  4. Back (/back): Returns the player to their previous location before the last teleport.
  5. Vertical Teleports (/top, /bottom): Teleports the player to the highest or lowest safe block at their current X/Z coordinates.
  6. World Teleport (/worldtp): Teleports a player to a specific world.

/tp Usage

SyntaxEffect
/tp <player>Teleport yourself to a player
/tp <player1> <player2>Teleport player1 to player2
/tp <x> <y> <z> [yaw] [pitch]Teleport yourself to coordinates. Relative coordinates (~, ~5) are supported
/tp <player> <x> <y> <z> [yaw] [pitch]Teleport a player to coordinates (@s targets yourself)

Request Queue

A player can receive several teleport requests at the same time:

  • /tpaccept or /tpdeny without argument handles the latest request
  • /tpaccept <player> or /tpdeny <player> handles the request of a specific player
  • /tpaccept * or /tpdeny * accepts or denies all pending requests at once

Blocking Requests

  • /tptoggle disables (or re-enables) all incoming teleport requests (/tpa and /tpahere). Staff with essentials.tp.toggle.other can use /tptoggle <player>.
  • /tpaheretoggle disables only incoming /tpahere requests. Staff with essentials.tpa.here.toggle.other can use /tpaheretoggle <player>.
  • A player who has been ignored with /ignore cannot send /tpa or /tpahere requests to the player ignoring them. See Messages Module.

/tptoggle and the ignore commands belong to the Messages Module: this module must be enabled for them to work.

Teleport Messages

The countdown and success messages (teleport-message, teleport-success, teleport-message-home, teleport-message-warp, ...) are defined in the messages file. Their internal placeholders (%seconds%, %name%, ...) are resolved for every message type, including TITLE and BOSSBAR.

CommandAliasesPermissionDescription
/tp-essentials.tpTeleport to a player, teleport a player to another player, or teleport to coordinates
/tpall-essentials.tp.allTeleport all online players to you
/tphere <player>sessentials.tp.hereTeleport a player to your location
/tpa <player>-essentials.tpaSend a teleport request to a player
/tpahere <player>-essentials.tpa.hereRequest a player to teleport to you
/tpaccept [player|*]tpyesessentials.tpa.acceptAccept the latest, a specific or all pending teleport requests
/tpdeny [player|*]tpnoessentials.tpa.denyDeny the latest, a specific or all pending teleport requests
/tpacancel <player>-essentials.tpa.cancelCancel your outgoing teleport request
/tptoggle [player]-essentials.tp.toggleToggle receiving teleport requests
/tpaheretoggle [player]-essentials.tpa.here.toggleToggle receiving /tpahere requests
/back-essentials.backTeleport to your previous location
/tprrtpessentials.tp.randomTeleport to a random location
/tpr other <player> <world>rtp otheressentials.tp.random.otherRandomly teleport another player in a world
/top-essentials.topTeleport to the highest block at your position
/bottom-essentials.bottomTeleport to the lowest safe block at your position
/worldtp <world> [player]wtpessentials.tp.worldTeleport to a specific world

For the full command list, see Commands & Permissions.

PermissionDescription
essentials.teleport.bypassSkip the teleport delay (requires teleport-delay-bypass: true)
essentials.tp.toggle.otherToggle teleport requests for another player
essentials.tpa.here.toggle.otherToggle /tpahere requests for another player
essentials.tp.world.otherTeleport another player into a world with /worldtp
essentials.teleport.delay.vipGrants VIP teleport delay (4 seconds in default config)
essentials.teleport.delay.staffGrants staff teleport delay (2 seconds in default config)
essentials.teleport.protection.vipGrants VIP teleport protection (2000ms in default config)
essentials.teleport.protection.staffGrants staff teleport protection (3000ms in default config)

The delay and protection permission nodes and their associated values are fully configurable. The permissions listed above are from the default configuration and can be changed to match your server's permission structure.

Example: Survival Server Setup

A typical survival server configuration with generous RTP bounds and ocean biome exclusion:

enable: true
teleport-safety: true
teleport-to-center: true
teleport-delay: 5
teleport-delay-permissions:
  - permission: "essentials.teleport.delay.donor"
    delay: 2
  - permission: "essentials.teleport.delay.staff"
    delay: 0
teleport-delay-bypass: false
countdown-sound:
  enabled: true
  sound: BLOCK_NOTE_BLOCK_HAT
  volume: 1.0
  pitch: 1.0
complete-sound:
  enabled: true
  sound: ENTITY_ENDERMAN_TELEPORT
  volume: 1.0
  pitch: 1.0
teleport-tpa-expire: 120
rtp-worlds:
  - world: "world"
    center-x: 0
    center-z: 0
    radius-x: 10000
    radius-z: 10000
max-rtp-attempts: 20
blacklist-biomes:
  - ocean
  - deep_ocean
teleport-protection: 3000
enable-first-join-rtp: true
first-join-rtp-world: "world"

Steps Module

Step-based progression tracking system

Vault Module

Personal player storage vaults with permission-based slot limits

On this page

Source ConfigurationOptionsGeneral OptionsTeleport DelayTeleport SoundsTPA (Teleport Ask) OptionsRandom Teleportation (RTP) OptionsBiome BlacklistTeleport ProtectionRTP QueueFirst Join RTPWorld OverridesHow It Works/tp UsageRequest QueueBlocking RequestsTeleport MessagesRelated CommandsRelated PermissionsExample: Survival Server Setup
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.