Guide

Game portal pair teleport puzzle systems explained

Harbor Prism Lab’s “Momentum Gallery” chamber shipped with paired portals, weighted cubes, and a laser receiver that only fired when the cube crossed a gap at speed. Playtesters loved the concept; only 24% finished the room. Replays showed the same failure: players entered a floor portal and emerged from a wall portal with zero horizontal velocity — the engine had zeroed tangential speed at the exit. After fixing the velocity transform through rotated portal frames, tagging portalable surfaces consistently, and adding a one-cube tutorial alcove, completion rose to 71% without lowering the intended fling distance.

Portal pair puzzles are spatial logic challenges built around two linked teleport endpoints the player places on tagged surfaces. Unlike fast-travel waypoints, portals are tools inside a bounded chamber: you route yourself, cubes, and sometimes energy beams through a pair while conserving (or deliberately redirecting) momentum. This guide covers placement rules, the math of velocity through rotated exits, rendering and collision tricks, coupling with pressure plates and beam puzzles, the Harbor Prism Lab refactor, a technique decision table, pitfalls, and a production checklist.

Portal pairs vs other teleport designs

Three teleport patterns show up in games and are easy to conflate:

Menu fast travel — player picks a discovered node; no physics, no mid-air state. Good for open worlds, not spatial puzzles.
Fixed pads and triggers — designer-placed endpoints with known entry/exit vectors. Simple to script; limited player expression.
Player-placed portal pairs — two active endpoints on allowed surfaces; firing the gun replaces one end of the pair. The puzzle is where to link space, not whether teleport exists.

Portal puzzles live in the third category. Success depends on readable surface rules, predictable velocity behavior, and chambers authored for a small number of “aha” configurations rather than brute-force search.

Core loop: placement, transit, and replacement

The standard loop mirrors the genre-defining formula without requiring a license:

Raycast from camera or muzzle to first hit within max range.
Validate surface — material tag, minimum flat area, not behind glass, not on moving geometry (unless you explicitly support it).
Spawn or move portal A or B on the hit normal; orient the portal plane flush to the surface.
On overlap with portal volume, teleport entity to the paired portal with transformed position and velocity.
Cooldown — brief invulnerability or position lock to prevent infinite portal oscillation when standing in the seam.

Most bugs cluster on step 4. Position-only teleport feels fine for cubes; players notice instantly when momentum is wrong.

Velocity through rotated portal frames

When exit portal normal differs from entry normal, speed must rotate with the portal basis, not merely copy world-space vx, vy, vz. The standard approach:

Express incoming velocity in the entry portal’s local frame (forward = into portal, up = portal up vector).
Map local components to the exit portal’s local frame (forward becomes out of exit, up aligns to exit up).
Reconstruct world velocity from exit basis vectors.

Intuition: speed into the entry portal becomes speed out of the exit portal; tangential components rotate with the wall/floor change. A player falling into a floor portal and exiting a wall portal should launch horizontally with magnitude equal to fall speed (minus any damping you apply for game feel).

Angular velocity on rigid bodies: rotate the angular velocity vector by the same basis change if cubes should spin realistically through portals. For character controllers, reset or clamp spin — spinning avatars induce motion sickness.

Player controller edge cases: if the exit portal faces down onto a floor, add a one-frame ground probe below the exit to avoid embedding in geometry. If exit is flush with a ceiling, nudge spawn slightly along exit forward so the capsule clears the lip.

Surface tagging and placement fairness

Players learn portal rules through visual language, not tutorial text walls:

Portalable — flat panels, concrete, designated white tiles. Consistent albedo + subtle shimmer shader.
Non-portalable — glass, grates, moving platforms (unless supported), decorative trim. Must read clearly at distance.
Minimum patch size — reject hits where the portal ellipse would clip an edge; show a denied-place sound/UI ping instead of half-spawn.

Author chambers so every required solution uses portalable area you have shown the player earlier in the level. Surprising a new surface type in the final room reads as a rule change, not a clever twist.

Common puzzle objects and coupling

Weighted cubes and routing

Cubes should use the same teleport pipeline as the player. Add a carry state: if the player holds a cube, teleport both with offset preserved relative to the player so the cube does not snap inside geometry. Uncarried cubes crossing a portal alone are the bread-and-butter of block-routing puzzles without grid snapping — momentum becomes part of the solution.

Buttons and plates

Route cubes through portals onto pressure plates the player cannot reach on foot. Telegraph plate locations from the entry side so players know the goal before solving placement.

Lasers and energy beams

Beam through portals is advanced but satisfying: when a laser hits an entry portal, emit from the exit along exit forward. Cap bounce count and document whether phase shifts break mirror chains. Test co-planar exits that fold the beam back into the same room.

Momentum flings and faith leaps

Chambers that require speed before entry (sprint, slide, fall) are the signature moment of the genre. Author with:

Visible landing zone or soft-lock camera on success.
Checkpoint before high-speed attempt — not after.
Optional low-speed alternate for accessibility (wider target, helper lift).

Rendering and collision implementation notes

Portal rendering traditionally uses an extra camera rendering the view through the exit portal, clipped to the portal polygon, composited onto the entry frame. Practical production tips:

Recursive depth cap — portal sees portal sees portal explodes cost; cap at 1–2 recursions for puzzles.
Stencil or oblique projection to clip the secondary view; watch for near-plane fighting on shallow angles.
Physics teleport should run in fixed update; render in late update to avoid one-frame desync.
Owned vs remote entities in co-op: server authoritative teleport with replicated portal transforms.

Simpler 2D games can fake portals with render textures on quads; keep the same velocity math in physics space regardless of presentation dimension.

Authoring chambers that teach without lectures

Structure a portal wing like a skill tree:

Room 1 — walk through floor-to-floor pair; no momentum.
Room 2 — cube through portal onto a plate.
Room 3 — fall speed → horizontal launch (short gap).
Room 4 — combine cube routing + player fling.
Capstone — reuse all three in one chamber with two legitimate portal layouts; avoid single-pixel placement wins.

Embed optional rooms inside puzzle platformers as self-contained volumes with reset buttons that restore cubes and portal pairs to defaults — distinct from world-map fast travel, which should not reset puzzle state.

Harbor Prism Lab refactor walkthrough

Harbor Prism Lab (fictional composite) is a first-person puzzle wing. Momentum Gallery metrics before refactor:

Completion rate: 24% (first visit, no guide)
Median time stuck: 6.8 minutes at the fling gap
Reported cause: 71% of failures showed exit velocity near zero
Cube-on-plate success: 41% (secondary goal in same room)

Root causes from telemetry and replay:

Velocity bug — code copied world velocity without basis change on 90° exits.
Deny-list inconsistency — trim looked portalable but rejected placement; players wasted shots.
Oscillation trap — standing in floor portal re-teleported every frame, draining health in a floor hazard below.
No low-speed path — accessibility players blocked entirely.

Interventions:

Shipped basis-correct velocity transform with unit tests on 0°, 90°, 180° exit normals.
Retextured non-portalable trim; added denied-place UI sound.
Added 250 ms post-teleport cooldown and upward nudge on exit spawn.
Widened receiving platform 20%; added optional boost pad for under-speed launches.
Inserted 2-minute tutorial alcove before the gallery.

Outcome: completion 24% → 71%, cube-on-plate success 41% → 68%, median stuck time 6.8 → 2.1 minutes.

Technique decision table

Design goal	Prefer portal pairs	Prefer alternative
Spatial reasoning with player-placed links	Two-endpoint gun in bounded chambers	Fixed pad teleports
Momentum and velocity puzzles	Rotated exit frames with fling gaps	Bounce pads and springs
Open-world traversal compression	Rarely — pacing and streaming cost	Fast-travel network
Routing objects to unreachable plates	Cube through portal onto switch	Sokoban push chains
Optical routing without movement	Laser-through-portal (advanced)	Mirror and splitter puzzles
Permission gating between rooms	Portal as traversal only after unlock	Key-door inventory graphs

Common pitfalls

World-space velocity copy — breaks every floor-to-wall fling.
Infinite portal loop — no cooldown; player traps in seam.
Exit spawn inside geometry — especially ceiling and floor pairs.
Ambiguous surface rules — portalable trim reads like gameplay.
Single-solution pixel hunting — one valid angle only; frustrates.
Moving platform portals — unless engineered, desync physics.
Carried cube clipping — cube teleports inside wall on exit.
Recursive render cost — two portals facing each other tank FPS.

Production checklist

Implement velocity transform in entry/exit local frames with unit tests on cardinal normals.
Tag portalable vs denied surfaces with distinct materials and audio feedback on deny.
Enforce minimum flat patch size before spawning portal quads.
Add post-teleport cooldown and exit position nudge along exit forward/up.
Run teleport logic in fixed update; sync render cameras after physics.
Cap portal view recursion depth; profile worst-case facing portals.
Reset cubes and portal pairs on room reset; document state vs fast travel.
Author tutorial alcove before first momentum fling.
Provide accessibility alternate for speed-gated gaps where possible.
Log exit speed and placement denials in playtests to catch zero-velocity bugs early.
Test carried cubes, rigid bodies, and character capsule separately.
Playtest with mouse, gamepad, and invert-look settings.

Key takeaways

Portal puzzles are about linking space, not skipping it. Distinct from open-world fast travel.
Momentum must rotate with the exit frame. Copying world velocity breaks the core fantasy.
Harbor Prism Lab rose from 24% to 71% completion after velocity fixes and surface clarity.
Teach floor → wall flings in isolation before combining cubes and plates.
Pair with plates and beams when routing objects or energy to unreachable targets.