WorldInstanceService

월드 인스턴스 관련 기능을 제공합니다.

# Properties

[{"index":"string WorldInstanceId (ReadOnly)","0":"현재 월드 인스턴스의 Id입니다."}]

# Methods

[{"index":"SharedMemoryResultCode DeleteSharedMemoryAndWait(string name) (ServerOnly) (Yield)","0":"공유 메모리를 삭제합니다. 해당 공유 메모리를 사용 중인 월드 인스턴스가 있더라도 삭제됩니다. 수행하는 동안 스크립트 실행을 중단합니다."}]

[{"index":"void DeleteSharedMemoryAsync(string name, func callbackFunction) (ServerOnly)","0":"공유 메모리를 삭제합니다. 해당 공유 메모리를 사용 중인 월드 인스턴스가 있더라도 삭제됩니다. 작업이 완료되면 결과 코드와 함께 callbackFunction으로 전달된 함수가 호출됩니다."}]

[{"index":"Division GetDivision() (ServerOnly)","0":"월드 인스턴스가 실행되고 있는 서버가 어느 지역의 서버인지 확인합니다. 메이커에서는 항상 Division.Unknown을 반환합니다."}]

[{"index":"SharedMemoryResultCode, WorldInstanceSharedMemory GetSharedMemory(string name) (ServerOnly)","0":"월드 인스턴스끼리 공유하는 공유 메모리 객체를 반환합니다. 같은 이름의 공유 메모리가 이미 존재할 경우 기존 것을 얻어오고, 없을 경우 새로 생성합니다."}]

[{"index":"boolean, WorldInstanceInfoPages GetWorldInstanceInfoPagesAndWait() (ServerOnly) (ReleaseOnly) (Yield)","0":"현재 월드의 WorldInstanceInfo를 페이지 단위로 조회합니다. 조회 결과는 반환된 객체로 확인할 수 있습니다. 수행하는 동안 스크립트 수행을 중단합니다. 출시 환경에서만 동작하는 함수입니다. 메이커에서 실행하면 false와 nil을 반환합니다."}]

[{"index":"void GetWorldInstanceInfoPagesAsync(func callbackFunction) (ServerOnly) (ReleaseOnly)","0":"현재 월드의 WorldInstanceInfo를 페이지 단위로 조회합니다. 조회 결과는 반환된 객체로 확인할 수 있습니다. 이 작업은 비동기로 수행되며, 작업이 완료되면 성공 여부, 조회용 객체와 함께 callbackFunction으로 전달된 함수가 호출됩니다. 출시 환경에서만 동작하는 함수입니다. 메이커에서 실행하면 false와 nil이 전달됩니다."}]

[{"index":"SharedMemoryResultCode ReleaseSharedMemoryAndWait(string name) (ServerOnly) (Yield)","0":"공유 메모리 사용을 마칩니다. 해당 공유 메모리를 사용하는 월드 인스턴스가 없으면 자동으로 삭제됩니다. 수행하는 동안 스크립트 실행을 중단합니다."}]

[{"index":"void ReleaseSharedMemoryAsync(string name, func callbackFunction) (ServerOnly)","0":"공유 메모리 사용을 마칩니다. 해당 공유 메모리를 사용하는 월드 인스턴스가 없으면 자동으로 삭제됩니다. 작업이 완료되면 결과 코드와 함께 callbackFunction으로 전달된 함수가 호출됩니다."}]

[{"index":"SendEventRequestResultCode RequestSendEventToAllWorldInstancesAndWait(EventType sendEvent) (Yield)","0":"이벤트를 모든 월드 인스턴스에 전송합니다. 수신자는 WorldInstanceService에 핸들러를 등록해 이벤트를 수신할 수 있습니다. 수행하는 동안 스크립트 실행을 중단합니다. Entity, EntityRef, Component, ComponentRef를 Event에 담아 전송하면 유효하지 않은 값이 전달될 수 있으므로 주의해야 합니다."}]

[{"index":"void RequestSendEventToAllWorldInstancesAsync(EventType sendEvent, func callbackFunction)","0":"이벤트를 모든 월드 인스턴스에 전송합니다. 수신자는 WorldInstanceService에 핸들러를 등록해 이벤트를 수신할 수 있습니다. 작업이 완료되면 결과 코드, 이벤트 객체와 함께 callbackFunction으로 전달된 함수가 호출됩니다. Entity, EntityRef, Component, ComponentRef를 Event에 담아 전송하면 유효하지 않은 값이 전달될 수 있으므로 주의해야 합니다."}]

[{"index":"SendEventRequestResultCode RequestSendEventToWorldInstanceAndWait(EventType sendEvent, string targetWorldInstanceId) (Yield)","0":"이벤트를 특정 월드 인스턴스에 전송합니다. 수신자는 WorldInstanceService에 핸들러를 등록해 이벤트를 수신할 수 있습니다. 수행하는 동안 스크립트 실행을 중단합니다. Entity, EntityRef, Component, ComponentRef를 Event에 담아 전송하면 유효하지 않은 값이 전달될 수 있으므로 주의해야 합니다."}]

[{"index":"void RequestSendEventToWorldInstanceAsync(EventType sendEvent, string targetWorldInstanceId, func callbackFunction)","0":"이벤트를 특정 월드 인스턴스에 전송합니다. 수신자는 WorldInstanceService에 핸들러를 등록해 이벤트를 수신할 수 있습니다. 작업이 완료되면 결과 코드, 이벤트 객체와 함께 callbackFunction으로 전달된 함수가 호출됩니다. Entity, EntityRef, Component, ComponentRef를 Event에 담아 전송하면 유효하지 않은 값이 전달될 수 있으므로 주의해야 합니다."}]

##### inherited from Service:

[{"index":"EventHandlerBase ConnectEvent(string key, IScriptFunction eventHandler)","0":"이벤트를 연결합니다. 이 서비스에서 타입의 이름이 key인 이벤트가 발생하면, 핸들러로 통지받습니다. 핸들러는 event 매개 변수를 전달받습니다."}]

[{"index":"EventHandlerBase ConnectEvent(Type eventType, IScriptFunction eventHandler)","0":"이벤트를 연결합니다. 이 서비스에서 타입이 eventType인 이벤트가 발생하면, 핸들러로 통지받습니다. 핸들러는 event 매개 변수를 전달받습니다."}]

[{"index":"boolean DisconnectEvent(string key, EventHandlerBase eventHandler)","0":"타입의 이름이 key인 이벤트와 핸들러와의 이벤트 연결을 끊습니다."}]

[{"index":"boolean DisconnectEvent(Type eventType, EventHandlerBase eventHandler)","0":"타입이 eventType인 이벤트와 핸들러와의 연결을 끊습니다."}]

[{"index":"void SendEvent(EventType sendEvent)","0":"이벤트를 발생시킵니다."}]

# Events

[{"index":"WorldInstanceExcludedEvent","0":"월드 서버가 은퇴 상태가 되면 해당 월드 서버에 속한 월드 인스턴스에서 발생하는 이벤트입니다."}]

# Examples

#### ETag

ETag를 사용하는 예제입니다.
    
    
    @Component
    script OptimisticVariableUpdater extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            local code, mem = _WorldInstanceService:GetSharedMemory("memname")
            
            -- current.Info.ETag에는 최신 ETag가 담겨 있습니다.
            local current = mem:GetVariableAndWait("varname")
            
            -- keyInfo에 최신 ETag를 담아 보내야 공유 변수가 수정됩니다. 다른 값을 담으면 수정되지 않습니다. 단, 빈 문자열이나 nil을 담으면 무조건 공유 변수가 수정됩니다.
            local keyInfo = SharedVariableKeyInfo(current.Info.Name, current.Info.ETag)
            
            -- 성공 시, updated.Info.ETag에는 새롭게 발급받은 최신 ETag가 담겨 있습니다.
            local updated = mem:UpdateVariableAndWait(keyInfo, "new value")
            
            -- ETag 불일치로 인한 실패 시, SharedMemoryResultCode.PreconditionFailed 오류 코드가 반환됩니다.
            if updated.Code == SharedMemoryResultCode.PreconditionFailed then
            	error ("ETag Mismatch.")
            end
        end
    end
    

#### RequestSendEvent

RequestSendEvent를 활용해 유저가 입장했을 때 모든 월드 인스턴스에 로그를 출력하는 예제입니다.
    
    
    @Component
    script UserEntryAnnouncer extends Component
        @EventSender("Service", "UserService")
        handler HandleUserEnterEvent(UserEnterEvent event)
        --------------- Native Event Sender Info ----------------
        -- Sender: UserService
        -- Space: Server
        ---------------------------------------------------------
    
        -- Parameters
        local UserId = event.UserId
        ---------------------------------------------------------
    
        local worldInstanceId = _WorldInstanceService.WorldInstanceId
        local user = _UserService:GetUserEntityByUserId(UserId)
        local nickname = user.PlayerComponent.Nickname
    
        local evt = MyUserEnterEvent()
        evt.WorldInstanceId = worldInstanceId
        evt.Nickname = nickname
        _WorldInstanceService:RequestSendEventToAllWorldInstancesAndWait(evt)
        end
    
        @EventSender("Service", "WorldInstanceService")
        handler HandleMyUserEnterEvent(any event)
         -- Parameters
        local WorldInstanceId = event.WorldInstanceId
        local Nickname = event.Nickname
        ---------------------------------------------------------
    
        local currWorldInstId = _WorldInstanceService.WorldInstanceId
    
        if currWorldInstId == WorldInstanceId then
        	log ("User '" .. Nickname .. "' has entered this world instance.")
        else
        	log ("User '" .. Nickname .. "' has entered another world instance.")
        end
        end
    end
    

# SeeAlso

  * PlayerComponent
  * Division
  * SharedMemoryResultCode
  * UserEnterEvent
  * SharedVariableInfo
  * SharedVariableKeyInfo
  * UserService
  * [월드 인스턴스 통신](/docs?postId=999)
  * [인스턴스 맵 만들기](/docs?postId=540)
  * [특정 월드 인스턴스로 워프하기](/docs?postId=1122)