RoomService

This service processes room-related events.

# Properties

[{"index":"ReadOnlyDictionary InstanceRooms (ReadOnly)","0":"A list of all active instance rooms."}]

[{"index":"string RoomKey (ReadOnly)","0":"The key of the current room. If the current room is an instance room, it shows the specified key value when creating the room. If it is a static room, it shows the same value as StaticRoomKey."}]

[{"index":"string StaticRoomKey (ReadOnly)","0":"The key of the static room. A string constant (\"__main__\") is used as the RoomKey of the static room."}]

# Methods

[{"index":"InstanceRoom CreateInstanceRoom(string key, table mapNames, float firstUserWaitSeconds = 10) (ServerOnly) (Yield)","0":"Creates and returns an instance room corresponding to the key. If a map list is specified in mapNames, only those maps are created. If it is empty, maps for which the InstanceMap property of MapComponent is true are created. After creating an instance room, if there is no first user entering within firstUserWaitSeconds, the instance room will be destroyed. Script executions are suspended during the operation."}]

[{"index":"SharedMemoryResultCode DeleteSharedMemoryAndWait(string name) (ServerOnly) (Yield)","0":"Deletes shared memory. Suspends script executions during performance."}]

[{"index":"void DeleteSharedMemoryAsync(string name, func callbackFunction) (ServerOnly)","0":"Deletes shared memory. The function passed to the callbackFunction is called with the result codes upon completion of the operation."}]

[{"index":"InstanceRoom GetOrCreateInstanceRoom(string key, float firstUserWaitSeconds = 10) (ServerOnly) (Yield)","0":"Gets or creates and returns an instance room corresponding to the key. After creating, if there is no first user entering within firstUserWaitSeconds, the room will be destroyed. Script executions are suspended during the operation."}]

[{"index":"SharedMemoryResultCode, RoomSharedMemory 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 IsInstanceRoom()","0":"Checks if you are in the current instance room."}]

[{"index":"int32 MoveUsersToInstanceRoom(string key, table userIds, string mapName = nil) (ServerOnly) (Yield)","0":"Moves the users corresponding to userId to the instance room corresponding to the key. Suspends script executions during performance."}]

[{"index":"int32 MoveUsersToStaticRoom(table userIds, string mapName = nil) (ServerOnly) (Yield)","0":"Moves the user with the userIds to the instance room corresponding to the key. Moves to the start map when mapName is not used. Suspends script executions during performance."}]

[{"index":"boolean MoveUserToInstanceRoom(string key, string userId, string mapName = nil) (ServerOnly) (Yield)","0":"Moves the user with the specified userId to the instance room corresponding to the key. Script executions are suspended during the operation."}]

[{"index":"boolean MoveUserToStaticRoom(string userId, string mapName = nil) (ServerOnly) (Yield)","0":"Moves the user with the specified userId to the static room. If mapName is not used, it moves to the start map. Script executions are suspended during the operation."}]

[{"index":"SendEventRequestResultCode RequestSendEventToAllRoomsAndWait(EventType sendEvent) (Yield)","0":"Sends the event to all rooms. Recipients will receive events when they register a handler on RoomService. 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 RequestSendEventToAllRoomsAsync(EventType sendEvent, func callbackFunction)","0":"Sends the event to all rooms. Recipients will receive events when they register a handler on RoomService. 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 RequestSendEventToRoomAndWait(EventType sendEvent, string targetRoomKey) (Yield)","0":"Sends the event to the specified room. Recipients will receive events when they register a handler on RoomService. 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 RequestSendEventToRoomAsync(EventType sendEvent, string targetRoomKey, func callbackFunction)","0":"Sends the event to the specified room. Recipients will receive events when they register a handler on RoomService. 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":"RoomBeginEvent","0":"This event occurs in a room when it is created."}]

[{"index":"RoomEndEvent","0":"This event occurs in a room when it is destroyed."}]

# Examples

#### Entering an Instance Room

This is an example of creating an instance room using specific maps and entering the instance room's designated map.
    
    
    @Component
    script GameInstanceProvisioner extends Component
        property integer GameIdx = "0"
    
        @ExecSpace("ServerOnly")
        method void EnterGame(table userIds)
        -- Creates a unique instance room identifier that does not overlap.
        local roomKey = "Game" .. tostring(self.gameIdx)
        self.gameIdx = self.GameIdx + 1
    
        -- Creates an instance room using GameMap01, GameMap02.
        -- These maps must have the InstanceMap property set to true.
        -- Must be operated in a static room.
        local instanceRoom = _RoomService:CreateInstanceRoom(roomKey, {"GameMap01", "GameMap02"})
    
        -- You may fail to create this if the identifier is already in use or has been requested frequently.
        if instanceRoom == nil then
        	log_error("Cannot create instance room. roomKey: " .. roomKey)
        	return
        end
    
        -- Place users in the created instance room's specific map.
        -- You can also use the _RoomService:MoveUsersToInstanceRoom() function.
        instanceRoom:MoveUsers(userIds, "GameMap01")
        end
    end
    

#### Returning to a Static Room
    
    
    @Component
    script LobbyReturner extends Component
        @ExecSpace("ServerOnly")
        method void ReturnToLobby(table userIds)
        -- Place users in the static room's specific map.
        _RoomService:MoveUsersToStaticRoom(userIds, "LobbyMap")
        end
    end
    

# SeeAlso

  * InstanceMapService
  * [Communicating Between Rooms using RoomService](/docs?postId=1035)
  * [Creating Instance Map](/docs?postId=540)
  * [World Instances](/docs?postId=984)