BattleScript
Home › Documentation › API Reference › Time and Timing

Time and Timing

Overview

BattleScript provides one standard time function, std::time.now(), for reading the current time. Timers and delays are language features provided by the after and every keywords (with optional limit) and can be stopped with cancel;.

Time Measurement

std::time.now

Description: Returns the current time in milliseconds since the device was powered on.

Syntax: std::time.now()

Returns: The current time in milliseconds

Example:

// Get the current time
int currentTime = std::time.now();
std::console.log("Current time:", currentTime);

Timers

BattleScript timers are built into the language via the after and every keywords. Use these constructs to schedule one-off and repeating work, optionally with a limit on repeats. You can stop a repeating timer inside its block with the cancel; statement.

after

Description: Run a block once after a delay (in milliseconds).

Syntax: after expression

Example:

// Run once after 2 seconds
after 2000 {
    std::console.log("2 seconds passed");
}

every

Description: Run a block repeatedly at a fixed interval (in milliseconds). Use limit n to cap the number of runs.

Syntax: every expression limit?

Examples:

// Log a message every 500ms
every 500 {
    std::console.log("tick");
}

// Run 5 times, then auto-stop
every 1000 limit 5 {
    std::console.log("repeat with limit");
}

cancel

Description: Stop a repeating every timer from within its block. The cancel; statement immediately stops further repeats.

Syntax: cancel;

Example:

int count = 0;

every 1000 {
    count += 1;
    std::console.log("count:", count);

    if (count == 3) {
        // Stop further repeats
        cancel;
    }
}

Note: There is no std::time.cancelTimer function. Use cancel; inside the timer block, or a limit clause to auto-stop.

Delays

Use after for one-off delays and every for repeated work. There are no time.delay or time.interval functions.

Delay once with after

after 3000 {
    std::console.log("This runs after 3 seconds");
}

Repeat with every

every 1000 {
    std::console.log("Tick");
}

// Stop after 10 seconds using limit
every 1000 limit 10 {
    std::console.log("Limited interval");
}

To stop a repeating block from inside, use cancel;.

Related Topics