LevelData — Level Data API Reference - RollingQuest Lua Scripting

The LevelData class represents the complete data structure of a level — its blocks, enemies, balls, items, messages, scripts, and global settings. This is the universal format used by both the in-game level editor and the campaign system. You can access LevelData in the OnLoadLevel campaign hook to modify level data before the level starts playing.

During gameplay you cannot create or destroy entities. You can only enable/disable existing ones. The LevelData API is for modifying the level’s design data before it loads, not for runtime entity creation.

Properties

Property	Type	Read/Write	Description
`initialTime`	`integer`	❌ Read/Write	Starting time for the level countdown.
`maxTime`	`integer`	❌ Read/Write	Maximum time allowed for the level.
`lives`	`integer`	❌ Read/Write	Number of lives the player starts with.
`hourglass`	`boolean`	❌ Read/Write	Whether the hourglass mechanic is enabled.
`infiniteLives`	`boolean`	❌ Read/Write	Whether the player has infinite lives.
`scriptRef`	`string`	❌ Read/Write	Script file reference for the level.
`scriptTag`	`string`	❌ Read/Write	Tag forwarded to the level’s script.
`scriptVars`	`ScriptVariables`	✅ Read	Variable table for the level’s script.
`messagesCount`	`integer`	✅ Read	Number of messages defined.
`scriptsCount`	`integer`	✅ Read	Number of scripts attached.

Message Methods

--- @param name string
--- @return boolean
function LevelData:hasMessage(name)

--- @param name string
--- @return MessageData
function LevelData:getMessage(name)

function LevelData:getAllMessagesIterator()
function LevelData:getAllMessages()  -- returns Table

Script Methods

--- @param name string
--- @return boolean
function LevelData:hasScript(name)

--- @param name string
--- @return ScriptData
function LevelData:getScript(name)

function LevelData:getAllScriptsIterator()
function LevelData:getAllScripts()  -- returns Table

Modifying Level Data with `OnLoadLevel`

The OnLoadLevel campaign hook receives a LevelData object before the level starts. You can modify level settings, but you cannot create or destroy entities — only change parameters.

Hook Signature

---@param levelData LevelData
---@param level CampaignLevel
function OnLoadLevel(levelData, level)
    -- Modify levelData properties here
end

What You Can Modify

Property	Description
`levelData.initialTime`	Change the starting time
`levelData.maxTime`	Change the maximum time
`levelData.lives`	Change the number of lives
`levelData.hourglass`	Enable/disable the hourglass
`levelData.infiniteLives`	Enable/disable infinite lives
`levelData.scriptRef`	Change the level script
`levelData.scriptTag`	Change the level script tag

Example: Dynamic Difficulty

---@param levelData LevelData
---@param level CampaignLevel
function OnLoadLevel(levelData, level)
    local prev = Campaign.getNormalLevelByNumber(Level.campaignNormalLevelNumber - 1)
    if prev ~= nil and Campaign.completionState:isLevelCompleted(prev) then
        levelData.maxTime = math.max(60, levelData.maxTime - 30)
    end
end

Example: Adjust Lives Based on Progress

---@param levelData LevelData
---@param level CampaignLevel
function OnLoadLevel(levelData, level)
    if level.episode.index >= 2 then
        levelData.lives = 5
    end
end

Namespaces

Entity Classes

Level Editor

Core Types

Enums

LevelData — Level Data API Reference

Properties

Message Methods

Script Methods

Modifying Level Data with `OnLoadLevel`

Hook Signature

What You Can Modify

Example: Dynamic Difficulty

Example: Adjust Lives Based on Progress

​Properties

​Message Methods

​Script Methods

​Modifying Level Data with OnLoadLevel

​Hook Signature

​What You Can Modify

​Example: Dynamic Difficulty

​Example: Adjust Lives Based on Progress

Properties

Message Methods

Script Methods

Modifying Level Data with `OnLoadLevel`

Hook Signature

What You Can Modify

Example: Dynamic Difficulty

Example: Adjust Lives Based on Progress