DynamicMapService

Provides functions related to controlling dynamic maps.

# Methods

[{"index":"DynamicMapResultCode CreateDynamicMap(string sourceMapName, string newMapName) (ServerOnly)","0":"Creates a dynamic map. The name of the original map to be copied is sourceMapName, and newMapName is the name of the dynamic map to be created.Maps that can be used as the original maps vary depending on the room type.Only static maps can be used as source maps in static rooms, and only instance maps can be used in instance rooms. Only instance maps contained in the room can be used as source maps in instance rooms."}]

[{"index":"DynamicMapResultCode DestroyDynamicMap(string mapName) (ServerOnly)","0":"Destroys a dynamic map. The name of the dynamic map to be destroyed is mapName. The map cannot be destroyed if a user has entered."}]

[{"index":"table GetDynamicMapNameList() (ServerOnly)","0":"Calls up the names of all existing dynamic maps."}]

##### 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."}]

# Notice

  1. ResultCode is returned after OnBeginPlay for all components in the dynamic map is called. If you create a map that takes a long time to execute OnBeginPlay as a dynamic map, the world's performance may suffer.

  2. Be mindful of recursively creating in OnBeginPlay. If you create a dynamic map in OnBeginPlay from the original map, the dynamic map will be created recursively and repeatedly, which may cause an error.




# Examples

An example of creating, managing, and destroying a DynamicMap follows.
    
    
    @Component
    script BossMapManager extends Component
        @ExecSpace("ServerOnly")
        method boolean TryEnterPartyBossMap(table userList, string bossName, integer difficult)
        -- Specifies the original map name. This example assumes Boss Name + Base + Difficulty (e.g. ZakumBase1).
        local bossMapName = bossName .. "Base" .. tostring(math.tointeger(difficult))
        local newMapName = bossName + tostring(_UtilLogic:RandomInteger())
    
        -- A dynamic map cannot use duplicate names. If there is a duplicate, a new name will be created.
        while not self:IsValidDynamicMapName(newMapName) do
        	newMapName = bossName + tostring(_UtilLogic:RandomInteger())
        end
    
        -- A dynamic map is created.
        local resultCode = _DynamicMapService:CreateDynamicMap(bossMapName, newMapName)
    
        if resultCode ~= DynamicMapResultCode.Success then
        	-- If it fails to generate a dynamic map, an error code is returned.
        	self:OnError(resultCode)
        	return false
        end
    
        local reservedUserEntities = {}
        local reserved = true
    
        -- Reserves to move to a new map.
        for index, userId in pairs(userList) do
        	local userEntity = _UserService:GetUserEntityByUserId(userId)
        	reserved = reserved & _TeleportService:ReserveTeleportToMapPosition(userEntity, Vector3.zero, newMapName)
        	if not reserved then
        		break
        	end
        	table.insert(reservedUserEntities, userEntity)
        end
    
        -- Handles failure when the reservation to move to a map fails.
        if not reserved then
        	for index, userEntity in pairs(reservedUserEntities) do
        		_TeleportService:UnReserveTeleport(userEntity)
        	end
        	self:DestroyDynamicMap(newMapName)
        	return false
        end
    
        -- Executes the reservation to move to a map after generating the information required for managing a dynamic map.
        local userIdSet = {}
        for index, userId in pairs(userList) do
        	userIdSet[userId] = true
        end
    
        self.userIdSetByDynamicMapName[newMapName] = userIdSet
        self.dynamicMapNameSet[newMapName] = true
        _TeleportService:TeleportReservedEntities()
    
        return true
        end
    
        @ExecSpace("ServerOnly")
        method void OnBossCleared(string mapName)
        if self.dynamicMapNameSet[mapName] == nil then
        	return
        end
    
        -- Moves all users in the dynamic map to the 'Lobby' map.
        local userEntityList = _UserService:GetUsersByMapName(mapName)
        for i, userEntity in pairs(userEntityList) do
        	_TeleportService:ReserveTeleportToMapPosition(userEntity, Vector3.zero, "Lobby")
        end
        _TeleportService:TeleportReservedEntities()
    
        self:DestroyDynamicMap(mapName)
        end
    
        @ExecSpace("ServerOnly")
        method void DestroyDynamicMap(string mapName)
        -- Destroys the dynamic map.
        local resultCode = _DynamicMapService:DestroyDynamicMap(mapName)
    
        if resultCode ~= DynamicMapResultCode.Success then
        	self:OnError(resultCode)
        	return
        end
    
        -- Removes all information related to the destroyed dynamic map.
        self.dynamicMapNameSet[mapName] = nil
        self.userIdSetByDynamicMapName[mapName] = nil
        end
    
        @ExecSpace("ServerOnly")
        @EventSender("Service", "UserService")
        handler HandleUserLeaveEven(UserLeaveEvent event)
        	-- Handles users who exist in a dynamic map when they leave the world.
        	local UserId = event.UserId
        	local userEntity = _UserService:GetUserEntityByUserId(UserId)
        	local mapName = userEntity.CurrentMapName
    
        	-- Checks if the map where a user stayed is a dynamic map.
        	if self.dynamicMapNameSet[mapName] == nil then
        		return
        	end
    
        	-- Removes a user from the list of users currently in the dynamic map.
        	local userSet = self.userIdSetByDynamicMapName[mapName]
        	userSet[UserId] = nil
    
        	-- Destroys the dynamic map if there are no users left there.
        	local isEmpty = (next(userSet, nil) == nil)
        	if isEmpty then
    
        -- 		userEntity:ConnectEvent(EntityDestroyEvent, function()
        -- 			self:DestroyDynamicMap(mapName)
        -- 		end)
        -- [Commented: MLUA requires @EventSender + handler pattern]
        	end
        end
    end
    

# SeeAlso

  * UtilLogic
  * math
  * TeleportService
  * UserService