GITHUB  •  DOCUMENTATION  •  DISCORD

What Wormholes actually is

Build a portal in any flat connected shape, see the destination through it, and step through. Link worlds on one server, or portals across separate servers. Use dimensional doors to take the portal with you.

Four features that share one portal.

1. Portals in any shape Place runes retrieved from /wormholes wand in any flat connected shape, then click it with the wand to activate your portal.

2. A live view through the frame The destination is rendered inside the opening from your own eye position, so it shifts as you move and widens as you approach.

3. Dimensional Doors Craftable doors and trapdoors that link to each other, or open into a private 32x32x32 pocket room that is yours alone.

4. Cross-server portals Link multiple servers together without a proxy server, you can even see the live view of where you would be teleported.

Making your first portal

Install

1. Drop the jar in plugins/ and start the server.

2. Config appears at plugins/Wormholes/config/wormholes.toml with every key visible and commented. It hot-reloads on save.

Your first portal

1. /wormholes wand gives you the Portal Wand and one rune

2. place runes in any flat connected shape

3. left-click a rune with the wand -> the shape becomes a portal

4. build a second portal somewhere else

5. point the wand at portal one and click -> Destination -> pick portal two

6. walk in

All settings are configurable per portal in-game with the wand!

Portal types and modes

Portal Types

Portal                     Basic linkable portables, walk through to end up on the other side.
Wormhole                   Linkable portal, plus the destination rendered through the frame
Gateway                    The cross-server type, pairs with a portal on another server
RTP                        Random teleport inside a radius, previewed before you go
Mirror                     Reflect the local world back to you, turns it into a looking glass

Travel Direction

Both Ways                  Cycle through the allowed travel directions
Outbound Only              You can leave through it, not arrive
Inbound Only               You can arrive through it, not leave
Locked                     You cannot travel through the portal

Access

Each portal has its own permission node built from its name.

portal named "Spawn Hub"   wormholes.portal.spawn_hub
Blacklist (default)        anyone may use it UNLESS they hold the node
Whitelist                  nobody may use it UNLESS they hold the node

Render modes

Venticular                 Shows visible surfaces and omits hidden destination geometry,
                           better for performance.
PanOptic                   Renders the full destination volume.

Random Teleport portals

Set any portal to RTP in the Type menu and it gets its own destination editor instead of a destination picker.

How the destination is chosen

Shared                     One destination everybody sees and uses
Per-player                 Each player gets their own private destination

When it re-rolls

Static                     Never, until you re-roll it by hand
Timed                      On a cycle, 5 minutes by default
On traversal               A fresh one after every trip

Defaults

radius                     512 to 4096 blocks
centre                     The portal itself, or fixed coordinates you set
vertical mode              Surface (the top solid block)
re-roll cycle              5 minutes
idle lease                 30 seconds
private release            15 seconds
search backoff             1s doubling to 30s on repeated failure

Landing safety

Safety checks are in place to avoid teleporting someone into water, lava, fire, cactus, magma and any other unsafe destinations.

Dimensional Doors and pockets

Craftable doors that give you access to pocket dimensions and your friends house!

Pair                       Two entangled doors linking any two points     default oak
Personal                   Your own private pocket room                   default dark oak
Public                     One shared pocket room everyone arrives in     default pale oak
Every kind has a trapdoor version using the same recipe with a wooden trapdoor.

Recipes R = Wormhole Rune, D = any door or wooden trapdoor

Pair kit                   Eye of Ender      D         Eye of Ender
                           Obsidian          R         Obsidian
                           -                 D         -
Personal                   -                 R         -
                           Recovery Compass  D         Ender Chest
Public                     R                 D         R
                           -                 Ender Chest  -
                           -                 Lodestone    -
Reskin                    shapeless: dimensional door + any ordinary door
                          keeps its data, changes its material

Per-door access

Whoever places a door owns it. Sneak and right-click it with an empty hand for the management GUI.

left-click                whitelist that player
right-click               blacklist that player
shift-left                remove them from the list

As soon as anyone is whitelisted, everyone not on the list becomes blacklisted. A refused player cannot open it, break it, or pass through it even if somebody else holds it open. Owners, operators and players with the wormholes.doors.bypass permission node bypass the whitelist/blacklist.

Open state Each door picks which physical position makes it live. By default the doorway works while the door stands open. Flip it and the shut door becomes the portal instead.

What else can pass Mobs and vehicles go through Pair doors. Arrows, tridents, snowballs, potions, dropped items and XP orbs go through Pair and Public doors, keeping their momentum and their entry point. Personal doors and pocket exits stay player-only.

Pocket rooms

room                      32x32x32 shell, 30x30x30 buildable interior
return door               At floor level, always hand-operable, unmineable
spacing                   8,192 blocks apart, slots never reused
protection                Shells of dimensions are protected and unbreakable
lighting                  Fullbright, fixed time, no monster spawning
rescue                    Lethal damage or leaving the shell ejects you out
                          Through your return route instead of killing you

Cross-server portals

Two servers, one portal, one continuous view. No proxy required.

Linking two servers

on server A                /wormholes server export           prints a click-to-copy code
on server B                /wormholes server import <code>    trusts A and saves the route
                           repeat in the other direction for a two-way link
                           /wormholes server list             shows live reachability

Code types

WHS1.xxxxx                 server code  -  trust and route to that server
WHP5.xxxxx                 portal code  -  link straight to one specific portal

The import command detects which you pasted.

How the servers talk

TCP                        Dedicated port, 8901 by default.
Unix sockets               Two servers on one machine. On by default.
Game-port                  Signed data is tunneled inside the
sideband                   Uses server-list-ping, but not great for large views.

Moving the player

• Direct transfer sends the player straight to the other host, picking the right endpoint for loopback, LAN or internet.

• Proxy mode sends a BungeeCord/Velocity connect message instead. Default is automatic. If a transfer cannot complete you are returned to where you started.

Security Every peer is identified by a public key pinned on first connect. A changed key is refused. Every routed message is signed by its origin and verified before it is acted on, so a trusted relay cannot impersonate another server.

The portal menu

Point the Portal Wand at a portal and click, or sneak and right-click it with an empty hand. You need to be the owner or an admin.

Main

Destination                Pick the portal this one leads to
                           Gateway -> pairing menu.  RTP -> destination editor
Rename                     Type a new name in chat (also changes its perm node)
Projections                Turn the through-portal view on or off
Settings                   Submenu, below
Orientation                Facing, flip face, rotate CW / CCW
Type                       Portal / Wormhole / Gateway / RTP / Mirror
Delete                     Shift-left-click only

Type menu

left-click                 Select that type
Mirror left                Enable mirror
Mirror right               Rotate the image clockwise
Mirror shift-right         Rotate counter-clockwise

Settings menu

Access                     Cycle whitelist / blacklist
                           Lore shows the exact permission node
Travel Direction           Cycle the four directions
Stream Quality             Left  = cycle presets
                           Shift-left = advanced page
Settings Sync              Push settings to the linked portal
Blackout Background        Left  = toggle solid backdrop
                           Right = colour picker
Ambient Particles          Left  = Sparks / Outline / Corners / Off
                           Right = RGB colour picker
Surface Skin               Left  = clear it
                           Right = picker
Activation Range           Left/right +-8   shift +-32
Render Mode                Venticular / PanOptic
Travel Cost                Opens the cost menu

Stream Quality presets

                           capture   full refresh   entity   grace
Standard                      64         60t         10t      30s
Performance                   32        100t         20t      10s
Balanced                      64         40t          5t      30s
Cinematic                     96         20t          2t      45s
Custom                     Edit any dial and the label switches to Custom

Surface Skins Right-click a portal you manage while holding a block to cover the opening with it. Glass reads as a clear window; a water or lava bucket gives it a fluid surface. Transparent skins keep the view visible behind them, opaque ones hide it. Sneak-right-click with an empty hand to clear.

Travel costs

Every portal has one of three cost modes, set from its Settings menu.

Free                       The default option
Vanilla                    Drop the item into the cost menu and that
                           exact item, custom name and components is used.
                           Quantity is then set in the menu.
Vault                      Hooks into Vault for your preferred economy plugin

• Item costs do not sync automatically, you would need to set it on both sides if you want the return trip to cost as well. A failed trip returns the item back to your inventory or the money used.

• If Vault is not installed the option is greyed out. A portal that already has a money cost stored will refuse travel rather than letting people through for free.

• Other plugins can also hook the traversal API to charge for or block a trip. On by default, switchable in the config.

Please visit our Docs for API Usage.

Commands and permissions

Root command /wormholes, aliases /wh and /wormhole. Optional parameters are named, so you write key=value.

Items

/wormholes wand                              Wand + one rune
/wormholes wand count=<1-64>
/wormholes door type=pair|personal|public
/wormholes door type=pair_trapdoor|personal_trapdoor|public_trapdoor

Maintenance

/wormholes stats now=<true|false>            Write a stats snapshot
/wormholes info                              Plugin info, no permission needed
/wormholes debug                             Toggle console telemetry stream

Projection

/wormholes admin freeze seconds=<5-300>      Hold every projection as-is
/wormholes admin freeze seconds=0            Resume immediately
/wormholes admin flush                       Rebuild every projection

Network

/wormholes server export                     Print this server's code
/wormholes server import code=<...>          Import a server or portal code
/wormholes server list                       Linked servers + reachability
/wormholes server remove name=<...>          Drop a link to a server
/wormholes server connect name=<...>         Transfer yourself to a server
/wormholes network status                    Peers, transport, health
/wormholes network doctor                    Diagnose a network problem

Reset

/wormholes admin deleteallportals
/wormholes admin deleteeverything

All configuration is done via the in-game editor, no commands needed.

wormholes.*                                  Gives access to everything
wormholes.admin                              Parent of: reload, items, network,
                                             projection, reset, doors.bypass
wormholes.admin.items                        Wand, runes, door items
wormholes.admin.network                      The server and network commands
wormholes.admin.projection                   Freeze and flush
wormholes.admin.reset                        The delete-everything commands
wormholes.portals                            Parent of: portal and wormhole runes
wormholes.portals.portal                     Build Portal and RTP portals, and
                                             adopt vanilla Nether / End frames
wormholes.portals.wormhole                   Build Wormhole portals
wormholes.gateway                            Build Gateway portals
wormholes.doors.craft                        Craft and reskin dimensional doors
wormholes.doors.place                        Place a live door or trapdoor
wormholes.doors.bypass                       Ignore every per-door access list
wormholes.portal.<name>                      Generated per portal from its name

All permission nodes are defaulted to OPs, per-portal nodes are created as you create and name your portals.

Configuration Files

Modify the main configuration at plugins/Wormholes/config/wormholes.toml Everything is documented inside the configuration and the configuration hot-reloads when you save it, no commands needed.

Start here: the quality profile

Automatically adjusts based on performance or set the default value when portals are created.

quality = "auto"  Uses your values exactly as written
  "performance"   Lighting + entity spoofing off, range capped 32, depth 48, fewer projectors per tick
  "balanced"      Slower lighting and entity refresh, 16 entities per portal, 20 projectors per tick
  "cinematic"     Range >= 64, depth >= 96, faster lighting, up to 48 entities per portal

[main]

replace-nether-and-end-portals  true    Vanilla portals become Wormholes portals as built
dimensional-doors-enabled       true    Doors and pockets dimensions
teleport-cooldown-millis        1000    Cooldown between trips, 0-60000
portal-pushback-multiplier      1.0     0 removes the knockback
portal-sound-volume-multiplier  1.0     0 mutes portal sounds
enable-particles                true
arrival-prewarm-on-interest     true    Preload when looked at
language                        en_US   17 Languages to pick from

[projection]

range                    48       How far away you can still see through a portal.  1-256
depth-blocks             64       How far into the destination.  1-256
max-projectors-per-tick  24       Lower this first if portals hurt your tick.
max-projected-cells      250000   Hard ceiling per portal per pass.
aperture-padding-blocks  0.75     How far the image extends past the frame. Raise if blocks bleed.
recursive-portal-depth   3        Portals seen through portals.
refresh-interval-ticks   1        Higher is cheaper and choppier

[render]

lighting-fidelity      false   Real destination lighting. Prettier, more bandwidth.
entity-spoofing        true    Show mobs and players through portals
max-spoofed-entities   24      Per portal, 0-256
entity-spoof-range     48      How far past a portal entities show

[network]

enabled             false  Master switch. Exporting or importing a code turns it on for you.
listen-port         8901   TCP Port used for server connection, falls back to game-port sideband.
trust-on-first-use  true   Auto-trust an unknown peer's key on first connect.
transfer-mode       auto   auto | proxy | direct
handoff-timeout-ms  5000   Wait time before bouncing the player back

Languages 17 languages are translated from the standard English default to choose from.

To switch, set language in plugins/Wormholes/config/wormholes.toml

language = "en_US"

de_DE    German (Germany)
es_ES    Spanish (Spain)
fi_FI    Finnish (Finland)
fr_FR    French (France)
he_IL    Hebrew (Israel)
it_IT    Italian (Italy)
ja-JP    Japanese (Japan)
ko_KR    Korean (South Korea)
lt_LT    Lithuanian (Lithuania)
nl_NL    Dutch (Netherlands)
pl_PL    Polish (Poland)
pt_PT    Portuguese (Portugal)
ru_RU    Russian (Russia)
tr_TR    Turkish (Turkey)
vi_VI    Vietnamese (Vietnam)
zh_CN    Chinese (Simplified)
zh_TW    Chinese (Traditional)

PlaceholderAPI

List of placeholders usable with PlaceholderAPI, run /papi info wormholes for a live list in-game and /papi ecloud download wormholes to install the Wormholes hook.

Server side information

%wormholes_available%              Is the data ready
%wormholes_portals%                Total portals on the server
%wormholes_projections.active%     Portals currently rendering
%wormholes_projections.observers%  Players watching a projection
%wormholes_peers.connected%        Linked peer servers
%wormholes_peers.link%             Network health word
%wormholes_transfers.in-flight%    Travellers mid-hop
%wormholes_failures%               Lifetime failure count
%wormholes_failures.per-minute%    Recent failure rate

The portal the player is looking at

%wormholes_portal.available%       Is portal data ready
%wormholes_portal.name%            Its name
%wormholes_portal.state%           Open / closed / syncing
%wormholes_portal.destination%     Where the portal leads
%wormholes_portal.distance%        Distance to the destination
%wormholes_portal.cross-server%    Whether the destination is remote
%wormholes_rtp.state%              Rerolling / warming / ready / cooldown / idle
%wormholes_rtp.cooldown%           Time until the next teleport

Compatibility

Wormholes supports Paper, Purpur, Leaf, Folia, Canvas and Spigot on Java 25 for Minecraft 26.x+

• PlaceholderAPI is an optional dependency

• Vault is an optional dependency for an economy hook

• React supports 14 live metrics with their own dashboards: mesh peers, remote portals, worst peer round-trip, wire bytes in and out, compression ratio, sideband backlog, view subscriptions, replicated blocks, resyncs and transfer counts

• Wormholes does not fight for the action/title bar space with other Volmit plugins, they are shared and gracefully changed based on priority and importance of the messages.

• All servers connected with the cross-server portals must run on the same version, a mismatch in protocols could cause issues.