> ## Documentation Index
> Fetch the complete documentation index at: https://playwave.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Teleport integration

> Maintain PlayWave authentication when teleporting to SubPlaces

## Background

In Experiences that use a Lobby Place to teleport players into SubPlaces, PlayWave authentication is lost during the `TeleportService` transition. Teleport integration solves this by passing session data through `TeleportOptions`, maintaining authentication across Places.

<Warning>
  Without teleport integration, billing will not apply after moving to a SubPlace, which can result in **revenue loss**.
</Warning>

## Prerequisites

<Steps>
  <Step title="Install the latest plugin">
    Install the latest PlayWave plugin from the Toolbox.

    <Warning>
      Clicking **Install SDK** will reset existing callback scripts (`PlayWaveSetup`, `PlayWaveClient`). Back up your existing code before proceeding.
    </Warning>
  </Step>

  <Step title="Install SDK on each Place">
    PlayWave SDK must be installed on **every SubPlace** that is a teleport destination. Run **Install SDK** from the plugin in each Place.
  </Step>
</Steps>

## Modify teleport code

In your existing teleport logic, create `TeleportOptions` and call `PlayWaveServer.prepareForTeleport` to inject session data.

```lua theme={null}
-- ServerScriptService/TeleportHandler (Script Example)
local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local SUB_PLACE_ID = 130143450994652

local PlayWaveServer = require(
    game:GetService("ServerScriptService")
        :WaitForChild("PlayWaveSetup")
        :WaitForChild("PlayWaveServer")
)

local teleportEvent = Instance.new("RemoteEvent")
teleportEvent.Name = "RequestTeleport"
teleportEvent.Parent = ReplicatedStorage

teleportEvent.OnServerEvent:Connect(function(player)
    local teleportOptions = Instance.new("TeleportOptions")
    PlayWaveServer.prepareForTeleport(player, teleportOptions)
    TeleportService:TeleportAsync(SUB_PLACE_ID, {player}, teleportOptions)
end)
```

### Key points

| Item                 | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `prepareForTeleport` | Injects PlayWave session data into `TeleportOptions`     |
| SubPlace SDK install | SDK is required on each SubPlace to receive session data |
| Callback restoration | Re-write `onPcCafe` callbacks after SDK reinstallation   |

## Integration checklist

<Checklist>
  * Latest PlayWave plugin installed
  * PlayWave SDK installed on all SubPlaces
  * `prepareForTeleport` call added to teleport code
  * Existing `onPcCafe` callback code restored
  * Tested with launcher to confirm PC cafe benefits persist after SubPlace teleport
</Checklist>

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/roblox/quickstart">
    Full walkthrough from plugin installation to basic integration.
  </Card>

  <Card title="Session lifecycle" icon="rotate" href="/roblox/session-flow">
    Understand how sessions, heartbeats, and termination work.
  </Card>
</Columns>