Level Namespace — RollingQuest Lua Scripting API

The Level namespace is your primary interface to everything happening inside a running level. Every variable and function documented here is accessed directly as a field on the global Level table — for example, Level.keysCount or Level.completeLevel(). All variables are read-only unless explicitly noted otherwise.

Campaign Info

These variables describe which campaign, episode, and level is currently running.

Variable	Type	Description
`Level.campaign`	`string`	Name of the campaign the level belongs to.
`Level.campaignEpisode`	`string`	Name of the current episode in the campaign.
`Level.campaignEpisodeIndex`	`integer`	Zero-based index of the current episode.
`Level.campaignLevelName`	`string`	Name of the current level in the campaign.
`Level.campaignLevelIndex`	`integer`	Index of the current level in the campaign.
`Level.isCampaignNormalLevel`	`boolean`	`true` if this is a normal (story) level.
`Level.isCampaignBonusLevel`	`boolean`	`true` if this is a bonus level.
`Level.isCampaignSecretLevel`	`boolean`	`true` if this is a secret level.
`Level.campaignNormalLevelNumber`	`integer`	Sequential number of this normal level in the campaign.
`Level.campaignGlobalData`	`LocalData`	Global data storage shared across the entire campaign.
`Level.tag`	`string`	The tag assigned to this level entity.
`Level.localData`	`LocalData`	Per-level local data storage.
`Level.type`	`EntityType`	Entity type of the level (`EntityType.Level`).

Level State

These variables expose the current structural state of the level.

Variable	Type	Description
`Level.keysCount`	`integer`	Total number of keys placed in the level.
`Level.remainingKeys`	`integer`	Number of keys not yet collected.
`Level.collectedKeys`	`integer`	Number of keys already collected.
`Level.areAllKeysCollected`	`boolean`	`true` when every key has been collected.
`Level.treasureCount`	`integer`	Total number of treasures in the level.
`Level.treasureScoreCount`	`integer`	Number of treasures that contribute to score.
`Level.treasureTotalScore`	`integer`	Combined score value of all treasures.
`Level.visitableBlocksCount`	`integer`	Number of blocks the ball can visit.
`Level.hasFruit`	`boolean`	`true` if at least one fruit is present.
`Level.areFruitsEnabled`	`boolean`	`true` if the fruit system is active.
`Level.currentFruitIndex`	`integer`	Index of the current active fruit.
`Level.areAllFruitsCollected`	`boolean`	`true` when every fruit has been collected.
`Level.areAllRequiredFruitsToBonusCollected`	`boolean`	`true` when enough fruits to unlock the bonus have been collected.

Time & Timer

Variable	Type	Writable	Description
`Level.maxTime`	`number`	No	Maximum allowed time configured for the level.
`Level.initialTime`	`number`	No	Time value the level started with.
`Level.remainingTime`	`number`	No	Current hourglass time remaining.
`Level.isHourglassEnabled`	`boolean`	Yes	Enable or disable the hourglass countdown.
`Level.isHourglassBlocked`	`boolean`	No	`true` when the hourglass is paused/blocked.
`Level.hourglassEndsCausesLoseLevel`	`boolean`	No	`true` if running out of hourglass time ends the level.
`Level.timer`	`Timer`	No	The level’s `Timer` object for precise time operations.
`Level.isElapsedTimeEnabled`	`boolean`	No	`true` if elapsed-time tracking is active.
`Level.elapsedTime`	`number`	No	Total seconds elapsed since level start.
`Level.glassesTime`	`number`	Yes	Duration of the glasses (lighting) effect.

Scoring

Variable	Type	Description
`Level.isPlayerScoreEnabled`	`boolean`	`true` if the global player score system is active.
`Level.isLevelScoreEnabled`	`boolean`	`true` if per-level scoring is active.
`Level.playerScore`	`integer`	The player’s cumulative score across the run.
`Level.levelScore`	`integer`	Score accumulated specifically within this level.
`Level.levelLosePenalty`	`integer`	Points deducted when the player loses the level.
`Level.levelRestartPenalty`	`integer`	Points deducted when the player restarts the level.
`Level.treasureCollected`	`integer`	Number of treasure items the player has collected.
`Level.treasureScoreCollected`	`integer`	Score earned from collected treasure items.
`Level.treasureCollectedPercentage`	`number`	Percentage of total treasures collected (`0.0`–`1.0`).

Lives

Variable	Type	Writable	Description
`Level.currentLives`	`integer`	No	The player’s current life count.
`Level.hasInfiniteLives`	`boolean`	Yes	Set to `true` to grant the player unlimited lives.

Special States

Variable	Type	Description
`Level.isDarkModeEnabled`	`boolean`	`true` when dark mode (reduced visibility) is active.
`Level.isSleepingPillEffectActive`	`boolean`	`true` while the sleeping-pill slow-motion effect is running.
`Level.lavaPool`	`LavaPool`	Reference to the level’s lava pool environment object.
`Level.currentBall`	`Ball`	The ball currently under player control.

Entity Accessors

These functions return entities from the level. Functions ending with Iterator return a lazy iterator for for loops; their counterparts return a plain Lua table.

Iterators

function Level.getAllBlocksIterator()
function Level.getAllEnemiesIterator()
function Level.getAllBallsIterator()
function Level.getAllItemsIterator()
function Level.getAllDecorationsIterator()

Tables

function Level.getBlocks()
function Level.getEnemies()
function Level.getBalls()
function Level.getItems()
function Level.getDecorations()

Single entity lookups

--- @param index integer
--- @return Ball
function Level.getBall(index)

--- @param x integer
--- @param y integer
--- @param z integer
--- @return Block
function Level.getBlock(x, y, z)

--- @param slot BlockSlot
--- @return Block
function Level.getBlock(slot)

--- @param x integer
--- @param y integer
--- @param z integer
--- @return boolean
function Level.hasBlock(x, y, z)

--- @param slot BlockSlot
--- @return boolean
function Level.hasBlock(slot)

--- @param color LevelColor
--- @return Side
function Level.getPortalSide(color)

--- @param origin Side
--- @return Side
function Level.getNextTeleportTarget(origin)

Level Control Functions

`completeLevel`

Marks the level as successfully completed and advances to the next level.

function Level.completeLevel()

--- @param nextLevel string
function Level.completeLevel(nextLevel)

`loseLevel`

Triggers the lose-level state with a specified cause.

--- @param cause LostLevelCause
function Level.loseLevel(cause)

--- @param cause string
function Level.loseLevel(cause)

--- @param cause string
--- @param causeIcon LostLevelCause
function Level.loseLevel(cause, causeIcon)

`restartLevel`

Restarts the current level from the beginning.

function Level.restartLevel()

Time Functions

--- @param amount number
function Level.increaseHourglassTime(amount)

--- @param amount number
function Level.decreaseHourglassTime(amount)

function Level.invertHourglass()

Scoring & Lives Functions

--- @param score integer
function Level.giveScore(score)

--- @param amount integer
function Level.giveLives(amount)

--- @param amount integer
function Level.loseLives(amount)

Effect Functions

Dark mode

function Level.activateDarkMode()
function Level.deactivateDarkMode()

Sleeping pill

--- @param seconds number
function Level.activateSleepingPillEffect(seconds)

function Level.deactivateSleepingPillEffect()

Checkpoints

function Level.saveCheckpoint()

--- @param side Side
function Level.saveCheckpoint(side)

Fruit Helpers

--- @param fruitIndex integer
--- @return boolean
function Level.isFruitEnabled(fruitIndex)

--- @param fruitIndex integer
--- @return boolean
function Level.isFruitCollected(fruitIndex)

Utility

`delayAction`

Schedules a Lua function to run after delayTime seconds.

--- @param delayTime number
--- @param action fun(): void
function Level.delayAction(delayTime, action)

`createProjectile`

Spawns a projectile in the level.

--- @param request ProjectileRequest
--- @return Projectile
function Level.createProjectile(request)

--- @param projectileProperties table
--- @return Projectile
function Level.createProjectile(projectileProperties)

`getAvailableProjectileSkins`

Returns a table of available skin name strings.

--- @return table
function Level.getAvailableProjectileSkins()

Cast Functions

function Level.asLevel()
function Level.asBlock()
function Level.asSide()
function Level.asItem()
function Level.asEnemy()
function Level.asBall()
function Level.asDecoration()

Usage Example

function OnStart()
    Dialog.createTemporary("Find all the keys!", 4.0)

    Level.delayAction(3.0, function()
        Level.activateDarkMode()
    end)
end

function OnBallRoll(self, rollIn, side, ball)
    if Level.areAllKeysCollected then
        Level.giveScore(500)
        Dialog.createTemporary("All keys found! Head to the exit.", 3.0)
    end
end

function OnLost(self)
    Level.loseLevel("Time ran out!", LostLevelCause.Hourglass)
end

Namespaces

Entity Classes

Level Editor

Core Types

Enums

Level Namespace — RollingQuest Lua Scripting API

Campaign Info

Level State

Time & Timer

Scoring

Lives

Special States

Entity Accessors

Iterators

Tables

Single entity lookups

Level Control Functions

`completeLevel`

`loseLevel`

`restartLevel`

Time Functions

Scoring & Lives Functions

Effect Functions

Dark mode

Sleeping pill

Checkpoints

Fruit Helpers

Utility

`delayAction`

`createProjectile`

`getAvailableProjectileSkins`

Cast Functions

Usage Example

​Campaign Info

​Level State

​Time & Timer

​Scoring

​Lives

​Special States

​Entity Accessors

​Iterators

​Tables

​Single entity lookups

​Level Control Functions

​completeLevel

​loseLevel

​restartLevel

​Time Functions

​Scoring & Lives Functions

​Effect Functions

​Dark mode

​Sleeping pill

​Checkpoints

​Fruit Helpers

​Utility

​delayAction

​createProjectile

​getAvailableProjectileSkins

​Cast Functions

​Usage Example

Campaign Info

Level State

Time & Timer

Scoring

Lives

Special States

Entity Accessors

Iterators

Tables

Single entity lookups

Level Control Functions

`completeLevel`

`loseLevel`

`restartLevel`

Time Functions

Scoring & Lives Functions

Effect Functions

Dark mode

Sleeping pill

Checkpoints

Fruit Helpers

Utility

`delayAction`

`createProjectile`

`getAvailableProjectileSkins`

Cast Functions

Usage Example