Why would you want to use this plugin?

Nether portals are notorious for creating lag and for spontaneously changing their associated exit portals without warning. This sometimes even happens when you carefully match coordinates between the Overworld and the Nether (the normal method for reliably linking portals). Resolving this on a busy server with many players building near each other can be particularly frustrating for the players. In addition, the normal portal search process that the server employs to find an exit portal can cause brief lag spikes. The linked portals supported by this plugi do not require broad searches and so avoid lag spikes.

How does this plugin work?

This plugin builds on the existing compass/lodestone mechanic to create an in-game mechanic so that a player can reliably link one nether portal to another. Specifically, a lodestone-linked compass placed in an item frame on a nether portal's obsidian frame will indicate where the game should find the corresponding exit portal. That is, the compass points to the lodestone and the lodestone (being part of the exit portal's frame) is used to find the desired exit portal.

In addition to the blocks needed to construct the portals themselves, a player will need the following to link the portals:

• a lodestone for each portal
• an item frame for each portal
• a compass for each portal

Go to the desired exit portal (constructing it in the desired location if necessary). Place a lodestone in one of the bottom corners of the destination/exit portal. Use a compass on the lodestone so that the compass becomes linked to the lodestone block. Note that while the lodestone can be in any corner of the portal frame, the plugin behaves best when the lodestone is in one of the bottom corners. Now, go to the entry portal that you wish to link to this exit portal and place an item frame somewhere on the portal frame and place the linked compass in the item frame. The entry portal is now linked to the exit portal.
Every time a player or entity enters that portal, the plugin will search for the compass in the item frame, use the compass to find the lodestone, and use the lodestone location to inform the game exactly where the exit is so that the game does not search for one.

You can now repeat this process in the other direction to link the exit portal back to the source portal for reliable return travel.

When a player successfully places a lodestone-linked compass in the item frame, the plugin will hide the item frame for a cleaner look. This also serves to confirm that the plugin will attempt to use the compass to link portals. This behavior can be changed in the plugin's configuration.

Which portals can be linked?

Normally, the plugin will only allow a player to link portals if the portals would otherwise be accessible to each other using normal game mechanics (see portal search). That is, by default, the plugin does not allow a player to create and link portals they otherwise could connect using normal game semantics. If a player attempts to link two portals that the game would never connect normally, then the plugin will notify the player that it refuses to honor the link and the normal search for an exit portal will occur.

Even though the default linking behavior is strict, this behavior can be relaxed by setting strictLinking to false in config.yml. When strictLinking has been disabled, the plugin will allow any two portals to be linked. Normal distance limitations between portals is no longer enforced. Players can even link two portals in the same world.

How do I configure the plugin?

When the plugin is loaded for the first time, it will create a LinkedPortals directory in the plugin directory and it will create a config.yml file in that directory if it does not already exist. If config.yml already exists, the plugin will NEVER modify it or overwrite it, so your changes to it will never be lost. However, every time the plugin starts, it will create/replace a config.default.yml file. This latter file serves as documentation for config.yml. It shows every configuration option that the plugin supports, describes how to set those options via comments, and documents the default values for those options.

Because the plugin never modifies config.yml, any new options supported by future releases of the plugin will only be documented in config.default.yml. If you wish to change the default settings for any new options once they are supported, you will need to add them to config.yml yourself, possibly using config.default.yml as a template.


DIAGNOSING PROBLEMS

• If the plugin cannot find an item frame with a lodestone compass in it, it will not override portal behavior. The player or entity will go wherever a normal portal would take them.
• If there is more than one item frame with a lodestone compass in it on the portal, the plugin will use one of them to find the exit portal, but which one it uses is unreliable.
• If the lodestone in the exit portal is broken or moved, its link to the lodestone compass may break. The portals will then become unlinked. The portal can be relinked by removing the broken compass from the item frame and repeating the linking procedure.
• If a player enters a portal with a compass in their off-hand, the plugin will notify that player of the location of the lodestone (which also should be the location of the exit portal). If the exit location cannot be determined the player will be given some indication why.
• For non-linked portals, the server will, normally, calculate a default exit location, search within a couple hundred blocks of that location for an existing portal, and not finding one attempt to create one. The plugin still uses these builtin server semantics to transfer the player or entities between portals. However, it overrides the exit location to be that of the lodestone linked to the compass with a very small search radius to find the portal surface and disables attempts to create a portal at the destination if one is not found. So, if the exit portal of a linked portal is broken or is moved, the exit portal will not be relit, nor will a new portal be created. In these circumstance, the player or entity will remain in the entry portal until they leave it.
• You can enable detailed logging of plugin decisions by setting logLevel to debug or trace in config.yml. These messages may help you understand why linked portals are behaving the way the do. These messages will also be helpful when reporting problems to the plugin's author.

KNOWN ISSUES

• If strict linking is disabled and an entry portal is linked to an exit portal in the same world, any (non-player) entities that enter the entry portal will be destroyed. This is currently being investigated as a bug by the Spigot team. Plugin versions 1.1.1 and later have a workaround, enabled by default, for this issue.

COMMANDS and PERMISSIONS
All commands are implemented as sub-commands of the /linkedportals command.