WorldInstanceService

This service processes events between world instances.

# Properties

[{"index":"string WorldInstanceId (ReadOnly)","0":"The Id of the current world instance."}]

# Methods

[{"index":"SharedMemoryResultCode DeleteSharedMemoryAndWait(string name) (ServerOnly) (Yield)","0":"Deletes shared memory. Even if there are world instances using that shared memory, they will be deleted. Suspends script executions during performance."}]

[{"index":"void DeleteSharedMemoryAsync(string name, func callbackFunction) (ServerOnly)","0":"Deletes shared memory. Even if there are world instances using that shared memory, they will be deleted. The function passed to the callbackFunction is called with the result codes upon completion of the operation."}]

[{"index":"Division GetDivision() (ServerOnly)","0":"Confirms which regional server the world instance is running in. Maker always returns Division.Unknown."}]

[{"index":"SharedMemoryResultCode, WorldInstanceSharedMemory GetSharedMemory(string name) (ServerOnly)","0":"Returns a shared memory entity between rooms in the same world instance. If a shared memory with the same name already exists, obtains the existing one; if not, creates a new one."}]

[{"index":"boolean, WorldInstanceInfoPages GetWorldInstanceInfoPagesAndWait() (ServerOnly) (ReleaseOnly) (Yield)","0":"Inquires about WorldInstanceInfo for the current World in page units. You can see the query result with the returned Entity. The script executions are suspended while performing. This function only works in the release environment. If executed in the Maker, false and nil will be returned."}]

[{"index":"void GetWorldInstanceInfoPagesAsync(func callbackFunction) (ServerOnly) (ReleaseOnly)","0":"Inquires about WorldInstanceInfo for the current World in page units. You can see the query result with the returned Entity. This operation is performed asynchronously, and whether it is successful or not, the function passed to the callbackFunction is called along with the entity for inquiry when completing the operation. This function only works in the release environment. Returns false and nil when executed in the Maker."}]

[{"index":"SharedMemoryResultCode ReleaseSharedMemoryAndWait(string name) (ServerOnly) (Yield)","0":"Finishes using the shared memory. If there are no world instances using that shared memory, it will be deleted automatically. Suspends script executions during performance."}]

[{"index":"void ReleaseSharedMemoryAsync(string name, func callbackFunction) (ServerOnly)","0":"Finishes using the shared memory. If there are no world instances using that shared memory, it will be deleted automatically. The function passed to the callbackFunction is called with the result codes upon completion of the operation."}]

[{"index":"SendEventRequestResultCode RequestSendEventToAllWorldInstancesAndWait(EventType sendEvent) (Yield)","0":"Sends the event to all world instances. Recipients will receive events when they register a handler on WorldInstanceService. Script executions are suspended during the operation. You should be cautious, since sending Entity, EntityRef, Component, and ComponentRef in an event may result in invalid values being transmitted."}]

[{"index":"void RequestSendEventToAllWorldInstancesAsync(EventType sendEvent, func callbackFunction)","0":"Sends the event to all world instances. Recipients will receive events when they register a handler on WorldInstanceService. The function passed to the callbackFunction is called with the result codes and an event entity upon completion of the operation. You should be cautious, since sending Entity, EntityRef, Component, and ComponentRef in an event may result in invalid values being transmitted."}]

[{"index":"SendEventRequestResultCode RequestSendEventToWorldInstanceAndWait(EventType sendEvent, string targetWorldInstanceId) (Yield)","0":"Sends the event to the specified world instance. Recipients will receive events when they register a handler on WorldInstanceService. Script executions are suspended during the operation. You should be cautious, since sending Entity, EntityRef, Component, and ComponentRef in an event may result in invalid values being transmitted."}]

[{"index":"void RequestSendEventToWorldInstanceAsync(EventType sendEvent, string targetWorldInstanceId, func callbackFunction)","0":"Sends the event to the specified world instance. Recipients will receive events when they register a handler on WorldInstanceService. The function passed to the callbackFunction is called with the result codes and an event entity upon completion of the operation. You should be cautious, since sending Entity, EntityRef, Component, and ComponentRef in an event may result in invalid values being transmitted."}]

##### inherited from Service:

[{"index":"EventHandlerBase ConnectEvent(string key, IScriptFunction eventHandler)","0":"Links events. When a key-type event occurs in this service, a handler is notified. The handler receives event parameters."}]

[{"index":"EventHandlerBase ConnectEvent(Type eventType, IScriptFunction eventHandler)","0":"Links events. This service notifies a handler when an eventType event occurs. The handler receives event parameters."}]

[{"index":"boolean DisconnectEvent(string key, EventHandlerBase eventHandler)","0":"Disconnects the event with the key-type event and the handler."}]

[{"index":"boolean DisconnectEvent(Type eventType, EventHandlerBase eventHandler)","0":"Disconnects the eventType event from its handler."}]

[{"index":"void SendEvent(EventType sendEvent)","0":"Generates an event."}]

# Events

[{"index":"WorldInstanceExcludedEvent","0":"In the event that the world server is retired, this event occurs in the world instances that belong to the world server."}]

# Examples

#### Etag

This is an example of using Etag.
    
    
    @Component
    script OptimisticVariableUpdater extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            local code, mem = _WorldInstanceService:GetSharedMemory("memname")
            
            -- current.Info.ETag contains the latest ETag.
            local current = mem:GetVariableAndWait("varname")
            
            -- You must include the latest ETag in keyInfo to modify the shared variable. If it's different, it will not be modified. However, if it's empty or nil, it will be modified regardless.
            local keyInfo = SharedVariableKeyInfo(current.Info.Name, current.Info.ETag)
            
            -- If successful, the updated.Info.ETag contains the newly issued and latest ETag.
            local updated = mem:UpdateVariableAndWait(keyInfo, "new value")
            
            -- If it fails due to a mismatch in ETag, the error code SharedMemoryResultCode.PreconditionFailed will be returned.
            if updated.Code == SharedMemoryResultCode.PreconditionFailed then
            	error ("ETag Mismatch.")
            end
        end
    end
    

#### RequestSendEvent

This is an example of utilizing RequestSendEvent to output logs in all world instances when a user enters.
    
    
    @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
  * [Creating Instance Map](/docs?postId=540)
  * [Warping to a Specific World Instance](/docs?postId=1122)
  * [World Instance Communication](/docs?postId=999)