Persisting and Sharing Data Across RollingQuest Scripts

Scripts often need to remember things — how many enemies the player has defeated, whether a secret door has been opened, or a score multiplier set in an earlier level. RollingQuest gives you two storage layers to cover both use cases: level-local data that lives for the duration of the current level session, and campaign-global data that persists across all levels in a campaign.

Storage Layers at a Glance

Property	Type	Scope	API Style
`Level.localData` / `entity.localData`	`LocalData`	Current level session only	Table indexing (`data.foo = "bar"`)
`Level.campaignGlobalData`	`LocalData`	Entire campaign (survives level transitions)	Method calls (`data:setString("foo", "bar")`)

Both are accessed from any script in the level without importing anything.

These two storage types have different APIs. localData on entities and Level uses direct table indexing. campaignGlobalData uses typed method calls. Make sure to use the correct style for each.

Level-Local Data: `localData`

Level.localData and every entity’s localData (Block, Side, Item, Enemy, Ball, Decoration) are instances that behave like a Lua table. You read and write values using standard Lua bracket notation.

localData works like a table but does not support pairs() iteration. You can read/write individual keys, but you cannot loop over all keys.

Reading and Writing

Writing values
Reading values

-- Store any value type directly
Level.localData.gate_open = true
Level.localData.coins_collected = 0
Level.localData.elapsed_seconds = 0.0
Level.localData.last_checkpoint = "bridge-area"
Level.localData.player_state = { lives = 3, score = 100 }

-- Same pattern on entities
self.localData.roll_count = 1
self.localData.is_active = false

-- Read values directly (returns nil if key doesn't exist)
local isOpen  = Level.localData.gate_open
local coins   = Level.localData.coins_collected or 0
local elapsed = Level.localData.elapsed_seconds or 0.0
local label   = Level.localData.last_checkpoint or "start"
local state   = Level.localData.player_state

-- Use 'or' for default values
local count = Level.localData.roll_count or 0

Deleting Keys

Set a key to nil to remove it:

-- Remove a key
Level.localData.gate_open = nil
self.localData.temp_flag = nil

Because Level.localData is shared across all scripts in the level, any script can read what another script wrote:

Script A writes a value

-- Block script: increment a counter when the ball rolls on
---@param self Block
---@param rollIn boolean
---@param side Side
---@param ball Ball
function OnBallRoll(self, rollIn, side, ball)
    if rollIn then
        local count = Level.localData.plates_activated or 0
        Level.localData.plates_activated = count + 1
    end
end

Script B reads the value

-- Level script: check if all three plates are active to open the final door
---@param self Level
---@param deltaTime number
function OnUpdate(self, deltaTime)
    local activated = Level.localData.plates_activated or 0
    if activated >= 3 then
        local door = Elements.tagged["final-door"]:asBlock()
        door:disable()
    end
end

Saving and Restoring State

localData values are preserved across save/load within the same level session. If the player saves mid-level and loads later, all localData values remain intact.

Campaign-Global Data: `campaignGlobalData`

Level.campaignGlobalData persists for the lifetime of the entire campaign. Any value you write here in level 1 is still readable in level 5. Use it to track campaign-wide progress, unlock states, or accumulated scores.

Level.campaignGlobalData is only meaningful when the level is played inside a campaign. If the level runs standalone, the data still works but will not persist between separate play sessions.

Reading and Writing with Typed Methods

campaignGlobalData uses explicit typed methods — not table indexing.

Writing values
Reading values

-- Store typed values
Level.campaignGlobalData:setBool("gate_open", true)
Level.campaignGlobalData:setInteger("coins_collected", 0)
Level.campaignGlobalData:setNumber("elapsed_seconds", 0.0)
Level.campaignGlobalData:setString("last_checkpoint", "bridge-area")
Level.campaignGlobalData:setTable("player_state", { lives = 3, score = 100 })

-- The second argument is the default value if the key doesn't exist
local isOpen  = Level.campaignGlobalData:getBool("gate_open", false)
local coins   = Level.campaignGlobalData:getInteger("coins_collected", 0)
local elapsed = Level.campaignGlobalData:getNumber("elapsed_seconds", 0.0)
local label   = Level.campaignGlobalData:getString("last_checkpoint", "start")
local state   = Level.campaignGlobalData:getTable("player_state")

Checking and Deleting Keys

-- Check if a key was ever set
if Level.campaignGlobalData:exists("gate_open") then
    print("Gate flag exists")
end

-- Check existence AND type (e.g. "boolean", "integer", "number", "string", "table")
if Level.campaignGlobalData:existsAsType("coins_collected", "integer") then
    local n = Level.campaignGlobalData:getInteger("coins_collected", 0)
end

-- Remove a key entirely
Level.campaignGlobalData:delete("gate_open")

Campaign Example

-- In a level-completion hook: record that this level was cleared
---@param self Level
function OnWon(self)
    Level.campaignGlobalData:setBool("level_" .. Level.campaignLevelIndex .. "_cleared", true)
    Level.campaignGlobalData:setInteger(
        "total_coins",
        Level.campaignGlobalData:getInteger("total_coins", 0) + Level.collectedKeys
    )
end

-- In a later level: check earlier progress
---@param self Level
function OnStart(self)
    local clearedFirst = Level.campaignGlobalData:getBool("level_1_cleared", false)
    if clearedFirst then
        -- Spawn the secret bonus block
        Elements.tagged["bonus-block"]:asBlock():enable()
    end
end

Quick Reference

localData (table indexing)

Operation	Code
Write	`localData.myKey = value`
Read	`localData.myKey` (returns `nil` if missing)
Read with default	`localData.myKey or defaultValue`
Delete	`localData.myKey = nil`

campaignGlobalData (method calls)

Method	Description
`data:setBool(key, value)`	Store a boolean.
`data:getBool(key, default)`	Read a boolean; returns `default` if missing.
`data:setInteger(key, value)`	Store an integer.
`data:getInteger(key, default)`	Read an integer; returns `default` if missing.
`data:setNumber(key, value)`	Store a floating-point number.
`data:getNumber(key, default)`	Read a number; returns `default` if missing.
`data:setString(key, value)`	Store a string.
`data:getString(key, default)`	Read a string; returns `default` if missing.
`data:setTable(key, table)`	Store a table (can be a `LocalArray` or `LocalObject`).
`data:getTable(key [, default])`	Read a table; returns `default` or `{}` if missing.
`data:exists(key)`	Returns `true` if the key is present.
`data:existsAsType(key, sType)`	Returns `true` if the key exists and matches the given type string.
`data:delete(key)`	Remove the key from storage.

Prefix your keys with a unique identifier (like the entity name or script role) to avoid accidental collisions when multiple scripts use the same storage instance.

Get Started

Core Concepts

Recipes

Persisting and Sharing Data Across RollingQuest Scripts

Storage Layers at a Glance

Level-Local Data: `localData`

Reading and Writing

Deleting Keys

Saving and Restoring State

Campaign-Global Data: `campaignGlobalData`

Reading and Writing with Typed Methods

Checking and Deleting Keys

Campaign Example

Quick Reference

localData (table indexing)

campaignGlobalData (method calls)

​Storage Layers at a Glance

​Level-Local Data: localData

​Reading and Writing

​Deleting Keys

​Cross-Script Sharing

​Saving and Restoring State

​Campaign-Global Data: campaignGlobalData

​Reading and Writing with Typed Methods

​Checking and Deleting Keys

​Campaign Example

​Quick Reference

​localData (table indexing)

​campaignGlobalData (method calls)

Storage Layers at a Glance

Level-Local Data: `localData`

Reading and Writing

Deleting Keys

Cross-Script Sharing

Saving and Restoring State

Campaign-Global Data: `campaignGlobalData`

Reading and Writing with Typed Methods

Checking and Deleting Keys

Campaign Example

Quick Reference

localData (table indexing)

campaignGlobalData (method calls)