Teleportation

Commands 37#

/setspawn
/setwarp spawn
/setwarp market
/warps
/warpinfo market
/warp market Steve

/sethome home
/sethome farm
/homes
/renamehome farm barn
/home barn
/home

/tptoggle off
/tpa Steve
/tptoggle on
/tpa Steve
/tpaccept
/tpo Steve

/tpoffline Steve
/settpr wild
/tpr wild

/tpall
/tppos ~ ~10 ~
/tphere Steve
/back

Permissions 61#

Detailed guide#

Version: 1.0.5+build.54 · Config: config.json → teleportation / generalSettings sections

Overview#

Full teleportation suite — homes, warps, player warps, spawn, TPA requests, random teleport, direct TP commands, and utility teleports. All with safe-location detection, delay/warmup, and /back support.

Safe Location Detection#

All teleport destinations are checked for safety: - Feet block must have a solid collision shape (correctly handles slabs, stairs, glass, trapdoors) - Head block must be passable (air, non-solid) - Dangerous blocks are rejected: lava, fire, soul fire, magma, cactus, sweet berry bush, wither rose, nether portal, campfire, soul campfire, powder snow - A top-down column scan finds the surface first, then an expanding XZ radius search as fallback - Safety can be disabled per feature in config

Chunk Loading & Safety Interaction#

Before any teleport fires, NeoEssentials force-loads the destination chunks to ensure the target location is fully loaded in memory. This happens regardless of whether safety checks are enabled.

How it works#

1. A 3×3 grid of chunks centred on the destination is loaded via ServerLevel.getChunkSource().addRegionTicket() using the FORCED ticket type.
2. Safety validation (if enabled) runs after chunk loading, so the safety scanner always has valid block data to work with.
3. Once the teleport completes the forced-load tickets are released; normal chunk unloading resumes.

Disabling safety checks#

Setting enableHomeTeleportSafety, enableWarpSafety, or enableSpawnSafety to false in config.json completely bypasses the block-level validation step. The chunks are still preloaded, but the player is teleported directly to the stored coordinates without any safe-location search.

Warning: Disabling safety can land players inside blocks or above the void if the destination has changed since the location was saved.

When teleport fails due to unloaded chunks#

If chunk loading itself fails (e.g., the target dimension is unavailable or the world is being unloaded), the teleport is cancelled with a descriptive error message that includes the world name and coordinates so the player knows exactly where the failed destination was.

Configuration quick-reference#

Homes#

Commands#

Aliases: /h for /home · /createhome for /sethome · /deletehome, /removehome, /rhome for /delhome · /homelist//listhomes for /homes. /h, /createhome, /removehome, /rhome are skipped automatically if a conflicting mod (FTB Essentials, Essentials) is detected.

Overwriting an existing home with /sethome <name> requires confirmation, same as /delhome — you'll be prompted with clickable /sethome confirm//sethome deny buttons.

Config (teleportation.homeSettings)#

teleportDelay (warmup before the teleport fires) and cancelOnMovement (cancel if the player moves during warm-up) are global settings under generalSettings, not per-feature — see the table below.

Warmup & Cooldown Behaviour#

Warps#

Commands#

Aliases: /createwarp//addwarp for /setwarp · /deletewarp, /removewarp, /rwarp for /delwarp · /warplist//listwarps for /warps.

Set perWarpPermission: true in config to require neoessentials.warps.<name> per warp.

Warp cooldown is configured via teleportation.warpSettings.warpCooldown in config.json (seconds; 0 = no cooldown).

Server-wide warp limit defaults to 50 total warps and, unlike the per-feature settings above, is not currently read from config.json at runtime — it's tracked in the warp data store's own internal record. The dashboard's Teleportation settings page shows/edits a warpSettings.maxWarps value in config.json, but changing it there has no effect on the actual enforced limit.

Spawn#

Spawn cooldown is configured via teleportation.spawnSettings.spawnCooldown in config.json (seconds; 0 = no cooldown). Warmup is controlled globally by generalSettings.teleportDelay + generalSettings.enableTeleportWarmup.

Teleport Requests (TPA)#

Random Teleport#

Config (teleportation.randomTeleportSettings)#

The built-in "default" named location under randomTeleportSettings.locations additionally excludes all ocean variants and minecraft:the_void — configure per-location via /settpr <name>.

Biome-Select GUI (mode: "gui")#

When enabled, bare /tpr//rtp opens a paginated chest GUI instead of teleporting instantly:

• One slot per biome the current dimension can actually generate — this is read live from the dimension's own generator (BiomeSource.possibleBiomes()), so modded biomes appear automatically with no configuration needed. 45 biomes per page, with prev/close/next nav buttons.
• A dedicated "Random — Any Biome" button (bottom-right) behaves exactly like plain /tpr — no biome constraint, uses the normal cached random-teleport path.
• Clicking a specific biome closes the GUI and searches for that biome using the same engine /locate biome uses (ServerLevel.findClosestBiome3d) from a jittered center within the configured range, then finds a safe Y the same way plain RTP does. If no match turns up within biomeSearchRadius blocks or the match falls outside the world border, the player gets a clear "could not find that biome within the server border" error instead of being teleported somewhere unexpected.
• /tpr <locationName> (an explicit location argument) always bypasses the GUI, even in "gui" mode — the GUI only intercepts the bare, no-argument form.
• Same neoessentials.teleport.tpr permission gates both the plain command and the GUI — no separate permission node.

Biome icons

Every biome gets a default icon — a wooded biome shows its own sapling/propagule/fungus (the "growable" item, not the log), and biomes with no tree of their own show a block unique to that biome (sand for desert, water bucket for ocean, netherrack for nether wastes, etc.). Anything not in that built-in table (every biome from a mod that isn't specifically supported) falls back to a generic minecraft:grass_block icon.

biomeMenuItems — pinning and icon overrides

"biomeMenuItems": [
  // Pin to a fixed slot (0 = top-left box, 1 = next box, ... 44 = last box on page 1),
  // keep the default icon (spruce_sapling, from the built-in table):
  { "slot": 0, "biome": "minecraft:taiga" },

  // Pin to a slot AND override the icon:
  { "slot": 1, "biome": "minecraft:desert", "item": "minecraft:cactus" },

  // Icon-only override, no slot — stays auto-positioned like any other biome,
  // just with a custom icon (this is also how to support a biome mod's own
  // saplings, since this mod can't auto-detect a modded biome's tree species):
  { "biome": "biomesoplenty:redwood_forest", "item": "biomesoplenty:redwood_sapling" }
]

Both slot and item are independently optional. A pin only reserves its slot on page 1; pinned biomes are removed from the auto-listed pool (shown once, at their pinned position) — every other biome, including unrecognized/modded ones, still fills the remaining slots automatically in alphabetical order, continuing onto later pages exactly as if no pins existed. A pin referencing a biome that doesn't exist in the current dimension, or a slot outside 0-44, is silently skipped — it can't break the GUI.

Cancelling an in-progress /tpr#

/tpr runs through the same warmup as /home//warp//tpa (teleportation.generalSettings. teleportDelay, 3 seconds by default) — just move and it cancels, same as any other teleport (generalSettings.cancelOnMovement, on by default). /tpr now announces this ("Teleporting in 3 second(s) — move to cancel.") when the warmup starts, so it's actually visible instead of a silent delay with no indication it could be interrupted. There's no separate /tpr cancel command — moving during the warmup already is the cancel.

Performance — why RTP could lag or crash a server#

Every teleport into terrain that hasn't been visited/generated before forces a real, main- thread-blocking chunk generation — there's no way around this for a genuinely random destination, but a naive implementation can force far more of these per /tpr than actually necessary, which is exactly what was happening before this was fixed:

• The safety-preload step used to force-generate a 3×3 grid (9 chunks) around every teleport destination unconditionally, even for RTP, which already verifies its own landing spot and never reads the 8 neighbour chunks at all. Fixed — RTP now only force-loads the one chunk it actually lands in.
• Refilling the background location cache after a successful teleport used to fire the entire gap up to cacheThreshold (up to 10 forced generations) as one burst immediately after the teleport — a second lag spike stacked right on top of the teleport's own cost. Fixed via prewarmBatchSize — now only a couple of new slots are force-generated per use, and the cache tops back up gradually across several /tpr calls instead of all at once.
• defaultMaxRange/findAttempts/cacheThreshold defaults were lowered (10000→5000, 10→6, 10→5) — smaller/fewer attempts by default means less chance of repeatedly pushing into brand-new, ungenerated territory on a server that hasn't pre-generated terrain around itself.

If /tpr is still causing lag/crashes after updating: pre-generate terrain out to your players' expected roaming radius (a chunk pre-generator mod, or just having players explore normally, both work — subsequent /tpr uses landing in already-generated terrain are cheap). Lowering defaultMaxRange further, or findAttempts, reduces worst-case cost at the expense of a higher "no safe location found" retry rate.

Admin Teleport Commands#

Utility Teleports#

Data Files#

All teleportation data is persisted through the pluggable DataStore backend (JSON by default — see Storage Backend), not dedicated bespoke files:

Legacy files: neoessentials/playerdata/homes/<uuid>.json, neoessentials/homes.json, neoessentials/warps.json, playerwarps.json, and neoessentials/spawn.json are the pre-DataStore on-disk formats. They are only read once, automatically, to migrate their contents into the DataStore collections above — they are never written to again afterward.

Back to Wiki Home