---
title: "Teleporters portals and warp pads"
description: "The player steps on a pad and reappears elsewhere, or walks through a portal to another level. Same-world jumps patch the player transform; cross-world portals use the dedicated teleport host op that issues a room handoff."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/teleporters-and-portals/
---

# Teleporters portals and warp pads

## When to use

The player steps on a pad and reappears elsewhere, or walks through a portal to
another level. Same-world jumps patch the player transform; cross-world portals
use the dedicated teleport host op that issues a room handoff.

## The recipe

Author with `project_apply_script_semantic_patch` using the `ai_safe` op pack.

1. Build the pad: an entity with a trigger `ColliderComponent`
   (`collision:"trigger"`) over the step zone, and `addTriggerHandler`
   `{ "handlerKey":"onWarp" }`.
2. Same-world jump: in the handler body (whole-body GessaScript via
   `replaceScriptFromGessaScript`), `ctx.entity.patchComponent` the entering
   player's `TransformComponent` `position` to the destination coordinates. Read
   a destination stored in state with `readTypedStateValue` if it is dynamic.
3. Cross-world portal: call `ctx.world.teleportPlayer` with the player id and the
   target world key. This is gated by `worlds.teleport_authority` and writes a
   teleport handoff into the warehouse, which the destination room admits; the
   player is not simply moved in place.
4. Face the exit: set the arrival `rotation` too, so the player looks into the
   new area rather than back at the pad they arrived on.
5. Prevent immediate re-trigger: place the destination outside the source pad's
   trigger volume, or set a short cooldown boolean so arriving does not bounce
   the player straight back.

## Pitfalls

- `ctx.world.teleportPlayer` is for player entities across worlds; for moving a
  fresh non-player entity use spawn (see spawn-points-and-checkpoints). For a
  same-world player nudge, patch the `TransformComponent` instead.
- Teleport is authority-gated and asynchronous through a warehouse handoff; do
  not assume the player is at the destination on the same tick you call it.
- Two pads that warp into each other's trigger zones cause an infinite bounce.
  Offset arrival points and add a re-entry cooldown.
- A `solid` collider blocks the player off the pad; the pad must be `trigger`.

## Verify

- `simulation_run` (`qa.run.start`) to prove stepping on the pad relocates the
  player and, for portals, that the destination world admits them.
- `project_get_graph_snapshot` to confirm the pad's trigger collider and warp
  handler exist.