Controlling Level State from Lua Scripts in RollingQuest

-- Complete the level normally (advances to the next level in the campaign)
function Level.completeLevel(): any

-- Complete and jump to a named level instead of the default next one
function Level.completeLevel(nextLevel: string): any

-- Lose the level with a standard cause (uses LostLevelCause enum)
function Level.loseLevel(cause: LostLevelCause): any

-- Lose the level with a custom message (icon taken from LostLevelCause)
function Level.loseLevel(cause: string, causeIcon: LostLevelCause): any

-- Lose the level with a fully custom message, no icon
function Level.loseLevel(cause: string): any

-- Restart the level from the beginning
function Level.restartLevel(): any

-- Kill the ball immediately with the "Burned" icon
Level.loseLevel(LostLevelCause.Burned)

-- Lose with a custom flavour-text message, borrowing the "Captured" icon
Level.loseLevel("The guardian caught you!", LostLevelCause.Captured)

-- Read-only properties
Level.currentLives    -- integer: current life count
Level.hasInfiniteLives -- boolean (read/write): toggle infinite lives

-- Functions
function Level.giveLives(amount: integer): any
function Level.loseLives(amount: integer): any

-- Grant a bonus life when the player finds a secret area
function OnBallRoll(self, rollIn, side, ball)
    if rollIn and self.tag == "secret_bonus" then
        Level.giveLives(1)
        Dialog.createTemporary("Secret found! +1 Life", 3.0, Color.new(0.1, 0.6, 0.1))
    end
end

-- Read-only score properties
Level.playerScore  -- integer: the player's cumulative campaign score
Level.levelScore   -- integer: the score accumulated in this level only

-- Function
function Level.giveScore(score: integer): any

-- Award a time bonus based on remaining hourglass time
local function awardTimeBonus()
    local bonus = math.floor(Level.remainingTime * 10)
    if bonus > 0 then
        Level.giveScore(bonus)
        Dialog.createTemporary("Time Bonus: +" .. bonus, 3.0, Color.yellow)
    end
end

-- Read-only / read-write properties
Level.remainingTime      -- number: seconds left on the hourglass (read-only)
Level.isHourglassEnabled -- boolean (read/write): enable or disable the hourglass
Level.isHourglassBlocked -- boolean (read-only): is the hourglass currently frozen?
Level.hourglassEndsCausesLoseLevel -- boolean (read-only)

-- Functions
function Level.increaseHourglassTime(amount: number): any
function Level.decreaseHourglassTime(amount: number): any
function Level.invertHourglass(): any

-- Add 10 seconds as a reward for collecting a bonus item
function OnCollect(self, ball)
    if self.tag == "time_gem" then
        Level.increaseHourglassTime(10.0)
        Dialog.createTemporary("+10 seconds!", 2.5, Color.cyan)
    end
end

function Level.activateDarkMode(): any
function Level.deactivateDarkMode(): any

-- Read-only status
Level.isDarkModeEnabled -- boolean

-- Activate dark mode when the ball enters a specific zone block
function OnBallRoll(self, rollIn, side, ball)
    if self.tag == "dark_zone_entry" then
        if rollIn then
            Level.activateDarkMode()
        else
            Level.deactivateDarkMode()
        end
    end
end

function Level.saveCheckpoint(): any
function Level.saveCheckpoint(side: Side): any

-- Save a checkpoint when the ball lands on a checkpoint block
function OnBallRoll(self, rollIn, side, ball)
    if rollIn and self.tag == "checkpoint" then
        Level.saveCheckpoint()
        Dialog.createTemporary("Checkpoint saved!", 2.0)
    end
end

function Level.activateSleepingPillEffect(seconds: number): any
function Level.deactivateSleepingPillEffect(): any

-- Read-only status
Level.isSleepingPillEffectActive -- boolean

function Level.delayAction(delayTime: number, action: fun(): void): any

-- Show a message then complete the level 2 seconds later
Level.delayAction(2.0, function()
    Level.completeLevel()
end)

-- Level script

local exitTriggered = false

function OnStart(self)
    Dialog.createCloseable(
        "Collect all " .. Level.keysCount .. " keys, then reach the exit!",
        Color.new(0.1, 0.1, 0.4, 0.9)
    )
end

function OnUpdate(self, deltaTime)
    -- Warn the player if time is running low
    if Level.isHourglassEnabled and Level.remainingTime <= 10.0 then
        -- This would fire every frame; in a real script guard with a flag
    end
end

-- Called from the exit block script via a shared tag check.
-- Attach this to the EXIT BLOCK entity instead if you prefer.
function onBallReachedExit(ball)
    if exitTriggered then return end

    if not Level.areAllKeysCollected then
        local remaining = Level.remainingKeys
        Dialog.createTemporary(
            "You still need " .. remaining .. " key(s)!",
            3.0,
            Color.new(0.7, 0.2, 0.0)
        )
        return
    end

    exitTriggered = true

    -- Award time bonus
    local timeBonus = math.floor(Level.remainingTime * 10)
    if timeBonus > 0 then
        Level.giveScore(timeBonus)
    end

    -- Save a checkpoint at the exit (just in case level transitions need it)
    Level.saveCheckpoint()

    -- Brief celebration message, then complete
    Dialog.createTemporary("All keys collected! Level complete!", 2.0, Color.green)
    Level.delayAction(2.0, function()
        Level.completeLevel()
    end)
end