특정 월드 인스턴스로 워프하기

# 학습 과정 소개

`WorldInstanceService`를 활용해 현재 월드 인스턴스Id와 생성된 다른 월드 인스턴스들의 상태를 알 수 있습니다. 또한 `TeleportService`를 활용해 플레이어를 특정 월드 인스턴스로 워프시킬 수 있습니다.

##### 참고 가이드

[월드 인스턴스](/docs/?postId=984) [월드 인스턴스 통신](d/ocs/?postId=999) [월드 워프하기](/docs/?postId=743)

##### 참고 APIReference

[TeleportService](/apiReference?postId=315)  
[WorldInstanceService](/apiReference?postId=1034) [WorldInstanceInfo](/apiReference?postId=1128)

# WorldInstanceId 알아보기

#### WorldInstanceId

WorldInstanceId란 [월드 인스턴스](/docs/?postId=984)가 생성될 때 발급되는 고유한 값으로 월드 인스턴스를 구분하기 위해 사용합니다. 예를 들어, 월드A의 월드 인스턴스가 30개 생성되면 월드 인스턴스마다 WorldInstanceId가 생성되어 총 30개의 WorldInstanceId가 있습니다.

현재 유저가 접속한 월드 인스턴스의 Id를 알 수 있는 두 가지 방법이 있습니다.

  1. `WorldInstanceService`의 `WorldInstanceId` 프로퍼티를 활용해 현재 접속한 월드 인스턴스의 WorldInstanceId를 알 수 있습니다.
  2. `WorldInstanceService`의 `GetWorldInstanceInfoPagesAndWait()`, `GetWorldInstanceInfoPagesAsync()`를 활용해 Page 단위로 WorldInstanceInfo를 조회할 수 있습니다.



#### WorldInstanceInfo

[WorldInstanceInfo](/apiReference/Misc/WorldInstanceInfo)는 각 월드 인스턴스의 정보를 가지고 있습니다. WorldInstanceInfo의 프로퍼티는 아래와 같습니다.

  * Id: 월드 인스턴스마다 가지고 있는 고유한 값입니다.
  * MaxUserCount: 월드 인스턴스에 입장할 수 있는 최대 인원수입니다.
  * CurrentUserCount: 현재 월드 인스턴스에 입장한 유저의 수입니다.
  * ShortCode: 월드 인스턴스의 식별자나 이름으로 사용할 수 있는 짧은 문자열입니다. 동일한 월드 내에서는 고유함이 보장되지만, 다른 월드 간에는 중복이 발생할 수 있습니다.



#### WorldInstanceInfoPages

[WorldInstanceInfoPages](/apiReference/Misc/WorldInstanceInfoPages)월드 인스턴스 관련 정보를 조회하기 위한 객체입니다. `GetCurrentPageDatas()`, `MoveToNextPageAndWait()` 함수를 사용해 데이터 목록을 가져오거나, 다음 페이지로 이동시킬 수 있습니다.

# 월드 인스턴스 워프하기

TeleportService의 `WarpUserToWorldInstanceAndWait()`, `WorldUserToWorldInstanceAsync()` 함수를 활용해 유저를 다른 월드 인스턴스로 워프시킬 수 있습니다.

플레이어를 워프시키기 위해선 워프시킬 유저의 UserId와 워프할 월드 인스턴스의 WorldInstanceId가 필요합니다. 플레이어가 워프를 시도하는 시점의 최신 월드 인스턴스들의 정보를 조회해 다른 월드 인스턴스로 이동할 수 있습니다. 이동 시 필요한 최신 WorldInstanceInfo 정보는 WorldInstanceService의 함수 `GetWorldInstanceInfoPagesAndWait()` 및 `GetWorldInstanceInfoPagesAsync()` 활용하여 Page 단위로 WorldInstanceInfo를 조회할 수 있습니다. 단, 이때 이동 가능한 월드 인스턴스는 유저가 접속한 월드 내에서만 가능합니다.

다른 월드 인스턴스로 워프할 때 유저가 지금까지 쌓아온 데이터를 함께 전달하려면 `WarpUserToWorldAndWait()`를 활용합니다. 전달 받은 데이터는 `GetWarpRecord()`로 접근해 얻어올 수 있습니다. 자세한 내용은 [TeleportService](/apiReference?postId=315)를 참고하세요.

> Tip. 공개 상태로 출시된 월드에서만 월드 인스턴스 워프가 가능합니다. 비공개 월드에서는 월드 인스턴스 워프가 불가합니다. 제작 중인 상황에서는 월드 인스턴스 워프 테스트를 할 수 없습니다. 출시된 월드에서 월드 인스턴스 워프가 작동하는지 확인해야 합니다.

> 더 알아보기 `WarpUserToWorldAndWait`, `WarpUserToWorldAsync`는 WorldId로 월드를 워프합니다. 이때 워프 대상인 월드는 유저가 있는 월드가 아닌 제2, 3의 월드가 대상이며, 옮겨갈 월드 인스턴스를 지정할 수 없습니다. 또한 이동 가능한 월드 인스턴스가 없는 경우, 새로운 인스턴스를 생성해 워프합니다.

#### 워프가 불가능한 월드 인스턴스

워프를 시도한 월드 인스턴스로 이동할 수 없는 경우가 발생할 수 있습니다. 워프에 실패할 경우 플레이어에게 실패 메시지 화면이 뜨고 월드의 로비 화면으로 돌아갑니다. 워프를 시도했던 월드 인스턴스로는 돌아갈 수 없습니다. 월드 인스턴스 워프에 실패하는 이유는 월드 인스턴스의 상태가 끊임없이 변화하기 때문입니다. 월드 인스턴스의 정원이 모두 찼을 수도 있고, 월드 인스턴스가 은퇴 준비 상태이기 때문에 더 이상 새로운 유저를 받지 않을 수도 있습니다.

# 활용 예시

#### 워프하기
    
    
    @Component
    script CrossWorldWarper extends Component
       @ExecSpace("ServerOnly")
       method void WarpToAnotherWorldInstance(string userId, string worldInstanceId)
       local warpData = {}
       local serializedData = _UtilLogic:TableToString(warpData)
    
       _TeleportService:WarpUserToWorldInstanceAndWait(userId, worldInstanceId, serializedData)
       end
    end
    

#### 월드 인스턴스 정보 페이지 단위로 조회하기

`GetWorldInstanceInfoPagesAndWait()` 함수를 활용해 월드 인스턴스 정보를 페이지 단위로 조회하는 예제입니다.
    
    
    @Component
    script WorldInstanceCrawler extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            local result, pages = _WorldInstanceService:GetWorldInstanceInfoPagesAndWait()
            
                while true do
            
                   --GetCurrentPageDatas()로 현재 페이지의 목록을 가져올 수 있습니다.
                	local datas = pages:GetCurrentPageDatas() 
            
                	for _, data in pair(datas) do
                		log(data.Id)
                	end
            
                   --IsLastPage 프로퍼티를 통해 현재 페이지가 마지막 페이지인지 확인할 수 있습니다.
                	if pages.IsLastPage == true then 
                		break
                	end
            
                	--MoveToNextPageAndWait()로 다음 페이지로 넘어갈 수 있습니다.
                	pages:MoveToNextPageAndWait() 
            
                end
        end
    end
    

`GetWorldInstanceInfoPagesAsync()` 함수를 활용해 월드 인스턴스 정보를 페이지 단위로 조회하는 예제입니다.
    
    
    @Component
    script WorldInstanceInfoLoader extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            local callback = function (result, pages)
            
                	while true do
                		local datas = pages:GetCurrentPageDatas()
            
                		for _, data in pair(datas) do
                			log(data.Id)
                		end
            
                		if pages.IsLastPage == true then
                			break
                		end
            
                		pages:MoveToNextPageAndWait()
                	end
                end
            
                _WorldInstanceService:GetWorldInstanceInfoPagesAsync(callback)
        end
    end