GameState — Global Game State API Reference - RollingQuest Lua Scripting

The GameState class provides access to global game state information that persists across levels. This includes the current game mode (arcade or exploration), persistent local data, and arcade-specific variables like score and level number.

For level-specific state during gameplay, use the Level namespace instead. For campaign structure, use the Campaign namespace.

Properties

Game Mode

Property	Type	Read-only	Description
`isArcadeGameMode`	`boolean`	✅	`true` when running in arcade mode.
`isExplorationGameMode`	`boolean`	✅	`true` when running in exploration mode.

Persistent Data

Property	Type	Read-only	Description
`localData`	`LocalData`	✅	Persistent key-value store for global game state.
`completionState`	`CampaignCompletionState`	✅	Completion tracking for all levels and episodes.

Arcade Mode

These properties are active only when isArcadeGameMode is true:

Property	Type	Read/Write	Description
`arcadeScore`	`integer`	❌	Current arcade mode score.
`arcadeLevelNumber`	`integer`	❌	Current arcade level number.
`arcadeCollectedFruits`	`integer`	❌	Number of fruits collected in arcade mode.

Usage Example

Store and retrieve global state across levels:

function OnStart()
    -- Track total play time across levels
    local totalTime = GameState.localData:getNumber("totalPlayTime", 0)
    Logger.info("Total play time: " .. totalTime .. " seconds")

    -- Update arcade score
    if GameState.isArcadeGameMode then
        Logger.info("Arcade score: " .. GameState.arcadeScore)
        Logger.info("Arcade level: " .. GameState.arcadeLevelNumber)
    end
end

Check completion state:

function OnStart()
    local level = Campaign.getNormalLevelByNumber(1)
    if GameState.completionState:isLevelCompleted(level) then
        Logger.info("Level 1 already completed!")
    end
end