Skip to main content

Level Instance

The LevelInstance API provides a simple interface for spawning and managing dynamically loaded level instances at runtime

Constructor​

  • returns: table | nil - Wrapper object with .Streaming property (ULevelStreamingDynamic)
Example
local level = LevelInstance(
    Vector(0, 0, 1000),
    Rotator(0, 90, 0),
    '/Game/Maps/MyLevel.MyLevel'
)
ParameterTypeDefaultDescription
LocationVector(0, 0, 0)World location where the level will be spawned
RotationRotator(0, 0, 0)World rotation for the level instance
MapPathstringrequiredFull asset path to the map (e.g., /Game/Maps/MyLevel.MyLevel)
LevelNamestring''Optional unique identifier for tracking the instance
bLoadAsTempPackagebooleanfalseWhether to load as a temporary package

Functions​

Hide​

Hides the level instance while keeping it loaded in memory This improves performance when you need to temporarily hide a level without unloading it

Example
level:Hide()

Show​

Makes a hidden level instance visible again

Example
level:Show()

Unload​

Completely unloads the level instance from memory, freeing up resources

Example
level:Unload()

Reload​

Reloads a previously unloaded level instance

Example
level:Reload()

IsHidden​

Returns whether the level instance is currently hidden

  • returns: boolean
Example
local hidden = level:IsHidden()

IsLoaded​

Returns whether the level instance is currently loaded in memory

  • returns: boolean
Example
local loaded = level:IsLoaded()

OnShown​

Registers a callback function to be called when the level becomes visible

  • Callback: function - Function to execute when the level is shown
Example
level:OnShown(function()
    print('Level is now visible!')
end)

OnHidden​

Registers a callback function to be called when the level is hidden

  • Callback: function - Function to execute when the level is hidden
Example
level:OnHidden(function()
    print('Level was hidden')
end)

OnLoaded​

Registers a callback function to be called when the level finishes loading

  • Callback: function - Function to execute when the level is loaded
Example
level:OnLoaded(function()
    print('Level finished loading!')
end)

OnUnloaded​

Registers a callback function to be called when the level is unloaded

  • Callback: function - Function to execute when the level is unloaded
Example
level:OnUnloaded(function()
    print('Level was unloaded')
end)

Usage Examples​

Basic Level Spawning​

Example
local level = LevelInstance(
    Vector(0, 0, 1000),
    Rotator(0, 0, 0),
    '/Game/Maps/Arena.Arena'
)

With Custom Name and Callbacks​

Example
local level = LevelInstance(
    Vector(1000, 500, 0),
    Rotator(0, 45, 0),
    '/Game/Maps/BossRoom.BossRoom',
    'BossRoom_Instance_01'
)

level:OnLoaded(function()
    print('Boss room loaded!')
    -- Spawn enemies, set up triggers, etc.
end)

level:OnUnloaded(function()
    print('Boss room cleaned up')
end)

Toggle Visibility​

Example
local isVisible = true

function ToggleLevel()
    if isVisible then
        level:Hide()
    else
        level:Show()
    end
    isVisible = not isVisible
end

Memory Management​

Example
-- When player leaves area
level:Unload()

-- When player returns
level:Reload()
level:OnShown(function()
    print('Welcome back!')
end)
✨