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

# Level Script Data

> How level-wide Lua scripts work in the RollingQuest editor: script reference, tag, and variables for the entire level.

Level Script Data allows you to attach a Lua script to the entire level. This script runs globally and can control level-wide behavior, manage state, and coordinate between sections.

## Accessing Level Script Data

1. Press **Escape** → **Level Properties**
2. Click the **Script** button

## Configuration

### Script Reference

The name of the script in the level's script collection. This script will be executed as the level's main script.

### Script Tag

A string identifier for this level instance. Useful when the same level is used in multiple contexts.

### Local Variables

Key-value pairs accessible from the level script. These are stored as `EditorLevelScriptData` and persisted with the level.

## How Level Scripts Work

The level script is attached to the level data via:

* `levelData.ScriptRef` — The script reference
* `levelData.ScriptTag` — The tag string
* `levelData.ScriptVars` — The variable collection

During gameplay, the level script receives hooks and signals for level-wide events:

* `OnStart` — When the level begins
* `OnUpdate` — Every frame
* `OnLevelEvent` — Custom level events

## Example

```lua theme={null}
-- Level script: level_main
function OnStart(self)
    -- Access level variables
    local difficulty = self.vars["difficulty"]
    local maxEnemies = self.vars["maxEnemies"]

    -- Set up the level
    Level.setInitialTime(120)
    Level.setLives(3)
end

function OnUpdate(self, deltaTime)
    -- Level-wide update logic
end
```

## Data Flow

The `EditorLevelScriptData` class implements `ILuaScriptOwnerInfo`, providing:

* `ScriptReference` — Get/set the script reference
* `LuaTag` — Get/set the tag string
* `LuaLocalVariablesDefinitions` — Get/set the variable collection

When the level is saved, these values are written to the `LevelData` object. When loaded, they are restored from the saved data.

<Note>
  Level scripts are separate from element scripts. A level script runs once for the entire level, while element scripts run per-element. Both can coexist.
</Note>