> ## 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.

# 빠른 시작

> PlayWave Roblox 플러그인을 설치하고 연동합니다

<Info>
  **사전 준비**

  * **API Key** — PlayWave 서비스 운영 담당자에게 발급 요청
  * **PlayWave 런처 (Dev 빌드)** — 테스트용 개발 빌드를 운영 담당자에게 요청
  * Roblox Studio 설치
</Info>

## 1단계 — Allow HTTP Requests 활성화

<Steps>
  <Step title="Experience Settings 열기">
    Roblox Studio에서 **File → Experience Settings**를 클릭합니다.

    <Frame caption="File → Experience Settings">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/experience-settings.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=45f3407bd54f866513a25cd80468be7e" alt="Roblox Studio File 메뉴에서 Experience Settings 강조 표시" width="1086" height="1230" data-path="images/plugin/experience-settings.png" />
    </Frame>
  </Step>

  <Step title="HTTP Requests 허용">
    왼쪽 메뉴에서 **Security**를 클릭하고, **Allow HTTP Requests**를 활성화합니다.

    <Frame caption="Security → Allow HTTP Requests 활성화">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/allow-http.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=a8eff3582a62a632ffa3ab0cd06e4f74" alt="Experience Settings Security 탭에서 Allow HTTP Requests 토글 활성화" width="1946" height="1290" data-path="images/plugin/allow-http.png" />
    </Frame>
  </Step>
</Steps>

## 2단계 — PlayWave 플러그인 설치

<Steps>
  <Step title="Toolbox 열기">
    Roblox Studio 우측 상단의 **Toolbox**를 클릭합니다. Toolbox 패널에서 **Plugins** 탭으로 전환하고 `playwave`를 검색합니다.

    <Frame caption="Toolbox → Plugins → 'playwave' 검색">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/toolbox-search.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=8cf6608f8c83df64affac34acacc0326" alt="Roblox Studio Toolbox에서 PlayWave 플러그인 검색" width="2524" height="1534" data-path="images/plugin/toolbox-search.png" />
    </Frame>
  </Step>

  <Step title="Install & Update">
    **PlayWave**를 클릭한 후 **Install**을 클릭합니다.

    <Frame caption="PlayWave 플러그인 설치 페이지">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/plugin-install.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=da766974bd4c889e17cb9e942ac9df69" alt="PlayWave 플러그인 상세 페이지의 Install 버튼" width="774" height="1176" data-path="images/plugin/plugin-install.png" />
    </Frame>
  </Step>
</Steps>

## 3단계 — PlayWave Setup 실행

<Steps>
  <Step title="Plugins 메뉴 열기">
    상단 메뉴바에서 **Plugins** 탭을 클릭합니다. **PlayWave Setup** 버튼이 표시됩니다.

    <Frame caption="Plugins 메뉴의 PlayWave Setup 버튼">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/plugins-menu.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=82e85a6b642da4bc3c99a7b9e31076a7" alt="Roblox Studio Plugins 탭에 PlayWave Setup 버튼 표시" width="3012" height="1544" data-path="images/plugin/plugins-menu.png" />
    </Frame>
  </Step>

  <Step title="설정 및 설치">
    **PlayWave Setup**을 클릭합니다. **API Key**를 입력하고, **Environment**를 선택한 후 **Install**을 클릭합니다.

    | Environment | 상태                                 |
    | ----------- | ---------------------------------- |
    | **Dev**     | <Badge color="green">사용 가능</Badge> |
    | **QA**      | <Badge color="yellow">준비 중</Badge> |
    | **Live**    | <Badge color="yellow">준비 중</Badge> |

    <Frame caption="PlayWave Settings 대화상자">
      <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/setup-dialog.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=6ecbc811096e03f309c97e3ef1c02a11" alt="API Key 입력과 환경 선택이 가능한 PlayWave Settings 대화상자" width="666" height="570" data-path="images/plugin/setup-dialog.png" />
    </Frame>
  </Step>
</Steps>

## 4단계 — 생성된 스크립트 확인

설치가 완료되면 다음 스크립트가 자동으로 생성됩니다.

<Frame caption="PlayWave 플러그인이 생성한 스크립트 구조">
  <img src="https://mintcdn.com/playwave/qY2JHnQsbwElkafF/images/plugin/script-structure.png?fit=max&auto=format&n=qY2JHnQsbwElkafF&q=85&s=ae3ae7cb7779b6e47922f5380e44b1fc" alt="Roblox Studio Explorer에 PlayWaveSetup과 PlayWaveClient 스크립트 표시" width="542" height="526" data-path="images/plugin/script-structure.png" />
</Frame>

<Tree>
  <Tree.Folder name="ServerScriptService" defaultOpen>
    <Tree.Folder name="PlayWaveSetup" defaultOpen>
      <Tree.File name="ApiKey (StringValue)" />

      <Tree.File name="ApiUrl (StringValue)" />

      <Tree.File name="PlayWaveServer (ModuleScript)" />
    </Tree.Folder>
  </Tree.Folder>

  <Tree.Folder name="StarterPlayer" defaultOpen>
    <Tree.Folder name="StarterPlayerScripts" defaultOpen>
      <Tree.File name="PlayWaveClient (LocalScript)" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

## 5단계 — 콜백 함수 작성

### PlayWaveSetup (서버)

서버 스크립트는 PlayWave를 초기화하고 `onPcCafe` 콜백을 정의합니다. 이 콜백은 PC방 유저가 검증되면 실행됩니다.

```lua theme={null}
local PlayWaveServer = require(script.PlayWaveServer)

local apiKey = script:WaitForChild("ApiKey").Value
local apiUrl = script:WaitForChild("ApiUrl").Value

PlayWaveServer.init({
    apiKey = apiKey,
    apiUrl = apiUrl,

    onPcCafe = function(player)
        -- PC방 혜택 지급 로직 (XP 부스트, 아이템, 코인 등)
        print("[PlayWave] PC cafe benefit granted:", player.Name)
    end,

    -- 선택: 검증 종료 시 카페 여부와 무관하게 플레이어당 1회 발화
    onVerified = function(player, isPcCafe, reason)
        print("[PlayWave] Verified:", player.Name, isPcCafe, reason)
    end,
})
```

<Tip>
  `onPcCafe`는 PC방 유저에게만 발화합니다. 비카페 유저에 대해서도 신호가 필요한 경우(예: 로딩 UI 종료) `onVerified`를 사용하세요 — 플레이어당 정확히 1회 발화합니다. 자세한 내용은 [onVerified 콜백 가이드](/ko/roblox/on-verified)를 참고하세요.
</Tip>

### PlayWaveClient (클라이언트)

클라이언트 스크립트는 준비 신호를 전송하고 혜택 이벤트를 수신합니다.

```lua theme={null}
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local evFolder         = ReplicatedStorage:WaitForChild("PlayWaveEvents", 30)
local clientReadyEvent = evFolder and evFolder:WaitForChild("PlayWaveClientReady", 30)

if clientReadyEvent then
    clientReadyEvent:FireServer()
else
    warn("[PlayWave] PlayWaveClientReady event not found.")
end

local benefitEvent = evFolder and evFolder:WaitForChild("PlayWaveBenefit", 30)
if benefitEvent then
    benefitEvent.OnClientEvent:Connect(function(benefitType)
        if benefitType == "PC_CAFE" then
            -- 클라이언트에서 PC방 혜택 처리 (예: UI 알림 표시)
        end
    end)
end
```

<Tip>
  서버의 `onPcCafe` 콜백에서 게임플레이 혜택(XP 부스트, 아이템 등)을 지급하세요. 클라이언트의 `PlayWaveBenefit` 이벤트는 UI 알림 표시용으로만 사용합니다.
</Tip>

## 6단계 — 테스트

<Steps>
  <Step title="Roblox Studio에서 테스트">
    Play 버튼으로 로컬 테스트합니다. LaunchData가 없으므로 OTT 없이 일반 유저로 접속됩니다.
  </Step>

  <Step title="PlayWave 런처로 테스트">
    런처에서 게임을 실행하면 LaunchData에 OTT가 포함됩니다. Output 콘솔에서 검증 로그를 확인하세요.
  </Step>
</Steps>

<Note>
  PlayWave 런처 없이 접속한 유저는 OTT가 없으므로 검증을 건너뜁니다. 일반 유저도 정상적으로 게임을 플레이할 수 있습니다.
</Note>

## 텔레포트 연동 (멀티 Place) <Badge color="red">중요</Badge>

<Warning>
  멀티 Place Experience를 사용하는 경우, 텔레포트 연동 없이 SubPlace로 이동하면 과금이 적용되지 않아 **수익 손실**이 발생할 수 있습니다.
</Warning>

로비(Lobby) Place에서 SubPlace로 텔레포트하는 구조의 Experience에서는 이동 시 PlayWave 인증이 끊어집니다. `TeleportOptions`에 세션 데이터를 포함하여 인증을 유지해야 합니다.

<Steps>
  <Step title="최신 플러그인 업데이트">
    Toolbox에서 최신 버전의 PlayWave 플러그인을 설치하고, **Install SDK**로 스크립트를 업데이트합니다.

    <Warning>
      Install SDK 클릭 시 기존 콜백 함수 스크립트가 초기화됩니다. **반드시 백업 후 진행**하세요.
    </Warning>
  </Step>

  <Step title="각 Place에 PlayWave SDK 설치">
    텔레포트 대상이 되는 모든 SubPlace에도 PlayWave SDK를 설치해야 합니다.
  </Step>

  <Step title="텔레포트 로직 수정">
    `TeleportOptions`에 PlayWave 세션 데이터를 포함하도록 텔레포트 코드를 수정합니다.

    ```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)
    ```
  </Step>
</Steps>

<Tip>
  텔레포트 연동에 대한 상세 가이드는 [텔레포트 연동 가이드](/ko/roblox/teleport)를 참고하세요.
</Tip>

## 다음 단계

<Columns cols={2}>
  <Card title="세션 라이프사이클" icon="rotate" href="/ko/roblox/session-flow">
    세션, 하트비트, 종료가 어떻게 동작하는지 이해합니다.
  </Card>

  <Card title="수동 설치" icon="code" href="/ko/roblox/manual-setup">
    플러그인 없이 PlayWave를 직접 설치하는 방법을 안내합니다.
  </Card>
</Columns>