Portal Planner

Portal Planner is a tool for planning advanced Nether portal linkages in Minecraft: Java Edition. It replicates the exact in-game computations to determine which portals are possible to link together

Try it online!

Download #

Windows Linux macOS Source code

Features #

• Tracks any number of portals in the Overworld and Nether with custom names and colors
• 3D planar projections with arrows showing portal linkages
• Test points for precise measurement
• Customizable entity size, with teleport region shown as a white box
• Undo/redo
• Import/export to file

Motivation #

In Minecraft, Nether portals link between corresponding points in the Overworld and the Nether dimensions at a ratio of 8:1, such that traveling one block horizontally in the Nether corresponds to traveling eight blocks horizontally (X or Z axis) in the Overworld. Vertical distance (Y axis) maps at a ratio of 1:1. For most purposes, simply multiplying or dividing coordinates by 8 is sufficient to map between the Overworld and Nether to ensure that Nether portals are placed in locations that will link together.

The exact mechanics of Nether portal linkage are much more complicated, however. Here is the procedure the game uses to determine where to teleport an entity entering a portal:

1. The entity’s X and Z coordinates¹ are multiplied or divided by 8
2. These coordinates are rounded down (toward -∞) to integer block coordinates
3. The game searches for portal blocks in a 257x257 (Overworld) or 33x33 (Nether) square prism spanning the entire height of the destination dimension, centered on those X and Z block coordinates
4. The nearest portal block (by Euclidean distance) is selected as the teleport destination
5. The entity’s coordinates are adjusted within the destination portal frame according to its position within the initial portal frame, rotated clockwise (+Z to +X) if the portals are facing perpendicular axes
6. If the entity is a projectile, its velocity vector is rotated 90 degrees (+Z to +X) if the portals are facing perpendicular axes

There are several results of these mechanics that may be surprising even to experienced Minecraft players:

• Teleportation does not always select the closest portal (due to the square prism limitation)
• The Euclidean distance prioritization may give different results for Nether-to-Overworld versus Overworld-to-Nether teleportation (due to the multiplication/division by 8 only applying to horizontal coordinates)
• If one portal links to another, the reverse link might not be possible, even if there are no other portals
• The destination portal depends only on the location of the entity being teleported, not the location of the portal it entered
• A single portal may link to entirely different destinations depending on the exact location of the entity when teleportation occurs
• Different entities may be able to reach different destinations due to differences in hitbox size²

These mechanics are especially useful with the new 0.1-second teleport cooldown for projectiles introduced in version 1.21.2, which enables building linkages of Nether portals that rapidly transport ender pearls from one part of the world to another. With very little infrastructure, it’s possible to teleport several thousand blocks in less than a second by chaining portals across dimensions, without the player ever leaving their initial dimension. Optimizing these linkages requires knowing exactly where portals can be placed without interfering with each other. After doing this by hand in Desmos (and getting it wrong several times), I created Portal Planner.