> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rollingquest.kramgames.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LevelData — Level Data API Reference

> API reference for the LevelData class in RollingQuest Lua scripting. Modify level settings, messages, and scripts before the level loads.

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.

<Note>
  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.
</Note>

## 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

```lua theme={null}
--- @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

```lua theme={null}
--- @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

```lua theme={null}
---@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

```lua theme={null}
---@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

```lua theme={null}
---@param levelData LevelData
---@param level CampaignLevel
function OnLoadLevel(levelData, level)
    if level.episode.index >= 2 then
        levelData.lives = 5
    end
end
```