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

# GameState — Global Game State API Reference

> API reference for the GameState class in RollingQuest Lua scripting. Access game mode, local data, completion state, and arcade mode variables.

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.

<Note>
  For level-specific state during gameplay, use the [`Level` namespace](/api/namespaces/level) instead. For campaign structure, use the [`Campaign` namespace](/api/namespaces/campaign).
</Note>

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

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

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