Portal gun

Introduction

The Portal Gun is a special item that allows players to place portals on Portal Surfaces. Portals work in pairs: a primary portal and a secondary portal. Walking or falling through one portal teleports the player to the other, preserving their entry speed and launching them along the exit portal's facing direction.

It can be obtained from a Mirror Chest when the puzzle creator has enabled it in the chest's configuration.

How to obtain

The Portal Gun is placed inside a Mirror Chest by the puzzle creator. The player opens the chest and picks it up like any other item.

When the player leaves the area, the Portal Gun is removed from the player's inventory and the chest is re-filled.

How to use

• Left click: places a primary portal (blue by default).
• Right click: places a secondary portal (orange by default).

Portals can only be placed on Portal Surfaces (Quartz Block, Smooth Quartz, Quartz Stairs, or Smooth Quartz Stairs, inside an area). A ray trace is cast from the player's eye up to 75 blocks away. If it hits a valid Portal Surface, the portal is placed. On Quartz Stairs and Smooth Quartz Stairs, portals can also be placed on the exposed 45° diagonal face.

Placement rules

• The portal's footprint (~1.8 × 0.8 blocks) must be entirely supported by Portal Surfaces with air in front.
• All footprint blocks must be within the same area.
• The portal center is automatically snapped to a block grid: the long axis is aligned to a block boundary (covering exactly 2 blocks) and the short axis is centered on a single block. This ensures consistent laser alignment.
• If the snapped position is invalid, the center is automatically adjusted (clamped) to the nearest valid grid-aligned position.
• Two portals cannot overlap on the same surface.

Portal orientation

• On a wall (north, south, east, west): the portal is always vertical (tall and narrow).
• On the floor or ceiling: the portal is horizontal, oriented along the direction the player is looking (aligned to the nearest cardinal axis).

Replacing portals

• Placing a new primary portal replaces the player's previous primary portal (same for secondary).
• Placing a portal on top of another player's portal destroys the other player's portal and places the new one.
• Placing a portal where the player's own opposite-type portal already exists is not allowed (e.g. you cannot place your primary portal on top of your secondary portal).

Multi-player colors

Each player is assigned a unique color pair for their portals upon first use of the Portal Gun within an area. This allows multiple players to coexist in the same puzzle with visually distinct portals.

#	Primary portal (left click)	Secondary portal (right click)
1	Light blue	Orange
2	Red	Purple
3	Lime	Yellow
4	Pink	Cyan
5	White	Black
6	Magenta	Light gray

Up to 6 players can simultaneously use Portal Guns in the same area. The color pair is released when the player leaves the area or loses their Portal Gun.

Portal lifecycle

Portals are not persistent — they exist only in memory and disappear on server restart. A player's portals are destroyed when:

• The player leaves the area.
• The area is reset.
• The player disconnects.
• The player loses the Portal Gun (dropped, moved to another inventory, death).
• The Portal Surface block under a portal is broken.
• A block is placed in the air space in front of the portal (obstruction).

Interactions

Player interaction

When a player walks or falls through a portal, they are teleported to the linked portal while conserving the magnitude of their entry speed. The exit velocity is always directed along the exit portal's normal (perpendicular to its surface), and the player is always placed at the exact center of the exit portal. Both rules combined make aerial trajectories fully predictable: the exit direction only depends on which portal you exit through, not on how you entered the first one.

The exit speed is entry_speed × portal_velocity_multiplier+portal_exit_impulse. With the defaults (1.0 and 0.2), the player exits at exactly their entry speed plus a small pop out of the portal. To absorb Minecraft's tick-alignment noise on the measured entry speed, the value is first rounded to the nearest portal_entry_speed_quantization bucket (default 0.5 blocks/tick) — so small variations in entry conditions still produce identical exits and consecutive portal jumps in the same setup land at the same spot.

During the aerial flight following a teleportation, Minecraft's ~9% horizontal air drag is cancelled each tick (see portal_drag_compensation) so aerial loops between two portals do not decay between bounces. Compensation stops automatically when the player lands, enters water or lava, glides with an elytra, or toggles creative/spectator flight.

• A player falling through a floor portal linked to a wall portal exits horizontally along that wall's direction at their falling speed.
• A player running through a wall portal linked to a floor portal is launched straight up at their running speed.
• Fall distance is reset after teleportation, preventing unfair fall damage.

Look direction

The player's view rotates through the portal using three simple rules:

• 45° diagonal portals are treated as vertical walls for the camera — the slope angle never tilts the view.
• Face-to-face portal pairs preserve the view 1:1. A pair is considered face-to-face when the two exit directions are strictly opposite — e.g. east ↔ west walls, north ↔ south walls, floor ↔ ceiling, or a mirrored 45° aerial loop. This keeps the camera stable while bouncing back and forth on the same axis.
• Any other configuration applies the natural reflection through the portal plane. Two portals facing the same direction (e.g. two east-facing walls, or two floor portals) produce a 180° camera flip; perpendicular orientations (e.g. east ↔ south walls) produce a 90° rotation, same as in Portal 2.

Players in Spectator mode or in editor mode are not teleported, allowing them to move freely through portals.

Floor portals

Walking onto a floor portal (normal facing up) teleports the player as soon as they step onto the portal's surface. No jump is required.

If a block sits on top of the portal surface (for example a glass block produced by a Laser Solidifier), the player standing on that block is one block too high to trigger teleportation by walking normally. To enter the portal from this elevated position, the player must crouch (sneak) and walk into the portal's footprint.

Ceiling portals

Jumping up into a ceiling portal teleports the player as soon as their head reaches the portal surface. This works even when the room below is tall enough that the feet alone never reach the portal's plane.

Laser interaction

Lasers that hit a portal from the front are teleported to the linked portal and continue their path from the exit point, keeping their color, light level, and direction (transformed relative to the exit portal's orientation).

A laser entering through the top-right of the entry portal exits through the top-right of the exit portal — the relative position within the portal is preserved.

Laser loops

If two portals face each other, a laser can bounce between them indefinitely. This is intentional and allows players to "store" light between two portals and release it later by moving one portal.

Sound feedback

• Successful placement: a confirmation sound is played at the portal's position.
• Failed placement (invalid surface, overlap, etc.): a failure sound is played.
• Teleportation: a teleportation sound is played at both the entry and exit positions.

Known issues

No known issue currently.

See our issue board for more information.