Teleportation

Homes, warps, TPA, staff teleports, RTP, and world manager. Config: teleport.yml, rtp.yml, waypoints.yml. Modules: teleportation, homes, warps, tpa, spawn, death-settings, rtp, waypoints, world-manager.

Commands reference: Commands: Player, Commands: Admin. Defaults: Default teleport.yml · Default rtp.yml · Default waypoints.yml · Config Reference.

Player how-to

1. Set a home: /sa sethome [name] → teleport with /sa home [name].
2. Request a teleport: /sa tpa <player> or /sa tpahere <player> → target /sa tpaccept or /sa tpdeny.
3. Use warps: /sa warps then /sa warp <name>.
4. Go to spawn: /sa spawn. Random explore: /sa rtp (or /sa rtp <world>).
5. Save a waypoint: /sa waypoint → Create, or /sa waypoint set <name>. Right-click to track (boss bar).
6. Return: /sa back after SoapsAdmin teleports, RTP, portals, or death (in-memory until logout).

Staff how-to

1. Pull / go to players: /sa tphere, /sa tpto, /sa tppos, /sa tpall, /sa tpoffline.
2. Set server spawn: /sa setspawn (and optional /sa setfirstspawn). Per-world Bukkit spawn: /sa setworldspawn.
3. Create warps: /sa setwarp <name>. Manage worlds: /sa world … (module world-manager).
4. Tune warmups/claims in teleport.yml, RTP in rtp.yml, waypoints in waypoints.yml, then /sa reload teleport / rtp / waypoints.

Config keys (teleport.yml)

Key	Default	Effect
teleportation.warmup-seconds	3	Delay before teleport (0 = instant)
teleportation.cooldown-seconds	0	Cooldown after teleport
teleportation.cancel-on-move	true	Cancel warmup if player moves >1 block
teleportation.cancel-on-damage	true	Cancel warmup on damage
teleportation.claims.enabled	true	Soft hooks for WorldGuard / Lands / GriefPrevention
teleportation.claims.block-rtp-in-claims	true	Reject RTP landings in foreign claims
teleportation.claims.block-set-in-claims	true	Block /sa sethome and /sa setwarp where player cannot build
teleportation.claims.allow-friends	true	Allow set/teleport when claim owner is a SoapsAdmin friend
homes.default-max	3	Default home limit (soapsadmin.home.limit.<n> overrides)
homes.max-name-length	16	Max home name length
warps.per-warp-permission	false	Require soapsadmin.warp.<name> per warp
tpa.timeout-seconds	60	Pending TPA expiry
tpa.cooldown-seconds	10	Cooldown between sending TPA requests
tpa.pending-bossbar	true	Boss bar countdown while a request is pending
death-settings.insta-respawn	false	Skip death screen / instant respawn
death-settings.bed-respawn	true	Allow bed/respawn-anchor respawn
death-settings.spawn-respawn	true	Respawn at server spawn when no bed
death-settings.rtp-respawn	false	Respawn via RTP (needs rtp module)

Bypass warmup/cooldown: soapsadmin.teleport.bypass. Claim bypass: soapsadmin.teleport.bypass-claims.

Homes (Shared Invite)

Action	Command
Set / delete	/sa sethome [name], /sa delhome <name>
Teleport / list	/sa home [name], /sa homes [player]
Rename / default / move	/sa home rename, setdefault, move
Share	/sa home invite <name> <player>
Unshare	/sa home uninvite <name> <player>
List shared with you	/sa home shared

Invited players teleport via shared-home resolution (owner + name). Limits: soapsadmin.home.limit.<n>. Others' homes: soapsadmin.home.others. Claim/region checks: teleport.yml → claims; bypass soapsadmin.teleport.bypass-claims.

Warps

Action	Command	Permission
Teleport	/sa warp <name>	soapsadmin.warp
List / info	/sa warps, /sa warp info <name>	soapsadmin.warp
Create / delete	/sa setwarp <name>, /sa delwarp <name>	soapsadmin.setwarp

TPA Cancel / Auto

Command	Effect
/sa tpa <player> / /sa tpahere <player>	Request
/sa tpaccept / /sa tpdeny	Respond
/sa tpacancel	Cancel outgoing
/sa tpa pending	Pending list
/sa tptoggle	Block incoming
/sa tpauto	Auto-accept

Warmup/cooldown: teleport.yml. Bypass: soapsadmin.teleport.bypass. Claim checks run before consuming a pending accept.

Staff Teleports / Jump / Offline

Command	Usage	Permission
/sa tphere <player>	Pull player to you	soapsadmin.tphere
/sa tpto <player>	Go to player	soapsadmin.tpto
/sa tppos <x> <y> <z> [world]	Absolute coords	soapsadmin.tppos
/sa tpall [world|player…]	All players, one world, or a named list to you	soapsadmin.tpall
/sa jump	Teleport to looked-at block	soapsadmin.jump
/sa top / /sa bottom	Highest / lowest block	soapsadmin.top / soapsadmin.bottom
/sa tpoffline <player>	Last logout location	soapsadmin.tpoffline
/sa back	Previous location (SoapsAdmin TPs, RTP, world TP, portals, death; in-memory until logout)	soapsadmin.back
/sa biome <biome>	Find and teleport to a biome	soapsadmin.biome
/sa spawn [player]	Server spawn	soapsadmin.spawn / spawn.others
/sa setspawn / /sa delspawn / /sa setfirstspawn	Server spawn points	soapsadmin.setspawn
/sa worldspawn	Current world's spawn	soapsadmin.worldspawn
/sa setworldspawn	Set current world's spawn	soapsadmin.setworldspawn

Server spawn vs world spawn

SoapsAdmin has two spawn systems. They are independent.

	Server spawn	World spawn
Commands	/sa setspawn, /sa spawn, /sa setfirstspawn, /sa delspawn	/sa setworldspawn, /sa worldspawn
Storage	plugins/SoapsAdmin/data/server/spawns.yml	Bukkit / vanilla world spawn (level.dat)
Scope	One (or first-join) point used across the server	Per world you are standing in
Typical use	Lobby / hub for /sa spawn and death respawn	Entry point for that world, /sa world tp, new world create

/sa spawn never uses the Bukkit world spawn. /sa worldspawn never reads spawns.yml.

Death respawn at the server spawn is controlled by death-settings.spawn-respawn in teleport.yml (module death-settings). New worlds created with the world manager get a Bukkit world spawn set on create; overwrite it with /sa setworldspawn.

RTP

Command	Usage	Permission
/sa rtp	World picker GUI (or current world if GUI off)	soapsadmin.rtp
/sa rtp <world>	Random teleport into that world	soapsadmin.rtp
/sa tprandom / /sa tp random	Teleport to a random online player	soapsadmin.tprandom

/sa tprandom cycles through online players before repeating the same target.

How search works

1. Samples random X/Z within min-radius–max-radius (from spawn, or from you when same-world-from-player and same world).
2. If the chunk is unloaded and load-chunks: true, SoapsAdmin loads/generates it, then checks height, biomes, unsafe blocks, claims.
3. On success, teleport warmup/cooldown from teleport.yml still apply; destination chunks are preloaded (3×3) before you arrive.

Platform	Chunk load during RTP
Paper	Async (getChunkAtAsync). Preferred.
Spigot	Sync getChunkAt on the main thread. Works, but may hitch under heavy generation.

Cooldown bypass: soapsadmin.rtp.bypass-cooldown. Claim blocking: teleport.yml → teleportation.claims.block-rtp-in-claims. Placeholder: %soapsadmin_rtp_cooldown%.

If search fails with CHUNK_NOT_READY and chunksLoaded=0, ensure settings.load-chunks: true in the server rtp.yml and update to 1.7.0+.

Config keys (rtp.yml)

Key	Default	Effect
settings.min-radius	500	Minimum search radius
settings.max-radius	10000	Maximum search radius
settings.max-attempts	60	Strict-pass attempts
settings.attempts-per-tick	6	Attempts spread per tick
settings.max-search-ticks	120	Search timeout in ticks
settings.cooldown	60	Seconds after a successful RTP
settings.respect-world-border	true	Stay inside world border
settings.same-world-from-player	true	Same-world RTP centers on you; cross-world still uses spawn/center
settings.load-chunks	true	Load/generate unloaded chunks during search
settings.max-pending-chunk-loads	4	In-flight chunk loads during search
settings.use-motion-blocking-no-leaves	true	Prefer surface under canopy
settings.fallback.enabled	true	Fallback pass when strict pass fails
settings.fallback.attempts	30	Fallback attempts
safety.min-y / max-y	48 / 320	Landing Y bounds
safety.require-air-above	true	Require air above feet
safety.avoid-blocks	lava/fire/…	Unsafe landing blocks
safety.avoid-biomes	ocean variants	Biomes skipped on strict pass
worlds.disabled	world_the_end	Worlds excluded from RTP

World picker look: gui.yml → menus.rtp-worlds. Reload with /sa guiconfig reload. RTP settings reload with /sa reload rtp.

World Manager

Command	Usage	Permission
/sa world list	List worlds	soapsadmin.world / worldmanager
/sa world tp|create|load|unload ...	Manage worlds	soapsadmin.worldmanager
/sa world fixgenerator <name>	Reattach void/custom generator after a bad boot load	soapsadmin.worldmanager

Module: world-manager. Settings: server.yml. New worlds get a Bukkit world spawn set on create (void: bedrock platform at 0,64,0; other types: surface at the generator spawn). Use /sa setworldspawn to overwrite it.

Void worlds

Void worlds use the named generator SoapsAdmin:void (saved into level.dat) so Paper/Spigot reattach it on restart. Meta also lives in plugins/SoapsAdmin/worlds.yml as generator: VOID.

If land suddenly appears (chunk walls of normal terrain):

1. Confirm worlds.yml has generator: VOID for that world.
2. Run /sa world fixgenerator <world> (unload → reload with void generator).
3. Already-generated terrain stays in region/. To wipe it: unload, delete the world's region/ folder (optionally keep other data), then /sa world load <world>.
4. Do not put the void world in bukkit.yml with a different generator.

Waypoints

/sa waypoint opens the waypoint list. Create waypoint places one at your feet, then opens the edit GUI (rename, move here, marker, color). You can still use /sa waypoint set <name> from chat.

Right-click a waypoint to track it. A boss bar at the top shows the name and how many meters away you are. The bar drains as you get closer. When you walk into settings.arrive-radius (default 3 blocks), the bar goes away and you get You reached waypoint <name>. Right-click again, or Stop Tracking in the GUI, to cancel.

Marker names float above the block when you are within display.marker-view-distance (default 48 blocks, same as the beam). Farther away the world marker hides so it does not become a distant black speck; tracking (boss bar / compass) still works. In the edit GUI, open Label style to change brightness, background plate, see-through, shadow, bold, and size. Server defaults live under display.label in waypoints.yml. If an old waypoints.yml is missing the new keys, jar defaults still apply: bossbar-tracking: true, bossbar-full-distance: 100, marker-view-distance falls back to beam-view-distance. Optional action bar: use-player-tracking: true.

Teleport, track, and display permissions: soapsadmin.waypoint.*. Reload: /sa reload waypoints.

Config keys (waypoints.yml)

Key	Default	Effect
settings.default-max	5	Max waypoints (soapsadmin.waypoint.limit.N overrides)
settings.max-name-length	24	Name length cap
settings.arrive-radius	3.0	Auto-stop tracking when this close
settings.max-tracking-distance	1000	Hide distance beyond this (0 = unlimited)
settings.use-player-tracking	false	Optional action-bar tracking
settings.compass-tracking	true	Point compass at tracked waypoint
settings.bossbar-tracking	true	Boss bar HUD while tracking
settings.bossbar-full-distance	100	Distance at which boss bar is full
settings.cross-world	false	Allow tracking across worlds
settings.require-safe-location	true	Reject set/update in lava/void/etc
settings.warmup-override	-1	Teleport warmup override (−1 = use teleport.yml)
display.enabled	true	World markers (BlockDisplay + label + beam)
display.owner-only	true	Owner-only markers on Paper; public on Spigot
display.beam-view-distance	48.0	Particle beam cull distance (blocks)
display.marker-view-distance	48.0	Hide BlockDisplay + label beyond this; tracking HUD still works
display.label.*	bright/soft/…	Floating name style (brightness, plate, size, …)

Related

• Commands: Player
• Commands: Staff
• Config Reference · Default teleport.yml