빠른 시작

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

사전 준비

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

​

1단계 — Allow HTTP Requests 활성화

1. Experience Settings 열기

   Roblox Studio에서 File → Experience Settings를 클릭합니다.

   
2. HTTP Requests 허용

   왼쪽 메뉴에서 Security를 클릭하고, Allow HTTP Requests를 활성화합니다.

   

​

2단계 — PlayWave 플러그인 설치

1. Toolbox 열기

   Roblox Studio 우측 상단의 Toolbox를 클릭합니다. Toolbox 패널에서 Plugins 탭으로 전환하고 playwave를 검색합니다.

   
2. Install & Update

   PlayWave를 클릭한 후 Install을 클릭합니다.

   

​

3단계 — PlayWave Setup 실행

1. Plugins 메뉴 열기

   상단 메뉴바에서 Plugins 탭을 클릭합니다. PlayWave Setup 버튼이 표시됩니다.

   
2. 설정 및 설치

   PlayWave Setup을 클릭합니다. API Key를 입력하고, Environment를 선택한 후 Install을 클릭합니다.

   Environment	상태
   Dev	사용 가능
   QA	준비 중
   Live	준비 중

   

​

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

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

ServerScriptService

PlayWaveSetup

ApiKey (StringValue)

ApiUrl (StringValue)

PlayWaveServer (ModuleScript)

StarterPlayer

StarterPlayerScripts

PlayWaveClient (LocalScript)

​

5단계 — 콜백 함수 작성

​

PlayWaveSetup (서버)

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

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,
})

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

​

PlayWaveClient (클라이언트)

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

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

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

​

6단계 — 테스트

1. Roblox Studio에서 테스트

   Play 버튼으로 로컬 테스트합니다. LaunchData가 없으므로 OTT 없이 일반 유저로 접속됩니다.

2. PlayWave 런처로 테스트

   런처에서 게임을 실행하면 LaunchData에 OTT가 포함됩니다. Output 콘솔에서 검증 로그를 확인하세요.

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

​

텔레포트 연동 (멀티 Place) 중요

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

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

1. 최신 플러그인 업데이트

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

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

2. 각 Place에 PlayWave SDK 설치

   텔레포트 대상이 되는 모든 SubPlace에도 PlayWave SDK를 설치해야 합니다.

3. 텔레포트 로직 수정

   TeleportOptions에 PlayWave 세션 데이터를 포함하도록 텔레포트 코드를 수정합니다.

   -- 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)
   

텔레포트 연동에 대한 상세 가이드는 텔레포트 연동 가이드를 참고하세요.

​

다음 단계

세션 라이프사이클

세션, 하트비트, 종료가 어떻게 동작하는지 이해합니다.

수동 설치

플러그인 없이 PlayWave를 직접 설치하는 방법을 안내합니다.